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

Python

import urllib.request

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

password_mgr = urllib.request.HTTPPasswordMgrWithDefaultRealm()
password_mgr.add_password(None, HOST, USER, PASS)
auth_handler = urllib.request.HTTPBasicAuthHandler(password_mgr)
opener = urllib.request.build_opener(auth_handler)
urllib.request.install_opener(opener)

o = urllib.request.urlopen(URL)
print(o.read())
C#
using System;
using System.IO;
using System.Net;
using System.Text;

class AuthExample
{
    static void Main(string[] args)
    {
        var host = "https://testbox.monetra.com";
        var url = "https://testbox.monetra.com/api/v1/report/failed";
        var username = "test_retail|public";
        var password = "publ1ct3st";

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

        var cred = new NetworkCredential(username, password);
        var ccache = new CredentialCache();
        ccache.Add(new Uri(host), "Basic", cred);

        var request = WebRequest.Create(url);
        request.Credentials = ccache;

        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());
                }
            }
        }
    }
}
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

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

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

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":
    {
    },
  • "lodging":
    {
    },
  • "order":
    {
    },
  • "shipping":
    {
    },
  • "lane":
    {
    },
  • "property1": "string",
  • "property2": "string"
}

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",
  • "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",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_form_factor": "rcpt_emv_form_factor",
  • "msoft_code": "INT_SUCCESS",
  • "card_msr_cvm": "sig",
  • "verbiage": "Transaction approved",
  • "ttid": "ttid",
  • "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",
  • "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 Card Type

Performs a real-time card type lookup against the system's current BIN table

The Card Type request should be used when you need to know (in advance of a financial request) what type of card is being presented. It is particularly useful for integrated systems (such as POS or E-commerce) which do not maintain their own internal BIN table(s).

Note: When a Global BIN file is configured, extended metadata may be returned. Any fields returned will be dependent on both relevance and/or if the particular field has been recorded on file.

Authorizations:
Request Body schema: application/json
account_data
object (_transaction_cardtype_account_data)

Account information parameters

There are multiple ways to collect the customer's account information. These are the minimum fields required for each entry method.

  • Chip card
    • icc
  • Swipe
    • trackdata
  • Keyed
    • account
    • expdate
  • Bank account
    • account
    • abaroute
    • accounttype
    • cardholdername
  • Check
    • account
    • abaroute
    • checknum
  • Ticket
    • cardshieldticket
  • Token
    • token

Additional modifiers are also present which can provide informations about how the data was received. For example, Cards and phones can be tapped in which case the rfid modifier need to be sent as yes to indicate the data was accepted by this entry method. Keyed can be marked as one of the cardpresent acceptance types to specify the circumstances of the keyed entry.

ENCRYPTION

Many of these can be sent encrypted when using an encrypting reader with a supported encryption method. The e_* fields are used with encrypted account data and either are sent in addition to or in place of the listed fields. Typically, integrators do not directly work with encrypting readers and instead use UniTerm for device integration.

Due to the difference in encrypted reader output and some formats being proprietary limited information about the encrypted account fields are provided. If it is necessary to directly send encrypted reader data to Monetra please contact support who can work with you and the device manufacturer on how to format the data for the relevant fields to a given device.

tokenize
string
Default: "no"
Enum: "yes" "no"

Whether or not the account data should be tokenized as part of this request.

Defaults to no if not present.

The token will be of type store which allows use with future financial transactions.

When enabled, by default, this will generate a new token. If matching_token is enabled, the behavior changes to attempt to return an existing token for the account before creating a new token.

Values:

  • yes - Turn the account data into a stored token
  • no - Do not turn the account data into a stored token
matching_token
string
Default: "no"
Enum: "yes" "no"

When paired with tokenize, Monetra will attempt to return an existing token for the account.

By default, every tokenization will generate a new token. Sending matching_token=yes changes the behavior to search for existing tokens for this account. If present, the existing token will be returned. If not present, a new token will be created. If multiple tokens for the same account are present, it is undefined which will be returned.

Values:

  • yes - Return existing token matching this account number
  • no - Do not return existing token matching this account number

Responses

200

processed operation

post /transaction/cardtype

Test server

https://testbox.monetra.com/api/v1/transaction/cardtype

Request samples