Requirements - API v2

This page is only valid for version 2 of our APIs.

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

  • test merchant account

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

Example of authorization header:

WP3-v2.1 7db11ea5d4a1af32421b564c79b946d1ead3daf0 1593457122 bd120476c656a8ec3ce5d6a150f17061d03a8e280b0fbba278a73a15066830562f73ce5536882c9222e265f1ff6c2df629173375b549cba5a9275b08686f32ea

where:
schema is WP3-v2.1
authenticity-token is 7db11ea5d4a1af32421b564c79b946d1ead3daf0
timestamp is 1593457122
digest is bd120476c656a8ec3ce5d6a150f17061d03a8e280b0fbba278a73a15066830562f73ce5536882c9222e265f1ff6c2df629173375b549cba5a9275b08686f32ea

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:

{
  "example": "1"
}

Then we create digest as:

const crypto = require('crypto');
var fullpath = `/v2/payment/new`
var body = JSON.stringify({
    "example": "1"
})
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{"example":"1"}
var digest = crypto.createHash('sha512')
    .update(merchantKey + timestamp + authenticityToken + fullpath + body)
    .digest('hex');
// we should get bd120476c656a8ec3ce5d6a150f17061d03a8e280b0fbba278a73a15066830562f73ce5536882c9222e265f1ff6c2df629173375b549cba5a9275b08686f32ea

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",
   //...other fields
}

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."
}
PreviousAPI v2NextPayment API

Last updated