Overview

This API utilizes robust key/value pairs for flexibility. To make transport easier, all pairs are comprised of strings.

Parameter Groups

Internally, all keys are a flat list and are not hierarchical. Throughout the documentation, parameters may be grouped together under a named object. The object name is not evaluated when processing the request. All key/value pairs are moved to the top level.

Parameter grouping is present simply to make it easier to understand the relationship between parameters. The parameters themselves do not need to be part of the documented object they may be under.

Time Formats

A value denoting a time can take on one of two different types:

  • formatted time
  • Unix timestamp

Formatted

Formatted times can either be a fixed time or based on an offset. The time zone for the date is the merchant's timezone.

Fixed

Fixed formats are very similar to written dates and times.

Formats:

  • YYYY-MM-DD
  • YYYY/MM/DD
  • YYYY-MM-DD hh:mm
  • YYYY-MM-DD hh-mm
  • YYYY/MM/DD hh:mm
  • YYYY/MM/DD hh-mm
  • YYYY-MM-DD hh:mm:ss
  • YYYY-MM-DD hh-mm-ss
  • YYYY/MM/DD hh:mm:ss
  • YYYY/MM/DD hh-mm-ss
  • MM-DD-YYYY
  • MM/DD/YYYY
  • MM-DD-YYYY hh:mm
  • MM-DD-YYYY hh-mm
  • MM/DD/YYYY hh:mm
  • MM/DD/YYYY hh-mm
  • MM-DD-YYYY hh:mm:ss
  • MM-DD-YYYY hh-mm-ss
  • MM/DD/YYYY hh:mm:ss
  • MM/DD/YYYY hh-mm-ss
  • MM-DD-YY
  • MM/DD/YY
  • MM-DD-YY hh:mm
  • MM-DD-YY hh-mm
  • MM/DD/YY hh:mm
  • MM/DD/YY hh-mm
  • MM-DD-YY hh:mm:ss
  • MM-DD-YY hh-mm-ss
  • MM/DD/YY hh:mm:ss
  • MM/DD/YY hh-mm-ss
  • MMDDYYYY
  • MMDDYY

Offset

Offsets take this format:

+ or -
  magnitude
  space
  modifier

Modifiers:

  • year[s]
  • month[s]
  • week[s]
  • day[s]
  • hour[s]
  • min[s|ute|utes]
  • sec[s|ond|onds]

Example

+1 day
-5 years

Special keywords

  • now - current date/time
  • epoch - Unix timestamp of 0 = Jan 1, 1970 00:00:00 UTC

Unix Timestamp

Any keys that end with _ts, such as last_modified_ts, are a Unix timestamp. A Unix timestamp is the number of seconds since Jan 1, 1970 00:00:00 UTC. That date and time is called the "epoch", and its value is 0.

Unix timestamps are always in UTC time and do not have a time zone.

Test Server

A test server with a public test account is provided to help integrators quickly get started.

Server: https://testbox.monetra.com Username: test_retail:public Password: publ1ct3st

If a private test account is needed please contact us.

Authentication

Only HTTP Basic authentication is currently supported.

The Monetra username and password for the account setup to run transactions is used with this authentication method.

basic_auth

Security scheme type: HTTP
HTTP Authorization Scheme basic

Basic Authentication

HTTP Basic Authentication involves sending the Authorization HTTP header with the type Basic and the base64 encoded username:password.

E.g.

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

If the authorization data is not present the response code 401 and WWW-Authenticate header is returned in the response indicating the authentication that must be used.

WWW-Authenticate: Basic realm="Payment Server Resource"

Colon escaping

Basic auth does not allow colons (':') to be present in usernames. However, most usernames for the system will include a colon. To deal with this, all colons must be replaced with a pipe ('|').

If a username contains a pipe, please contact support.

user:sub -> user|sub

For example, take the username test_retail:public and a password of publ1ct3st. Therefore, the username must be transformed to test_retail|public, resulting in basic authentication data to be encoded of test_retail|public:publ1ct3st. The resulting Authentication header data would be Authorization: Basic dGVzdF9yZXRhaWx8cHVibGljOnB1YmwxY3Qzc3Q=

Programming language examples

We do not recommend using most programming language's build in credential management APIs. Such as .Net's HTTPPasswordMgrWithDefaultRealm with a HTTPBasicAuthHandler object. Or Python's NetworkCredential with the CredentialCache. Instead we recommend sending the authorization data directly/explicitly in the request header.

Using the language API credential management can increase the transaction processing time. Many language APIs will first send the request without authorization data. The server will respond with a 401 authorization data required response. The request will be sent a second time with the authorization data. The extra request that is known to fail adds additional and unnecessary, messaging which increases request processing time.

Python

import urllib.request

URL = 'https://testbox.monetra.com/api/v1/report/failed'
USER = 'test_retail|public'
PASS = 'publ1ct3st'

auth_data = '%s:%s' % (USER, PASS)
auth_data = base64.b64encode(auth_data.encode()).decode('utf-8')
headers = {
    'Authorization': 'Basic %s' % auth_data
}

req = urllib.request.Request(URL, headers=headers)
with urllib.request.urlopen(req) as o:
    print(o.read().decode('utf-8'))
C#
using System;
using System.IO;
using System.Net;
using System.Text;

class AuthExample
{
    static void Main(string[] args)
    {
        var url      = "https://testbox.monetra.com/api/v1/report/failed";
        var username = "test_retail|public";
        var password = "publ1ct3st";
        var authData = System.Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(username + ":" + password));
        // var json = 'json data to post'

        ServicePointManager.Expect100Continue = false;
        ServicePointManager.UseNagleAlgorithm = true;
        ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;

        var request = WebRequest.Create(url);
        request.Method = "GET";
        request.Headers.Add("Authorization", "Basic " + authData);
        // # For POST
        //   request.ContentType   = "application/json";
        // # 'json' contains data to post
        //   request.ContentLength = json.Length;
        //   Stream requestStream  = request.GetRequestStream();
        //   requestStream.Write(Encoding.ASCII.GetBytes(json), 0, json.Length);
        //   requestStream.Close();

        using (var response = (HttpWebResponse)request.GetResponse()) {
            Console.WriteLine(response.StatusDescription);

            using (var dataStream = response.GetResponseStream()) {
                using (var reader = new StreamReader(dataStream)) {
                    Console.WriteLine(reader.ReadToEnd());
                }
            }
        }
    }
}

Using the language API credential management increase the transaction processing time. Using the language API will first send the request without authorization data. The server will respond with a 401 authorization data required response. The request will be sent a second time with the authorization data. The extra request that is known to fail adds additional and unnecessary, messaging which increases request processing time.

PHP
<?php
$url = "https://testbox.monetra.com/api/v1/report/failed";
$username = "test_retail|public";
$password = "publ1ct3st";
$opts = array(
  "http"=>array(
    "method"=>"GET",
    "header" => "Authorization: Basic " . base64_encode("$username:$password")
  ),
);
$context = stream_context_create($opts);
$file = file_get_contents($url, false, $context);
echo $file;
?>

Transaction

Transaction operations

Reverse Transaction

Removes a previously authorized transaction in real time

The hold from the authorization will be removed from the customer's account.

Some card brands allow partial reversals where only part of the hold, not the entire transaction, is removed. This is beneficial in some industries such as E-commerce where an order might be changed before the transaction is completed.

Authorizations:
path Parameters
ttid
required
string

Transaction identifier

query Parameters
amount
string
Example: amount=19.92

The final amount to be settled, NOT the amount to be reversed.

Responses

200

processed operation

delete /transaction/{ttid}

Test server

https://testbox.monetra.com/api/v1/transaction/{ttid}

Request samples

Copy
curl -X DELETE 'https://testbox.monetra.com/api/v1/transaction/926573735405091' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "rcpt_emv_aid": "rcpt_emv_aid",
  • "card_fsa": "Y",
  • "code": "AUTH",
  • "phard_code": "SUCCESS",
  • "auth": "auth",
  • "rcpt_emv_pinbypass": "Y",
  • "rcpt_emv_actype": "AAC",
  • "rcpt_custom": "rcpt_custom",
  • "rcpt_emv_name": "rcpt_emv_name",
  • "rcpt_emv_ac": "rcpt_emv_ac",
  • "language": "en",
  • "rcpt_emv_tsi": "rcpt_emv_tsi",
  • "card_cardclass": "CREDIT",
  • "card_debit_network": "card_debit_network",
  • "rcpt_host_ts": "rcpt_host_ts",
  • "rcpt_emv_iad": "rcpt_emv_iad",
  • "card_currency": "card_currency",
  • "rcpt_entry_mode": "G",
  • "cardholdername": "John Doe",
  • "card_prepaidcard": "Y",
  • "cardtype": "VISA",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_card_decline": "rcpt_emv_card_decline",
  • "timestamp": "timestamp",
  • "card_token_card": "Y",
  • "item": "item",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_form_factor": "rcpt_emv_form_factor",
  • "issuer_decline": "Y",
  • "batch": "batch",
  • "msoft_code": "INT_SUCCESS",
  • "card_msr_cvm": "sig",
  • "verbiage": "Transaction approved",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "card_issuer_bank",
  • "card_country_code": "card_country_code",
  • "rcpt_emv_tvr": "rcpt_emv_tvr",
  • "card_cardlevel": "card_cardlevel",
  • "card_reloadable": "Y",
  • "stan": "stan",
  • "pclevel": "0",
  • "card_signature_debit": "Y",
  • "rcpt_resp_code": "rcpt_resp_code",
  • "printdata": "printdata",
  • "rcpt_issuer_resp_code": "rcpt_issuer_resp_code",
  • "account": "XXXXXXXXXXXX1234"
}

Get Transaction Details

Gets fine-grained detail about a transaction

Includes all the fields returned from an original transaction response, as well as non-sensitive request data. Additionally, metadata about the transaction state is also returned. The result data is very verbose, and only fields that are relevant to making this call should be evaluated.

The most common use for this operation is re-printing receipts. All data needed for receipts is returned as part of this request. Sending the rcpt parameter will allow for formatted receipt data to also be returned.

Authorizations:
path Parameters
ttid
required
string

Transaction identifier

query Parameters
rcpt
string
Example: rcpt=yes

The rcpt key/value pair is sent in the request to indicate whether or not to output a series of pre-formatted receipt blocks, as well as optional formatting requirements.

A value of no (the default) will not return a receipt.

A value of yes will return a receipt with a default format.

All other values are key/value pairs indicating formatting configurations, separated by semicolons, as in this example:

rcpt=type=plain;line_len=24;use_merch_lang=no;line_break="\n"

rcpt=type=plain|html

Receipt configuration options:

  • type - Values can be specified pipe-delimited (|) if more than one receipt output format is desired. When specifying more than one type, the response keys will indicate the format in the key name, but if only one type is specified, the type is omitted.
    • plain - Plain Text (default).
    • html - HTML. Needs style sheet applied.
    • xml - XML. Suitable for XSLT transformations. Typically used to generate complex HTML when CSS alone is not capable of providing the desired formatting.
    • json - JSON. Typically used for easy manipulation with JavaScript.
  • line_len - Only relevant for type=plain. Number of characters per line. Default is 24.
  • line_break - Only relevant for type=plain. Character sequence for newlines. Default is \r\n.
  • use_merch_lang - True/False. Use the merchant's selected language rather than the cardholder's language for the receipt. Default is True.

Responses

200

processed operation

get /transaction/{ttid}

Test server

https://testbox.monetra.com/api/v1/transaction/{ttid}

Request samples

Copy
curl -X GET 'https://testbox.monetra.com/api/v1/transaction/926572778835889' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "phard_code": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaidcard": "Y",
  • "card_reloadable": "Y",
  • "card_signature_debit": "Y",
  • "card_token_card": "Y",
  • "rcpt_host_ts": "string",
  • "rcpt_entry_mode": "G",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "Y",
  • "rcpt_resp_code": "string",
  • "rcpt_issuer_resp_code": "string",
  • "rcpt_emv_aid": "string",
  • "rcpt_emv_name": "string",
  • "rcpt_emv_tvr": "string",
  • "rcpt_emv_tsi": "string",
  • "rcpt_emv_actype": "AAC",
  • "rcpt_emv_ac": "string",
  • "rcpt_emv_form_factor": "string",
  • "rcpt_custom": "string",
  • "rcpt_emv_iad": "string",
  • "rcpt_emv_card_decline": "string",
  • "printdata": "string",
  • "auth": "string",
  • "batch": "string",
  • "issuer_decline": "Y",
  • "item": "string",
  • "stan": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "abaroute": "string",
  • "checknum": "string",
  • "accounttype": "BUSINESS",
  • "cof_transid": "string",
  • "cof_authamount": "string",
  • "installment_num": "string",
  • "installment_total": "string",
  • "recurring": "recurring",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "shipcountry": "string",
  • "shipzip": "string",
  • "zip": "32606",
  • "action": "string",
  • "orig_code": "string",
  • "orig_msoft_code": "string",
  • "orig_phard_code": "string",
  • "orig_reqamount": "string",
  • "orig_verbiage": "string",
  • "merch_name": "string",
  • "merch_addr1": "string",
  • "merch_addr2": "string",
  • "merch_addr3": "string",
  • "merch_phone": "string",
  • "merch_email": "string",
  • "merch_url": "string",
  • "merch_proc": "string",
  • "custref": "55",
  • "ordernum": "A13DDES345",
  • "ptrannum": "1987",
  • "amount": "19.92",
  • "cashbackamount": "20.00",
  • "currency": "string",
  • "examount": "0.33",
  • "surchargeamount": "1.25",
  • "tax": "1.29",
  • "discountamount": "100.00",
  • "dutyamount": "5.07",
  • "freightamount": "225.82",
  • "bdate": "string",
  • "edate": "string",
  • "excharges": "REST",
  • "rate": "12.00",
  • "roomnum": "string",
  • "descmerch": "string",
  • "descloc": "string",
  • "clerkid": "string",
  • "stationid": "7",
  • "laneid": "4",
  • "comments": "string",
  • "divisionnum": "PAYROLL",
  • "expdate": "0129",
  • "healthcare": "yes",
  • "reversible": "yes",
  • "reversal_reason": "CLERKVOID",
  • "offline_decline": "string",
  • "tranflags": "HASAVS",
  • "txnstatus": "DECLINED",
  • "last_modified_ts": "string",
  • "property1": "string",
  • "property2": "string"
}

Adjust Transaction

Modifies transaction data

This allows adding or modifying transaction parameters after authorization.

Not all parameters are required or known at the time of authorization, and some might change after the authorization is approved. For example, in E-commerce, the customer might change their shipping zip code.

This action can also edit fields that affect interchange rates (e.g tax, rate, and bdate/edate). If an interchange parameter is not known or finalized, it can be added or updated.

This process will only affect those transactions that are currently unsettled. It should be used with captured transactions. This should not be used with preauths that have not been completed. Those transactions should be adjusted when issuing the corresponding preauthcomplete.

When dealing with changes to amounts, it is typically better to use a preauth and preauthcomplete instead of adjusting a sale. WorldPay's 610 platform is a special case where it is better to use sale and adjust.

Authorizations:
path Parameters
ttid
required
string

Transaction identifier

Request Body schema: application/json
money
object

Monetary parameters

lodging
object

Lodging parameters

order
object

Order detail parameters

shipping
object

Shipping detail parameters

lane
object

Merchant lane parameters

property name*
string

Responses

200

processed operation

patch /transaction/{ttid}

Test server

https://testbox.monetra.com/api/v1/transaction/{ttid}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "money":
    {