WebPay

Payment API, version 21.02.2022

Versions

21.02.2022

30.11.2021

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

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:

{
  "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 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) 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."
}

Create Payment

Request

To create a Payment you’ll need to provide:

Request endpoint details

name value description
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, HRK, 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_methods predefined Array<String> NO An array of pan-tokens and/or card (see below for more details)
customer_uuid new 20 String NO An id of a customer. Check documentation how to create a customer.
success_url_override predefined valid HTTPS URL NO Provide this value if you want to override success URL
cancel_url_override predefined valid HTTPS URL NO Provide this value if you want to override cancel URL
callback_url_override predefined valid HTTPS URL NO Provide this value if you want to override callback URL

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.
----------------------------------------------
WARNING - add_payment_method scenario will automatically execute refund or void depending on transaction type. ONLY use for saving cards.
----------------------------------------------

Supported payment methods

supported_payment_methods in an array of valid payment methods.

Valid payment methods are:

Requirements / options:

Example of valid payment methods:

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

Setup above will result in:

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:

Request

name value description
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, HRK, 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"
}