WebPay

Transactions API

Variables - names, lengths and formats

Here are the variables and their definitions used when generating JSON documents for API calls:

Buyer’s profile

name length format additional info
ch_full_name 3-30 alphanumeric buyer’s full name
ch_address 3-100 alphanumeric buyer’s address
ch_city 3-30 alphanumeric buyer’s city
ch_zip 3-9 alphanumeric buyer’s zip
ch_country 3-30 alphanumeric buyer’s country
ch_phone 3-30 alphanumeric buyer’s phone
ch_email 3-100 alphanumeric buyer’s email

Card details

name length format additional info
temp_card_id 0-40 alphanumeric value representing tokenized card data - value injected in merchants form as monriToken
Optional - pan_token predefined alphanumeric Used with COF Payment / Saved Card Payment

Order details

name length format additional info
order_info 3-100 alphanumeric short description of order being processed
order_number 1-40 alphanumeric unique identifier
amount 3-11 integer amount is in minor units, ie. 10.24 USD is sent as 1024
currency predefined alpha possible values are USD, EUR, BAM or HRK

Processing data

name length format additional info
ip 7-15 alphanumeric valid IPv4 address
language predefined alpha used for errors localization, possible values are en, es, ba or hr
transaction_type predefined alpha possible values are authorize, purchase, capture, refund, void
authenticity_token 40 alphanumeric auto generated value for merchant account, can be found under merchant settings
digest 40 alphanumeric SHA512 hash generated from concatenation of key, order_number, amount and currency as strings; key can be found under merchant settings
number_of_installments 1-2 integer range 2-12
moto predefined boolean possible value is true or false; missing variable is equivalent to false

Transaction messages

Authorization

Authorization is a preferred transaction type for e-commerce. Merchant must capture these transactions within 28 days in order to transfer the money from buyer’s account to his own. This transaction can also be voided if buyer cancel the order. Refund can be done after original authorization is captured.

Below is an JSON example of authorization message in which transaction_type tag has a value authorize. This JSON document is generated according to variable definitions.

Digest is calculated using following formula:

digest = SHA512(key + order_number + amount + currency)

You can check digest on this link Calculate Digest

With the following example data

the digest formula gives a result as follows:

digest = SHA512("qwert123abcdef54321EUR") = "5cb109cd348b74824c29a46fc029b6b7d3fc2c34835b834f276451c8c48c5d921b9a85fa1701ed01d2031b81f998ecbd99707df6e9e0a1087f40f4f82aacf514"

key is a shared secret used to calculate digest value. It is set through merchant interface under API settings of your merchant account.authenticity_token is auto generated value and is copied from merchant account.

NOTICE Client does not send a TID/MID pair in authorization message, those are set in merchant account.

Authorization request example

{
   "transaction":{
      "transaction_type":"authorize",
      "amount":100,
      "ip":"10.1.10.111",
      "order_info":"Monri components trx",
      "ch_address":"Adresa",
      "ch_city":"Grad",
      "ch_country":"BIH",
      "ch_email":"[email protected]",
      "ch_full_name":"Test",
      "ch_phone":"061 000 000",
      "ch_zip":"71000",
      "currency":"BAM",
      "digest":"6af94189788cc073464764c69a9afaea3196bd7ca84b442a76aa141f6b48f8cf323b77aebe0cb72099816e69c08981eccd312ff30d88fa293670a830d78e2466",
      "order_number":"1568236677437",
      "authenticity_token":"6a13d79bde8da9320e88923cb3472fb638619ccb",
      "language":"en"
   }
}

This JSON is now posted to https://ipgtest.monri.com/v2/transaction.

IMPORTANT Parametrize https://ipgtest.monri.com URL, in production mode the subdomain will be different.

If all values pass validations at our side, transaction is send to the bank and response is returned. This response may look like this:

New transaction is generated - 201 Created HTTP status code, and it’s location is set in appropriate HTTP header. A client then must parse a body from HTTP response and extract all values from that JSON document. Transaction is approved only and if only status is set to approved. All other fields are standard data carried over payment networks. If issuer declines a transaction, status flag is set to declined. In a case of an error, the flag will be set to invalid.

IMPORTANT Do not rely on any output variable except status to determine successful of authorization.

IMPORTANT authorize messages won’t be settled unless they are captured within 28 days. After authorization is captured, it can be refunded within 180 days.

NOTICE We highly recommend to our merchants to keep a whole response (this includes HTTP headers and body) and to save all parsed values for easier troubleshooting during the integration phase and production later on. Even if the body is empty, HTTP response code is valuable information; HTTP headers are in the hearth of REST architecture. The quality of our support depends on availability of these information.

In case of invalid request, service will also return a response with 422 Unprocessable Entity HTTP status code and JSON document in its body. Each offended variable will be printed out along with brief explanation what went wrong. That response may look like this:

{
   "errors":[
      "Ch email is invalid"
   ]
}

This invalid request is also recorded and errors are visible through merchant account interface.

List of response codes

Here is the list of response codes and their description