Payment Method 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

body

<body>

Empty string if GET request, request body if POST request

Digest example

If we have:

  • url: https://ipgtest.monri.com/v2/payment/new

  • method: POST

  • fullpath is then: /v2/payment/new

  • 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/payment/new`
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/payment/new{"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) 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:

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

  • card - representing new card

  • <pan_token> - secure vault token - Secure Vault Tokens

Requirements / options:

  • If payment method card is provided then user will be able to enter new card instead of selecting one of saved cards

    • User must enter card number

    • Expiry date

    • Cvv

  • If payment method <pan_token> is provided provided and valid(cards not expired, valid tokens etc)

    • Then only cvv input will be updaten 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.

Example of valid payment methods:

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

Setup above will result in:

  • preselected saved card with token f167252fecfeff8f134001bf8e7a700c53e8653f631362dd84913e23260199bf

  • with an option to select card with token 0df5d4eac4f36d0dee9f48c17ddac2f66c12e5edfc4f92a92d3e6085f31368ea

  • with an option to enter new card

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:

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

  • Create resource beforehand

  • Provide valid resource id

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, 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"
}
PreviousPay By Link APINextToken API

Last updated