WebPay

Customers API, version 22.03.2022

Versions

22.03.2022

21.02.2022

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

Request

To create a Customer you’ll need to provide:

Request endpoint details

name value description
path v2/customers This path is used for create action
method POST We are creating resource, hence POST method

Request body:

field length type required description
merchant_customer_id 1-100 String NO Merchant’s customer id
description 1-200 String NO The Customer description
email 1-200 String NO Customer’s email address.
name 1-50 String NO Customer’s full name or business name.
phone 1-30 String NO Customer’s phone
metadata predefined Dictionary NO Set of key-value pairs. Useful for storing additional data about the object
zip_code 1-9 String NO Customer’s ZIP or postal code.
city 3-30 String NO Customer’s city, district, suburb, town, or village.
address 3-100 String NO Customer’s address
country 2 String NO Two-letter country code, see ISO 3166-1 alpha-2

Response

field length type description
status enum String approved, invalid-request or error
uuid predefined String Customer’s uuid - use this value for operations with customer
merchant_customer_id 100 String Merchant’s customer id
description 1-200 String The Customer description
email 1-200 String Customer’s email address.
name 1-50 String Customer’s full name
phone 1-30 String Customer’s phone
metadata predefined Dictionary Set of key-value pairs. Useful for storing additional data about the object
zip_code 1-9 String Customer’s ZIP or postal code.
city 3-30 String Customer’s city
address 3-100 String Customer’s address
country 2 String Two-letter country code, see ISO 3166-1 alpha-2
deleted predefined Boolean True if customer is deleted
created_at predefined DateTime Created at
updated_at predefined DateTime Created at
deleted_at predefined DateTime Nullable, set if customer is deleted

Example of response:


{
  "uuid": "4b281da4-d145-4233-b957-2018cf9aa0fb",
  "merchant_customer_id": "customer-id-1234",
  "description": "Customer",
  "email": "[email protected]",
  "name": "Test",
  "phone": null,
  "status": "approved",
  "deleted": false,
  "city": null,
  "country": "BA",
  "zip_code": "71000",
  "address": null,
  "metadata": {
    "key": "value"
  },
  "created_at": "2019-02-12T11:22:33Z",
  "updated_at": "2019-02-12T11:22:33Z",
  "deleted_at": null
}

Retrieve a customer

To retrieve previously created customer you’ll need to provide:

Request

name value description
path /v2/customers/:uuid uuid of previously created resource
method GET  

Response

Response is the same as the one for create

Retrieve a customer via merchant_customer_id

To retrieve previously created customer you’ll need to provide:

Request

name value description
path /v2/merchants/customers/:merchant_customer_id merchant_customer_id of previously created resource
method GET  

Response

Response is the same as the one for create

Update a customer

To update previously created customer you’ll need to provide:

Request

name value description
path /v2/customers/:uuid uuid of previously created resource
method POST We are updating resource, hence POST method

Request body:

Response

Response is the same as the one for create

Delete a customer

To delete previously created customer you’ll need to provide:

Request

name value description
path /v2/customers/:uuid uuid of previously created resource
method DELETE  

Response

field length type description
status enum String approved, invalid-request or error
id 20 String Customer’s id
deleted predefined Boolean True if customer is deleted

Example of response:


{
  "status": "approved",
  "id": "4b281da4-d145-4233-b957-2018cf9aa0fb",
  "deleted": true
}

List all customers

To list previously created customers you’ll need to provide:

Request

name value description
path /v2/customers uuid of previously created resource
method GET We are retrieving resources, thus GET
query limit Limit number of objects listed, default limit is 50. Must be valid number.
query offset If you need to skip values set offset to non 0 value, objects are sorted by created_at DESC. Must be valid number.

Response

field length type description          
status enum String approved, invalid-request or error   data 20 Array<Dictionary> An array of customers
                  
{
  "status": "approved",
  "data": [
    {
      "id": "4b281da4-d145-4233-b957-2018cf9aa0fb",
      "description": "Customer",
      "email": "[email protected]",
      "name": "Test",
      "phone": null,
      "status": "approved",
      "deleted": false,
      "city": null,
      "country": "BA",
      "zip_code": "71000",
      "address": null,
      "metadata": {
        "key": "value"
      },
      "created_at": "2019-02-12T11:22:33Z",
      "updated_at": "2019-02-12T11:22:33Z",
      "deleted_at": null
    }
  ]
}

List all payment methods

To list previously created customers you’ll need to provide:

Request

name value description
path /v2/customers/:uuid/payment-methods uuid of previously created resource
method GET We are retrieving resources, thus GET
query limit Limit number of objects listed, default limit is 50. Must be valid number.
query offset If you need to skip values set offset to non 0 value, objects are sorted by created_at DESC. Must be valid number.

Response

field length type description
status enum String approved, invalid-request or error
data 20 Array<Dictionary> An array of customers 
{
  "status": "approved",
  "data": [
    {
      "status": "approved",
      "id": "00c1eb1a4a0b61d1c2921c8d3a3f4570801da3f3f087c280e832cb4876a5e633",
      "masked_pan": "405840******0005",
      "expiration_date": "2025-12-31",
      "keep_until": "2024-12-31T23:00:00Z",
      "created_at": "2019-02-12T11:22:33Z",
      "updated_at": "2019-02-12T11:22:33Z",
      "customer_uuid": "4b281da4-d145-4233-b957-2018cf9aa0fb",
      "token": "00c1eb1a4a0b61d1c2921c8d3a3f4570801da3f3f087c280e832cb4876a5e633",
      "expired": false
    }
  ]
}