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

Many operations allow a variety of key value pair parameters in order to perform the given action. All key and values are strings. Even numeric amounts or counts are sent as strings. Response parameter key and values are also strings.

Empty values (key="") are different than omitting a key entirely. Only in very specific situations should an empty value be sent.

An empty value is a valid value. For example, when setting user or merchant parameters empty means clear that parameter. Whereas omitting means do not change. The only time sending an empty value is valid is when intending to clear a stored value.

For a transaction, sending zip="" will result in zip code evaluation and will result in an AVS failure. Due to the zip being present but "" not matching the customers zip code on file with the issuer. Omitting zip entirely will not perform AVS verification.

$0.00 Amounts

Amounts should always be above 0. A value of $0.00 for amount, tax, examount and other monetary parameters should be considered invalid. For example, tax=0.00 indicates the transaction is taxable and but the merchant has opted not to collect tax. This can cause problems for the merchant because it indicates the merchant is not collecting sales tax as required by law. This can result in higher interchange fees.

Some actions allow custom parameters that are not defined by the API. These parameters are defined by the group or merchant. They can not be documented due to this. Operations that allow customer parameters are marked with property. For example in schema it will be listed as property name*. In examples it may be listed as property1, property2 and so forth.

property* is not itself a parameter and should not be sent. It is an indicator that custom parameters that are undocumented are supported by a given operation.

Payload Samples

Payload Samples are examples of parameters that could be sent with the operation. They are not meant to be copy and paste payloads.

cURL

cURL Examples are copy and paste examples. However, they may need to be modified slightly. Specifically if they are referencing other data in the system. For example, ttid, order_id, or token. These may not existing in the test account and are placeholder values that would need to be replaces with real values from the test account.

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.

With ReST HTTP response codes are used to determine the outcome of an operation.

• 200 - processed operation
• 304 - no change
• 400 - bad data
• 401 - must authenticate
• 402 - payment declined
• 403 - forbidden
• 404 - record not found
• 405 - not allowed
• 415 - setup error
• 423 - resource locked
• 429 - too many attempts
• 451 - licensing
• 500 - system failure
• 503 - system not available
• 504 - timeout

For financial transactions 200 means approved, 402 means declined by the processor, issuer, or Monetra based on merchant configuration (for example, fraud detection rules). A code other than these indicates a decline by Monetra.

The code, msoft_code and phard_code response keys can be used to obtain more information about an operation's result.

code is the overall disposition of the transaction. This is reflected in the http response code when using ReST. code may not always be present in a response. For example, a report will not return code and instead the report data. It is not wrong for an integration to check code it is typically used by non-ReST integrations that do not have something like an HTTP response code. For example, libMonetra uses code and for reports the presence of CSV, JSON, or bulk data to determine the disposition of the operation.

msoft_code is an internal code for Monetra. It can be determined if a decline is from Monetra if msoft_code is anything other than SUCCESS.

When a transaction goes online to a processor a phard_code will be returned in the response. A phard_code is the response reason from the processor. When this is anything other than SUCCESS the processor has returned a decline. Either from themselves or from the issue.

Reports will not include code on success. The HTTP response code needs to be used to determine if the report was successful. If the not sucessfull (any repsonse other than 200) key value pairs will be returend instead of the report output. The following two keys will always be returned but additonal can appear too.

• code
• verbiage

Specific reports, ones where an id is specified to get information about a specific entry, will also not return code. code could be reservered for the report and thus may have a different meaning than the action disposition.

libMonetra

libMonetra also does not return code when generating reports. Due to libMonetra not using HTTP an HTTP resposne code cannot be returned. In this situation success can be determiend by the presence of CSV (or JSON) data. Otherwise, if key value pairs are present, there was a failure.

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

• formatted time
• Unix timestamp

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
• BOD - Beginning of the current day
• EOD - End of the current day

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.

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.

API Keys and HTTP Basic authentication are currently supported.

An API key ID and secret need to be generated to use API keys.

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

API keys are composed of two parts. A public key id and a private key secret. The key secret must be protected by the integrator. Keys can represent a user or profile. It is recommended to create a profile key for unattended POS systems so the keys are not invalided if a user leaves.

These allow users to disassociate their username and password from authentication. They will be able to manage and revoke keys in case an application (POS) is compromised. Also, integrated applications will be able to request a key instead of storing the user's username and password. Finally, the POST protocol will use this key instead of the user's password for HMAC.

API Key information is passed in the following headers when using ReST:

• X-API-KEY-ID: <key id>
• X-API-KEY: <key secret>

If using the libmonetra key value pair protocol, api keys use these fields:

• auth_apikey_id
• auth_apikey_secret

Programming language examples

Python

import urllib.request
import base64

URL = 'https://testbox.monetra.com/api/v2/report/failed'
KEY_ID = 'P0055817F457C3AFE'
KEY_SECRET = 'bpWBB75zuW1sD6U4wJAzWDl9CAzoqJ/q1a5RnOHgShE='

headers = {
    'X-API-KEY-ID': KEY_ID,
    'X-API-KEY': KEY_SECRET,
}

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/v2/report/failed";
        var key_id     = "P0055817F457C3AFE";
        var key_secret = "bpWBB75zuW1sD6U4wJAzWDl9CAzoqJ/q1a5RnOHgShE=";
        // 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("X-API-KEY-ID", key_id);
        request.Headers.Add("X-API-KEY", key_secret);
        // # 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());
                }
            }
        }
    }
}

PHP

<?php
$url = "https://testbox.monetra.com/api/v2/report/failed";
$key_id = "P0055817F457C3AFE";
$key_secret = "bpWBB75zuW1sD6U4wJAzWDl9CAzoqJ/q1a5RnOHgShE=";
$opts = array(
  "http"=>array(
    "method"=>"GET",
    "header" => "X-API-KEY-ID:" . $key_id . "\r\n" . "X-API-KEY: " . $key_secret . "\r\n"
  ),
);
$context = stream_context_create($opts);
$file = file_get_contents($url, false, $context);
echo $file;
?>

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, it's valid for usernames to have been created with a colon (':'). If colons (':') are present they need to be replaced with a pipe ('|').

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 built-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
import base64

URL = 'https://testbox.monetra.com/api/v2/report/failed'
USER = 'test_retail'
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/v2/report/failed";
        var username = "test_retail";
        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());
                }
            }
        }
    }
}

PHP

<?php
$url = "https://testbox.monetra.com/api/v2/report/failed";
$username = "test_retail";
$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;
?>

Dual authentication requires two user's to authorize the action to take place. Dual authentication requires the username, and password for each user. API keys cannot be used. Additionally if MFA is enabled for a user, the MFA code must be sent. MFA cookies cannot be used.

With the LibMonetra protocol the keys user and pwd are used to specify the authentication information for the dual control user. For REST the dual user's username and password is encoded using HTTP Basic authorization and placed in the X-DUAL-Authorization header. E.g. X-DUAL-Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=.

For the MFA code in the LibMonetra protocol it is placed in the mfa_code_dual key. For REST the MFA code is placed in the X-DUAL-MFA-CODE header.

The users must be different.

When Multi Factor Authentication is in use the mfa_code needs to be sent with the request. With the LibMonetra protocol it would be placed in the mfa_code key value pair. For REST it cannot be sent here due to GET actions not having a body.

Instead the MFA code needs to be sent in the header X-MFA-CODE. Where the value is the MFA code.

MFA supports MFA "cookies" which allow a long lived code to be cached and reused. See "Generate Multi Factor Authentication Cookie" for additional information.

Gift routes will use the default bin range for the provider. However, merchants may have cards that fall into a different bin range. It is possible to define a custom bin range to handle these situations.

BIN ranges are specified using a formula that details exactly what values are allowed. An individual range is specified using this formula:

min_prefix[-max_prefix][:min_len[-max_len][:cardtype[:pclevel]]]

Multiple ranges are joined together with semicolons (;).

Example ranges:

Interchange fees are transaction processing fees that are typically a percentage of the transaction amount. These fees are set by the card brands and are separate from provider (gateway, processor, POS, other services, etc) fees.

Interchange rates are typically disclosed as a percentage range and vary between brands. Some providers will offer a "blended rate" which is a flat rate for all transactions across all brands. This is can be advantageous because merchants will have a known cost for every transaction. However, the blended rate typically works out to be higher than a non-blended rate. Due to the blended rate typically having a higher average cost to facilitate the provider offering the service.

Interchange rates are calculated using a number of factors. Some examples of which are:

• Card brand
• Card brand's card sub type
• Merchant industry and MCC code within a given industry
• Account entry method. E.g. contact EMV, contactless EMV, swipe, keyed, token, etc.
• Information provided with the transaction, such as zip code.
• Transaction type
• Credit vs debit, vs prepaid
• The card issuer
• Whether the card is level 2 capable and if level 2 data was sent
• Whether the card is level 3 capable and if level 3 data was sent
• Tax information
• Transaction amount

Some data is only used for interchange in some situations. For example, zip code will impact interchange rates for card not present transaction but should not for card present. Level 2 and level 3 data will only impact rates of the card is level 2 or level 3 capable.

Additionally, rates could be impacted by use of other services that are related to the transaction. In e-commerce use of 3D Secure data from a 3D Secure provider could impact interchange rates. However, 3D Secure services themselves have a fee.

Interchange rates can only be calculated on a per transaction basis due to the large number of factors that go into calculating the rate for a specific transaction. There is no way to know beforehand and it is difficult to estimate costs. It is typically recommended that merchants use the maximum possible interchange cost for instal calculations and use historic fee amounts after in order to estimate general interchange costs.

Note, this is an API guide and not an interchange qualification guide. It does not cover in detail how and when certain API fields will impact interchange rates. Questions regarding actual interchange fees should be directed to the merchant's processor.

Transaction operations