Pay By Link API

Requests

Documentation below describes:

api url values
required headers
authentication header

Api URL

environment

value

NOTE Parametrize api url value.

Headers

name

value

description

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:

merchant_key (available on merchant’s dashboard)
authenticity_token (available on merchant’s dashboard)

Authorization header for GET|POST request is created from:

Digest generation

Digest example

If we have:

url: https://ipgtest.monri.com/v2/terminal-entry/create-or-update
method: POST
fullpath is then: /v2/terminal-entry/create-or-update
merchant_key: qwert1234
timestamp: 1593457122
authenticity_token: 7db11ea5d4a1af32421b564c79b946d1ead3daf0
body:

{"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":"john.doe@email.com","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":"john.doe@email.com","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":"john.doe@email.com","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 field is always in response and has values:

If response code is 2**: Request is accepted and processed, response is returned
If response code is 401: Authorization failed, there's probably an issue with Authorization header
If response code is 400: Request processing failure, eg. attempted to create resource with invalid amount

Valid (approved, created, updated) response

Example of valid response:

{
   "status":"approved",
   "id":1,
   "transaction_type":"purchase",
   "number_of_installments":null,
   "amount":100,
   "currency":"EUR",
   "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":"test@test.com",
   "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:

Valid Authorization header (see above how to create one)
Required fields (described below)

Request endpoint details

Request body:

Supported payment methods

supported_payment_methods in an array of valid payment methods

Valid payment method is:

pan token - Secure Vault Tokens.
or a card

Functionality:

If saved card is provided and valid (card(s) not expired, valid token(s) etc) then only cvv input will be shown on the payment form.
All other information (masked pan, expiry date etc) will be pre filled.
Multiple tokens can be sent. In that case, the user will have an option which card to use.
It's possible to send card payment method which will offer payment with a new card to the buyer

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": "john.doe@email.com",
  "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

CHARGED there's approved transaction authorization for order_number, with transaction_type authorize or purchase
NOT CHARGED there's no approved transaction authorization, with transaction_type authorize or purchase for order_number

Example of response:

{
   "status":"approved",
   "id":1,
   "transaction_type":"purchase",
   "number_of_installments":null,
   "amount":100,
   "currency":"EUR",
   "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":"test@test.com",
   "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:

Valid Authorization header (see above how to create one)
Create resource beforehand
Provide valid resource order-number

Request

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:

Valid Authorization header (see above how to create one)
Create resource beforehand
Provide expires_at

Request

Response

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

PreviousPayment API NextPayment Method API

Last updated 6 months ago