Payment API, version 30.11.2021

Versions

30.11.2021

Requirements

To start integrating with our service you will need the following:

If you don’t have a test merchant account, please contact us at [email protected] and we
will open one for you. Then you can login into your account
at https://ipgtest.monri.com/en/login with login and password provided.

Requests

Documentation below describes:

Api URL

environment value
test https://ipgtest.monri.com
prod https://ipg.monri.com

NOTE Parametrize api url value.

Headers

name value description
Content-Type application/json All api endpoints require application/json Content-Type header
Accept application/json All api endpoints require application/json Accept header
Authorization <authorization_header> All api endpoints require Authorization header. See below how to generate one

Authentication

Every request to the Monri’s backend requires authentication. Depending on HTTP method algorithm used to
create Authorization header differs.

To create authorization header you’ll need:

Authorization header for GET|POST request is created from:

name value description
schema WP3-v2.1  
authenticity_token <authenticity_token> Available on merchant’s dashboard
timestamp <timestamp> Unix timestamp, eg PHP’s time()
digest <digest> See docs for digest generation

Digest generation

name value description
merchant_key <merchant_key> Value available on merchant’s dashboard
timestamp <timestamp> Same timestamp value used in authorization header
authenticity_token <authenticity_token> Value available on merchant’s dashboard
fullpath <fullpath> Full path of request, eg, /v2/terminal-entries/create
body <body> Empty string if GET request, request body if POST request
Digest example

If we have:

{
  "transaction_type": "purchase",
  "amount": 30,
  "currency": "BAM",
  "number_of_installments": "",
  "order_number": "6f3946764b6b41634845734b6b4d71344f516a4f",
  "order_info": "Order info",
  "language": "hr",
  "ch_full_name": "John Doe",
  "ch_address": "Elm street 22",
  "ch_city": "Orgrimmar",
  "ch_zip": "q123abc99",
  "ch_country": "US",
  "ch_phone": "123456",
  "ch_email": "[email protected]",
  "comment": "",
  "supported_payment_methods": [
    "fa603bc5007cc9c0527cf8e940364335129966b60e502390"
  ]
}

Then we create digest as:

const crypto = require('crypto');
var fullpath = `/v2/payment/new`
var body = JSON.stringify({
  "transaction_type": "purchase",
  "amount": 30,
  "currency": "BAM",
  "number_of_installments": "",
  "order_number": "6f3946764b6b41634845734b6b4d71344f516a4f",
  "order_info": "Order info",
  "language": "hr",
  "ch_full_name": "John Doe",
  "ch_address": "Elm street 22",
  "ch_city": "Orgrimmar",
  "ch_zip": "q123abc99",
  "ch_country": "US",
  "ch_phone": "123456",
  "ch_email": "[email protected]",
  "comment": "",
  "supported_payment_methods": ["fa603bc5007cc9c0527cf8e940364335129966b60e502390"]
})
var merchantKey = `qwert1234`
var authenticityToken = `7db11ea5d4a1af32421b564c79b946d1ead3daf0`
var timestamp = 1593457122 // If you are using this as an example replace exact value with call to eg (new Date()).getTime()

// we create digest for merchantKey + timestamp + authenticityToken + fullpath + body which is equal to
// qwert123415934571227db11ea5d4a1af32421b564c79b946d1ead3daf0/v2/payment/new{"transaction_type":"purchase","amount":30,"currency":"BAM","number_of_installments":"","order_number":"6f3946764b6b41634845734b6b4d71344f516a4f","order_info":"Order info","language":"hr","ch_full_name":"John Doe","ch_address":"Elm street 22","ch_city":"Orgrimmar","ch_zip":"q123abc99","ch_country":"US","ch_phone":"123456","ch_email":"[email protected]","comment":"","supported_payment_methods":["fa603bc5007cc9c0527cf8e940364335129966b60e502390"]}
var digest = crypto.createHmac('sha512', merchantKey + timestamp + authenticityToken + fullpath + body).digest('hex');
// we should get 9d4725e83a4c49559203e055312e14a44aa1c039c4ed9d0adf8a74aa6ed842103f585cd343450ed1857ee7b402a266ad57238a89e2ead603ec0563057c612865

Response Handling

Monri’s API adheres to following principles:

status status code description
created 200 Resource is created
updated 200 Resource is updated
approved 200 Request successful
invalid-request 4** There’s something wrong with request
error 500 Something went wrong while processing the request

Valid (approved) response

Example of valid response:


{
  "status": "approved",
  "id": "992a1c068e7d1254672de48cc47efc98468a5bc4",
  "client_secret": "992a1c068e7d1254672de48cc47efc98468a5bc4"
}

Invalid-request response

Example of invalid-request response:

{
  "status": "invalid-request",
  "message": "Order number can't be blank, Order number is too short (minimum is 3 characters)"
}

Error response

Example of error response:

{
  "status": "error",
  "message": "An error occurred while processing request. Please try later."
}

Create Payment

Request

To create a Payment you’ll need to provide:

Request endpoint details

name value description
base_url ipgtest.monri.com or ipg.monri.com Parametrize this value
path v2/payment/new This path is used for create action
method POST We are creating/updating resource, hence POST method

Request body:

field length type required description
amount 1-11 Integer YES amount is in minor units, ie. 10.24 USD is sent as 1024
order_number 2-40 String YES unique order identifier
currency 3 String YES One of supported currencies (BAM, HRK, EUR, USD, CHF etc)
transaction_type enum String YES possible values are: authorizeor purchase
order_info 3-100 String YES short description of order being processed
scenario enum String NO possible values are: chargeor add_payment_method
supported_payment_methodsnew predefined Array<String> NO An array of pan-tokens and/or card (see below for more details)

Scenario charge charges customer amount. Depending on transaction_type amount is reserved (authorize) or captured (purchase).

Scenario add_payment_method provides simple way to implement ‘Save card for future payments’ functionality.

Supported payment methods

supported_payment_methods in an array of valid payment methods.

Valid payment methods are:

Requirements / options:

Example of valid payment methods:

{
  "supported_payment_methods": [
    "f167252fecfeff8f134001bf8e7a700c53e8653f631362dd84913e23260199bf",
    "0df5d4eac4f36d0dee9f48c17ddac2f66c12e5edfc4f92a92d3e6085f31368ea",
    "card"
  ]
}

Setup above will result in:

Response

field length type description
status enum String approved, invalid-request or error
client_secret 40 String Client secret
id 40 String Payment id
message - String OPTIONAL - available if status is error or invalid-request

Example of response:


{
  "status": "approved",
  "id": "992a1c068e7d1254672de48cc47efc98468a5bc4",
  "client_secret": "992a1c068e7d1254672de48cc47efc98468a5bc4"
}

Update

To update previously created Payment you’ll need to provide:

Request

name value description
base_url ipgtest.monri.com or ipg.monri.com Parametrize this value
path /v2/payment/<payment-id>/update id of previously created resource
method POST We are creating/updating resource, hence POST method

Request body:

field length type required description
amount 1-11 Integer YES amount is in minor units, ie. 10.24 USD is sent as 1024

Response

field length type description
status enum String approved, invalid-request or error
client_secret 40 String Client secret
amount 1-11 Integer amount is in minor units, ie. 10.24 USD is sent as 1024
currency 3 String One of supported currencies (BAM, HRK, EUR, USD, CHF etc)
id 40 String Payment id
message - String OPTIONAL - available if status is error or invalid-request

Example of response:


{
  "status": "approved",
  "id": "992a1c068e7d1254672de48cc47efc98468a5bc4",
  "client_secret": "992a1c068e7d1254672de48cc47efc98468a5bc4",
  "amount": 100,
  "currency": "BAM"
}