WebPay



Pay By Link API, version 17.09.2020

Versions

10.05.2022

12.04.2021

17.09.2020

08.09.2020

30.06.2020

29.06.2020

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-or-update
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":"6638614b544b7058414b5467304146574c647841","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/terminal-entry/create-or-update`
var body = JSON.stringify({"transaction_type":"purchase","amount":30,"currency":"BAM","number_of_installments":"","order_number":"6638614b544b7058414b5467304146574c647841","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/terminal-entry/create-or-update{"transaction_type":"purchase","amount":30,"currency":"BAM","number_of_installments":"","order_number":"6638614b544b7058414b5467304146574c647841","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"]}
const digest = crypto.createHash('sha512')
        .update(merchantKey + timestamp + authenticityToken + fullpath + body)
        .digest('hex');
// we should get 9d4725e83a4c49559203e055312e14a44aa1c039c4ed9d0adf8a74aa6ed842103f585cd343450ed1857ee7b402a266ad57238a89e2ead603ec0563057c612865

You can check digest on this link Calculate Digest

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, created, updated) response

Example of valid response:


{
   "status":"approved",
   "id":1,
   "transaction_type":"purchase",
   "number_of_installments":null,
   "amount":100,
   "currency":"HRK",
   "language":"en",
   "order_number":"6638614b544b7058414b5467304146574c647841",
   "order_info":"Test trx",
   "ch_full_name":"Test",
   "ch_address":"Test",
   "ch_city":"Test",
   "ch_zip":"Test",
   "ch_country":"BIH",
   "ch_phone":"061 000 000",
   "ch_email":"[email protected]",
   "terminal_entry_status":"pending",
   "expires_at":"2019-02-22 11:22:33 UTC",
   "active": true,
   "comment":null,
   "created_at":"2019-02-12 11:22:33 UTC",
   "updated_at":"2019-02-12 11:22:33 UTC",
   "moto":false,
   "force_cc_type":false,
   "payment_url":"http://127.0.0.1:31337/v2/order/6638614b544b7058414b5467304146574c647841",
   "supported_payment_methods":[],
   "tokenize_pan": false,
   "tokenize_pan_offered": false
}

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 Or Update

Every resource on Monri’s API has idempotency key used for create-or-update action.
Idempotency key for PayByLink is order_number. To update resource previously created simply provided same order_number.

Request

To create PayByLink 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/terminal-entry/create-or-update This path is used for both create and update action
method POST We are creating/updating resource, hence POST method

Request body:

field length type required updateable description
amount 1-11 Integer YES YES amount is in minor units, ie. 10.24 USD is sent as 1024
currency 3 String YES YES One of supported currencies (BAM, HRK, EUR, USD, CHF etc)
order_number 2-40 String YES NO Unique order identifier
transaction_type enum String YES YES possible values are: authorize or purchase
order_info 3-100 String YES YES Short description of order being processed
number_of_installments 1-2 Integer NO YES range 2-12
supported_payment_methods predefined Array<String> NO YES An array of payment methods, pan token or card (see below for more details)
status enum String NO YES buyer’s full name
ch_address 3-100 String NO YES buyer’s address
ch_city 3-30 String NO YES buyer’s city
ch_zip 3-9 String NO YES buyer’s zip
ch_country 2-3 String NO YES buyer’s country in alpha2, alpha3 letter code or 3 digit ISO numeric code
ch_phone 3-30 String NO YES buyer’s phone
ch_email 3-100 String NO YES buyer’s email
language predefined String NO YES used for errors localization, possible values are en, es, ba or hr
tokenize_pan_offered predefined boolean NO YES offer the client to tokenize his PAN
tokenize_pan predefined boolean NO YES tokenize PAN when the client enters it
expires_at ISO 8601 date-time String NO YES expiration time, eg: “2021-09-26T07:58:30.996+0200”
success_url_override predefined String NO YES Your custom success URL
cancel_url_override predefined String NO YES Your custom cancel URL
callback_url_override predefined String NO YES Your callback URL
Supported payment methods

supported_payment_methods in an array of valid payment methods

Valid payment method is:

Functionality:

Request body example

{
  "transaction_type": "purchase",
  "amount": 30,
  "currency": "BAM",
  "number_of_installments": "",
  "order_number": "6638614b544b7058414b5467304146574c647841",
  "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",
    "card"
  ],
  "success_url_override:" : "https://webpage.com/success",
  "cancel_url_override" : "https://webpage.com/cancel",
  "callback_url_override" : "https://webpage.com/callback"
}

Response

field length type description
status enum String buyer’s full name
id 1-11 Integer Resource id
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)
order_number 2-40 String Unique order identifier
transaction_type enum String possible values are: authorize or purchase
order_info 3-100 String Short description of order being processed
number_of_installments 1-2 Integer range 2-12
ch_address 3-100 String buyer’s address
ch_city 3-30 String buyer’s city
ch_zip 3-9 String buyer’s zip
ch_country 2-3 String buyer’s country in alpha2, alpha3 letter code or 3 digit ISO numeric code
ch_phone 3-30 String buyer’s phone
ch_email 3-100 String buyer’s email
language predefined String used for errors localization, possible values are en, es, ba or hr
payment_url predefined String Order’s link, send this url to the buyer/customer
terminal_entry_status enum String pending if not charged*, approved if charged*, expired if entry is no longer active
created_at predefined DateTime ISO UTC timestamp
updated_at predefined DateTime ISO UTC timestamp
supported_payment_methods predefined Array<String> An array of payment methods. An empty array if none provided.
tokenize_pan_offered predefined boolean offer the client to tokenize his PAN
tokenize_pan predefined boolean tokenize PAN when the client enters it
expires_at ISO 8601 date-time String expiration time, eg: “2021-09-26T07:58:30.996+0200”

Example of response:


{
   "status":"approved",
   "id":1,
   "transaction_type":"purchase",
   "number_of_installments":null,
   "amount":100,
   "currency":"HRK",
   "language":"en",
   "order_number":"6638614b544b7058414b5467304146574c647841",
   "order_info":"Test trx",
   "ch_full_name":"Test",
   "ch_address":"Test",
   "ch_city":"Test",
   "ch_zip":"Test",
   "ch_country":"BIH",
   "ch_phone":"061 000 000",
   "ch_email":"[email protected]",
   "terminal_entry_status":"pending",
   "comment":null,
   "created_at":"2019-02-12 11:22:33 UTC",
   "updated_at":"2019-02-12 11:22:33 UTC",
   "moto":false,
   "force_cc_type":false,
   "payment_url":"http://127.0.0.1:31337/v2/order/6638614b544b7058414b5467304146574c647841",
   "supported_payment_methods":[],
   "tokenize_pan": false,
   "tokenize_pan_offered": false
}

Show

To retrieve previously created PayByLink you’ll need to provide:

Request

name value description
base_url ipgtest.monri.com or ipg.monri.com Parametrize this value
path /v2/terminal-entry/<order-number>/show order-number of previously created resource
method GET We are retrieving resource, hence GET

Response

Response is same as create-or-update response, only difference is status which is always approved (if request is valid).

Deactivate / Activate

To deactivate/activate previously created PayByLink you’ll need to provide:

Request

name value description
base_url ipgtest.monri.com or ipg.monri.com Parametrize this value
path /v2/terminal-entry/create-or-update This path is used for both create and update action
method POST We are updating resource, hence POST method

Response

Response is same as create-or-update response. Active field shows current status.