Pay By Link API

Requests

Documentation below describes:

  • api url values

  • required headers

  • authentication header

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:

  • merchant_key (available on merchant’s dashboard)

  • authenticity_token (available on merchant’s dashboard)

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:

  • 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:

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

  • 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

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, 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:

  • 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

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, 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"

  • 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

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:

  • Valid Authorization header (see above how to create one)

  • Create resource beforehand

  • Provide expires_at

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.

PreviousPayment APINextPayment Method API

Last updated