logo
Documentation Powered by ReDoc

Monetra - BETA (2.0.0)

Download OpenAPI specification:Download

Technical Support: support@monetra.com URL: https://www.monetra.com/support License: Creative Commons Attribution-NonCommercial-NoDerivs (CC BY-NC-ND) Terms of Service
Developer resources

Overview

BETA Documentation for ReST API version 2. The version 2 API is available for testing now on the tester server. The version 1 API remains will continue to work even after the version 2 API is released to production.

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.

Response Codes

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

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

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.

phard_code

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

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.

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

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.

basic_auth

Security Scheme Type HTTP
HTTP Authorization Scheme basic

apikey_id

Security Scheme Type API Key
Header parameter name: X-API-KEY-ID

apikey

Security Scheme Type API Key
Header parameter name: X-API-KEY

dual_control

Security Scheme Type HTTP
HTTP Authorization Scheme basic

API Key Authentication

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 = 'X123'
KEY_SECRET = 'b64a='

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     = "X123";
        var key_secret = "b64a=";
        // 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 = "X123";
$key_secret = "b64a=";
$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;
?>

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, 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

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.

MFA Code

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.

Transactions

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.

libmonetra KVS equivalent for endpoint

  • action_trans = reversal
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

amount
string
Example: amount=19.92

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

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/transaction/926573735405091' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "timestamp": "string",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "ttid": "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 was not known at time of authorization but is required for settlement the transaction can be modified to add this data. Also, if the parameter was sent during authorization but was not the final value, it can be updated with the final value. For example, adding a tip after the fact to a transaction if it was not sent during authorization. Or changing the tip amount after authorization.

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.

libmonetra KVS equivalent for endpoint

  • action_trans = adjust
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object

Monetary parameters

object

Lodging parameters

object

Order detail parameters

object

Shipping detail parameters

object

Merchant lane parameters

property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "money": {
    },
  • "lodging": {
    },
  • "order": {
    },
  • "shipping": {
    },
  • "lane": {
    },
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "account": "XXXXXXXXXXXX1234",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "timestamp": "string",
  • "ttid": "string"
}

Balance

Balance inquiry

Applies to:

  • Credit
  • Debit
  • Gift

libmonetra KVS equivalent for endpoint

  • action_trans = balanceinq
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object (_vault_account_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
  • Ticket
    • cardshieldticket
  • Token
    • token

Additional modifiers are also present which can provide information about how the data was received. For example, Cards and phones can be tapped in which case the rfid modifier needs 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.

object (_transaction_balance_verification)

Verification parameters

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.

Requires:

  • tokenize

Values:

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

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 40.
  • 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

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "verification": {
    },
  • "tokenize": "yes",
  • "matching_token": "yes",
  • "rcpt": "yes"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "account": "XXXXXXXXXXXX1234",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "balance": "string",
  • "timestamp": "string",
  • "token": "string"
}

Capture

Add an uncaptured sale to a batch

If a sale was sent with capture=no and approved, then a hold has been placed on funds, but the transaction was not added to a batch and is not eligible for settlement. This will add the uncaptured transaction to a batch and make it eligible for settlement.

This is functionally equivalent to a preauthcomplete, except that the original transaction is a sale instead of a preauth.

In the vast majority of cases a preauth and preauthcomplete should be used instead of sale with capture=no followed by the capture action. Only very specific MCCs need to use this functionality. Specifically, businesses that need to hold transaction settlement but are unable to use a preauth for this purpose. Your merchant account provider should have informed you if sale with capture=no is necessary instead of preauth.

Using capture=no outside of MCC's where it's required will not cause processing errors. However, the amount should not be changed in this situation. If its is acceptable to use this flow but using a preauth and preauthcomplete is encouraged because it provides more flexibility.

libmonetra KVS equivalent for endpoint

  • action_trans = capture
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

priority
string
Default: "normal"
Enum: "low" "normal" "high"

Processing priority.

You should process large batches as priority low, so that any real-time transactions that come through will be processed immediately

Values:

  • low - Low priority
  • normal - Normal priority
  • high - High priority
timeout
string\d+

Length of time transaction can sit in send queue before sending to the processor. This is a hint/estimate and not a hard value

rcpt
string

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 40.
  • 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.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "priority": "normal",
  • "timeout": "30",
  • "rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "account": "XXXXXXXXXXXX1234",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "timestamp": "string",
  • "ttid": "string"
}

Duplicate a Pre-Authorize

Run a new transaction as a Pre-Authorization by duplicating transaction data from a previous transaction

Any previous financial transaction where sensitive data has not been cleared can be duplicated. When duplicating a previous transaction, data from the referenced transaction will be used. Any parameter can be overridden/replaced. For example, specifying a new amount.", Places a hold on funds without capturing for settlement

This is functionally equivalent to a sale transaction with capture=no. The difference between sale and preauth is that a preauth is split into two parts. In both transactions, the transaction data is sent online through the processor to the issuer. The issuer will approve or decline the transaction and place a temporary hold on the amount. A sale will add the transaction to a batch and mark it eligible for settlement. A preauth will not add the transaction to a batch, and it will be marked as not-yet eligible for settlement. A preauthcomplete must be performed to add the transaction to a batch and mark it as eligible for settlement.

The transaction amount can change between the preauth and preauthcomplete. This should be used if the final amount is not known at the time of authorization. For example, adding a tip. If the transaction amount is known and not subject to change, a sale should be used instad.

Some industries, such as E-commerce, necessitate the use of preauth. When selling physical goods, the final charge (settle) cannot take place until the goods are shipped. If there is a short delay between taking payment and shipping, a preauth can be used to delay taking the funds from a customer's account. You may need to work with your merchant account provider to determine whether a sale or preauth is more appropriate for your business needs.

libmonetra KVS equivalent for endpoint

  • action_trans = preauth
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Identifier for transaction to duplicate

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object

Verification parameters

object

Shipping detail parameters

object

E-commerce parameters

object

Healthcare parameters

object

Lodging parameters

object

Merchant descriptor parameters

object

Merchant lane parameters

required
object

Monetary parameters

object

Order detail parameters

object

PIN data parameters

object

Processing options

object

Recurring group

nsf
string
Enum: "yes" "no"

Approve transactions even if there are non-sufficient funds (NSF). This will result in a partial approval if there are not enough funds to cover the full requested amount, in which case an authamount response parameter will be returned. When a partial authorization is received, a merchant should request another payment method for the remaining funds. It is acceptable to request a reversal if no additional payment methods are possible.

Gift cards default to yes while other cards default to no if not sent.

If a partial approval is received, it will automatically be reversed internally and the returned decline will have msoft_code=NSFAUTODENY set.

Values:

  • yes - Allow partial approvals
  • no - Request that partial approvals are not returned
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.

Requires:

  • tokenize

Values:

  • yes - Return existing token matching this account number
  • no - Do not return existing token matching this account number
carddenylist_check
string
Enum: "yes" "no"

Check the card deny list before going online for authorization

If on the list, decline with msoft_code=CARDDENYLIST.

The value no can be used to disable checking. Merchants can have their account configured to always check the list before going online for atuhorization. no allows them to disable this check on a per transaction basis. As does yes which allows checking on a per transaction basis.

Only the account number is used to determine if there is a match on the list. Other paramters, such as card holder name and card expiration date are not used.

Values:

  • yes - Check the card deny list before going online and decline if present
  • no - Do not check the card deny list before going online
carddenylist_decline
string
Enum: "yes" "no"

Automatically add account to the card deny list if declined by the issuer

Values:

  • yes - Add the account to the deny list on issuer decline
  • no - Do not add the account to the deny list on issuer decline
rcpt
string

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 40.
  • 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.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "verification": {
    },
  • "shipping": {
    },
  • "ecomm": {
    },
  • "health": {
    },
  • "lodging": {
    },
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "money": {
    },
  • "order": {
    },
  • "pin_data": {
    },
  • "processing_options": {
    },
  • "recurring_data": {
    },
  • "nsf": "yes",
  • "tokenize": "yes",
  • "matching_token": "yes",
  • "carddenylist_check": "no",
  • "carddenylist_decline": "no",
  • "rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "authamount": "string",
  • "balance": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "cof_authamount": "string",
  • "cof_transid": "string",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "timestamp": "string",
  • "token": "string",
  • "carddenylist_id": "string",
  • "ttid": "string"
}

Duplicate a Purchase

Run a new transaction as a purchase by duplicating transaction data from a previous transaction

Any previous financial transaction where sensitive data has not been cleared can be duplicated.

When duplicating a previous transaction, data from the referenced transaction will be used. Any parameter can be overridden/replaced. For example, specifying a new amount.

The transaction amount is assumed to be the final transaction amount that will be settled. If the transaction amount is subject to change, a preauth transaction should be used instead.

libmonetra KVS equivalent for endpoint

  • action_trans = sale
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Identifier for transaction to duplicate

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object

Verification parameters

object

Shipping detail parameters

object

E-commerce parameters

object

Healthcare parameters

object

Lodging parameters

object

Merchant descriptor parameters

object

Merchant lane parameters

required
object

Monetary parameters

object

Order detail parameters

object

PIN data parameters

object

Processing options

object

Recurring group

nsf
string
Enum: "yes" "no"

Approve transactions even if there are non-sufficient funds (NSF). This will result in a partial approval if there are not enough funds to cover the full requested amount, in which case an authamount response parameter will be returned. When a partial authorization is received, a merchant should request another payment method for the remaining funds. It is acceptable to request a reversal if no additional payment methods are possible.

Gift cards default to yes while other cards default to no if not sent.

If a partial approval is received, it will automatically be reversed internally and the returned decline will have msoft_code=NSFAUTODENY set.

Values:

  • yes - Allow partial approvals
  • no - Request that partial approvals are not returned
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.

Requires:

  • tokenize

Values:

  • yes - Return existing token matching this account number
  • no - Do not return existing token matching this account number
carddenylist_check
string
Enum: "yes" "no"

Check the card deny list before going online for authorization

If on the list, decline with msoft_code=CARDDENYLIST.

The value no can be used to disable checking. Merchants can have their account configured to always check the list before going online for atuhorization. no allows them to disable this check on a per transaction basis. As does yes which allows checking on a per transaction basis.

Only the account number is used to determine if there is a match on the list. Other paramters, such as card holder name and card expiration date are not used.

Values:

  • yes - Check the card deny list before going online and decline if present
  • no - Do not check the card deny list before going online
carddenylist_decline
string
Enum: "yes" "no"

Automatically add account to the card deny list if declined by the issuer

Values:

  • yes - Add the account to the deny list on issuer decline
  • no - Do not add the account to the deny list on issuer decline
rcpt
string

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 40.
  • 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.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "verification": {
    },
  • "shipping": {
    },
  • "ecomm": {
    },
  • "health": {
    },
  • "lodging": {
    },
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "money": {
    },
  • "order": {
    },
  • "pin_data": {
    },
  • "processing_options": {
    },
  • "recurring_data": {
    },
  • "nsf": "yes",
  • "tokenize": "yes",
  • "matching_token": "yes",
  • "carddenylist_check": "no",
  • "carddenylist_decline": "no",
  • "rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "authamount": "string",
  • "balance": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "cof_authamount": "string",
  • "cof_transid": "string",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "timestamp": "string",
  • "token": "string",
  • "carddenylist_id": "string",
  • "ttid": "string"
}

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.

libmonetra KVS equivalent for endpoint

  • action_trans = cardtype
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object (_vault_account_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
  • Ticket
    • cardshieldticket
  • Token
    • token

Additional modifiers are also present which can provide information about how the data was received. For example, Cards and phones can be tapped in which case the rfid modifier needs 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.

Requires:

  • tokenize

Values:

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

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "tokenize": "yes",
  • "matching_token": "yes"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "account": "XXXXXXXXXXXX1234",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "timestamp": "string",
  • "token": "string"
}

Incremental

Operation used to increase amount for an existing authorization

Monetra does not impose any restrictions on attempting an Incremental request. It will simply relay that onto the processing institution. Support across card brands is not uniform and some card brands impose restrictions. For example, the business MCC.

Historically incremental was used for the lodging industry and has support with Visa and MC for this industry. Other industries are supported, but again, use is based on card brand restrictions. The merchant needs to verify with the processor how they can use incremental industry for a given card type.

In the hotel industry, an example use is to add items charged to the room to an existing authorization. It is also used to extend the customer's stay. As well as other hotel specific conditions.

This should not be used instead of a preauth in most cases. This is intended for authorizations that are long lived. For example, a hotel stay where the guest is charging items to their room. This operation will ensure the funds are held on the guest's card until they check out and the authorization is submitted for settlement.

This is specific for changing the amount and lodging stay. It differs from an adjust which allows changing multiple parameters. Also, an adjust may not be an online operation and only modify parameters for settlement. An incremental is always online and, if successful, will increase the funds held on the customer's card. An adjust does not guarantee funds are available or will be held for the new amount.

The transaction amount is assumed to be the final transaction amount that will be settled. This is inclusive of the increase and the original amount that has already been authorized.

libmonetra KVS equivalent for endpoint

  • action_trans = incremental
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Identifier for transaction to increase amount

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

amount
required
string\d*(\.\d{0,2})?

New total amount, not amount being added

tax
string(?i)NT|\d*(\.\d{0,2})?

Amount of tax that applies to the order

The value 'NT' without the quotes indicates a non-taxable (tax exempt) transaction.

nsf
string
Enum: "yes" "no"

Approve transactions even if there are non-sufficient funds (NSF). This will result in a partial approval if there are not enough funds to cover the full requested amount, in which case an authamount response parameter will be returned. When a partial authorization is received, a merchant should request another payment method for the remaining funds. It is acceptable to request a reversal if no additional payment methods are possible.

Gift cards default to yes while other cards default to no if not sent.

If a partial approval is received, it will automatically be reversed internally and the returned decline will have msoft_code=NSFAUTODENY set.

Values:

  • yes - Allow partial approvals
  • no - Request that partial approvals are not returned
object

Lodging parameters

object

Merchant descriptor parameters

object

Merchant lane parameters

rcpt
string

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 40.
  • 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.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "amount": "19.92",
  • "tax": "1.29",
  • "nsf": "yes",
  • "lodging": {
    },
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "authamount": "string",
  • "balance": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "timestamp": "string",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "ttid": "string"
}

Pre-Authorization Completion

Finalize a Pre-Authorization

Adds the transaction to a batch, and marks it as eligible for settlement.

libmonetra KVS equivalent for endpoint

  • action_trans = preauthcomplete
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object

Shipping detail parameters

zip
string <= 32 characters

Zip code for AVS verification. All Card Not Present transactions require this to avoid being 'downgraded'

object

Lodging parameters

object

Merchant lane parameters

object

Monetary parameters

object

Order detail parameters

priority
string
Default: "normal"
Enum: "low" "normal" "high"

Processing priority.

You should process large batches as priority low, so that any real-time transactions that come through will be processed immediately

Values:

  • low - Low priority
  • normal - Normal priority
  • high - High priority
timeout
string\d+

Length of time transaction can sit in send queue before sending to the processor. This is a hint/estimate and not a hard value

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.

Requires:

  • tokenize

Values:

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

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 40.
  • 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.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "shipping": {
    },
  • "zip": "32606",
  • "lodging": {
    },
  • "lane": {
    },
  • "money": {
    },
  • "order": {
    },
  • "priority": "normal",
  • "timeout": "30",
  • "tokenize": "yes",
  • "matching_token": "yes",
  • "rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "authamount": "string",
  • "balance": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "cof_authamount": "string",
  • "cof_transid": "string",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "timestamp": "string",
  • "token": "string",
  • "ttid": "string"
}

Pre-Authorize

Places a hold on funds without capturing for settlement

This is functionally equivalent to a sale transaction with capture=no. The difference between sale and preauth is that a preauth is split into two parts. In both transactions, the transaction data is sent online through the processor to the issuer. The issuer will approve or decline the transaction and place a temporary hold on the amount. A sale will add the transaction to a batch and mark it eligible for settlement. A preauth will not add the transaction to a batch, and it will be marked as not-yet eligible for settlement. A preauthcomplete must be performed to add the transaction to a batch and mark it as eligible for settlement.

The transaction amount can change between the preauth and preauthcomplete. This should be used if the final amount is not known at the time of authorization. For example, adding a tip. If the transaction amount is known and not subject to change, a sale should be used instad.

Some industries, such as E-commerce, necessitate the use of preauth. When selling physical goods, the final charge (settle) cannot take place until the goods are shipped. If there is a short delay between taking payment and shipping, a preauth can be used to delay taking the funds from a customer's account. You may need to work with your merchant account provider to determine whether a sale or preauth is more appropriate for your business needs.

libmonetra KVS equivalent for endpoint

  • action_trans = preauth
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object

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
  • Ticket
    • cardshieldticket
  • Token
    • token

Additional modifiers are also present which can provide information about how the data was received. For example, Cards and phones can be tapped in which case the rfid modifier needs 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.

object

Verification parameters

object

Shipping detail parameters

object

E-commerce parameters

object

Healthcare parameters

object

Lodging parameters

object

Merchant descriptor parameters

object

Merchant lane parameters

required
object

Monetary parameters

object

Order detail parameters

object

PIN data parameters

object

Processing options

object

Recurring group

nsf
string
Enum: "yes" "no"

Approve transactions even if there are non-sufficient funds (NSF). This will result in a partial approval if there are not enough funds to cover the full requested amount, in which case an authamount response parameter will be returned. When a partial authorization is received, a merchant should request another payment method for the remaining funds. It is acceptable to request a reversal if no additional payment methods are possible.

Gift cards default to yes while other cards default to no if not sent.

If a partial approval is received, it will automatically be reversed internally and the returned decline will have msoft_code=NSFAUTODENY set.

Values:

  • yes - Allow partial approvals
  • no - Request that partial approvals are not returned
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.

Requires:

  • tokenize

Values:

  • yes - Return existing token matching this account number
  • no - Do not return existing token matching this account number
carddenylist_check
string
Enum: "yes" "no"

Check the card deny list before going online for authorization

If on the list, decline with msoft_code=CARDDENYLIST.

The value no can be used to disable checking. Merchants can have their account configured to always check the list before going online for atuhorization. no allows them to disable this check on a per transaction basis. As does yes which allows checking on a per transaction basis.

Only the account number is used to determine if there is a match on the list. Other paramters, such as card holder name and card expiration date are not used.

Values:

  • yes - Check the card deny list before going online and decline if present
  • no - Do not check the card deny list before going online
carddenylist_decline
string
Enum: "yes" "no"

Automatically add account to the card deny list if declined by the issuer

Values:

  • yes - Add the account to the deny list on issuer decline
  • no - Do not add the account to the deny list on issuer decline
rcpt
string

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 40.
  • 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.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "verification": {
    },
  • "shipping": {
    },
  • "ecomm": {
    },
  • "health": {
    },
  • "lodging": {
    },
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "money": {
    },
  • "order": {
    },
  • "pin_data": {
    },
  • "processing_options": {
    },
  • "recurring_data": {
    },
  • "nsf": "yes",
  • "tokenize": "yes",
  • "matching_token": "yes",
  • "carddenylist_check": "no",
  • "carddenylist_decline": "no",
  • "rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "authamount": "string",
  • "balance": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "cof_authamount": "string",
  • "cof_transid": "string",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "timestamp": "string",
  • "token": "string",
  • "ttid": "string"
}

Purchase

Debits available funds from cardholder's account.

The transaction amount is assumed to be the final transaction amount that will be settled. If the transaction amount is subject to change, a preauth transaction should be used instead.

libmonetra KVS equivalent for endpoint

  • action_trans = sale
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object

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
  • Ticket
    • cardshieldticket
  • Token
    • token

Additional modifiers are also present which can provide information about how the data was received. For example, Cards and phones can be tapped in which case the rfid modifier needs 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.

object

Verification parameters

object

Shipping detail parameters

object

E-commerce parameters

object

Healthcare parameters

object

Lodging parameters

object

Merchant descriptor parameters

object

Merchant lane parameters

required
object

Monetary parameters

object

Order detail parameters

object

PIN data parameters

object

Processing options

object

Recurring group

nsf
string
Enum: "yes" "no"

Approve transactions even if there are non-sufficient funds (NSF). This will result in a partial approval if there are not enough funds to cover the full requested amount, in which case an authamount response parameter will be returned. When a partial authorization is received, a merchant should request another payment method for the remaining funds. It is acceptable to request a reversal if no additional payment methods are possible.

Gift cards default to yes while other cards default to no if not sent.

If a partial approval is received, it will automatically be reversed internally and the returned decline will have msoft_code=NSFAUTODENY set.

Values:

  • yes - Allow partial approvals
  • no - Request that partial approvals are not returned
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.

Requires:

  • tokenize

Values:

  • yes - Return existing token matching this account number
  • no - Do not return existing token matching this account number
carddenylist_check
string
Enum: "yes" "no"

Check the card deny list before going online for authorization

If on the list, decline with msoft_code=CARDDENYLIST.

The value no can be used to disable checking. Merchants can have their account configured to always check the list before going online for atuhorization. no allows them to disable this check on a per transaction basis. As does yes which allows checking on a per transaction basis.

Only the account number is used to determine if there is a match on the list. Other paramters, such as card holder name and card expiration date are not used.

Values:

  • yes - Check the card deny list before going online and decline if present
  • no - Do not check the card deny list before going online
carddenylist_decline
string
Enum: "yes" "no"

Automatically add account to the card deny list if declined by the issuer

Values:

  • yes - Add the account to the deny list on issuer decline
  • no - Do not add the account to the deny list on issuer decline
rcpt
string

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 40.
  • 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.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "verification": {
    },
  • "shipping": {
    },
  • "ecomm": {
    },
  • "health": {
    },
  • "lodging": {
    },
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "money": {
    },
  • "order": {
    },
  • "pin_data": {
    },
  • "processing_options": {
    },
  • "recurring_data": {
    },
  • "nsf": "yes",
  • "tokenize": "yes",
  • "matching_token": "yes",
  • "carddenylist_check": "no",
  • "carddenylist_decline": "no",
  • "rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "authamount": "string",
  • "balance": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "cof_authamount": "string",
  • "cof_transid": "string",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "timestamp": "string",
  • "token": "string",
  • "carddenylist_id": "string",
  • "ttid": "string"
}

Refund Existing Transaction

Refunds a prior purchase

By default users are only allowed to refund to a previous purchase transaction. This linked transaction is referenced by the original transaction's ttid The cumulative amount that can be refunded cannot exceed the original transaction amount.

If the transaction being referenced is still unsettled, the refund amount must be different than the original authorization amount; if not, reversal should be used instead.

libmonetra KVS equivalent for endpoint

  • action_trans = refund
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Identifier for transaction to refund

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object

Merchant descriptor parameters

object

Merchant lane parameters

object

Monetary parameters

object

Order detail parameters

object

PIN data parameters

object

Recurring group

priority
string
Default: "normal"
Enum: "low" "normal" "high"

Processing priority.

You should process large batches as priority low, so that any real-time transactions that come through will be processed immediately

Values:

  • low - Low priority
  • normal - Normal priority
  • high - High priority
timeout
string\d+

Length of time transaction can sit in send queue before sending to the processor. This is a hint/estimate and not a hard value

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.

Requires:

  • tokenize

Values:

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

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 40.
  • 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.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "money": {
    },
  • "order": {
    },
  • "pin_data": {
    },
  • "recurring_data": {
    },
  • "priority": "normal",
  • "timeout": "30",
  • "tokenize": "yes",
  • "matching_token": "yes",
  • "rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "authamount": "string",
  • "balance": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "cof_authamount": "string",
  • "cof_transid": "string",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "timestamp": "string",
  • "token": "string",
  • "ttid": "string"
}

Unlinked Refund

Unlinked Refund

By default users are only allowed to refund to a previous purchase transaction. This linked transaction is referenced by the original transaction's ttid The cumulative amount that can be refunded cannot exceed the original transaction amount.

If the transaction being referenced is still unsettled, the refund amount must be different than the original authorization amount; if not, reversal should be used instead.

A user can have the ALLOW_UNLINKED_REFUND which will allow refunding any account without referencing a ttid. Typically, sensitive account info is required to specify the account that will receive the funds. Which users are allowed to send unlinked refunds should be highly restricted because it is a common avenue for fraud.

Gift cards use this operation to load funds onto the cards and is not specifically intended for returning a product. Instead a gift merchandise refund should be used for that situation. If the gift card provider does not support the merchandise refund operation, this refund operation should be used.

libmonetra KVS equivalent for endpoint

  • action_trans = refund
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object

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
  • Ticket
    • cardshieldticket
  • Token
    • token

Additional modifiers are also present which can provide information about how the data was received. For example, Cards and phones can be tapped in which case the rfid modifier needs 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.

object

Merchant descriptor parameters

object

Merchant lane parameters

object

Monetary parameters

object

Order detail parameters

object

PIN data parameters

object

Recurring group

priority
string
Default: "normal"
Enum: "low" "normal" "high"

Processing priority.

You should process large batches as priority low, so that any real-time transactions that come through will be processed immediately

Values:

  • low - Low priority
  • normal - Normal priority
  • high - High priority
timeout
string\d+

Length of time transaction can sit in send queue before sending to the processor. This is a hint/estimate and not a hard value

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.

Requires:

  • tokenize

Values:

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

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 40.
  • 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.
ttid
string

Identifier for transaction to refund

property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "money": {
    },
  • "order": {
    },
  • "pin_data": {
    },
  • "recurring_data": {
    },
  • "priority": "normal",
  • "timeout": "30",
  • "tokenize": "yes",
  • "matching_token": "yes",
  • "rcpt": "yes",
  • "ttid": "string",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "authamount": "string",
  • "balance": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "cof_authamount": "string",
  • "cof_transid": "string",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "timestamp": "string",
  • "token": "string",
  • "ttid": "string"
}

Verify Card

Verifies avs and cv data

The two main uses for this operation are to:

  1. Verify the card is valid and open
  2. Verify avs and cv for fraud logic

This does not verify availability of funds. This is account verification only.

libmonetra KVS equivalent for endpoint

  • action_trans = verifyonly
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object

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
  • Ticket
    • cardshieldticket
  • Token
    • token

Additional modifiers are also present which can provide information about how the data was received. For example, Cards and phones can be tapped in which case the rfid modifier needs 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.

object

Verification parameters

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.

Requires:

  • tokenize

Values:

  • yes - Return existing token matching this account number
  • no - Do not return existing token matching this account number
carddenylist_check
string
Enum: "yes" "no"

Check the card deny list before going online for authorization

If on the list, decline with msoft_code=CARDDENYLIST.

The value no can be used to disable checking. Merchants can have their account configured to always check the list before going online for atuhorization. no allows them to disable this check on a per transaction basis. As does yes which allows checking on a per transaction basis.

Only the account number is used to determine if there is a match on the list. Other paramters, such as card holder name and card expiration date are not used.

Values:

  • yes - Check the card deny list before going online and decline if present
  • no - Do not check the card deny list before going online
carddenylist_decline
string
Enum: "yes" "no"

Automatically add account to the card deny list if declined by the issuer

Values:

  • yes - Add the account to the deny list on issuer decline
  • no - Do not add the account to the deny list on issuer decline
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "verification": {
    },
  • "tokenize": "yes",
  • "matching_token": "yes",
  • "carddenylist_check": "no",
  • "carddenylist_decline": "no",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "account": "XXXXXXXXXXXX1234",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "timestamp": "string",
  • "token": "string",
  • "carddenylist_id": "string"
}

Void Transaction

Removes a previously authorized transaction

In the vast majority of cases, a reversal should be used and not a void.

In many instances this is not a real time transaction, and the funds held on the customer's account will not be removed. There is no guarantee this will be an online transaction.

The main use for a void is to ensure the transaction will not settle if a 'reversal' was issued and failed. Since this can be an offline transaction, processor permitting, there is still a chance of success.

Realize that a reversal can fail for legitimate reasons, such as the transaction already being settled, in which case a refund should be issued. Another case is when the transaction has already been reversed. These are the most likely cases for a reversal failing, so the reversal response should be evaluated to determine if a void is actually necessary as a follow up.

libmonetra KVS equivalent for endpoint

  • action_trans = void
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/transaction/926573735405091/void' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "timestamp": "string",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "ttid": "string"
}

Gift

Gift specific operations

This applies to private label gift cards. Not credit card branded gift cards. Such as Visa, Mastercard, or Amex gift cards. Brand cards are handled in the same manner as credit cards.

Gift cards have a number of operations that are specific to gift card processing. For example issuing gift cards. Using gift cards for transaction processing uses the standard transaction operations. Specifically, purchase, reversal, and refund.

Gift cards are also included in the standard transaction reports. Which can be filtered to only include gift cards is gift card specific reporting is needed.

Loyalty cards are not supported. Only gift cards used as payment are supported.

Gift Activate

Activate a Gift card

See description for the gift card issue operation for details.

Processors supporting activate

  • Givex
  • NCR Gift
  • Stored Value Solutions (SVS)
  • Valutec
  • FIServ Gift
  • FIServ Chockstone
  • FIServ Rapid Connect
  • Paymentech (Tampa platform)
  • WorldPay (Legacy TCMP platform)
  • WorldPay (Raft 610 platform)

libmonetra KVS equivalent for endpoint

  • action_trans = activate
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object (_vault_account_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
  • Ticket
    • cardshieldticket
  • Token
    • token

Additional modifiers are also present which can provide information about how the data was received. For example, Cards and phones can be tapped in which case the rfid modifier needs 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.

pin
string(?i)PINLESS|[[:xdigit:]]{16}|[[:xdigit:]]{20}...

Customer PIN number

The PIN data can vary depending on the transaction and card type.

For PINless debit bill payments, this should be set to pinless

For Gift, this is typically the plain text PIN.

Otherwise, this is a hex-encoded encrypted PIN block.

cv
string [ 3 .. 4 ] characters [0-9]{3,4}

Card Verification value.

Used to help with fraud prevention. 3 digits on back of VISA/MC/Discover, or 4 digits on front of AMEX cards.

It's use is HIGHLY recommended for Mail Order/Telephone Order and E-commerce industries.

Other indicators may be used, such as 'NR' if the CV is unreadable, 'NA' if the CV is physically not present on the card, or 'N' if the CV is intentionally not provided. If no CV is present, this will default to 'N'.

object (_transaction_activate_merchant_descriptors)

Merchant descriptor parameters

object (_transaction_activate_lane)

Merchant lane parameters

object (_transaction_activate_order)

Order detail parameters

object (_transaction_activate_processing_options)

Processing options

amount
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

nsf
string
Enum: "yes" "no"

Approve transactions even if there are non-sufficient funds (NSF). This will result in a partial approval if there are not enough funds to cover the full requested amount, in which case an authamount response parameter will be returned. When a partial authorization is received, a merchant should request another payment method for the remaining funds. It is acceptable to request a reversal if no additional payment methods are possible.

Gift cards default to yes while other cards default to no if not sent.

If a partial approval is received, it will automatically be reversed internally and the returned decline will have msoft_code=NSFAUTODENY set.

Values:

  • yes - Allow partial approvals
  • no - Request that partial approvals are not returned
rcpt
string

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 40.
  • 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

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "pin": "string",
  • "cv": "123",
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "order": {
    },
  • "processing_options": {
    },
  • "amount": "19.92",
  • "nsf": "yes",
  • "rcpt": "yes"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "authamount": "string",
  • "balance": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "timestamp": "string",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "ttid": "string"
}

Gift Cash Out

Remove all funds from a gift card

Funds are intended to be remitted to the customer either as cash or via another method. Many states have laws requiring merchants to provide the operation at the customer's request.

The authamount response parameter will contain the amount of money that needs to be remitted to the customer.

Depending on the gift card processor this may or may not deactivate the card.

libmonetra KVS equivalent for endpoint

  • action_trans = cashout
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object (_vault_account_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
  • Ticket
    • cardshieldticket
  • Token
    • token

Additional modifiers are also present which can provide information about how the data was received. For example, Cards and phones can be tapped in which case the rfid modifier needs 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.

pin
string(?i)PINLESS|[[:xdigit:]]{16}|[[:xdigit:]]{20}...

Customer PIN number

The PIN data can vary depending on the transaction and card type.

For PINless debit bill payments, this should be set to pinless

For Gift, this is typically the plain text PIN.

Otherwise, this is a hex-encoded encrypted PIN block.

cv
string [ 3 .. 4 ] characters [0-9]{3,4}

Card Verification value.

Used to help with fraud prevention. 3 digits on back of VISA/MC/Discover, or 4 digits on front of AMEX cards.

It's use is HIGHLY recommended for Mail Order/Telephone Order and E-commerce industries.

Other indicators may be used, such as 'NR' if the CV is unreadable, 'NA' if the CV is physically not present on the card, or 'N' if the CV is intentionally not provided. If no CV is present, this will default to 'N'.

object (_transaction_activate_merchant_descriptors)

Merchant descriptor parameters

object (_transaction_activate_lane)

Merchant lane parameters

object (_transaction_activate_order)

Order detail parameters

object (_transaction_activate_processing_options)

Processing options

rcpt
string

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 40.
  • 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

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "pin": "string",
  • "cv": "123",
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "order": {
    },
  • "processing_options": {
    },
  • "rcpt": "yes"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "authamount": "string",
  • "balance": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "timestamp": "string",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "ttid": "string"
}

Gift Issue

Issue a Gift card

There are two operations that can open and fund a gift card activate and issue. The difference between these two is blurry and often they are used interchangeably.

activate typically applies to denominated cards. Where the amount is tied to the card and does not need to be specified as part of the operation. This is in contrast to issue which typically applies to non-denominated cards. In this case, the amount being placed onto the card must be specified.

Using activate vs issue can be processor specific. Some gift processors do not make a distinction between the two and will use the same operation for both non-denominated and denominated cards.

Further, processors that support both types of cards may have different programs for different merchants. Such as, providing one, the other, or both for the merchant. Thus it is necessary to work with both the merchant and processor to determine how gift cards need to be funded.

Processors supporting issue

  • Paytronix
  • Opticard
  • Stored Value Solutions (SVS)
  • FIServ Rapid Connect
  • NCR Gift
  • NCR Aloha
  • Factor 4
  • Paymentech (Tampa platform)

libmonetra KVS equivalent for endpoint

  • action_trans = issue
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object (_vault_account_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
  • Ticket
    • cardshieldticket
  • Token
    • token

Additional modifiers are also present which can provide information about how the data was received. For example, Cards and phones can be tapped in which case the rfid modifier needs 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.

pin
string(?i)PINLESS|[[:xdigit:]]{16}|[[:xdigit:]]{20}...

Customer PIN number

The PIN data can vary depending on the transaction and card type.

For PINless debit bill payments, this should be set to pinless

For Gift, this is typically the plain text PIN.

Otherwise, this is a hex-encoded encrypted PIN block.

cv
string [ 3 .. 4 ] characters [0-9]{3,4}

Card Verification value.

Used to help with fraud prevention. 3 digits on back of VISA/MC/Discover, or 4 digits on front of AMEX cards.

It's use is HIGHLY recommended for Mail Order/Telephone Order and E-commerce industries.

Other indicators may be used, such as 'NR' if the CV is unreadable, 'NA' if the CV is physically not present on the card, or 'N' if the CV is intentionally not provided. If no CV is present, this will default to 'N'.

object (_transaction_activate_merchant_descriptors)

Merchant descriptor parameters

object (_transaction_activate_lane)

Merchant lane parameters

object (_transaction_activate_order)

Order detail parameters

object (_transaction_activate_processing_options)

Processing options

amount
required
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

nsf
string
Enum: "yes" "no"

Approve transactions even if there are non-sufficient funds (NSF). This will result in a partial approval if there are not enough funds to cover the full requested amount, in which case an authamount response parameter will be returned. When a partial authorization is received, a merchant should request another payment method for the remaining funds. It is acceptable to request a reversal if no additional payment methods are possible.

Gift cards default to yes while other cards default to no if not sent.

If a partial approval is received, it will automatically be reversed internally and the returned decline will have msoft_code=NSFAUTODENY set.

Values:

  • yes - Allow partial approvals
  • no - Request that partial approvals are not returned
rcpt
string

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 40.
  • 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

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "pin": "string",
  • "cv": "123",
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "order": {
    },
  • "processing_options": {
    },
  • "amount": "19.92",
  • "nsf": "yes",
  • "rcpt": "yes"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "authamount": "string",
  • "balance": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "timestamp": "string",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "ttid": "string"
}

Gift Merchandise Refund

Refunds merchandise to a gift card

Instead of sending the sensitive account info, a prior transaction's ttid may be referenced (if the transaction hasn't been secured or purged).

If the transaction being referenced is still unsettled, the refund amount must be different than the original authorization amount; if not, reversal should be used instead.

Gift cards use this operation to denote funds are being loaded onto the card due to returning merchandise. Adding funds to a card should use the refund operation.

Not all gift card providers support the merchandise refund operation. In which case, a standard refund to load the funds onto the gift card should be used.

libmonetra KVS equivalent for endpoint

  • action_trans = merchreturn
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object

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
  • Ticket
    • cardshieldticket
  • Token
    • token

Additional modifiers are also present which can provide information about how the data was received. For example, Cards and phones can be tapped in which case the rfid modifier needs 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.

object

Merchant descriptor parameters

object

Merchant lane parameters

object

Monetary parameters

object

Order detail parameters

priority
string
Default: "normal"
Enum: "low" "normal" "high"

Processing priority.

You should process large batches as priority low, so that any real-time transactions that come through will be processed immediately

Values:

  • low - Low priority
  • normal - Normal priority
  • high - High priority
timeout
string\d+

Length of time transaction can sit in send queue before sending to the processor. This is a hint/estimate and not a hard value

rcpt
string

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 40.
  • 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.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "money": {
    },
  • "order": {
    },
  • "priority": "normal",
  • "timeout": "30",
  • "rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "authamount": "string",
  • "balance": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "timestamp": "string",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "ttid": "string"
}

Gift Merchandise Refund Existing Transaction

Issue a refund for merchandise to a gift card based on a previous transaction

If amount is not specified, the amount from the referenced transaction will be used.

libmonetra KVS equivalent for endpoint

  • action_trans = merchreturn
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Identifier for the gift card transaction to refund merchandise

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object

Merchant descriptor parameters

object

Merchant lane parameters

object

Monetary parameters

object

Order detail parameters

priority
string
Default: "normal"
Enum: "low" "normal" "high"

Processing priority.

You should process large batches as priority low, so that any real-time transactions that come through will be processed immediately

Values:

  • low - Low priority
  • normal - Normal priority
  • high - High priority
timeout
string\d+

Length of time transaction can sit in send queue before sending to the processor. This is a hint/estimate and not a hard value

rcpt
string

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 40.
  • 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.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "money": {
    },
  • "order": {
    },
  • "priority": "normal",
  • "timeout": "30",
  • "rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "authamount": "string",
  • "balance": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "timestamp": "string",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "ttid": "string"
}

EBT

Electronic Benefits Transfer (EBT) cards can have two different accounts associated with a single account number. Typically these are food and cash account.

Food accounts have specific product qualification requirement which vary by state. Only qualified products can be purchased using the food account. It is up to the merchant to determine what qualifies in their jurisdiction.

Cash accounts are typically unrestricted.

Due to these cards having two different accounts, transaction operations specific to EBT are necessary in order to differentiate. Specifically, purchase, refund, and balance operations.

EBT is included in the standard transaction reports. Which can be filtered to only include EBT if EBT specific reporting is needed.

EBT Cash Balance

Get the balance on a Cash account

libmonetra KVS equivalent for endpoint

  • action_trans = ebtcbbalance
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object

Account information parameters

There are multiple ways to collect the customer's account information for EBT cards. Currently there are no EBT cards issued as EMV chip cards. EBT cards also cannot be tokenized.

These are the minimum fields required for each entry method.

  • Swipe
    • trackdata
  • Keyed
    • account
    • expdate
  • Ticket
    • cardshieldticket

All EBT transactions require PIN entry along with the account data. Only EBT food transactions allow keyed entry. They still require PIN even when keyed. EBT cash transactions must be swiped.

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.

required
object

PIN data parameters

rcpt
string

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 40.
  • 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.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "pin_data": {
    },
  • "rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "Y",
  • "card_signature_debit": "Y",
  • "card_token_card": "Y",
  • "account": "XXXXXXXXXXXX1234",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "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",
  • "balance": "string",
  • "timestamp": "string"
}

EBT Cash Purchase

Debit funds from a Cash account

libmonetra KVS equivalent for endpoint

  • action_trans = ebtcbsale
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object

Account information parameters

There are multiple ways to collect the customer's account information for EBT cards. Currently there are no EBT cards issued as EMV chip cards. EBT cards also cannot be tokenized.

These are the minimum fields required for each entry method.

  • Swipe
    • trackdata
  • Keyed
    • account
    • expdate
  • Ticket
    • cardshieldticket

All EBT transactions require PIN entry along with the account data. Only EBT food transactions allow keyed entry. They still require PIN even when keyed. EBT cash transactions must be swiped.

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.

object

Merchant descriptor parameters

object

Merchant lane parameters

object

Order detail parameters

required
object

PIN data parameters

object

Processing options

amount
required
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

nsf
string
Enum: "yes" "no"

Approve transactions even if there are non-sufficient funds (NSF). This will result in a partial approval if there are not enough funds to cover the full requested amount, in which case an authamount response parameter will be returned. When a partial authorization is received, a merchant should request another payment method for the remaining funds. It is acceptable to request a reversal if no additional payment methods are possible.

Gift cards default to yes while other cards default to no if not sent.

If a partial approval is received, it will automatically be reversed internally and the returned decline will have msoft_code=NSFAUTODENY set.

Values:

  • yes - Allow partial approvals
  • no - Request that partial approvals are not returned
carddenylist_check
string
Enum: "yes" "no"

Check the card deny list before going online for authorization

If on the list, decline with msoft_code=CARDDENYLIST.

The value no can be used to disable checking. Merchants can have their account configured to always check the list before going online for atuhorization. no allows them to disable this check on a per transaction basis. As does yes which allows checking on a per transaction basis.

Only the account number is used to determine if there is a match on the list. Other paramters, such as card holder name and card expiration date are not used.

Values:

  • yes - Check the card deny list before going online and decline if present
  • no - Do not check the card deny list before going online
carddenylist_decline
string
Enum: "yes" "no"

Automatically add account to the card deny list if declined by the issuer

Values:

  • yes - Add the account to the deny list on issuer decline
  • no - Do not add the account to the deny list on issuer decline
rcpt
string

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 40.
  • 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.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "order": {
    },
  • "pin_data": {
    },
  • "processing_options": {
    },
  • "amount": "19.92",
  • "nsf": "yes",
  • "carddenylist_check": "no",
  • "carddenylist_decline": "no",
  • "rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "authamount": "string",
  • "balance": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "timestamp": "string",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "carddenylist_id": "string",
  • "ttid": "string"
}

EBT Food Balance

Get the balance on a Food account

libmonetra KVS equivalent for endpoint

  • action_trans = ebtfsbalance
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object

Account information parameters

There are multiple ways to collect the customer's account information for EBT cards. Currently there are no EBT cards issued as EMV chip cards. EBT cards also cannot be tokenized.

These are the minimum fields required for each entry method.

  • Swipe
    • trackdata
  • Keyed
    • account
    • expdate
  • Ticket
    • cardshieldticket

All EBT transactions require PIN entry along with the account data. Only EBT food transactions allow keyed entry. They still require PIN even when keyed. EBT cash transactions must be swiped.

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.

required
object

PIN data parameters

rcpt
string

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 40.
  • 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.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "pin_data": {
    },
  • "rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "account": "XXXXXXXXXXXX1234",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "balance": "string",
  • "timestamp": "string"
}

EBT Food Purchase

Debit funds from a Food account

libmonetra KVS equivalent for endpoint

  • action_trans = ebtfssale
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object

Account information parameters

There are multiple ways to collect the customer's account information for EBT cards. Currently there are no EBT cards issued as EMV chip cards. EBT cards also cannot be tokenized.

These are the minimum fields required for each entry method.

  • Swipe
    • trackdata
  • Keyed
    • account
    • expdate
  • Ticket
    • cardshieldticket

All EBT transactions require PIN entry along with the account data. Only EBT food transactions allow keyed entry. They still require PIN even when keyed. EBT cash transactions must be swiped.

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.

object

Merchant descriptor parameters

object

Merchant lane parameters

object

Order detail parameters

required
object

PIN data parameters

object

Processing options

amount
required
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

nsf
string
Enum: "yes" "no"

Approve transactions even if there are non-sufficient funds (NSF). This will result in a partial approval if there are not enough funds to cover the full requested amount, in which case an authamount response parameter will be returned. When a partial authorization is received, a merchant should request another payment method for the remaining funds. It is acceptable to request a reversal if no additional payment methods are possible.

Gift cards default to yes while other cards default to no if not sent.

If a partial approval is received, it will automatically be reversed internally and the returned decline will have msoft_code=NSFAUTODENY set.

Values:

  • yes - Allow partial approvals
  • no - Request that partial approvals are not returned
carddenylist_check
string
Enum: "yes" "no"

Check the card deny list before going online for authorization

If on the list, decline with msoft_code=CARDDENYLIST.

The value no can be used to disable checking. Merchants can have their account configured to always check the list before going online for atuhorization. no allows them to disable this check on a per transaction basis. As does yes which allows checking on a per transaction basis.

Only the account number is used to determine if there is a match on the list. Other paramters, such as card holder name and card expiration date are not used.

Values:

  • yes - Check the card deny list before going online and decline if present
  • no - Do not check the card deny list before going online
carddenylist_decline
string
Enum: "yes" "no"

Automatically add account to the card deny list if declined by the issuer

Values:

  • yes - Add the account to the deny list on issuer decline
  • no - Do not add the account to the deny list on issuer decline
rcpt
string

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 40.
  • 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.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "order": {
    },
  • "pin_data": {
    },
  • "processing_options": {
    },
  • "amount": "19.92",
  • "nsf": "yes",
  • "carddenylist_check": "no",
  • "carddenylist_decline": "no",
  • "rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "authamount": "string",
  • "balance": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "timestamp": "string",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "carddenylist_id": "string",
  • "ttid": "string"
}

EBT Food Refund

Refund to a EBT Food account

The card holder must be present and provide the card including PIN in order to perform the refund. The user flag ALLOW_UNLINKED_REFUND must be enabled on the user account in order to perform this action.

libmonetra KVS equivalent for endpoint

  • action_trans = ebtfsreturn
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object

Account information parameters

There are multiple ways to collect the customer's account information for EBT cards. Currently there are no EBT cards issued as EMV chip cards. EBT cards also cannot be tokenized.

These are the minimum fields required for each entry method.

  • Swipe
    • trackdata
  • Keyed
    • account
    • expdate
  • Ticket
    • cardshieldticket

All EBT transactions require PIN entry along with the account data. Only EBT food transactions allow keyed entry. They still require PIN even when keyed. EBT cash transactions must be swiped.

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.

object

Merchant descriptor parameters

object

Merchant lane parameters

object

Order detail parameters

required
object

PIN data parameters

object

Processing options

amount
required
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

nsf
string
Enum: "yes" "no"

Approve transactions even if there are non-sufficient funds (NSF). This will result in a partial approval if there are not enough funds to cover the full requested amount, in which case an authamount response parameter will be returned. When a partial authorization is received, a merchant should request another payment method for the remaining funds. It is acceptable to request a reversal if no additional payment methods are possible.

Gift cards default to yes while other cards default to no if not sent.

If a partial approval is received, it will automatically be reversed internally and the returned decline will have msoft_code=NSFAUTODENY set.

Values:

  • yes - Allow partial approvals
  • no - Request that partial approvals are not returned
carddenylist_check
string
Enum: "yes" "no"

Check the card deny list before going online for authorization

If on the list, decline with msoft_code=CARDDENYLIST.

The value no can be used to disable checking. Merchants can have their account configured to always check the list before going online for atuhorization. no allows them to disable this check on a per transaction basis. As does yes which allows checking on a per transaction basis.

Only the account number is used to determine if there is a match on the list. Other paramters, such as card holder name and card expiration date are not used.

Values:

  • yes - Check the card deny list before going online and decline if present
  • no - Do not check the card deny list before going online
carddenylist_decline
string
Enum: "yes" "no"

Automatically add account to the card deny list if declined by the issuer

Values:

  • yes - Add the account to the deny list on issuer decline
  • no - Do not add the account to the deny list on issuer decline
rcpt
string

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 40.
  • 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.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "order": {
    },
  • "pin_data": {
    },
  • "processing_options": {
    },
  • "amount": "19.92",
  • "nsf": "yes",
  • "carddenylist_check": "no",
  • "carddenylist_decline": "no",
  • "rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "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",
  • "authamount": "string",
  • "balance": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "timestamp": "string",
  • "carddenylist_id": "string",
  • "ttid": "string"
}

Check

Paper checks can be converted to a digital check and processed. This is not an ACH transaction, it is for accepting physical, paper checks. ACH processing uses standard transaction operations.

Checks do not undergo real time authorization with the customer's bank. The verification operation uses a block list service provided by the check processor in order to determine if the account has had non-payment instances in the past.

In order to alleviate issues with failure to fund, check processors provide conversation with guarantee. The guarantee is provided by the check processor who will fund even if the check cannot be funded. Typically, an additional fee is charged by the check processor for this service.

The paper check after being accepted and approved by the check processor can be scanned and an image uploaded to Monetra using the "Store Check" image operation for record keeping purposes.

Check Conversion

Convert a check

This is a simple conversion with no additional features

libmonetra KVS equivalent for endpoint

  • action_trans = checkconvonly
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

required
object

Account information parameters

object

Verification parameters

object

Shipping detail parameters

object

Healthcare parameters

object

Lodging parameters

object

Merchant descriptor parameters

required
object

Monetary parameters

object

Order detail parameters

object

Merchant lane parameters

object

Processing options

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.

Requires:

  • tokenize

Values:

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

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 40.
  • 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.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "verification": {
    },
  • "shipping": {
    },
  • "health": {
    },
  • "lodging": {
    },
  • "merchant_descriptors": {
    },
  • "money": {
    },
  • "order": {
    },
  • "lane": {
    },
  • "processing_options": {
    },
  • "tokenize": "yes",
  • "matching_token": "yes",
  • "rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "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",
  • "cardtype": "VISA",
  • "issuer_decline": "Y",
  • "item": "string",
  • "stan": "string",
  • "timestamp": "string",
  • "ttid": "string"
}

Check Conversion With Guarantee

Convert a check with a guarantee on funds

libmonetra KVS equivalent for endpoint

  • action_trans = checkconvguar
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

required
object

Account information parameters

object

Verification parameters

object

Shipping detail parameters

object

Healthcare parameters

object

Lodging parameters

object

Merchant descriptor parameters

required
object

Monetary parameters

object

Order detail parameters

object

Merchant lane parameters

object

Processing options

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.

Requires:

  • tokenize

Values:

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

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 40.
  • 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.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "verification": {
    },
  • "shipping": {
    },
  • "health": {
    },
  • "lodging": {
    },
  • "merchant_descriptors": {
    },
  • "money": {
    },
  • "order": {
    },
  • "lane": {
    },
  • "processing_options": {
    },
  • "tokenize": "yes",
  • "matching_token": "yes",
  • "rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "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",
  • "cardtype": "VISA",
  • "issuer_decline": "Y",
  • "item": "string",
  • "stan": "string",
  • "timestamp": "string",
  • "ttid": "string"
}

Check Conversion With Override

Convert a check with override

This overrides a previous failure.

libmonetra KVS equivalent for endpoint

  • action_trans = checkconvover
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

required
object

Account information parameters

object

Verification parameters

object

Shipping detail parameters

object

Healthcare parameters

object

Lodging parameters

object

Merchant descriptor parameters

required
object

Monetary parameters

object

Order detail parameters

object

Merchant lane parameters

object

Processing options

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.

Requires:

  • tokenize

Values:

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

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 40.
  • 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.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "verification": {
    },
  • "shipping": {
    },
  • "health": {
    },
  • "lodging": {
    },
  • "merchant_descriptors": {
    },
  • "money": {
    },
  • "order": {
    },
  • "lane": {
    },
  • "processing_options": {
    },
  • "tokenize": "yes",
  • "matching_token": "yes",
  • "rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "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",
  • "cardtype": "VISA",
  • "issuer_decline": "Y",
  • "item": "string",
  • "stan": "string",
  • "timestamp": "string",
  • "ttid": "string"
}

Check Conversion With Verification

Convert a check with verification

libmonetra KVS equivalent for endpoint

  • action_trans = checkconvonly
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

required
object

Account information parameters

object

Verification parameters

object

Shipping detail parameters

object

Healthcare parameters

object

Lodging parameters

object

Merchant descriptor parameters

required
object

Monetary parameters

object

Order detail parameters

object

Merchant lane parameters

object

Processing options

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.

Requires:

  • tokenize

Values:

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

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 40.
  • 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.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "verification": {
    },
  • "shipping": {
    },
  • "health": {
    },
  • "lodging": {
    },
  • "merchant_descriptors": {
    },
  • "money": {
    },
  • "order": {
    },
  • "lane": {
    },
  • "processing_options": {
    },
  • "tokenize": "yes",
  • "matching_token": "yes",
  • "rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "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",
  • "cardtype": "VISA",
  • "issuer_decline": "Y",
  • "item": "string",
  • "stan": "string",
  • "timestamp": "string",
  • "ttid": "string"
}

Check Verify

Verify a check

This does not actually verify that the check's account exists or is in good standing. While some processors differ in their offerings, this typically performs a fraud test by checking if the account owner is known to write bad checks.

libmonetra KVS equivalent for endpoint

  • action_trans = checkverify
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

required
object

Account information parameters

There are multiple ways to collect the customer's check information.

These are the minimum fields required for each entry method.

  • Swipe via a check reader
    • micr
  • Keyed
    • account
    • abaroute
    • checknum

Additonal parameters such as drivers license information may be provided.

object

Merchant lane parameters

object

Processing options

rcpt
string

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 40.
  • 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.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "lane": {
    },
  • "processing_options": {
    },
  • "rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "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",
  • "cardtype": "VISA",
  • "issuer_decline": "Y",
  • "item": "string",
  • "stan": "string",
  • "timestamp": "string",
  • "ttid": "string"
}

Transaction Details

Transaction detail operations

Get All Payment Details For an Order

Get all order payment transaction details

Gets fine-grained detail about all payments in an order.

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.

libmonetra KVS equivalent for endpoint

  • action_admin = tran_detail
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

Cannot be combined with:

  • ttid
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ttid
string

Transaction identifier

Cannot be combined with:

  • order_id
payment_id
string

Unique ID of a payment for an order

Requires:

  • order_id

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/transaction/order/17485767483/payment' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "Y",
  • "card_signature_debit": "Y",
  • "card_token_card": "Y",
  • "auth": "string",
  • "batch": "string",
  • "issuer_decline": "Y",
  • "item": "string",
  • "stan": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "abaroute": "string",
  • "checknum": "string",
  • "accounttype": "BUSINESS",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "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",
  • "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",
  • "order_id": "string",
  • "payment_id": "string",
  • "order_cash_discount": "string",
  • "order_cash_price": "string",
  • "order_noncash_price": "string",
  • "order_tip": "string",
  • "order_total": "string",
  • "order_tax": "string",
  • "order_discount": "string",
  • "detail_order_notes": "string",
  • "trans": "string",
  • "line_items": "string",
  • "ttid": "string",
  • "property1": "string",
  • "property2": "string"
}

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.

libmonetra KVS equivalent for endpoint

  • action_admin = tran_detail
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/transaction/926572778835889' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "Y",
  • "card_signature_debit": "Y",
  • "card_token_card": "Y",
  • "auth": "string",
  • "batch": "string",
  • "issuer_decline": "Y",
  • "item": "string",
  • "stan": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "abaroute": "string",
  • "checknum": "string",
  • "accounttype": "BUSINESS",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "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",
  • "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",
  • "order_id": "string",
  • "payment_id": "string",
  • "order_cash_discount": "string",
  • "order_cash_price": "string",
  • "order_noncash_price": "string",
  • "order_tip": "string",
  • "order_total": "string",
  • "order_tax": "string",
  • "order_discount": "string",
  • "detail_order_notes": "string",
  • "trans": "string",
  • "line_items": "string",
  • "ttid": "string",
  • "property1": "string",
  • "property2": "string"
}

Get Transaction Details For Order Payment

Gets fine-grained detail about an order payment

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.

libmonetra KVS equivalent for endpoint

  • action_admin = tran_detail
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

payment_id
required
string

Unique ID of a payment for an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/transaction/order/17485767483/payment/7849345732' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "Y",
  • "card_signature_debit": "Y",
  • "card_token_card": "Y",
  • "auth": "string",
  • "batch": "string",
  • "issuer_decline": "Y",
  • "item": "string",
  • "stan": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "abaroute": "string",
  • "checknum": "string",
  • "accounttype": "BUSINESS",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "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",
  • "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",
  • "order_id": "string",
  • "payment_id": "string",
  • "order_cash_discount": "string",
  • "order_cash_price": "string",
  • "order_noncash_price": "string",
  • "order_tip": "string",
  • "order_total": "string",
  • "order_tax": "string",
  • "order_discount": "string",
  • "detail_order_notes": "string",
  • "trans": "string",
  • "line_items": "string",
  • "ttid": "string",
  • "property1": "string",
  • "property2": "string"
}

Transaction Receipts

Receipts can be generated for transactions, payments, and orders

Order receipts are special in that they can be sent to customers when open and before payment. This is the primary way to notify customers about a pending invoice. If the order is closed then the notification email or SMS message will allow the customer to view all payment receipts for the order.

Receipts can be generated for order payments using the order payment id instead of a linked ttid due to orders being able to accept check and cash payments as external transactions which are reported to the order system for reporting.

If the transaction is part of an order or if an order payment was referenced all line items will be included in the receipt.

Receipts can be pre-formatted, or emailed. Orders can be sent by email or SMS.

Email

Email of receipts will contain a formatted receipt.

SMS

SMS will contain a link to view the order and pay, or view receipts of the order is complete. The link will redirect to Monetra.

Pre-formatted

Pre-formatted receipts are generated as blocks the merchant can use to construct the receipts themselves. The blocks are generated from data that can be obtained using "Transaction Details" if the merchant wants the raw data to build receipts fully themself.

Email Transaction Receipt

Email a receipt for a transaction to the customer

libmonetra KVS equivalent for endpoint

  • action_admin = tran_receipt
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

email
required
string

Email to send customer receipt copy to

Can be an email or customer if the transaction is linked to a customer and their email is on file

duplicate
object
Enum: "yes" "no"
Example: duplicate=no

Values:

  • yes - Requesting duplicate receipt copy
  • no - Requesting original receipt copy

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/transaction/926572778835889/receipt' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "property1": "string",
  • "property2": "string"
}

Email Transaction Receipt For Order Payment

Email a receipt for an order payment to a customer

Will send the receipt not a link to view the invoice.

libmonetra KVS equivalent for endpoint

  • action_admin = tran_receipt
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

payment_id
required
string

Unique ID of a payment for an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

email
required
string

Email to send customer receipt copy to

Can be an email or customer if the transaction is linked to a customer and their email is on file

duplicate
object
Enum: "yes" "no"
Example: duplicate=no

Values:

  • yes - Requesting duplicate receipt copy
  • no - Requesting original receipt copy
merch_copy
object
Enum: "yes" "no"
Example: merch_copy=yes

Values:

  • yes - Email merchant receipt to the merchant
  • no - Do not email merchant receipt to the merchant

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/transaction/order/17485767483/payment/7849345732/receipt' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "property1": "string",
  • "property2": "string"
}

Email an Invoice to Customer

Email a link to view the invoice to a customer

The message will indicate the invoice is open and awaiting payment. The link will take the customer to the payment server where they can make payment.

The message will indicate the invoice is closed. The link will take the customer to the payment server where they can view payment receipts.

libmonetra KVS equivalent for endpoint

  • action_admin = tran_receipt
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

email
required
string

Email to send customer receipt copy to

Can be an email or customer if the transaction is linked to a customer and their email is on file

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/transaction/order/17485767483/receipt/email?email=customer' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "property1": "string",
  • "property2": "string"
}

Get Transaction Receipt

Get Pre-formatted receipt for a transaction

Gets pre-formatted receipt output that can be provided to a customer. When pre-formatted output is returned it will take the form rcpt_cust_*, rcpt_mercht_* for the various parts of the customer and merchant copy. If more than one format is requested for output then the response fields will take the form rcpt_<FORMAT_TYPE>_cust_* and rcpt_<FORMAT_TYPE>_merch_*.

The following receipt blocks may be returned based on the transaction.

  • *_merch_info - Merchant contact information
  • *_reference - Information about the transaction
  • *_items - Line items if part of an invoice or order
  • *_money - Money related to the transaction. Amount, tip, discounts, etc
  • *_disposition - Transaction outcome
  • *_signature - Blank signature line
  • *_emv - EMV card information
  • *_notice - Notice to customer they should keep the receipt for their records
  • *_notes - Notes associated with an order or invoice

Merchants using pre-formatted receipt output can augment the receipt with additional data the merchant feels is needed. Additional data is the responsibility of the merchant as to how they will include it on the receipt.

libmonetra KVS equivalent for endpoint

  • action_admin = tran_receipt
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

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 40.
  • 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.

Cannot be combined with:

  • email
duplicate
object
Enum: "yes" "no"
Example: duplicate=no

Values:

  • yes - Requesting duplicate receipt copy
  • no - Requesting original receipt copy
merch_copy
object
Enum: "yes" "no"
Example: merch_copy=yes

Values:

  • yes - Email merchant receipt to the merchant
  • no - Do not email merchant receipt to the merchant

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/transaction/926572778835889/receipt' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "property1": "string",
  • "property2": "string"
}

Get Transaction Receipt For Order Payment

Get Pre-formatted receipt for an order payment

Gets pre-formatted receipt output that can be provided to a customer. When pre-formatted output is returned it will take the form rcpt_cust_*, rcpt_mercht_* for the various parts of the customer and merchant copy. If more than one format is requested for output then the response fields will take the form rcpt_<FORMAT_TYPE>_cust_* and rcpt_<FORMAT_TYPE>_merch_*.

The following receipt blocks may be returned based on the transaction.

  • *_merch_info - Merchant contact information
  • *_reference - Information about the transaction
  • *_items - Line items if part of an invoice or order
  • *_money - Money related to the transaction. Amount, tip, discounts, etc
  • *_disposition - Transaction outcome
  • *_signature - Blank signature line
  • *_emv - EMV card information
  • *_notice - Notice to customer they should keep the receipt for their records
  • *_notes - Notes associated with an order or invoice

Merchants using pre-formatted receipt output can augment the receipt with additional data the merchant feels is needed. Additional data is the responsibility of the merchant as to how they will include it on the receipt.

libmonetra KVS equivalent for endpoint

  • action_admin = tran_receipt
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

payment_id
required
string

Unique ID of a payment for an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

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 40.
  • 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.
duplicate
object
Enum: "yes" "no"
Example: duplicate=no

Values:

  • yes - Requesting duplicate receipt copy
  • no - Requesting original receipt copy
merch_copy
object
Enum: "yes" "no"
Example: merch_copy=yes

Values:

  • yes - Email merchant receipt to the merchant
  • no - Do not email merchant receipt to the merchant

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/transaction/order/17485767483/payment/7849345732/receipt' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "property1": "string",
  • "property2": "string"
}

SMS an Invoice to Customer

SMS a link to view the invoice to a customer

The message will indicate the invoice is open and awaiting payment. The link will take the customer to the payment server where they can make payment.

The message will indicate the invoice is closed. The link will take the customer to the payment server where they can view payment receipts.

libmonetra KVS equivalent for endpoint

  • action_admin = tran_receipt
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

sms
required
string

Send SMS for order invoices

Can be an phone number or customer if the transaction is linked to a customer and their phone number is on file. Only US and Canada phone numbers are supported.

Requires:

  • order_id

Cannot be combined with:

  • ttid
  • payment_id

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/transaction/order/17485767483/receipt/sms?sms=customer' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "property1": "string",
  • "property2": "string"
}

Transaction Reports

Transaction Report operations

List Declined Transactions

Lists all failed transactions for the requested profile

The resulting report will contain these headers:

user, ttid, msoft_code, phard_code, type, proc, entrymode, txnstatus,
tranflags, capture, reversible, card, pclevel, cardlevel, abaroute, account,
expdate, checknum, timestamp, last_modified_ts, accounttype, reasoncode,
amount, reqamount, orig_authamount, authamount, examount, tax, cashback,
authnum, stan, batch, item, code, verbiage, cardholdername, avs, cv, clerkid,
stationid, comments, divisionnum, promoid, descmerch, descloc, ptrannum,
ordernum, custref, discountamount, freightamount, dutyamount, shipzip,
shipcountry, l3num, bdate, edate, roomnum, excharges, rate, customer_id, token,
order_id, surchargeamount, accounting_id

Additional columns may be present if profile custom fields are in use.

libmonetra KVS equivalent for endpoint

  • action_admin = report_tran
  • txnstatus = DECLINED
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

acct
string

Account number for auditing

Note: Only the last four digits of the card should be sent

amount
string
Example: amount=19.92

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

bdate
string

Start of date range

edate
string

End of date range

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder

cardtypes
object
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "BML" "GIFT" "VISADEBIT" "MCDEBIT" "OTHERDEBIT" "EBT" "CHECK" "INTERAC" "CUP" "PAYPALEC" "ACH"
Example: cardtypes=VISA|MC

Cardtypes

Pipe (|) separated.

Cardtype support is dependant on the processor. Not all processor support all cardtypes.

Flag values (pipe separated):

  • VISA - Visa credit
  • MC - Mastercard credit
  • AMEX - American Express credit
  • DISC - Discover credit
  • DINERS - Diners credit
  • JCB - JCB credit. Formerly Japan Credit Bureau
  • BML - Bill me later
  • GIFT - Private label Gift. Not cards backed by a credit card brand such as Visa, Mastercard, etc.
  • VISADEBIT - Visa debit
  • MCDEBIT - Mastercard debit
  • OTHERDEBIT - Debit not Visa or Mastercard
  • EBT - Electronic Benefits Transfer
  • CHECK - Paper checks
  • INTERAC - Interac (Canadian debit)
  • CUP - China Union Pay credit
  • PAYPALEC - PayPal Express Checkout token
  • ACH - Bank transfer
clerkid
string

Identifier for the clerk running the transaction

comments
string

User-defined comments related to the transaction

ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to Monetra, an order number should be sent on all transactions.

Normally, an order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

stationid
string
Example: stationid=7

Identifier for the physical station running the transaction

type
string
Example: type=sale

Type of action that was taken.

Can be a pipe (|) separated list of actions

last_modified_bdate
string

Used to filter report by date range. This is the beginning date as most recently modified for a transaction, not the bdate that was originally entered.

last_modified_edate
string

Used to filter report by date range. This is the ending date as most recently modified for a transaction, not the edate that was originally entered.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/report/declined' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

List Settled Transactions

Lists all settled transactions for the requested profile

The resulting report will contain these headers:

user, ttid, msoft_code, phard_code, type, proc, entrymode, txnstatus,
tranflags, capture, reversible, card, pclevel, cardlevel, abaroute, account,
expdate, checknum, timestamp, last_modified_ts, accounttype, reasoncode,
amount, reqamount, orig_authamount, authamount, examount, tax, cashback,
authnum, stan, batch, item, code, verbiage, cardholdername, avs, cv, clerkid,
stationid, comments, divisionnum, promoid, descmerch, descloc, ptrannum,
ordernum, custref, discountamount, freightamount, dutyamount, shipzip,
shipcountry, l3num, bdate, edate, roomnum, excharges, rate, customer_id, token,
order_id, surchargeamount, accounting_id

libmonetra KVS equivalent for endpoint

  • action_admin = report_tran
  • txnstatus = COMPLETE
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

acct
string

Account number for auditing

Note: Only the last four digits of the card should be sent

amount
string
Example: amount=19.92

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

batch
string

The batch number associated with the transaction

bdate
string

Start of date range

edate
string

End of date range

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder

cardtypes
object
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "BML" "GIFT" "VISADEBIT" "MCDEBIT" "OTHERDEBIT" "EBT" "CHECK" "INTERAC" "CUP" "PAYPALEC" "ACH"
Example: cardtypes=VISA|MC

Cardtypes

Pipe (|) separated.

Cardtype support is dependant on the processor. Not all processor support all cardtypes.

Flag values (pipe separated):

  • VISA - Visa credit
  • MC - Mastercard credit
  • AMEX - American Express credit
  • DISC - Discover credit
  • DINERS - Diners credit
  • JCB - JCB credit. Formerly Japan Credit Bureau
  • BML - Bill me later
  • GIFT - Private label Gift. Not cards backed by a credit card brand such as Visa, Mastercard, etc.
  • VISADEBIT - Visa debit
  • MCDEBIT - Mastercard debit
  • OTHERDEBIT - Debit not Visa or Mastercard
  • EBT - Electronic Benefits Transfer
  • CHECK - Paper checks
  • INTERAC - Interac (Canadian debit)
  • CUP - China Union Pay credit
  • PAYPALEC - PayPal Express Checkout token
  • ACH - Bank transfer
clerkid
string

Identifier for the clerk running the transaction

comments
string

User-defined comments related to the transaction

pclevel
object
Enum: "0" "1" "2"
Example: pclevel=0

Indicates the level of payment card

Values:

  • 0 - Consumer card
  • 1 - Business card
  • 2 - Corporate or purchase card
ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to Monetra, an order number should be sent on all transactions.

Normally, an order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

stationid
string
Example: stationid=7

Identifier for the physical station running the transaction

ttid
string

Transaction identifier

token
string

Filter based on token. Can be yes to only show tokens, no to not show any tokens, or a stored accont token id to only show transactions for the specified token.

type
string
Example: type=sale

Type of action that was taken.

Can be a pipe (|) separated list of actions

last_modified_bdate
string

Used to filter report by date range. This is the beginning date as most recently modified for a transaction, not the bdate that was originally entered.

last_modified_edate
string

Used to filter report by date range. This is the ending date as most recently modified for a transaction, not the edate that was originally entered.

user
string

User name used to limit results of report to only the specified user

interchange
object
Enum: "yes" "no"
Example: interchange=yes

Include interchange response data

This is has very limited use because interchange data is not necessary in the vast majority of circumstances.

Receiving interchange data is highly restricted and not accessible to most accounts.

Values:

  • yes - Include interchange response data
  • no - Do not include interchange response data
showvoids
object
Enum: "yes" "no" "only"
Example: showvoids=yes

Whether or not the report should include voids

Values:

  • yes - Include voided transactions
  • no - Do not include voided transactions
  • only - Only show voided transactions
reversible
object
Enum: "yes" "no"
Example: reversible=yes

Whether or not the report should include reversible transactions

If not present, show both reversible and non-reversible transactions

Values:

  • yes - Include reversible transactions
  • no - Do not include reversible transactions

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/report/settled' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

List Transactions

Lists all transactions for the requested profile

This allows combining multiple transaction status. For example, generating a report of only transactions that have sensitive data and are settled.

The resulting report will contain these headers:

user, ttid, msoft_code, phard_code, type, proc, entrymode, txnstatus,
tranflags, capture, reversible, card, pclevel, cardlevel, abaroute, account,
expdate, checknum, timestamp, last_modified_ts, accounttype, reasoncode,
amount, reqamount, orig_authamount, authamount, examount, tax, cashback,
authnum, stan, batch, item, code, verbiage, cardholdername, avs, cv, clerkid,
stationid, comments, divisionnum, promoid, descmerch, descloc, ptrannum,
ordernum, custref, discountamount, freightamount, dutyamount, shipzip,
shipcountry, l3num, bdate, edate, roomnum, excharges, rate, customer_id, token,
order_id, surchargeamount, accounting_id

libmonetra KVS equivalent for endpoint

  • action_admin = report_tran
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

txnstatus
required
object
Enum: "DECLINED" "UNCAPTURED" "CAPTURED" "COMPLETE" "VOIDED" "ONLINE" "SENSITIVEDATA"
Example: txnstatus=DECLINED

Pipe (|) separated list of flags that describe the current status of the transaction

Flag values (pipe separated):

  • DECLINED - Transaction has been declined
  • UNCAPTURED - Transaction is in the unsettled and uncaptured state
  • CAPTURED - Transaction is in the unsettled, but captured (ready for settlement) state
  • COMPLETE - Transaction is complete (settled or voided)
  • VOIDED - Transaction has been voided/reversed
  • ONLINE - The transaction went out to the processing institution
  • SENSITIVEDATA - The transaction still contains sensitive data on file
acct
string

Account number for auditing

Note: Only the last four digits of the card should be sent

amount
string
Example: amount=19.92

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

batch
string

The batch number associated with the transaction

bdate
string

Start of date range

edate
string

End of date range

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder

cardtypes
object
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "BML" "GIFT" "VISADEBIT" "MCDEBIT" "OTHERDEBIT" "EBT" "CHECK" "INTERAC" "CUP" "PAYPALEC" "ACH"
Example: cardtypes=VISA|MC

Cardtypes

Pipe (|) separated.

Cardtype support is dependant on the processor. Not all processor support all cardtypes.

Flag values (pipe separated):

  • VISA - Visa credit
  • MC - Mastercard credit
  • AMEX - American Express credit
  • DISC - Discover credit
  • DINERS - Diners credit
  • JCB - JCB credit. Formerly Japan Credit Bureau
  • BML - Bill me later
  • GIFT - Private label Gift. Not cards backed by a credit card brand such as Visa, Mastercard, etc.
  • VISADEBIT - Visa debit
  • MCDEBIT - Mastercard debit
  • OTHERDEBIT - Debit not Visa or Mastercard
  • EBT - Electronic Benefits Transfer
  • CHECK - Paper checks
  • INTERAC - Interac (Canadian debit)
  • CUP - China Union Pay credit
  • PAYPALEC - PayPal Express Checkout token
  • ACH - Bank transfer
clerkid
string

Identifier for the clerk running the transaction

comments
string

User-defined comments related to the transaction

pclevel
object
Enum: "0" "1" "2"
Example: pclevel=0

Indicates the level of payment card

Values:

  • 0 - Consumer card
  • 1 - Business card
  • 2 - Corporate or purchase card
ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to Monetra, an order number should be sent on all transactions.

Normally, an order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

stationid
string
Example: stationid=7

Identifier for the physical station running the transaction

ttid
string

Transaction identifier

token
string

Filter based on token. Can be yes to only show tokens, no to not show any tokens, or a stored accont token id to only show transactions for the specified token.

type
string
Example: type=sale

Type of action that was taken.

Can be a pipe (|) separated list of actions

last_modified_bdate
string

Used to filter report by date range. This is the beginning date as most recently modified for a transaction, not the bdate that was originally entered.

last_modified_edate
string

Used to filter report by date range. This is the ending date as most recently modified for a transaction, not the edate that was originally entered.

user
string

User name used to limit results of report to only the specified user

interchange
object
Enum: "yes" "no"
Example: interchange=yes

Include interchange response data

This is has very limited use because interchange data is not necessary in the vast majority of circumstances.

Receiving interchange data is highly restricted and not accessible to most accounts.

Values:

  • yes - Include interchange response data
  • no - Do not include interchange response data

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/report' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

List Unsettled Transactions

Lists all unsettled transactions for the requested profile

This is useful for monitoring which transactions have yet to be Settled.

The resulting report will contain these headers:

user, ttid, msoft_code, phard_code, type, proc, entrymode, txnstatus,
tranflags, capture, reversible, card, pclevel, cardlevel, abaroute, account,
expdate, checknum, timestamp, last_modified_ts, accounttype, reasoncode,
amount, reqamount, orig_authamount, authamount, examount, tax, cashback,
authnum, stan, batch, item, code, verbiage, cardholdername, avs, cv, clerkid,
stationid, comments, divisionnum, promoid, descmerch, descloc, ptrannum,
ordernum, custref, discountamount, freightamount, dutyamount, shipzip,
shipcountry, l3num, bdate, edate, roomnum, excharges, rate, customer_id, token,
order_id, surchargeamount, accounting_id

libmonetra KVS equivalent for endpoint

  • action_admin = report_tran
  • txnstatus = CAPTURED|UNCAPTURED
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

acct
string

Account number for auditing

Note: Only the last four digits of the card should be sent

amount
string
Example: amount=19.92

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

batch
string

The batch number associated with the transaction

bdate
string

Start of date range

edate
string

End of date range

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder

cardtypes
object
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "BML" "GIFT" "VISADEBIT" "MCDEBIT" "OTHERDEBIT" "EBT" "CHECK" "INTERAC" "CUP" "PAYPALEC" "ACH"
Example: cardtypes=VISA|MC

Cardtypes

Pipe (|) separated.

Cardtype support is dependant on the processor. Not all processor support all cardtypes.

Flag values (pipe separated):

  • VISA - Visa credit
  • MC - Mastercard credit
  • AMEX - American Express credit
  • DISC - Discover credit
  • DINERS - Diners credit
  • JCB - JCB credit. Formerly Japan Credit Bureau
  • BML - Bill me later
  • GIFT - Private label Gift. Not cards backed by a credit card brand such as Visa, Mastercard, etc.
  • VISADEBIT - Visa debit
  • MCDEBIT - Mastercard debit
  • OTHERDEBIT - Debit not Visa or Mastercard
  • EBT - Electronic Benefits Transfer
  • CHECK - Paper checks
  • INTERAC - Interac (Canadian debit)
  • CUP - China Union Pay credit
  • PAYPALEC - PayPal Express Checkout token
  • ACH - Bank transfer
clerkid
string

Identifier for the clerk running the transaction

comments
string

User-defined comments related to the transaction

pclevel
object
Enum: "0" "1" "2"
Example: pclevel=0

Indicates the level of payment card

Values:

  • 0 - Consumer card
  • 1 - Business card
  • 2 - Corporate or purchase card
ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to Monetra, an order number should be sent on all transactions.

Normally, an order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

stationid
string
Example: stationid=7

Identifier for the physical station running the transaction

ttid
string

Transaction identifier

token
string

Filter based on token. Can be yes to only show tokens, no to not show any tokens, or a stored accont token id to only show transactions for the specified token.

type
string
Example: type=sale

Type of action that was taken.

Can be a pipe (|) separated list of actions

last_modified_bdate
string

Used to filter report by date range. This is the beginning date as most recently modified for a transaction, not the bdate that was originally entered.

last_modified_edate
string

Used to filter report by date range. This is the ending date as most recently modified for a transaction, not the edate that was originally entered.

user
string

User name used to limit results of report to only the specified user

interchange
object
Enum: "yes" "no"
Example: interchange=yes

Include interchange response data

This is has very limited use because interchange data is not necessary in the vast majority of circumstances.

Receiving interchange data is highly restricted and not accessible to most accounts.

Values:

  • yes - Include interchange response data
  • no - Do not include interchange response data

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/report/unsettled' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Chart Data

Chart data is used to generate breakdowns over time in order to visualize statical information.

The chats provide buckets based on time segments over a given time period. Each bucket will have the number of the charted data in order to generate graphs.

Card Type Chart Data

Totals for card types used to generate charts

The resulting report will contain these headers:

cardtype count

libmonetra KVS equivalent for endpoint

  • action_admin = report_chartdata
  • chartdata = cardtype
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

bdate
required
string

Start of date range

edate
required
string

End of date range

grouping
required
object
Enum: "hour" "day"
Example: grouping=day

Group chart data within a time period

Grouping allows fine or course grained details about the data requested.

Values:

  • hour - Report is an hourly breakdown
  • day - report is a daily breakdown

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/report/chartdata/carddtype?bdate=-2%20days&edate=now' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Order Chart Data

Totals for orders used to generate charts

The resulting report will contain these headers:

ts_begin, ts_end, sale_count, sale_amount, return_count, return_amount

libmonetra KVS equivalent for endpoint

  • action_admin = report_chartdata
  • chartdata = orders
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

bdate
required
string

Start of date range

edate
required
string

End of date range

grouping
required
object
Enum: "hour" "day"
Example: grouping=day

Group chart data within a time period

Grouping allows fine or course grained details about the data requested.

Values:

  • hour - Report is an hourly breakdown
  • day - report is a daily breakdown

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/report/chartdata/orders?bdate=-2%20days&edate=now' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Transaction Chart Data

Totals for transactions used to generate charts

The resulting report will contain these headers:

ts_begin, ts_end, sale_count, sale_amount, return_count, return_amount, failed_count

libmonetra KVS equivalent for endpoint

  • action_admin = report_chartdata
  • chartdata = transactions
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

bdate
required
string

Start of date range

edate
required
string

End of date range

grouping
required
object
Enum: "hour" "day"
Example: grouping=day

Group chart data within a time period

Grouping allows fine or course grained details about the data requested.

Values:

  • hour - Report is an hourly breakdown
  • day - report is a daily breakdown

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/report/chartdata/transactions?bdate=-2%20days&edate=now' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Level 3

Level 3 processing (aka Enhanced Processing) is a feature specifically designed for processing commercial cards and government purchasing cards within a business to business and/or business to government environment. In order to process Level 3 transactions successfully, you must be able to supply detailed line item information to complete the transaction. The required line item details are basically the same as the details a customer might see on an invoice such as: products purchased, SKU numbers, descriptions, quantities, etc.

Limitations

Both Visa and Mastercard are currently supported for passing Level 3 details. While all Visa and Mastercard Corporate/Business/Purchase cards will allow Level3 data to be sent, on Visa, only Purchase cards will provide interchange rate reductions. Other card brands do not support Level 3 line items and will not provide a rate reduction.

Not all processors support Level 3 line items.

Adding line items

If manually adding Level 3 line items, they are added to a transaction after authorization using the ttid from the transaction.

Line items will be automatically added in the when using the Monetra order system. As long as the line items in the order contain all required information for Level 3 line items. This includes items from Monetra's inventory system or custom order line items. This only applies when a transaction is associated with an order before settlement.

A transaction can be associated in two ways:

  • Manually, using the order payment system
  • Automatically, by sending order_id with the purchase or pre-authorization

Line item pre-populate

Profiles can be configured with pre-populated, default, Level 3 line items. The relevant information is configured on the profile. The default values will be used to create a single line item added to the transaction. This is intended for merchants that routinely sell a single item and is a convince to simplify this common type of integration.

If manual line items are added either manually or via an order, they will be used instead of the pre-populate default values. If the transaction contains more than the default item, or additional items, the integration must send the line items that are actually part of the transaction.

List Line Items

Retrieves a list of Level 3 line items associated with an unsettled transaction

The resulting report will contain these headers:

l3id, ttid, commoditycode, description, productcode, qty, unit, unitprice,
discountamount, discountrate, amount

libmonetra KVS equivalent for endpoint

  • action_admin = level3
  • level3 = list
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/level3/926660343286234' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Line Item

Adds Level 3 line item to an unsettled transaction

libmonetra KVS equivalent for endpoint

  • action_admin = level3
  • level3 = add
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

commoditycode
required
string[0-9a-zA-Z]{8,12}

Contains an international description code of the individual good or service being supplied

The acquiring bank or processor should provide the merchant an updated listing of currently defined codes. Please note that this is different from the 4-character summary commodity code. Codes can be found online at http://www.unspsc.org

The code itself will not be validated; only the format is validated.

description
required
string[0-9a-zA-Z ]{1,26}

Merchant-defined description of the item or service being sold

This is a free-form field.

productcode
required
string[0-9a-zA-Z ]{1,12}

Merchant-defined code for the item being purchased, such as a UPC #, SKU #, or Item #

qty
required
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

unit
required
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

unitprice
required
string

Item price per Unit

Must not reflect any duty, freight, discount, or tax. This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum amount is 0.00005. Maximum amount is 9999999.99.

discountamount
string

Discount amount per line item

The total discount amount applied against the line item total. This field allows up to 2 decimal places of precision. The sum of all line item discounts must be less than or equal to the transaction's discount amount. If a discount was applied to this line item, this field must be populated.

Minimum amount is 0.00. Maximum amount is 9999999.99.

discountrate
string

Discount rate per line item

The discount rate applied against the line item. This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded. This field appears to be optional. It is not valid to specify this if discount amount is not specified or is 0.

Minimum rate is 0.00. Maximum rate is 99.99.

amount
required
string

Line item total amount

This is the line item amount after all taxes and discounts have been applied (but not inclusive of duty or freight). This amount must be greater than or equal to (unitprice * qty) - discountamount. This amount has 2 decimal places of precision.

Minimum amount is 0.01. Maximum amount is 9999999.99.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "commoditycode": "string",
  • "description": "string",
  • "productcode": "string",
  • "qty": "string",
  • "unit": "string",
  • "unitprice": "string",
  • "discountamount": "string",
  • "discountrate": "string",
  • "amount": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "l3id": "string"
}

Delete Line Item

Deletes Level 3 line item from an unsettled transaction

libmonetra KVS equivalent for endpoint

  • action_admin = level3
  • level3 = del
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

l3id
required
string

ID associated with the Level 3 line item

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/level3/926660343286234/19266603985142159' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Line Item Details

Gets the specified line item for the transaction

libmonetra KVS equivalent for endpoint

  • action_admin = level3
  • level3 = list
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

l3id
required
string

ID associated with the Level 3 line item

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/level3/926660343286234/19266603985142159' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "l3id": "string",
  • "ttid": "string",
  • "commoditycode": "string",
  • "description": "string",
  • "productcode": "string",
  • "qty": "string",
  • "unit": "string",
  • "unitprice": "string",
  • "discountamount": "string",
  • "discountrate": "string",
  • "amount": "string"
}

Batch

Basic and advanced batch management operations.

Basic operations manual settlement and reports.

It is recommended to use automatic settlement instead of manual settlement. As it simplifies the settlement process and removed points of error. No one can forget to settle or forgets to retry settlement if it fails.

One case where manual settlement is necessary is if the profile is changing processing routes. Often transactions authorized by one processor can only be settled with that processor. In this case outstanding batches must be settled before the route change takes place.

More advanced operations are should be used with care and typically only after consultation, and confirmation with the processor.

Clear a Batch

Marks the batch as settled within Monetra without ever requesting funding

The transaction data in the batch is not sent to the processing institution. This should only be used if the processing institution has accepted the batch, but Monetra did not receive the response.

This must only be used after the processing institution has confirmed they've received the batch and they've instructed not sending it again.

WARNING: This function should be used with extreme caution as clearing a batch which the processing institution has not received will prevent funding of those transactions in the batch. It is imperative confirmation by the processor of funding will take place before using this action.

libmonetra KVS equivalent for endpoint

  • action_admin = batch_clear
Authorizations:
basic_authapikey_idapikey
path Parameters
batch
required
string

The batch number associated with the transaction

route_id
required
string

Processing route

More than one route ID may be associated with a profile. This can happen when split-routing is in use. The specific ID for the route being operated on must be specified in requests that accept route_id.

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Close a Batch

Close the currently open batch without sending it to the processor

This will force Monetra to start adding transactions to a new batch.

The closed batch will remain in an unsettled state and will not be sent to the processor. To settle a batch, which will send it to the processor to request funds, see "Settle Batch". This is different than clearing a batch.

Only one batch per settlement route can be open at a time. This request enables a Merchant to close a batch so as to prevent additional transactions from being added to it while preventing the batch from being sent online to the processor.

There is often no need to manually close a batch. Batches will be closed and opened per processor requirements and after settlement.

libmonetra KVS equivalent for endpoint

  • action_admin = batch_close
Authorizations:
basic_authapikey_idapikey
path Parameters
batch
required
string

The batch number associated with the transaction

route_id
required
string

Processing route

More than one route ID may be associated with a profile. This can happen when split-routing is in use. The specific ID for the route being operated on must be specified in requests that accept route_id.

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Settled Batch Totals

Gets an abbreviated 'batch totals' summary for each 'Settled' batch, within a given date range.

The resulting report will contain these headers:

batch, route_id, timestamp, totaltransNum, totaltransAmount, totalAuthNum,
totalAuthAmount, totalReturnNum, totalReturnAmount, totaltransExamount,
totalAuthExamount, totalReturnExamount, NumVisaAuth, AmntVisaAuth,
NumVisaReturn, AmntVisaReturn, NumVisaDSAuth, AmntVisaDSAuth, NumVisaDSReturn,
AmntVisaDSReturn, NumMCAuth, AmntMCAuth, NumMCReturn, AmntMCReturn,
NumDiscAuth, AmntDiscAuth, NumDiscReturn, AmntDiscReturn, NumCUPAuth,
AmntCUPAuth, NumCUPReturn, AmntCUPReturn, NumAmexAuth, AmntAmexAuth,
NumAmexReturn, AmntAmexReturn, NumDinersAuth, AmntDinersAuth, NumDinersReturn,
AmntDinersReturn, NumCBAuth, AmntCBAuth, NumCBReturn, AmntCBReturn, NumJCBAuth,
AmntJCBAuth, NumJCBReturn, AmntJCBReturn, NumGIFTAuth, AmntGIFTAuth,
NumGIFTReturn, AmntGIFTReturn, NumOtherAuth, AmntOtherAuth, NumOtherReturn,
AmntOtherReturn, NumDebitAuth, AmntDebitAuth, NumDebitReturn, AmntDebitReturn,
NumEBTAuth, AmntEBTAuth, NumEBTReturn, AmntEBTReturn, NumCheckAuth,
AmntCheckAuth, NumACHAuth, AmntACHAuth, NumACHReturn, AmntACHReturn,
NumUnknownAuth, AmntUnknownAuth, NumUnknownReturn, AmntUnknownReturn

libmonetra KVS equivalent for endpoint

  • action_admin = report_totals
  • report_totals = settled
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

batch
string

The batch number associated with the transaction

bdate
string

Start of date range

edate
string

End of date range

reversible
object
Enum: "yes" "no"
Example: reversible=yes

Whether or not the report should include reversible transactions

If not present, show both reversible and non-reversible transactions

Values:

  • yes - Include reversible transactions
  • no - Do not include reversible transactions

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/batch/totals/settled?bdate=-5%20days&edate=now' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Get Unsettled Batch Totals

Gets an abbreviated 'batch totals' summary for each 'Unsettled' batch.

The resulting report will contain these headers:

batch, route_id, status, totaltransNum, totaltransAmount, totalAuthNum,
totalAuthAmount, totalReturnNum, totalReturnAmount, totaltransExamount,
totalAuthExamount, totalReturnExamount, NumVisaAuth, AmntVisaAuth,
NumVisaReturn, AmntVisaReturn, NumVisaDSAuth, AmntVisaDSAuth, NumVisaDSReturn,
AmntVisaDSReturn, NumMCAuth, AmntMCAuth, NumMCReturn, AmntMCReturn,
NumDiscAuth, AmntDiscAuth, NumDiscReturn, AmntDiscReturn, NumCUPAuth,
AmntCUPAuth, NumCUPReturn, AmntCUPReturn, NumAmexAuth, AmntAmexAuth,
NumAmexReturn, AmntAmexReturn, NumDinersAuth, AmntDinersAuth, NumDinersReturn,
AmntDinersReturn, NumCBAuth, AmntCBAuth, NumCBReturn, AmntCBReturn, NumJCBAuth,
AmntJCBAuth, NumJCBReturn, AmntJCBReturn, NumGIFTAuth, AmntGIFTAuth,
NumGIFTReturn, AmntGIFTReturn, NumOtherAuth, AmntOtherAuth, NumOtherReturn,
AmntOtherReturn, NumDebitAuth, AmntDebitAuth, NumDebitReturn, AmntDebitReturn,
NumEBTAuth, AmntEBTAuth, NumEBTReturn, AmntEBTReturn, NumCheckAuth,
AmntCheckAuth, NumACHAuth, AmntACHAuth, NumACHReturn, AmntACHReturn,
NumUnknownAuth, AmntUnknownAuth, NumUnknownReturn, AmntUnknownReturn

libmonetra KVS equivalent for endpoint

  • action_admin = report_totals
  • report_totals = unsettled
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

batch
string

The batch number associated with the transaction

bdate
string

Start of date range

edate
string

End of date range

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/batch/totals/unsettled' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Renumber Single Batch

Change an individual batch's number.

This will not affect any other batch number or the batch counter. For example, an open batch is numbered 10. When that batch is settled, the next batch will be numbered 11. If batch 10 has its number set to 50 using this action, then the next batch will still be numbered 11. To also set the batch counter so that the next batch number will be incremented from the new batch number provided (to 50 in this example) see "Resequence Open Batch Numbers".

This action is relevant when batch numbers conflict, such as can happen when a merchant is attempting to fix a settlement issue with a processor.

Some notes to keep in mind when modifying a batch number:

Processors keep batch numbers for 7 days to check for duplicates. Batch numbers within that window should not be reused. It is probably wise to not reuse batch numbers within a 90-day window, so as to stay within the card brand's chargeback window to avoid an actual chargeback. Monetra will retain data on a settled batch until that batch number is used again, at which point it will be overwritten.

libmonetra KVS equivalent for endpoint

  • action_admin = batch_set
  • batch_set = renumber
Authorizations:
basic_authapikey_idapikey
path Parameters
batch
required
string

The batch number associated with the transaction

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

newbatch
required
string
route_id
string\d+

Processing route

More than one route ID may be associated with a profile. This can happen when split-routing is in use. The specific ID for the route being operated on must be specified in requests that accept route_id.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "newbatch": "string",
  • "route_id": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Resequence Open Batch Numbers

Set open batch numbering to the given value

This will have two effects on the batch number: it will change the open batch's number to the provided value, and it will set the batch counter to that same value. When the batch is then closed/settled, the batch number will be incremented for the new batch. For example, an open batch is numbered "10". When that batch is settled, the next batch will be numbered "11". If instead batch "10" has its number set to "50" using this action, then the next batch will be numbered "51". To only change a batch's number without affecting the numbering of any other batch, see "Renumber Single Batch".

This action is relevant when batch numbers conflict, such as can happen when a merchant is attempting to fix a settlement issue with a processor.

Some notes to keep in mind when modifying a batch number:

Processors keep batch numbers for 7 days to check for duplicates. Batch numbers within that window should not be reused. It is probably wise to not reuse batch numbers within a 90-day window, so as to stay within the card brand's chargeback window to avoid an actual chargeback. Monetra will retain data on a settled batch until that batch number is used again, at which point it will be overwritten.

libmonetra KVS equivalent for endpoint

  • action_admin = batch_set
  • batch_set = batchnum
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

batch
required
string\d+

The batch number associated with the transaction

route_id
string\d+

Processing route

More than one route ID may be associated with a profile. This can happen when split-routing is in use. The specific ID for the route being operated on must be specified in requests that accept route_id.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "batch": "string",
  • "route_id": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Settle Batch

Submits transactions for funding

To determine which route IDs are in use for the profile, the 'Unsettled Batch Totals' report can be used to determine which routes need to be settled.

This operation can be scheduled to run automatically using the scheduler. It is recommended to use the scheduler to automatically settle all closed and open batches instead of issuing this action manually.

libmonetra KVS equivalent for endpoint

  • action_trans = settle
Authorizations:
basic_authapikey_idapikey
path Parameters
batch
required
string

The batch number associated with the transaction

route_id
required
string

Processing route

More than one route ID may be associated with a profile. This can happen when split-routing is in use. The specific ID for the route being operated on must be specified in requests that accept route_id.

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Unsettle Batch

Marks a batch in Monetra as unsettled

This will allow the batch to be submitted for funding again. A batch should only be unsettled when the processor has confirmed that they did not receive the batch but it is showing as settled in Monetra. It is important that this action only be taken with confirmation from the processor that this should happen.

This will not unsettle with the processor. Any batches accepted by the processor will be funded regardless if they are rescinded via this action.

Warning: Rescinding and then settling again will most likely cause double charging of customers. It is imperative to confirm with the processor a batch marked as settled will not be funded unless rescinded and settled.

libmonetra KVS equivalent for endpoint

  • action_admin = batch_rescind
Authorizations:
basic_authapikey_idapikey
path Parameters
batch
required
string

The batch number associated with the transaction

route_id
required
string

Processing route

More than one route ID may be associated with a profile. This can happen when split-routing is in use. The specific ID for the route being operated on must be specified in requests that accept route_id.

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Image

Image operations

Delete Check

Delete a check image

libmonetra KVS equivalent for endpoint

  • action_admin = image_del
  • image_type = check
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/image/19538953454/check' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Store Check

Stores a check image

libmonetra KVS equivalent for endpoint

  • action_admin = image_add
  • image_type = check
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

image
required
string[a-zA-Z0-9+/\n]+={0,2}[\n]*

Base64-encoded image data. Supports TIFF, PNG and PBM formats.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "image": "ABC="
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Delete Signature

Delete a signature image

libmonetra KVS equivalent for endpoint

  • action_admin = image_del
  • image_type = signature
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/image/19538953454/signature' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Store Signature

Stores a signature.

Typically used for receipts

libmonetra KVS equivalent for endpoint

  • action_admin = image_add
  • image_type = signature
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

image
required
string[a-zA-Z0-9+/\n]+={0,2}[\n]*

Base64-encoded image data. Supports TIFF, PNG and PBM formats.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "image": "ABC="
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Images

Gets images for the specified transaction.

See List Images for report output

libmonetra KVS equivalent for endpoint

  • action_admin = image_get
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

query Parameters
image_format
object
Enum: "TIFF" "PNG" "PBM"
Example: image_format=TIFF

Image format

Values:

  • TIFF - TIFF Image
  • PNG - PNG Image
  • PBM - PBM Image

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/image/4783758439245' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

List Images

Lists stored images

The resulting report will contain these headers:

ttid, ts, status, ptrannum, batch, image_type, image

libmonetra KVS equivalent for endpoint

  • action_admin = image_get
Authorizations:
basic_authapikey_idapikey
query Parameters
batch
string

The batch number associated with the transaction

status
object
Enum: "unsettled" "settled"
Example: status=unsettled

Transaction status

Values:

  • unsettled - Unsettled
  • settled - Settled
bdate
string

Start of date range

edate
string

End of date range

image_format
object
Enum: "TIFF" "PNG" "PBM"
Example: image_format=TIFF

Image format

Values:

  • TIFF - TIFF Image
  • PNG - PNG Image
  • PBM - PBM Image

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/image?bdate=-5%20months&edate=now' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Account Vault

The account vault allows for security storing customer accounts. Both cards and ACH information.

When storing an account it is recommended to tokenize the as part of a transaction instead of manually creating an entry. If no charge is taking place at the time, it is recommended to use the verification transaction to at least verify the card is valid.

Stored accounts can be referenced when processing transactions to charge the card. They can also be attached to a schedule for an installment or recurring payment. Additionally, they can be attached to a customer.

When working with customers in the customer system, a default_token can be associated with the customer for using the customer to process payments. Additionally a stored account can have a customer_id set to associate the account to a customer. A customer can have multiple stored accounts associated with them.

It is recommend that a zip code be added to the stored account to ensure proper interchange rates.

Remove Account

Permanently removes a stored account from the vault

libmonetra KVS equivalent for endpoint

  • action_admin = token_del
Authorizations:
basic_authapikey_idapikey
path Parameters
token
required
string

Referent to the account data that's been stored

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/vault/account/1719266678671633432' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Account Details

Gets details for the specified stored account

libmonetra KVS equivalent for endpoint

  • action_admin = token_list
Authorizations:
basic_authapikey_idapikey
path Parameters
token
required
string

Referent to the account data that's been stored

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/vault/account/1001709895560774683' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "token": "string",
  • "tokengroup_id": "string",
  • "create_profile_id": "string",
  • "create_ts": "string",
  • "update_ts": "string",
  • "type": "NORMAL",
  • "flags": "PROC_TOKEN",
  • "cardtype": "VISA",
  • "abaroute": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "expdate": "0129",
  • "cardholdername": "John Doe",
  • "descr": "string",
  • "clientref": "string",
  • "customer_id": "string",
  • "street": "91st St",
  • "zip": "32606",
  • "descmerch": "string",
  • "descloc": "string"
}

Edit Account

Edits a stored account

libmonetra KVS equivalent for endpoint

  • action_admin = token_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
token
required
string

Referent to the account data that's been stored

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

active
string
Enum: "yes" "no"

Token active status

Values:

  • yes - The token is active
  • no - The token is not active
object (_vault_account__token__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
  • Ticket
    • cardshieldticket
  • Token
    • token

Additional modifiers are also present which can provide information about how the data was received. For example, Cards and phones can be tapped in which case the rfid modifier needs 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.

street
string

Street address for AVS.

Typically, only numbers need to be passed in this field, as letters and other characters are ignored by the processor

zip
string <= 32 characters

Zip code for AVS verification. All Card Not Present transactions require this to avoid being 'downgraded'

clientref
string\d+

Reference number associated with the customer

matching_token
string
Enum: "yes" "no"

When enabled, the token vault will be searched for tokens matching this account. If found, the token will be updated instead of a new token being added.

Values:

  • yes - Try to match an existing token with this account
  • no - Do not try to match an existing token with this account
customer_id
string[0-9]+

Customer identifier, numeric only

cof_transid
string

Transaction ID from initial transaction

cof_authamount
string

Authorized amount from initial transaction

descr
string <= 128 characters

Description of the account

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "active": "yes",
  • "account_data": {
    },
  • "street": "1st St",
  • "zip": "32606",
  • "clientref": "string",
  • "matching_token": "yes",
  • "customer_id": "string",
  • "cof_transid": "string",
  • "cof_authamount": "string",
  • "descr": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Export Accounts

Export stored account tokens

Stored accounts are exported per group and are only exported encrypted. A PGP public key must be provided in order to encrypt the report data.

Stored account tokens can only be exported by users within the top most group. Users within a sub group cannot export stored accounts.

The resulting PGP encrypted data will contain a report which will contain these headers:

token, create_ts, update_ts, flags, status, cardtype, abaroute, account,
expdate, cardholdername, descr, clientref, customer_id, street, zip, descmerch,
descloc

libmonetra KVS equivalent for endpoint

  • action_su = token_export
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
pgp_pubkey
required
string

PGP public key

group_id
required
string\d+

Group identifier

Responses

Request samples

Content type
application/json
{
  • "pgp_pubkey": "string",
  • "group_id": "string"
}

Response samples

Content type
application/json
{
  • "datablock": "string"
}

Get Stored Account Count

Get count of stored accounts for the user's group

libmonetra KVS equivalent for endpoint

  • action_admin = token_list
  • token_list = count
Authorizations:
basic_authapikey_idapikey

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/vault/account/count' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "count": "string"
}

List Accounts

Lists stored account details

The resulting report will contain these headers:

token, tokengroup_id, create_profile_id, create_ts, update_ts, type, flags,
status, cardtype, abaroute, account, expdate, cardholdername, descr, clientref,
customer_id, au_ts, au_status, street, zip, descmerch, descloc

libmonetra KVS equivalent for endpoint

  • action_admin = token_list
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

active
object
Enum: "yes" "no"
Example: active=yes

Token active status

Values:

  • yes - The token is active
  • no - The token is not active
clientref
string

Reference number associated with the customer

id
string

Customer identifier

expdate_end
string

Maximum expiration date a card can have. Limit all expiration dates to before this time.

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder.

Will be read from account data (EMV, Track 1, etc.) but is not guaranteed to be present. Some presentation methods, such as keyed, do not have any way to capture the name as part of the account data.

Further, Visa explicitly does not allow the cardholder name to be transmitted as part of a contactless read. Typically, a contactless read will result in a cardholder name of "/".

If the name is known by another means, it can be entered in this parameter to override what was read (or not read) from the card.

cardtypes
object
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "BML" "GIFT" "VISADEBIT" "MCDEBIT" "OTHERDEBIT" "EBT" "CHECK" "INTERAC" "CUP" "PAYPALEC" "ACH"
Example: cardtypes=VISA|MC

Cardtypes

Pipe (|) separated.

Cardtype support is dependant on the processor. Not all processor support all cardtypes.

Flag values (pipe separated):

  • VISA - Visa credit
  • MC - Mastercard credit
  • AMEX - American Express credit
  • DISC - Discover credit
  • DINERS - Diners credit
  • JCB - JCB credit. Formerly Japan Credit Bureau
  • BML - Bill me later
  • GIFT - Private label Gift. Not cards backed by a credit card brand such as Visa, Mastercard, etc.
  • VISADEBIT - Visa debit
  • MCDEBIT - Mastercard debit
  • OTHERDEBIT - Debit not Visa or Mastercard
  • EBT - Electronic Benefits Transfer
  • CHECK - Paper checks
  • INTERAC - Interac (Canadian debit)
  • CUP - China Union Pay credit
  • PAYPALEC - PayPal Express Checkout token
  • ACH - Bank transfer
account
string

Last 4 digits of account number

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/vault/account?active=no&cardtypes=VISA%7CMC' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Store Account

Stores an account

Allows for manually tokenizing a payment method and storing it in the token vault. The token can be used for later transaction processing.

Note: Tokenization can happen at time of authorization or verification by using the tokenize=yes parameter as part of the transaction.

libmonetra KVS equivalent for endpoint

  • action_admin = token_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object (_vault_account_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
  • Ticket
    • cardshieldticket
  • Token
    • token

Additional modifiers are also present which can provide information about how the data was received. For example, Cards and phones can be tapped in which case the rfid modifier needs 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.

carddenylist_id
string\d+

ID in the card deny list

street
string

Street address for AVS.

Typically, only numbers need to be passed in this field, as letters and other characters are ignored by the processor

zip
string <= 32 characters

Zip code for AVS verification. All Card Not Present transactions require this to avoid being 'downgraded'

clientref
string\d+

Reference number associated with the customer

matching_token
string
Enum: "yes" "no"

When enabled, the token vault will be searched for tokens matching this account. If found, the token will be updated instead of a new token being added.

Values:

  • yes - Try to match an existing token with this account
  • no - Do not try to match an existing token with this account
customer_id
string[0-9]+

Customer identifier, numeric only

cof_transid
string

Transaction ID from initial transaction

cof_authamount
string

Authorized amount from initial transaction

descr
string <= 128 characters

Description of the account

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "carddenylist_id": "string",
  • "street": "1st St",
  • "zip": "32606",
  • "clientref": "string",
  • "matching_token": "yes",
  • "customer_id": "string",
  • "cof_transid": "string",
  • "cof_authamount": "string",
  • "descr": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "token": "string"
}

Scheduled Payments

Scheduled payments allow using a stored account to be charged on a configured period. Both recurring and installment payments are supported.

Scheduled payments are a schedule and instructions on how much, how often, and what to charge. They are linked to a stored account stored in Monetra. The stored account a schedule is using for the charge can be changed to a different account. This allows updating schedules without disrupting them.

List Installment Payments

Lists installment payment details

The resulting report will contain these headers:

id, token, create_ts, update_ts, type, flags, status, cardtype, account,
cardholdername, bdate, edate, frequency, installment_total, amount, last_run,
last_run_success, last_run_ttid, next_run, installment_num, total_paid, notes

Additional columns may be present if profile custom fields are in use.

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = list
  • type = installment
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

clientref
string

Reference number associated with the customer

customer_id
string

Customer identifier, numeric only

expdate_end
string

Maximum expiration date a card can have. Limit all expiration dates to before this time.

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder.

Will be read from account data (EMV, Track 1, etc.) but is not guaranteed to be present. Some presentation methods, such as keyed, do not have any way to capture the name as part of the account data.

Further, Visa explicitly does not allow the cardholder name to be transmitted as part of a contactless read. Typically, a contactless read will result in a cardholder name of "/".

If the name is known by another means, it can be entered in this parameter to override what was read (or not read) from the card.

cardtypes
object
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "BML" "GIFT" "VISADEBIT" "MCDEBIT" "OTHERDEBIT" "EBT" "CHECK" "INTERAC" "CUP" "PAYPALEC" "ACH"
Example: cardtypes=VISA|MC

Cardtypes

Pipe (|) separated.

Cardtype support is dependant on the processor. Not all processor support all cardtypes.

Flag values (pipe separated):

  • VISA - Visa credit
  • MC - Mastercard credit
  • AMEX - American Express credit
  • DISC - Discover credit
  • DINERS - Diners credit
  • JCB - JCB credit. Formerly Japan Credit Bureau
  • BML - Bill me later
  • GIFT - Private label Gift. Not cards backed by a credit card brand such as Visa, Mastercard, etc.
  • VISADEBIT - Visa debit
  • MCDEBIT - Mastercard debit
  • OTHERDEBIT - Debit not Visa or Mastercard
  • EBT - Electronic Benefits Transfer
  • CHECK - Paper checks
  • INTERAC - Interac (Canadian debit)
  • CUP - China Union Pay credit
  • PAYPALEC - PayPal Express Checkout token
  • ACH - Bank transfer
account
string

Last 4 digits of account number

status
object
Enum: "ACTIVE" "DISABLED" "ERROR" "DONE" "PENDING"
Example: status=ACTIVE

Status of scheduled payment

Values:

  • ACTIVE - Payment will process at the next scheduled time
  • DISABLED - Payment will not process at the next scheduled time. Payment can be re-activated to continue processing. If the RECURRING_SKIPMISSED flag is not set a catchup for all missed payments will take place.
  • ERROR - Payment will not process at the next scheduled time. Payment has failed in a way that corrective action must be taken. For example, account closed.
  • DONE - Payment will not process at the next scheduled time. Payment sequence has been completed based on configured schedule.
  • PENDING - Payment is enabled but has not processed any payments

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/vault/payment/installment?active=yes' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Installment Payment

Adds an installment payment

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = add
  • type = installment
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

customer_id
string[0-9]+

Customer identifier, numeric only

token
required
string\d+

Reference to the stored account that's being charged for the scheduled payment

clientref
string\d+

Reference number associated with the customer

cof_transid
string

Transaction ID from initial transaction

cof_authamount
string

Authorized amount from initial transaction

descr
string <= 128 characters

Description of the payment

bdate
string

Start of date range

installment_total
required
string\d+

Total number of installment payments to make

frequency
required
string
Enum: "daily" "weekly" "biweekly" "monthly" "bimonthly" "quarterly" "semiannually" "annually"

Frequency of payment

Values:

  • daily - Takes place every day
  • weekly - Takes place every week on the given day of week. Ex. Every Wednesday
  • biweekly - Takes place every two weeks on the given day. Ex. Every other Friday
  • monthly - Takes place every month on the given day of the month. If the day is after the last day of the month (e.g. 31st when the month only has 30 days), the last day of the month will be used for that month
  • bimonthly - Takes place every two months on the given day of the month
  • quarterly - Takes place every three months on the given day of the month
  • semiannually - Takes place every six months
  • annually - Takes place once a year
amount
required
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "customer_id": "string",
  • "token": "string",
  • "clientref": "string",
  • "cof_transid": "string",
  • "cof_authamount": "string",
  • "descr": "string",
  • "bdate": "string",
  • "installment_total": "string",
  • "frequency": "daily",
  • "amount": "19.92",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

List Recurring Payments

Lists recurring payment details

The resulting report will contain these headers:

id, token, create_ts, update_ts, type, flags, status, cardtype, account,
cardholdername, bdate, edate, frequency, installment_total, amount, last_run,
last_run_success, last_run_ttid, next_run, installment_num, total_paid, notes

Additional columns may be present if profile custom fields are in use.

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = list
  • type = recurring
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

clientref
string

Reference number associated with the customer

customer_id
string

Customer identifier, numeric only

expdate_end
string

Maximum expiration date a card can have. Limit all expiration dates to before this time.

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder.

Will be read from account data (EMV, Track 1, etc.) but is not guaranteed to be present. Some presentation methods, such as keyed, do not have any way to capture the name as part of the account data.

Further, Visa explicitly does not allow the cardholder name to be transmitted as part of a contactless read. Typically, a contactless read will result in a cardholder name of "/".

If the name is known by another means, it can be entered in this parameter to override what was read (or not read) from the card.

cardtypes
object
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "BML" "GIFT" "VISADEBIT" "MCDEBIT" "OTHERDEBIT" "EBT" "CHECK" "INTERAC" "CUP" "PAYPALEC" "ACH"
Example: cardtypes=VISA|MC

Cardtypes

Pipe (|) separated.

Cardtype support is dependant on the processor. Not all processor support all cardtypes.

Flag values (pipe separated):

  • VISA - Visa credit
  • MC - Mastercard credit
  • AMEX - American Express credit
  • DISC - Discover credit
  • DINERS - Diners credit
  • JCB - JCB credit. Formerly Japan Credit Bureau
  • BML - Bill me later
  • GIFT - Private label Gift. Not cards backed by a credit card brand such as Visa, Mastercard, etc.
  • VISADEBIT - Visa debit
  • MCDEBIT - Mastercard debit
  • OTHERDEBIT - Debit not Visa or Mastercard
  • EBT - Electronic Benefits Transfer
  • CHECK - Paper checks
  • INTERAC - Interac (Canadian debit)
  • CUP - China Union Pay credit
  • PAYPALEC - PayPal Express Checkout token
  • ACH - Bank transfer
account
string

Last 4 digits of account number

status
object
Enum: "ACTIVE" "DISABLED" "ERROR" "DONE" "PENDING"
Example: status=ACTIVE

Status of scheduled payment

Values:

  • ACTIVE - Payment will process at the next scheduled time
  • DISABLED - Payment will not process at the next scheduled time. Payment can be re-activated to continue processing. If the RECURRING_SKIPMISSED flag is not set a catchup for all missed payments will take place.
  • ERROR - Payment will not process at the next scheduled time. Payment has failed in a way that corrective action must be taken. For example, account closed.
  • DONE - Payment will not process at the next scheduled time. Payment sequence has been completed based on configured schedule.
  • PENDING - Payment is enabled but has not processed any payments

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/vault/payment/recurring?clientref=55' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Recurring Payment

Adds a recurring payment

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = add
  • type = recurring
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

token
required
string\d+

Reference to the stored account that's being charged for the scheduled payment

clientref
string\d+

Reference number associated with the customer

cof_transid
string

Transaction ID from initial transaction

cof_authamount
string

Authorized amount from initial transaction

descr
string <= 128 characters

Description of of the payment

bdate
string

Start of date range

edate
string

End of date range

frequency
required
string
Enum: "daily" "weekly" "biweekly" "monthly" "bimonthly" "quarterly" "semiannually" "annually"

Frequency of payment

Values:

  • daily - Takes place every day
  • weekly - Takes place every week on the given day of week. Ex. Every Wednesday
  • biweekly - Takes place every two weeks on the given day. Ex. Every other Friday
  • monthly - Takes place every month on the given day of the month. If the day is after the last day of the month (e.g. 31st when the month only has 30 days), the last day of the month will be used for that month
  • bimonthly - Takes place every two months on the given day of the month
  • quarterly - Takes place every three months on the given day of the month
  • semiannually - Takes place every six months
  • annually - Takes place once a year
amount
required
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "token": "string",
  • "clientref": "string",
  • "cof_transid": "string",
  • "cof_authamount": "string",
  • "descr": "string",
  • "bdate": "string",
  • "edate": "string",
  • "frequency": "daily",
  • "amount": "19.92",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Get Installment Payment Details

Gets details for the specified installment payment

Additional columns may be present if profile custom fields are in use.

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = list
  • type = installment
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Schedule ID

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/vault/payment/installment/1719266657160421715' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "token": "string",
  • "create_ts": "string",
  • "update_ts": "string",
  • "type": "NORMAL",
  • "flags": "PROC_TOKEN",
  • "status": "ACTIVE",
  • "cardtype": "VISA",
  • "account": "XXXXXXXXXXXX1234",
  • "cardholdername": "John Doe",
  • "bdate": "string",
  • "edate": "string",
  • "installment_total": "string",
  • "amount": "19.92",
  • "last_run": "string",
  • "last_run_success": "string",
  • "last_run_ttid": "string",
  • "next_run": "string",
  • "installment_num": "string",
  • "total_paid": "string",
  • "notes": "string",
  • "property1": "string",
  • "property2": "string"
}

Edit Installment Payment

Edits a stored installment payment

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = edit
  • type = installment
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Schedule ID

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

active
string
Enum: "yes" "no"

Token active status

Values:

  • yes - The token is active
  • no - The token is not active
customer_id
string[0-9]+

Customer identifier, numeric only

token
string\d+

Referent to the account data that's been stored

clientref
string\d+

Reference number associated with the customer

cof_transid
string

Transaction ID from initial transaction

cof_authamount
string

Authorized amount from initial transaction

descr
string <= 128 characters

Description of the payment

bdate
string

Start of date range

installment_total
string\d+

Total number of installment payments to make

frequency
string
Enum: "daily" "weekly" "biweekly" "monthly" "bimonthly" "quarterly" "semiannually" "annually"

Frequency of payment

Values:

  • daily - Takes place every day
  • weekly - Takes place every week on the given day of week. Ex. Every Wednesday
  • biweekly - Takes place every two weeks on the given day. Ex. Every other Friday
  • monthly - Takes place every month on the given day of the month. If the day is after the last day of the month (e.g. 31st when the month only has 30 days), the last day of the month will be used for that month
  • bimonthly - Takes place every two months on the given day of the month
  • quarterly - Takes place every three months on the given day of the month
  • semiannually - Takes place every six months
  • annually - Takes place once a year
amount
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "active": "yes",
  • "customer_id": "string",
  • "token": "string",
  • "clientref": "string",
  • "cof_transid": "string",
  • "cof_authamount": "string",
  • "descr": "string",
  • "bdate": "string",
  • "installment_total": "string",
  • "frequency": "daily",
  • "amount": "19.92",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Recurring Payment Detail

Gets details for the specified recurring payment

Additional columns may be present if profile custom fields are in use.

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = list
  • type = recurring
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Schedule ID

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/vault/payment/recurring/' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "token": "string",
  • "create_ts": "string",
  • "update_ts": "string",
  • "type": "NORMAL",
  • "flags": "PROC_TOKEN",
  • "status": "ACTIVE",
  • "cardtype": "VISA",
  • "account": "XXXXXXXXXXXX1234",
  • "cardholdername": "John Doe",
  • "bdate": "string",
  • "edate": "string",
  • "frequency": "daily",
  • "amount": "19.92",
  • "last_run": "string",
  • "last_run_success": "string",
  • "last_run_ttid": "string",
  • "next_run": "string",
  • "total_paid": "string",
  • "notes": "string",
  • "property1": "string",
  • "property2": "string"
}

Edit Recurring Payment

Edits a stored recurring payment

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = edit
  • type = recurring
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Schedule ID

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

active
string
Enum: "yes" "no"

Token active status

Values:

  • yes - The token is active
  • no - The token is not active
token
string\d+

Reference to the stored account that's being charged for the scheduled payment

clientref
string\d+

Reference number associated with the customer

cof_transid
string

Transaction ID from initial transaction

cof_authamount
string

Authorized amount from initial transaction

descr
string <= 128 characters

Description of of the payment

bdate
string

Start of date range

edate
string

End of date range

frequency
string
Enum: "daily" "weekly" "biweekly" "monthly" "bimonthly" "quarterly" "semiannually" "annually"

Frequency of payment

Values:

  • daily - Takes place every day
  • weekly - Takes place every week on the given day of week. Ex. Every Wednesday
  • biweekly - Takes place every two weeks on the given day. Ex. Every other Friday
  • monthly - Takes place every month on the given day of the month. If the day is after the last day of the month (e.g. 31st when the month only has 30 days), the last day of the month will be used for that month
  • bimonthly - Takes place every two months on the given day of the month
  • quarterly - Takes place every three months on the given day of the month
  • semiannually - Takes place every six months
  • annually - Takes place once a year
amount
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "active": "yes",
  • "token": "string",
  • "clientref": "string",
  • "cof_transid": "string",
  • "cof_authamount": "string",
  • "descr": "string",
  • "bdate": "string",
  • "edate": "string",
  • "frequency": "daily",
  • "amount": "19.92",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

List Payment History

Lists transactions that have been run by the recurring billing system

This includes both recurring and installment payments but does not include transactions run using stored accounts.

The resulting report will contain these headers:

user, ttid, msoft_code, phard_code, type, proc, entrymode, txnstatus,
tranflags, capture, reversible, card, pclevel, cardlevel, abaroute, account,
expdate, checknum, timestamp, last_modified_ts, accounttype, reasoncode,
amount, reqamount, orig_authamount, authamount, examount, tax, cashback,
authnum, stan, batch, item, code, verbiage, cardholdername, avs, cv, clerkid,
stationid, comments, divisionnum, promoid, descmerch, descloc, ptrannum,
ordernum, custref, discountamount, freightamount, dutyamount, shipzip,
shipcountry, l3num, bdate, edate, roomnum, excharges, rate, customer_id, token,
order_id, surchargeamount, accounting_id

libmonetra KVS equivalent for endpoint

  • action_admin = report_tran
  • token = yes
  • txnstatus = CAPTURED|UNCAPTURED|COMPLETE|DECLINED
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

bdate
string

Start of date range

edate
string

End of date range

token
string

Referent to the account data that's been stored

customer_id
string

Customer identifier, numeric only

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/vault/payment/history?bdate=-1%20year&edate=now' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Remove Stored Payment

Permanently removes a stored payment from the vault

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Schedule ID

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/vault/payment/1719266657160421715' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Card Deny List

The card deny list is an internal, merchant maintained, list of cards or ACH accounts the merchant is choosing not to accept.

Accounts can be added to the list two different ways:

  • Manually
  • Atomically when a transaction is online declined.
    • This will happen if the CARDDENYLIST_DECLINE profile flag is set
    • A transaction includes the carddenylist_decline flag set to yes

Accounts can be checked if they are on the card deny list two different ways:

  • Manually
  • Automatically when a transaction is attempted
    • This will happen if the CARDDENYLIST_CHECK profile flag is set
    • A transaction includes the carddenylist_check flag set to yes

List Deny List

Lists accounts on the card deny list

The resulting report will contain these headers:

id, last4, expdate, cardtype, added, last_seen,
expire, cardholdername, reason_code

libmonetra KVS equivalent for endpoint

  • action_admin = carddenylist
  • carddenylist = list
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

expdate_bdate
string

Used to filter report by card expiration date range. Expiration is when the card expires, the expdate parameter sent with account. This is the beginning date of the expiration date range to match.

expdate_edate
string

Used to filter report by card expiration date range. Expiration is when the card expires, the expdate parameter sent with account. This is the ending date of the expiration date range to match.

added_bdate
string

Used to filter report by added date range. This is the beginning date of the added date rate to match.

added_edate
string

Used to filter report by added date range. This is the ending date of the added date range to match.

last_seen_bdate
string

Used to filter report by last seen date range. This is the beginning date of the last seen date range to match.

last_seen_edate
string

Used to filter report by last seen date range. This is the ending date of the last seen date range to match.

expire_bdate
string

Used to filter report by expire date range

Expiration is when the entry in the list will be removed.

Coresponds expire parameter sent with an add operation. This is the beginning of the expire range to match."

expire_edate
string

Used to filter report by expire date range

Expiration is when the entry in the list should be removed.

Coresponds expire parameter sent with an add operation. This is the endinf of the expire range to match."

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/cardlist/deny' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add a card to the deny list

Add a card to the deny list

libmonetra KVS equivalent for endpoint

  • action_admin = carddenylist
  • carddenylist = add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object (_vault_account_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
  • Ticket
    • cardshieldticket
  • Token
    • token

Additional modifiers are also present which can provide information about how the data was received. For example, Cards and phones can be tapped in which case the rfid modifier needs 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.

reason_code
string
Default: "DECLINE"
Enum: "DECLINE" "TESTCARD" "CHARGEBACK"

Reason an account was added to the deny list

Values:

  • DECLINE - Due to decline
  • TESTCARD - Identified as a test card
  • CHARGEBACK - Due to receiving a chargeback
expire
string

How long to keep a card on file before being automatically removed

Standard date format accepted by the payment server. Can be a specific date to expire on or a relative data (E.g "+10 days").

Default is 180 days if not specified. Smallest amount of time allowed is 1 day. Anything shorter will be rounded up to 1 day.

The deny list is automatically cleaned up on a regular basis. Anything added to the list will have an expiration associated with it for how long it should be on the list. This expiration is different than the card's expiration date associated with the account number. This is how long the entry will remain in the list. It can be set to a very long time such as 50+ years.

Card expiration date is not used for removal for several reasons.

  1. Test cards do not have a "real" expiration date and should not necessarily be removed when the account expdate is reached.
  2. When cards are close to expiring the issuer will send new cards with an updated expdate but the same account number. A merchant may still want to deny these cards and a separate removal expiration is intended to handle this situation.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "reason_code": "DECLINE",
  • "expire": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "carddenylist_id": "string"
}

Check if card is on deny list

Check if account is on the card deny list

Will return details about the card if it is on the list.

No fields returned indicates it is not on the list. Use the presence of the id response key to determine if a record was found.

libmonetra KVS equivalent for endpoint

  • action_admin = carddenylist
  • carddenylist = list
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object (_vault_account_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
  • Ticket
    • cardshieldticket
  • Token
    • token

Additional modifiers are also present which can provide information about how the data was received. For example, Cards and phones can be tapped in which case the rfid modifier needs 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.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "last4": "string",
  • "expdate": "0129",
  • "cardtype": "VISA",
  • "added": "string",
  • "last_seen": "string",
  • "expire": "string",
  • "cardholdername": "John Doe",
  • "reason_code": "DECLINE"
}

Remove a card from the deny list

Remove a card from the deny list

libmonetra KVS equivalent for endpoint

  • action_admin = carddenylist
  • carddenylist = remove
Authorizations:
basic_authapikey_idapikey
path Parameters
carddenylist_id
required
string

ID in the card deny list

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/cardlist/deny/134543245543' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Card Details

Account detail for a card on the card deny list

libmonetra KVS equivalent for endpoint

  • action_admin = carddenylist
  • carddenylist = list
Authorizations:
basic_authapikey_idapikey
path Parameters
carddenylist_id
required
string

ID in the card deny list

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/cardlist/deny/143432' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "last4": "string",
  • "expdate": "0129",
  • "cardtype": "VISA",
  • "added": "string",
  • "last_seen": "string",
  • "expire": "string",
  • "cardholdername": "John Doe",
  • "reason_code": "DECLINE"
}

Customer

The Customer database is a limited Client Management System (CMS) with a focus on payments. It is not a full replacement for a dedicated CMS but is intended for smaller merchants that only need payment handling functionality of a CMS.

This system allows creating customer, managing metadata about the customer. For example, addresses, stored cards, and scheduled payments. Customer can optionally be utilized by Monetra's order system. This is to aid in creating and notification of invoices.

Larger business with an existing CMS are expected to use the Monetra customer database for helping manage customer payments. The external CMS would include the ID for the customer created in Monetra's system. The external CMS then be able to use the Monetra system to manage payment information and initiate transactions.

List Customers

Lists customers

The billing and shipping address information provided by the report are the customer's default addresses. They may not be present if no addresses were set as defaults.

The resulting report will contain these headers:

id, tokengroup_id, create_profile_id, ts_created, ts_modified, flags,
display_name, name_company, name_prefix, name_first, name_middle, name_last,
name_suffix, phone_work, phone_home, phone_mobile, phone_fax, email, website,
business_id, accounting_id, notes, default_billing_id, default_shipping_id,
default_token, billing_display_name, billing_address1, billing_address2,
billing_city, billing_state, billing_country, billing_postal_code,
billing_delivery_notes, shipping_display_name, shipping_address1,
shipping_address2, shipping_city, shipping_state, shipping_country,
shipping_postal_code, shipping_delivery_notes

Additional columns may be present if profile custom fields are in use.

libmonetra KVS equivalent for endpoint

  • action_admin = customer_list
  • customer_list = customer
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/customer' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Customer

Adds a customer to the customer database for the merchant or token group

libmonetra KVS equivalent for endpoint

  • action_admin = customer_add
  • customer_add = customer
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

display_name
required
string <= 128 characters

Display name

name_company
string <= 128 characters

Company name

name_prefix
string <= 32 characters

Name prefix, Mr. Mrs. Ms. Dr...

Free-form field

name_first
string <= 32 characters

First name

name_middle
string <= 32 characters

Middle name

name_last
string <= 32 characters

Last name

name_suffix
string <= 32 characters

Name suffix, Jr. Sr. III...

Free-form field

phone_work
string <= 32 characters [-+0-9() .]*

Work phone

phone_home
string <= 32 characters [-+0-9() .]*

Home phone

phone_mobile
string <= 32 characters [-+0-9() .]*

Mobile phone

phone_fax
string <= 32 characters [-+0-9() .]*

Fax number

email
string <= 128 characters

email

website
string <= 128 characters

Website

business_id
string <= 32 characters

Business ID - FEIN

accounting_id
string <= 128 characters

ID used in external accounting system for customer

notes
string <= 1024 characters

General free-form information

flags
string
Enum: "TAXEXEMPT" "EMAIL_RECEIPT_RECURRING"

flags controlling behavior

Values:

  • TAXEXEMPT - Customer is non-taxable
  • EMAIL_RECEIPT_RECURRING - Send receipt email for recurring transactions. The following conditions must be met for customers to receive recurring receipt emails. + This flag must be enabled. + Customer must have an email on file. + The merchant profile must have a name configured. + The merchant profile must have a public reply email configured.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "display_name": "string",
  • "name_company": "string",
  • "name_prefix": "string",
  • "name_first": "string",
  • "name_middle": "string",
  • "name_last": "string",
  • "name_suffix": "string",
  • "phone_work": "string",
  • "phone_home": "string",
  • "phone_mobile": "string",
  • "phone_fax": "string",
  • "email": "string",
  • "website": "string",
  • "business_id": "string",
  • "accounting_id": "string",
  • "notes": "string",
  • "flags": "TAXEXEMPT",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Delete Customer

Deletes a customer

WARNING: This will purge tokens associated with the customer! If tokens need to be retained, remove them from the customer before deleting.

libmonetra KVS equivalent for endpoint

  • action_admin = customer_del
  • customer_del = customer
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Customer identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/customer/19266575665036873' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Customer Details

Details for a specific customer

libmonetra KVS equivalent for endpoint

  • action_admin = customer_list
  • customer_list = customer
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Customer identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/customer/19266575665036873' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "tokengroup_id": "string",
  • "create_profile_id": "string",
  • "ts_created": "string",
  • "ts_modified": "string",
  • "flags": "TAXEXEMPT",
  • "display_name": "string",
  • "name_company": "string",
  • "name_prefix": "string",
  • "name_first": "string",
  • "name_middle": "string",
  • "name_last": "string",
  • "name_suffix": "string",
  • "phone_work": "string",
  • "phone_home": "string",
  • "phone_mobile": "string",
  • "phone_fax": "string",
  • "email": "string",
  • "website": "string",
  • "business_id": "string",
  • "accounting_id": "string",
  • "notes": "string",
  • "default_billing_id": "string",
  • "default_shipping_id": "string",
  • "default_token": "string",
  • "billing_display_name": "string",
  • "billing_address1": "string",
  • "billing_address2": "string",
  • "billing_city": "string",
  • "billing_state": "string",
  • "billing_country": "string",
  • "billing_postal_code": "string",
  • "billing_delivery_notes": "string",
  • "shipping_display_name": "string",
  • "shipping_address1": "string",
  • "shipping_address2": "string",
  • "shipping_city": "string",
  • "shipping_state": "string",
  • "shipping_country": "string",
  • "shipping_postal_code": "string",
  • "shipping_delivery_notes": "string",
  • "property1": "string",
  • "property2": "string"
}

Edit Customer

Edits an existing customer

libmonetra KVS equivalent for endpoint

  • action_admin = customer_edit
  • customer_edit = customer
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Customer identifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

display_name
string <= 128 characters

Display name

name_company
string <= 128 characters

Company name

name_prefix
string <= 32 characters

Name prefix, Mr. Mrs. Ms. Dr...

Free-form field

name_first
string <= 32 characters

First name

name_middle
string <= 32 characters

Middle name

name_last
string <= 32 characters

Last name

name_suffix
string <= 32 characters

Name suffix, Jr. Sr. III...

Free-form field

phone_work
string <= 32 characters [-+0-9() .]*

Work phone

phone_home
string <= 32 characters [-+0-9() .]*

Home phone

phone_mobile
string <= 32 characters [-+0-9() .]*

Mobile phone

phone_fax
string <= 32 characters [-+0-9() .]*

Fax number

email
string <= 128 characters

email

website
string <= 128 characters

Website

business_id
string <= 32 characters

Business ID - FEIN

accounting_id
string <= 128 characters

ID used in external accounting system for customer

notes
string <= 1024 characters

General free-form information

flags
string
Enum: "TAXEXEMPT" "EMAIL_RECEIPT_RECURRING"

flags controlling behavior

Values:

  • TAXEXEMPT - Customer is non-taxable
  • EMAIL_RECEIPT_RECURRING - Send receipt email for recurring transactions. The following conditions must be met for customers to receive recurring receipt emails. + This flag must be enabled. + Customer must have an email on file. + The merchant profile must have a name configured. + The merchant profile must have a public reply email configured.
default_token
string[0-9]*

Default token/payment to use

default_billing_id
string[0-9]+

Default ID of billing address in use from customer_addresses

0 means no default

default_shipping_id
string[0-9]+

Default ID of shipping address in use from customer_addresses

0 means no default

property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "display_name": "string",
  • "name_company": "string",
  • "name_prefix": "string",
  • "name_first": "string",
  • "name_middle": "string",
  • "name_last": "string",
  • "name_suffix": "string",
  • "phone_work": "string",
  • "phone_home": "string",
  • "phone_mobile": "string",
  • "phone_fax": "string",
  • "email": "string",
  • "website": "string",
  • "business_id": "string",
  • "accounting_id": "string",
  • "notes": "string",
  • "flags": "TAXEXEMPT",
  • "default_token": "string",
  • "default_billing_id": "string",
  • "default_shipping_id": "string",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

List Customer's Tokens

Lists all stored accounts associated with this customer

The resulting report will contain these headers:

token, tokengroup_id, create_profile_id, create_ts, update_ts, type, flags,
cardtype, abaroute, account, expdate, cardholdername, descr, clientref,
customer_id, street, zip, descmerch, descloc

libmonetra KVS equivalent for endpoint

  • action_admin = token_list
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Customer identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/customer/19266575665036873/tokens' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Customer Address

Customer address operations

List Customer Addresses

Lists a customer's addresses

The resulting report will contain these headers:

id, customer_id, display_name, address1, address2, city, state, country,
postal_code, delivery_notes

Additional fields may be present if profile custom fields are in use.

libmonetra KVS equivalent for endpoint

  • action_admin = customer_list
  • customer_list = customer_address
Authorizations:
basic_authapikey_idapikey
path Parameters
customer_id
required
string

Customer identifier, numeric only

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/customer/19266575665036873/address' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Customer Address

Adds an address to a customer

libmonetra KVS equivalent for endpoint

  • action_admin = customer_add
  • customer_add = customer_address
Authorizations:
basic_authapikey_idapikey
path Parameters
customer_id
required
string

Customer identifier, numeric only

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

display_name
string <= 128 characters

Display name

address1
required
string <= 128 characters

Address line 1

address2
string <= 128 characters

Address line 2

city
string <= 128 characters

City

state
string <= 128 characters

State

country
string <= 3 characters [a-zA-Z]{0,3}

Country

ISO 3166-1 alpha-3 country code

postal_code
string

Postal code

delivery_notes
string <= 1024 characters

Delivery notes

default_billing
string
Default: "no"
Enum: "yes" "no"

Specifies whether or not this is the default billing address

Values:

  • yes - Set this address as the customer's default billing address
  • no - This is not the default billing address
default_shipping
string
Default: "no"
Enum: "yes" "no"

Specifies whether or not this is the default shipping address

Values:

  • yes - Set this address as the customer's default shipping address
  • no - This is not the default shipping address
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "display_name": "string",
  • "address1": "string",
  • "address2": "string",
  • "city": "string",
  • "state": "string",
  • "country": "str",
  • "postal_code": "string",
  • "delivery_notes": "string",
  • "default_billing": "yes",
  • "default_shipping": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Delete Customer Address

Deletes a customer's address

libmonetra KVS equivalent for endpoint

  • action_admin = customer_del
  • customer_del = customer_address
Authorizations:
basic_authapikey_idapikey
path Parameters
customer_id
required
string

Customer identifier, numeric only

id
required
string

Customer address identifier

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/customer/19266575665036873/address/19266578682904270' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Customer Address Details

Details for a specific customer address

Additional fields may be present if profile custom fields are in use.

libmonetra KVS equivalent for endpoint

  • action_admin = customer_list
  • customer_list = customer_address
Authorizations:
basic_authapikey_idapikey
path Parameters
customer_id
required
string

Customer identifier, numeric only

id
required
string

Customer address identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/customer/19266575665036873/address/19266578682904270' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "customer_id": "string",
  • "display_name": "string",
  • "address1": "string",
  • "address2": "string",
  • "city": "string",
  • "state": "string",
  • "country": "string",
  • "postal_code": "string",
  • "delivery_notes": "string",
  • "property1": "string",
  • "property2": "string"
}

Edit Customer Address

Edits an existing customer's address

libmonetra KVS equivalent for endpoint

  • action_admin = customer_edit
  • customer_edit = customer_address
Authorizations:
basic_authapikey_idapikey
path Parameters
customer_id
required
string

Customer identifier, numeric only

id
required
string

Customer address identifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

display_name
string <= 128 characters

Display name

address1
string <= 128 characters

Address line 1

address2
string <= 128 characters

Address line 2

city
string <= 128 characters

City

state
string <= 128 characters

State

country
string <= 3 characters [a-zA-Z]{0,3}

Country

ISO 3166-1 alpha-3 country code

postal_code
string

Postal code

delivery_notes
string <= 1024 characters

Delivery notes

default_billing
string
Default: "no"
Enum: "yes" "no"

Specifies whether or not this is the default billing address

Values:

  • yes - Set this address as the customer's default billing address
  • no - This is not the default billing address
default_shipping
string
Default: "no"
Enum: "yes" "no"

Specifies whether or not this is the default shipping address

Values:

  • yes - Set this address as the customer's default shipping address
  • no - This is not the default shipping address
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "display_name": "string",
  • "address1": "string",
  • "address2": "string",
  • "city": "string",
  • "state": "string",
  • "country": "str",
  • "postal_code": "string",
  • "delivery_notes": "string",
  • "default_billing": "yes",
  • "default_shipping": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Inventory Bulk

Inventory bulk operations

Bulk Inventory Operation

Allows for grouping multiple inventory operations into a single operation

The bulk operation is "atomic" and if any steps fail everything will fail.

Bulk operations take any of the actions for the category as KVS pairs.

Actions to be performed are structured as a JSON-array of objects, with the key/value pairs matching the field definitions, plus a prodmanage key with value set to the appropriate action being taken. Reference the libMonetra KVS for the appropriate values. This JSON object is passed in to the bulk key on the request.

Back references can be used for ids and timestamps in the format of: :id[{idx}] or :timestamp_ms[{idx}] Where the {idx} is the array index of the response for a member being referenced.

The result of a bulk operation will also return a bulk key in the response with JSON output containing: result, id, timestamp_ms, error if appropriate.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = bulk
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

bulk
required
string

Bulk data encoded as JSON

If the bulk JSON data is being sent in a protocol which itself is JSON data (ReST submitting JSON) the data within this key must be escaped as a string.

This also applies to JSON response data. If the protocol is JSON the data will be escaped as a string and will need to be decoded.

E.g. when using a JSON protocol for transport

JSON Data
[ { "action": "sub_action_1", "key1": "val1", "key2": "val2" }, { "action": "sub_action_2", "key1": "val1", "key2": "val2" }, { "action": "sub_action_3", "key1": "val1", "key2": "val2" } ]

Encoded for JSON transport protocol
{
    "key": "val",
    "bulk": "[{\"action\":\"sub_action_1\",\"key1\":\"val1\",\"key2\":\"val2\"},{\"action\":\"sub_action_2\",\"key1\":\"val1\",\"key2\":\"val2\"},{\"action\":\"sub_action_3\",\"key1\":\"val1\",\"key2\":\"val2\"}]"
}

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "bulk": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "bulk": "string"
}

Inventory Categories

All inventory discounts and products are grouped into categories. Before anything can be added to the system categories must be created to hold them.

Categories allow for logical grouping of similar types of items and make it easier to find items. Specifically in a POS setting where the items will be displayed for a clerk to select.

Example categories for a restaurant

  • Drinks
  • Sandwiches
  • Deserts
  • Discounts

List Categories

List inventory categories

The resulting report will contain these headers:

id, name, timestamp_ms, description, sortorder, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = category
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string

Name of the category

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/inventory/category' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Category

Add an inventory category

Products, and discounts are added to categories. The category allows for grouping similar products and discounts that apply specifically to those products.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = category_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
required
string <= 32 characters

Name of the category

description
string <= 128 characters

Description of the category

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "name": "string",
  • "description": "string",
  • "sortorder": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string",
  • "timestamp_ms": "string"
}

Delete Category

Delete an inventory category

The category must be empty.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = category_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the category

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/inventory/category/20120539065950458?timestamp_ms=1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get Category Detail

Gets details for the specified category

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = category
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the category

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/inventory/category/1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "timestamp_ms": "string",
  • "description": "string",
  • "sortorder": "string",
  • "is_deleted": "yes"
}

Edit Category

Edit an inventory category

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = category_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the category

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the category

description
string <= 128 characters

Description of the category

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "name": "string",
  • "description": "string",
  • "sortorder": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "timestamp_ms": "string"
}

Inventory Discounts

Multiple types of discounts are supported and can be applied in different ways.

Specifically discounts can be:

  • Fixed
  • Percentage

They can apply to:

  • Items
  • The entire order
  • Both items and the entire order
  • A cash discount

Cash discounts

A cash discount can be added to an order to reduce the total to account for the discount offered when paying with cash. This should be a percentage discount.

Except in special cases, per brand processing rules the amount shown to customer must be the total when paying with a credit card. There are special cases for certain MCC designations that can show the credit card processing as a separate additional fee.

However, the vast majority of merchants do not qualify these special cases and instead need to show the credit card price and that paying with cash will result in a discount.

This is purely how the price is presented to the customer. Whether notifying there is an additional credit card fee or a discount when paying with cash the customer is paying the difference for the convince of using a credit card.

The discount is offered when paying with cash due to the merchant not incurring some credit card processing fees when accepting cash. However, the merchant is not required to offer a cash discount. They can charge the same price for credit card and cash. Or they can offer a discount less than the credit card processing fee would cost them.

This discount does not have to be specifically for credit card processing fees either. The merchant is free to cash discount for any reason. The requirement that the total is the credit card total. A second cash total can still be presented to the customer.

If a merchant is not accepting cash the total needs to be inclusive all credit card fees. Except in special cases. If a merchant is unsure if they qualify for any special cases, they most likely don't.

List Discounts

List inventory category discounts

The resulting report will contain these headers:

id, name, timestamp_ms, category_id, amount, type, usecase, description,
sortorder, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = discount
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string

Name of the discount

category_id
string

Unique ID of the product category

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/inventory/discount' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Discount

Add a discount to an inventory category

Discounts can be applied to products, orders or both. They can be percentage based or a fixed amount.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = discount_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

category_id
required
string\d+

Unique ID of the product category

name
required
string <= 32 characters

Name of the discount

description
string <= 128 characters

Description of the discount

type
required
string
Default: "percentage"
Enum: "percentage" "fixed"

How the discount amount is applied

Values:

  • percentage - Amount is applied as a percentage
  • fixed - Discount is applied as a fixed amount
usecase
required
string
Enum: "item" "order" "both" "cashdiscount"

What the discount applies to in the order

Values:

  • item - The discount is applied to a specific item in the order
  • order - The discount is applied to the total order amount
  • both - The discount can be applied to either a specific item or the total order amount
  • cashdiscount - The discount applies exclusivly to full cash payments
amount
required
string\d*(\.\d{0,5})?

Amount (up to 5 decimal places)

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "category_id": "string",
  • "name": "string",
  • "description": "string",
  • "type": "percentage",
  • "usecase": "item",
  • "amount": "string",
  • "sortorder": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string",
  • "timestamp_ms": "string"
}

Delete Discount

Delete an inventory category discount

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = discount_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the discount

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v1/inventory/discount/26863859502458458?timestamp_ms=1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get Discount Detail

Gets details for the specified discount

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = discount
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the discount

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/inventory/discount/1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "timestamp_ms": "string",
  • "category_id": "string",
  • "amount": "string",
  • "type": "percentage",
  • "usecase": "item",
  • "description": "string",
  • "sortorder": "string",
  • "is_deleted": "yes"
}

Edit Discount

Edit an inventory category discount

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = discount_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the discount

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the discount

description
string <= 128 characters

Description of the discount

type
string
Default: "percentage"
Enum: "percentage" "fixed"

How the discount amount is applied

Values:

  • percentage - Amount is applied as a percentage
  • fixed - Discount is applied as a fixed amount
usecase
string
Enum: "item" "order" "both" "cashdiscount"

What the discount applies to in the order

Values:

  • item - The discount is applied to a specific item in the order
  • order - The discount is applied to the total order amount
  • both - The discount can be applied to either a specific item or the total order amount
  • cashdiscount - The discount applies exclusivly to full cash payments
amount
string\d*(\.\d{0,5})?

Amount (up to 5 decimal places)

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "name": "string",
  • "description": "string",
  • "type": "percentage",
  • "usecase": "item",
  • "amount": "string",
  • "sortorder": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "timestamp_ms": "string"
}

Inventory Products

Products are high level metadata about items being sold by the merchant.

Products must have at least one SKU added to them in order to be sold. Due to the potential for product variations having different barcodes but still being considered the same product, SKUs are necessary.

Price is not set on the products but instead on SKUs.

Multiple tax rates can be set on a product in order to account for products that are untaxed vs taxed. Multiple tax rates can be applied.

List Products

List inventory products

The resulting report will contain these headers:

id, name, timestamp_ms, category_id, taxrates, modifiersets,
fractional_qty, description, commoditycode, unit, req_modifiersets, sortorder,
image_type, image_data, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = product
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string

Name of the product

category_id
string

Unique ID of the product category

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

fetch_images
object
Enum: "yes" "no"
Example: fetch_images=yes

Include base64-encoded image data

Values:

  • yes - Return image data
  • no - Do not return image data

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/inventory/product' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Product

Add an inventory product

Products represent base items. All products will have SKUs which are the actual item's. All products are part of a category.

For example

  • Category = Classic Literature
    • Product = A Tale of Two Cities
      • SKU = Hard cover
      • SKU = Paperback
      • SKU = Audio

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = product_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
required
string <= 32 characters

Name of the product

category_id
required
string\d+

Unique ID of the product category

description
string <= 128 characters

Description of the product

taxrates
string

comma separated list of taxrate ids (up to 4)

modifiersets
string

comma separated list of modifierset ids (up to 8)

req_modifiersets
string

comma separated list of required modifierset ids (must exist in modifiersets)

commoditycode
string[0-9a-zA-Z]{8,12}

Contains an international description code of the individual good or service being supplied

The acquiring bank or processor should provide the merchant an updated listing of currently defined codes. Please note that this is different from the 4-character summary commodity code. Codes can be found online at http://www.unspsc.org

The code itself will not be validated; only the format is validated.

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

sortorder
string\d+

UI sort order (display purposes only)

image_data
string[a-zA-Z0-9+/\n]+={0,2}[\n]*

Base64-encoded image data. Supports JPG and PNG formats. 300x300, 256KB max size.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "name": "string",
  • "category_id": "string",
  • "description": "string",
  • "taxrates": "string",
  • "modifiersets": "string",
  • "req_modifiersets": "string",
  • "commoditycode": "string",
  • "unit": "string",
  • "sortorder": "string",
  • "image_data": "ABC="
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string",
  • "timestamp_ms": "string"
}

Delete Product

Delete an inventory product

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = product_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the product

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/inventory/product/27589475894035458?timestamp_ms=1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get Product Detail

Gets details for the specified product

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = product
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the product

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

fetch_images
object
Enum: "yes" "no"
Example: fetch_images=yes

Include base64-encoded image data

Values:

  • yes - Return image data
  • no - Do not return image data

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/inventory/product/1758939453334' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "timestamp_ms": "string",
  • "category_id": "string",
  • "taxrates": "string",
  • "modifiersets": "string",
  • "fractional_qty": "yes",
  • "description": "string",
  • "commoditycode": "string",
  • "unit": "string",
  • "req_modifiersets": "string",
  • "sortorder": "string",
  • "image_type": "PNG",
  • "image_data": "ABC=",
  • "is_deleted": "yes"
}

Edit Product

Edit an inventory product

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = product_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the product

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the product

category_id
string\d+

Unique ID of the product category

description
string <= 128 characters

Description of the product

taxrates
string

comma separated list of taxrate ids (up to 4)

modifiersets
string

comma separated list of modifierset ids (up to 8)

req_modifiersets
string

comma separated list of required modifierset ids (must exist in modifiersets)

commoditycode
string[0-9a-zA-Z]{8,12}

Contains an international description code of the individual good or service being supplied

The acquiring bank or processor should provide the merchant an updated listing of currently defined codes. Please note that this is different from the 4-character summary commodity code. Codes can be found online at http://www.unspsc.org

The code itself will not be validated; only the format is validated.

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

sortorder
string\d+

UI sort order (display purposes only)

image_data
string[a-zA-Z0-9+/\n]+={0,2}[\n]*

Base64-encoded image data. Supports JPG and PNG formats. 300x300, 256KB max size.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "name": "string",
  • "category_id": "string",
  • "description": "string",
  • "taxrates": "string",
  • "modifiersets": "string",
  • "req_modifiersets": "string",
  • "commoditycode": "string",
  • "unit": "string",
  • "sortorder": "string",
  • "image_data": "ABC="
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "timestamp_ms": "string"
}

Inventory SKUs

SKUs are the actual item being sold and are contained within a product.

Product variations can be manufacturing variations of the same product. For example a refreshed version of a product with the same name and functionality.

Another possibility is a product with multiple variations. For example, a vacuum cleaner. Model is XYZ but there are three SKUs that different based on accessory bundles offered as part of the SKU. While it is one product it has multiple SKUs. This is typically manufacturer bundles where each SKU has a different accompanying UPC code.

In both examples the price may differ between the SKUs. This is why price is set on the SKU and not on the product.

List SKUs

List inventory product SKUs

The resulting report will contain these headers:

id, name, timestamp_ms, product_id, inventory, price, in_stock,
inventory_timestamp_ms, barcode, description, sortorder, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = sku
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string

Name of the SKU

product_id
string

Unique ID of the product

in_stock
object
Enum: "yes" "no"
Example: in_stock=yes

Whether the in stock status should be evaulated as a condition

Values:

  • yes - Only return in-stock skus
  • no - Only return out-of-stock skus
timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/inventory/sku' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add SKU

Add an inventory product SKU

A SKU is a specific version of a product. For example, if the product is a book, there could be hardcover and paperback SKUs.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = sku_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

product_id
required
string\d+

Unique ID of the product

name
required
string <= 32 characters

Name of the SKU

price
required
string\d*(\.\d{0,5})?

Price (up to 5 decimal places)

inventory
string
Default: "unlimited"
Enum: "unlimited" "tracked" "outofstock"

Type of item stocking

Values:

  • unlimited - The item quantity is not tracked
  • tracked - The item quantity is tracked and there is a finite number available at a given time
  • outofstock - The item is not currently in stock
barcode
string <= 32 characters

Decoded Barcode. E.g. 2d barcode decoded to the UPC number

description
string <= 128 characters

Description of the SKU

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "product_id": "string",
  • "name": "string",
  • "price": "string",
  • "inventory": "unlimited",
  • "barcode": "string",
  • "description": "string",
  • "sortorder": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string",
  • "timestamp_ms": "string"
}

Delete SKU

Delete an inventory product SKU

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = sku_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the SKU

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/inventory/sku/13748493859345458?timestamp_ms=57849320845' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get SKU Detail

Gets details for the specified SKU

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = sku
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the SKU

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/inventory/sku/1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "timestamp_ms": "string",
  • "product_id": "string",
  • "inventory": "unlimited",
  • "price": "string",
  • "in_stock": "yes",
  • "inventory_timestamp_ms": "string",
  • "barcode": "string",
  • "description": "string",
  • "sortorder": "string",
  • "is_deleted": "yes"
}

Edit SKU

Edit an inventory product SKU

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = sku_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the SKU

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the SKU

price
string\d*(\.\d{0,5})?

Price (up to 5 decimal places)

inventory
string
Default: "unlimited"
Enum: "unlimited" "tracked" "outofstock"

Type of item stocking

Values:

  • unlimited - The item quantity is not tracked
  • tracked - The item quantity is tracked and there is a finite number available at a given time
  • outofstock - The item is not currently in stock
barcode
string <= 32 characters

Decoded Barcode. E.g. 2d barcode decoded to the UPC number

description
string <= 128 characters

Description of the SKU

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "name": "string",
  • "price": "string",
  • "inventory": "unlimited",
  • "barcode": "string",
  • "description": "string",
  • "sortorder": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "timestamp_ms": "string"
}

Set SKU Quantity

Set the quantity for SKU

Tracking for the number of items in stock

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = inventory_set
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the SKU

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

cnt
required
string\d+

Exact count of inventory in stock

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "cnt": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "timestamp_ms": "string"
}

Inventory Modifier Sets

Modifier sets are similar to categories. In that they are a logical grouping of modifiers.

Modifier sets are attached to products in order to allow modifying products.

In the SKU section an example of a vacuum cleaner with multiple accessory bundle variations was used. In that case the SKUs were due to manufacturer bundles with different UPC codes.

Building on that example, a product might have a single SKU for the item because the manufacturer only produces one item. Instead the merchant has their on add on bundles they sell with the item. A modifier set can be used with a modifier for each add on.

List Modifier Sets

List inventory modifier sets

The resulting report will contain these headers:

id, name, timestamp_ms, description, multiselect, maxselect, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = modifierset
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string

Name of the modifier set

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/inventory/modifierset' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Modifier Set

Add an inventory modifier set

A grouping of like modifiers. For example, pizza toppings. Where each topping is a modifier within the set.

Modifier sets are applied to products. It can be applied to multiple products. For example, a pizza topping modifier set could apply to product pizza and product calzone (which is like a pizza but harder to eat and they're dumb). Both can and often use the same topping modifiers.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifierset_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
required
string <= 32 characters

Name of the modifier set

description
string <= 128 characters

Description of the modifier set

multiselect
string
Default: "no"
Enum: "yes" "no"

Whether or not multiple selection is allowed

Values:

  • yes - Multiple selection is allowed
  • no - Multiple selection is NOT allowed
maxselect
string\d+

How many items may be selected at once (only if multiselect, default=unlimited)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "name": "string",
  • "description": "string",
  • "multiselect": "yes",
  • "maxselect": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string",
  • "timestamp_ms": "string"
}

Delete Modifier Set

Delete an inventory modifier set

The modifier set must be empty.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifierset_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the modifier set

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/inventory/modifierset/84578903855643344?timestamp_ms=1895849024551' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get Modifier Set Detail

Gets details for the specified modifier set

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = modifierset
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the modifier set

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/inventory/modifierset/1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "timestamp_ms": "string",
  • "description": "string",
  • "multiselect": "yes",
  • "maxselect": "string",
  • "is_deleted": "yes"
}

Edit Modifier Set

Edit an inventory modifier set

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifierset_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the modifier set

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the modifier set

description
string <= 128 characters

Description of the modifier set

multiselect
string
Default: "no"
Enum: "yes" "no"

Whether or not multiple selection is allowed

Values:

  • yes - Multiple selection is allowed
  • no - Multiple selection is NOT allowed
maxselect
string\d+

How many items may be selected at once (only if multiselect, default=unlimited)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "name": "string",
  • "description": "string",
  • "multiselect": "yes",
  • "maxselect": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "timestamp_ms": "string"
}

Inventory Modifiers

Modifiers are ways a product can be altered. They belong to modifier sets to better group the modifiers. A common term for a modifier is an add on.

Modifiers can have their own price that can increase the total price of a product. They are not required to have a price and will not increase the product price if added.

An example is a pizza where a topping modifier set is created and within the set is a modifier representing each topping and it's additional price per topping.

List Modifiers

List inventory modifiers

The resulting report will contain these headers:

id, name, timestamp_ms, modifierset_id, price, description, unit, sortorder,
is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = modifier
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string

Name of the modifier

modifierset_id
string

Unique ID of the modifier set

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/inventory/modifier' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Modifier

Add an inventory modifier to a modifier set

Modifiers augment a product and are typically add ons. This is different than a SKU.

For example, a pizza topping would be a modifier. Pepperoni, mushroom, or bacon. Multiple modifiers can be applied to an order.

All modifiers are part of a modifier set in order to provide logical groupings for modifiers.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifier_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

modifierset_id
required
string\d+

Unique ID of the modifier set

name
required
string <= 32 characters

Name of the modifier

description
string <= 128 characters

Description of the modifier

price
string\d*(\.\d{0,5})?

Price (up to 5 decimal places)

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "modifierset_id": "string",
  • "name": "string",
  • "description": "string",
  • "price": "string",
  • "unit": "string",
  • "sortorder": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string",
  • "timestamp_ms": "string"
}

Delete Modifier

Delete an inventory modifier

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifier_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the modifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/inventory/modifier/82859028592849248?timestamp_ms=1895849024551' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get Modifier Detail

Gets details for the specified modifier

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = modifier
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the modifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/inventory/modifier/1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "timestamp_ms": "string",
  • "modifierset_id": "string",
  • "price": "string",
  • "description": "string",
  • "unit": "string",
  • "sortorder": "string",
  • "is_deleted": "yes"
}

Edit Modifier

Edit an inventory modifier

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifier_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the modifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the modifier

description
string <= 128 characters

Description of the modifier

price
string\d*(\.\d{0,5})?

Price (up to 5 decimal places)

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "name": "string",
  • "description": "string",
  • "price": "string",
  • "unit": "string",
  • "sortorder": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "timestamp_ms": "string"
}

Inventory Tax Rates

Tax rates are the amount of tax that is charged to an item. This is used for automatic calculation of tax when the inventory system is used in conjunction with the order system.

Multiple tax rates may be necessary and multiple can be applied to products. There may be a state and county tax that are tracked and remitted separately. Two tax rates would be created and both added to a product. When the inventory is used with the order system, this allows generating tax rate reports to aid with remittance to the relevant governments.

List Tax Rates

List inventory tax rates

The resulting report will contain these headers:

id, name, timestamp_ms, percentage, default, roundmethod, sortorder, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = taxrate
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string

Name of the tax rate

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/inventory/taxrate' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Tax Rate

Add an inventory tax rate

Allows creating a tax rate that can be applied to products. Multiple tax rates could be necessary for reporting purposes.

For example, separate rates for state, county, and city. Multiple tax rates can be applied to products.

Having several tax rates my be necessary if products are taxed differently based on their type. For example, some places have digital and physical goods rates.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = taxrate_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
required
string <= 32 characters

Name of the tax rate

percentage
required
string\d*(\.\d{0,5})?

Percentage of tax rate (up to 5 decimal places)

default
string
Default: "no"
Enum: "yes" "no"

Whether this should be applied by default to new products (UI)

Values:

  • yes - Apply by default to new products
  • no - Do not apply by default to new products
roundmethod
string
Enum: "normal" "bankers"

Method used for rounding

Values:

  • normal - Round to the nearest whole number
  • bankers - Round to the nearest even whole number
sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "name": "string",
  • "percentage": "string",
  • "default": "yes",
  • "roundmethod": "normal",
  • "sortorder": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string",
  • "timestamp_ms": "string"
}

Delete Tax Rate

Delete an inventory tax rate

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = taxrate_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the tax rate

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/inventory/taxrate/14859438593544438?timestamp_ms=1859386643324' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get Tax Rate Detail

Gets details for the specified tax rate

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = taxrate
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the tax rate

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/inventory/taxrate/1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "timestamp_ms": "string",
  • "percentage": "string",
  • "default": "yes",
  • "roundmethod": "normal",
  • "sortorder": "string",
  • "is_deleted": "yes"
}

Edit Tax Rate

Edit an inventory tax rate

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = taxrate_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the tax rate

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the tax rate

percentage
string\d*(\.\d{0,5})?

Percentage of tax rate (up to 5 decimal places)

default
string
Default: "no"
Enum: "yes" "no"

Whether this should be applied by default to new products (UI)

Values:

  • yes - Apply by default to new products
  • no - Do not apply by default to new products
roundmethod
string
Enum: "normal" "bankers"

Method used for rounding

Values:

  • normal - Round to the nearest whole number
  • bankers - Round to the nearest even whole number
sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "name": "string",
  • "percentage": "string",
  • "default": "yes",
  • "roundmethod": "normal",
  • "sortorder": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "timestamp_ms": "string"
}

Orders

The order system allows creating orders

The profile flag ALLOW_INVOICING must be set.

Order types

There are three types of 'orders':

  • Order - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • Quick - Single or no line item orders. Typically used for single amount payments
  • Invoice - Billing invoice for later payment

The line items can be based on inventory items from the inventory system or a custom (one off) line item. Customers who have an external product system and only need the invoice for billing will often use a single custom line item for the order amount. You can attach the external system generated PDF so the customer will be able to view it from the link they get sent to pay. This is useful in the external invoice generation scenario where Monetra is only being used to send and collect the payment.

Order flow

  • Create the order (specifying the type as order)
  • Add line items
  • Edit the order to put the order into an open status
  • Link payment to order

Quick flow

  • Create the order (specifying the type as quick)
  • Add single custom line item with the order amount
  • Edit the order to put the order into an open status
  • Link payment to order

Invoice flow

  • Create the order (specifying the type as invoice)
  • Add line items
  • Edit the order to put the order into an open status
  • Provide invoice to customer (email or SMS)
  • Accept payment
  • Link payment to order

Typically the last two steps will be handled by the customer using the invoice link emailed or SMS messaged to the customer. The customer can make payment online using that link.

Payments

Payments are a way to link transactions to orders so the order can be closed. Accepting transactions does not require the use of the order system.

There are two ways a payment can be linked to an order.

  1. The order_id can be specified with a transaction, such as purchase at the time the transaction is processed. This will automatically update the order and create a payment linking the transaction to the order.
  2. A payment can be manually added to the order by specifying the ttid of the transaction being linked.

Emailing or SMS sending orders

It is possible to email or SMS send an order to a customer. This applies to all order types. The customer will receive a link that will take them to the payment server to view and pay the order. If the order is closed they will be able to view receipts. Additionally, if an external invoice PDF was added to the order they will be able to download the PDF here.

Sending orders to customers is handled by the "Receipt" system. They can be sent by email or SMS message. Orders are sent as a links to Monetra for viewing. Since it's the same link for open orders to allow payment and closed orders for viewing receipts, sending is contained in one place ("Receipts").

Invoices will be automatically email to the customer when closed. This requires a customer from the customer system to be associated with the order and that customer must have an email on file. Further, if the profile has the RECEIVE_RECEIPTS_INVOICE flag set, an email will be sent to the notify_email.

timestamp_ms

The timestamp_ms parameter is used to ensure changes do not create conflicts. The value for timestamp_ms is either returned by an operation and is then used in the next. Or it can be retrieved by getting an order details or when listing orders.

Cancel an Order or Invoice

Cancel an order in the OPEN or PENDING states

The order is not removed from the system. Must be used instead of order delete if there have been payments attempted against it.

It is recommended to delete orders if possible as it doesn't leave stale records.

NOTE: must cancel all applied payments before canceling an order or invoice.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = order_cancel
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order identifier, numeric only

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

cancel_reason
required
string
Enum: "CANCEL" "RETURN" "SATISFACTION"

Reason for order cancellation

Values:

  • CANCEL - Generic cancel
  • RETURN - All items in the order were returned
  • SATISFACTION - Customer was not satisfied
timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "cancel_reason": "CANCEL",
  • "timestamp_ms": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

List Orders

List orders

The resulting report will contain these headers:

id, timestamp_ms, user, id_base62, type, flags, status, cancel_reason,
merch_status, customer_id, customer_display_name, ordernum, ponumber,
allowed_cardtypes, securitytoken, timestamp_create, timestamp_close,
timestamp_sent, timestamp_viewed, invoice_date, invoice_due, taxrates,
taxamounts, total_amount, total_tax, total_discount, total_paid, total_tip,
total_amount_cash, total_amount_noncash, notes, total_tax_override, ship_name,
ship_address1, ship_address2, ship_city, ship_state, ship_zip, ship_country,
ship_notes, invoice_filename, invoice_data, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = orders
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

customer_id
string

Comma separated list of customer identifiers

ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to Monetra, an order number should be sent on all transactions.

Normally, an order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

type
object
Enum: "ORDER" "QUICK" "INVOICE"
Example: type=ORDER,QUICK

Comma separated list of order types

Flag values (comma separated):

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
object
Enum: "PENDING" "OPEN" "PARTIALPAID" "COMPLETE" "CANCEL" "FORCECLOSED"
Example: status=OPEN,PARTIALPAID

Comma separated list of order status

Flag values (comma separated):

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
  • PARTIALPAID - Order has been partially paid
  • COMPLETE - Order is complete
  • CANCEL - Order has been canceled
  • FORCECLOSED - Order was force closed
timestamp_create_bdate
string

Start of order created date range as a timestamp

timestamp_create_edate
string

End of order created date range as a timestamp

timestamp_close_bdate
string

Start of order closed date range as a timestamp

timestamp_close_edate
string

End of order closed date range as a timestamp

fetch_invoices
object
Enum: "yes" "no"
Example: fetch_invoices=yes

Include base64-encoded invoice data

Applies to invoices with external (PDF) invoice documents.

Values:

  • yes - Return invoice data
  • no - Do not return invoice data
timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/order' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Create an Order or Invoice

Create an order or invoice

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = order_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

type
required
string
Enum: "ORDER" "QUICK" "INVOICE"

Type of order

Values:

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
required
string
Enum: "PENDING" "OPEN"

Status of the order

Values:

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
flags
string
Value: "NOTIP"

Type of order

Flag values (pipe separated):

  • NOTIP - Do not attempt to perform tip prompting when collecting payment
merch_status
string
Enum: "PENDING" "COMPLETE" "PREPARING" "BACKORDERED"

Merchant status of the order

Values:

  • PENDING - Order is pending
  • COMPLETE - Order is complete
  • PREPARING - Order is being prepared
  • BACKORDERED - Order is delayed while waiting for back ordered items
customer_id
string[0-9]+

Customer identifier, numeric only

Required when type = Invoice

ordernum
string <= 128 characters

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to Monetra, an order number should be sent on all transactions.

Normally, an order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

ponumber
string <= 32 characters

Unique identifier of the order

Typically used with Invoices

allowed_cardtypes
string
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "CUP" "GIFT" "ACH"

Card types allowed to be used for payment

Pipe-separated (|) list of cardtypes accepted for payment. Merchant must be configured to accept the provided cardtypes. Defaults to allow all if not provided.

This is typically used in conjunction with accepting payment online using the Monetra Invoice Payment Web Page for online order or invoice payment.

Flag values (pipe separated):

  • VISA - Visa
  • MC - Mastercard
  • AMEX - American Express
  • DISC - Discover
  • DINERS - Diners
  • JCB - Japan Credit Bureau
  • CUP - China Union Pay
  • GIFT - Generic gift card
  • ACH - Electronic funds transfer, e.g. CCD,PPD
invoice_date
string

Date the order was created

Current date if not provided

invoice_due
string

Date the order is due

Current date if not provided

notes
string <= 1024 characters

General free-form information

Will be shown to customers!

total_tax_override
string0?\.\d{2}

Tax override amount, only used if all line items have no tax rates

ship_name
string <= 32 characters

Shipping name of recipient

"To" field on shipping label.

ship_address1
string <= 32 characters

Shipping street address of recipient

Line 1

ship_address2
string <= 32 characters

Shipping street address of recipient

Line 2

ship_city
string <= 32 characters

Shipping city of recipient

ship_state
string <= 32 characters

Shipping state / provence of recipient

ship_zip
string <= 32 characters

Shipping zip / postal Code of recipient

Used for tax zones

ship_country
string <= 32 characters

Shipping country of recipient

ship_notes
string <= 128 characters

Shipping delivery instructions

invoice_filename
string <= 32 characters

Filename of externally attached invoice PDF

Requires:

  • invoice_data
invoice_data
string[a-zA-Z0-9+/\n]+={0,2}[\n]*

PDF base64 encoded invoice PDF

Used for externally generated invoice billing

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "type": "ORDER",
  • "status": "PENDING",
  • "flags": "NOTIP",
  • "merch_status": "PENDING",
  • "customer_id": "string",
  • "ordernum": "A13DDES345",
  • "ponumber": "string",
  • "allowed_cardtypes": "VISA",
  • "invoice_date": "string",
  • "invoice_due": "string",
  • "notes": "string",
  • "total_tax_override": "string",
  • "ship_name": "string",
  • "ship_address1": "string",
  • "ship_address2": "string",
  • "ship_city": "string",
  • "ship_state": "string",
  • "ship_zip": "string",
  • "ship_country": "string",
  • "ship_notes": "string",
  • "invoice_filename": "string",
  • "invoice_data": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string",
  • "timestamp_ms": "string"
}

Delete an Order or Invoice

Completely remove an order or invoice from the system

Cannot be used if an order has had payments applied. If payments have been applied the order must be canceled.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = order_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order identifier, numeric only

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/order/1456543256' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get Order Detail

Gets details for the specified order

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = orders
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order identifier, numeric only

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

fetch_invoices
object
Enum: "yes" "no"
Example: fetch_invoices=yes

Include base64-encoded invoice data

Applies to invoices with external (PDF) invoice documents.

Values:

  • yes - Return invoice data
  • no - Do not return invoice data
timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/order/789567654256' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp_ms": "string",
  • "user": "string",
  • "id_base62": "string",
  • "type": "ORDER",
  • "flags": "NOTIP",
  • "status": "PENDING",
  • "cancel_reason": "CANCEL",
  • "merch_status": "PENDING",
  • "customer_id": "string",
  • "customer_display_name": "string",
  • "ordernum": "A13DDES345",
  • "ponumber": "string",
  • "allowed_cardtypes": "VISA",
  • "securitytoken": "string",
  • "timestamp_create": "string",
  • "timestamp_close": "string",
  • "timestamp_sent": "string",
  • "timestamp_viewed": "string",
  • "invoice_date": "string",
  • "invoice_due": "string",
  • "taxrates": "string",
  • "taxamounts": "string",
  • "total_amount": "string",
  • "total_tax": "string",
  • "total_discount": "string",
  • "total_paid": "string",
  • "total_tip": "string",
  • "total_amount_cash": "string",
  • "total_amount_noncash": "string",
  • "notes": "string",
  • "total_tax_override": "string",
  • "ship_name": "string",
  • "ship_address1": "string",
  • "ship_address2": "string",
  • "ship_city": "string",
  • "ship_state": "string",
  • "ship_zip": "string",
  • "ship_country": "string",
  • "ship_notes": "string",
  • "invoice_filename": "string",
  • "invoice_data": "string",
  • "is_deleted": "yes"
}

Edit an Order or Invoice

Edit and order or invoice

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = order_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order identifier, numeric only

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

type
string
Enum: "ORDER" "QUICK" "INVOICE"

Type of order

Values:

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
string
Enum: "PENDING" "OPEN"

Status of the order

Values:

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
flags
string
Value: "NOTIP"

Type of order

Flag values (pipe separated):

  • NOTIP - Do not attempt to perform tip prompting when collecting payment
merch_status
string
Enum: "PENDING" "COMPLETE" "PREPARING" "BACKORDERED"

Merchant status of the order

Values:

  • PENDING - Order is pending
  • COMPLETE - Order is complete
  • PREPARING - Order is being prepared
  • BACKORDERED - Order is delayed while waiting for back ordered items
customer_id
string[0-9]+

Customer identifier, numeric only

ordernum
string <= 128 characters

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to Monetra, an order number should be sent on all transactions.

Normally, an order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

ponumber
string <= 32 characters

Unique identifier of the order

Typically used with Invoices

allowed_cardtypes
string
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "CUP" "GIFT" "ACH"

Card types allowed to be used for payment

Pipe-separated (|) list of cardtypes accepted for payment. Merchant must be configured to accept the provided cardtypes. Defaults to allow all if not provided.

This is typically used in conjunction with accepting payment online using the Monetra Invoice Payment Web Page for online order or invoice payment.

Flag values (pipe separated):

  • VISA - Visa
  • MC - Mastercard
  • AMEX - American Express
  • DISC - Discover
  • DINERS - Diners
  • JCB - Japan Credit Bureau
  • CUP - China Union Pay
  • GIFT - Generic gift card
  • ACH - Electronic funds transfer, e.g. CCD,PPD
invoice_date
string

Date the order was created

Current date if not provided

invoice_due
string

Date the order is due

Current date if not provided

notes
string <= 1024 characters

General free-form information

Will be shown to customers!

total_tax_override
string0?\.\d{2}

Tax override amount, only used if all line items have no tax rates

ship_name
string <= 32 characters

Shipping name of recipient

"To" field on shipping label.

ship_address1
string <= 32 characters

Shipping street address of recipient

Line 1

ship_address2
string <= 32 characters

Shipping street address of recipient

Line 2

ship_city
string <= 32 characters

Shipping city of recipient

ship_state
string <= 32 characters

Shipping state / provence of recipient

ship_zip
string <= 32 characters

Shipping zip / postal Code of recipient

Used for tax zones

ship_country
string <= 32 characters

Shipping country of recipient

ship_notes
string <= 128 characters

Shipping delivery instructions

invoice_filename
string <= 32 characters

Filename of externally attached invoice PDF

Requires:

  • invoice_data
invoice_data
string[a-zA-Z0-9+/\n]+={0,2}[\n]*

PDF base64 encoded invoice PDF

Used for externally generated invoice billing

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "type": "ORDER",
  • "status": "PENDING",
  • "flags": "NOTIP",
  • "merch_status": "PENDING",
  • "customer_id": "string",
  • "ordernum": "A13DDES345",
  • "ponumber": "string",
  • "allowed_cardtypes": "VISA",
  • "invoice_date": "string",
  • "invoice_due": "string",
  • "notes": "string",
  • "total_tax_override": "string",
  • "ship_name": "string",
  • "ship_address1": "string",
  • "ship_address2": "string",
  • "ship_city": "string",
  • "ship_state": "string",
  • "ship_zip": "string",
  • "ship_country": "string",
  • "ship_notes": "string",
  • "invoice_filename": "string",
  • "invoice_data": "string",
  • "timestamp_ms": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "timestamp_ms": "string"
}

Order Bulk

Order bulk operations

Bulk Order Operation

Allows for grouping multiple order operations into a single operation

The bulk operation is "atomic" and if any steps fail everything will fail.

Bulk operations take any of the actions for the category as KVS pairs.

Actions to be performed are structured as a JSON-array of objects, with the key/value pairs matching the field definitions, plus a ordermanage key with value set to the appropriate action being taken. Reference the libMonetra KVS for the appropriate values. This JSON object is passed in to the bulk key on the request.

Back references can be used for ids and timestamps in the format of: :id[{idx}] or :timestamp_ms[{idx}] Where the {idx} is the array index of the response for a member being referenced.

The result of a bulk operation will also return a bulk key in the response with JSON output containing: result, id, timestamp_ms, error if appropriate.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = bulk
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

bulk
required
string

Bulk data encoded as JSON

If the bulk JSON data is being sent in a protocol which itself is JSON data (ReST submitting JSON) the data within this key must be escaped as a string.

This also applies to JSON response data. If the protocol is JSON the data will be escaped as a string and will need to be decoded.

E.g. when using a JSON protocol for transport

JSON Data
[ { "action": "sub_action_1", "key1": "val1", "key2": "val2" }, { "action": "sub_action_2", "key1": "val1", "key2": "val2" }, { "action": "sub_action_3", "key1": "val1", "key2": "val2" } ]

Encoded for JSON transport protocol
{
    "key": "val",
    "bulk": "[{\"action\":\"sub_action_1\",\"key1\":\"val1\",\"key2\":\"val2\"},{\"action\":\"sub_action_2\",\"key1\":\"val1\",\"key2\":\"val2\"},{\"action\":\"sub_action_3\",\"key1\":\"val1\",\"key2\":\"val2\"}]"
}

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "bulk": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "bulk": "string"
}

Order Discounts

Order discount management. This is for managing discounts applied to the entire order. Discounts can be added to an order using a custom discount or by referencing a discount from the inventory system. An inventory system discount must be of a type that can be applied to orders.

When operating on a discount, such as edit or delete, the id of the discount within the order is referenced. Not the discount id within the inventory system if the inventory system was used.

Add a Custom Fixed Discount

Add a custom fixed discount to the order

For adding discounts that are not in the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_add
  • ref_id = 0
  • type = DISCOUNT_FIXED
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

amount
required
string\d*(\.\d{0,5})?

Amount of money, including up to 5 decimal places. E.g 1.00 or 2.399

This is the amount of 1 unit.

taxrates
string

comma separated list of taxrate ids (up to 4)

name
required
string <= 32 characters

Name of the discount

productcode
string[0-9a-zA-Z ]{1,12}

Merchant-defined code for the item being purchased, such as a UPC #, SKU #, or Item #

commoditycode
string[0-9a-zA-Z]{8,12}

Contains an international description code of the individual good or service being supplied

The acquiring bank or processor should provide the merchant an updated listing of currently defined codes. Please note that this is different from the 4-character summary commodity code. Codes can be found online at http://www.unspsc.org

The code itself will not be validated; only the format is validated.

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "amount": "4.779",
  • "taxrates": "string",
  • "name": "string",
  • "productcode": "string",
  • "commoditycode": "string",
  • "unit": "string",
  • "notes": "string",
  • "group_name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Add a Custom Percent Discount

Add a custom percent discount to the order

For adding discounts that are not in the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_add
  • ref_id = 0
  • type = DISCOUNT_PERCENT
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

amount
required
string\d*(\.\d{0,5})?

Amount of money, including up to 5 decimal places. E.g 1.00 or 2.399

This is the amount of 1 unit.

taxrates
string

comma separated list of taxrate ids (up to 4)

name
required
string <= 32 characters

Name of the discount

productcode
string[0-9a-zA-Z ]{1,12}

Merchant-defined code for the item being purchased, such as a UPC #, SKU #, or Item #

commoditycode
string[0-9a-zA-Z]{8,12}

Contains an international description code of the individual good or service being supplied

The acquiring bank or processor should provide the merchant an updated listing of currently defined codes. Please note that this is different from the 4-character summary commodity code. Codes can be found online at http://www.unspsc.org

The code itself will not be validated; only the format is validated.

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "amount": "4.779",
  • "taxrates": "string",
  • "name": "string",
  • "productcode": "string",
  • "commoditycode": "string",
  • "unit": "string",
  • "notes": "string",
  • "group_name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Add a Fixed Discount

Add a fixed amount discount to the order

The discount references a discount from the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_add
  • type = DISCOUNT_FIXED
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ref_id
required
string[0-9]+

Unique ID of the discount

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ref_id": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "notes": "string",
  • "group_name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Add a Percent Discount

Add a percentage discount to the order

The discount references a discount from the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_add
  • type = DISCOUNT_PERCENT
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ref_id
required
string[0-9]+

Unique ID of the discount

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ref_id": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "notes": "string",
  • "group_name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Remove a Discount

Remove a discount form an order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order discount identifier

order_id
required
string

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/order/20245528771333405/discount/5894387586' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Edit a Discount

Edit a discount for an order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order discount identifier

order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

ringorder
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "notes": "string",
  • "group_name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Order Items

Order item management. This is for managing items added to an order. Items can be added to an order using a custom item or by referencing a SKU from the inventory system.

When operating on a item, such as edit or delete, the id of the item within the order is referenced. Not the SKU id within the inventory system if the inventory system was used.

Add a Custom Item

Add a custom line item to the order

For adding line items that are not SKUs in the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_add
  • ref_id = 0
  • type = ADDON
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

amount
required
string\d*(\.\d{0,5})?

Amount of money, including up to 5 decimal places. E.g 1.00 or 2.399

This is the amount of 1 unit.

taxrates
string

comma separated list of taxrate ids (up to 4)

name
required
string <= 32 characters

Name of the line item

productcode
string[0-9a-zA-Z ]{1,12}

Merchant-defined code for the item being purchased, such as a UPC #, SKU #, or Item #

commoditycode
string[0-9a-zA-Z]{8,12}

Contains an international description code of the individual good or service being supplied

The acquiring bank or processor should provide the merchant an updated listing of currently defined codes. Please note that this is different from the 4-character summary commodity code. Codes can be found online at http://www.unspsc.org

The code itself will not be validated; only the format is validated.

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "amount": "4.779",
  • "taxrates": "string",
  • "name": "string",
  • "productcode": "string",
  • "commoditycode": "string",
  • "unit": "string",
  • "notes": "string",
  • "group_name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

List Items

List order items

Gets Items for the specified Order.

The resulting report will contain these headers:

id, timestamp_ms, order_id, type, ringorder, ref_id, qty, amount,
total_modifiers, total_mod_disc, total_ord_disc, taxrates, name,
productcode, commoditycode, unit, notes, group_name, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = items
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

customer_id
string

Comma separated list of customer identifiers

ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to Monetra, an order number should be sent on all transactions.

Normally, an order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

type
object
Enum: "ORDER" "QUICK" "INVOICE"
Example: type=ORDER,QUICK

Comma separated list of order types

Flag values (comma separated):

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
object
Enum: "PENDING" "OPEN" "PARTIALPAID" "COMPLETE" "CANCEL" "FORCECLOSED"
Example: status=OPEN,PARTIALPAID

Comma separated list of order status

Flag values (comma separated):

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
  • PARTIALPAID - Order has been partially paid
  • COMPLETE - Order is complete
  • CANCEL - Order has been canceled
  • FORCECLOSED - Order was force closed
timestamp_create_bdate
string

Start of order created date range as a timestamp

timestamp_create_edate
string

End of order created date range as a timestamp

timestamp_close_bdate
string

Start of order closed date range as a timestamp

timestamp_close_edate
string

End of order closed date range as a timestamp

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/order/7589432567654/item' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add an Item

Add a line item to the order

The line item references a SKU from the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_add
  • type = ADDON
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ref_id
required
string[0-9]+

Unique ID of the inventory SKU

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ref_id": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "notes": "string",
  • "group_name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Remove an Item

Remove a line item form an order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/order/item/675894315' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get Item Detail

Gets details for the specified Item in an order

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = items
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to Monetra, an order number should be sent on all transactions.

Normally, an order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/order/item/8594387568950432' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp_ms": "string",
  • "type": "ADDON",
  • "ringorder": "string",
  • "ref_id": "string",
  • "qty": "string",
  • "amount": "19.92",
  • "total_modifiers": "string",
  • "total_mod_disc": "string",
  • "total_ord_disc": "string",
  • "taxrates": "string",
  • "name": "string",
  • "productcode": "string",
  • "commoditycode": "string",
  • "unit": "string",
  • "notes": "string",
  • "group_name": "string",
  • "is_deleted": "yes"
}

Edit an Item

Edit a line item for an order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

ringorder
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "notes": "string",
  • "group_name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Order Item Discounts

Order item discount management. This is for managing item discounts added to an item in an order. Item discounts can be added to an order using a custom item discount or by referencing discount from the inventory system. An inventory system discount must be of a type that can be applied to items.

When referencing an item to apply a discount, the item must be added to the order first. The item id within the order, not the inventory SKU id, is referenced when adding the discount.

When operating on a item discount, such as edit or delete, the id of the item discount within the order is referenced. Not the discount id within the inventory system if the inventory system was used.

Add a Custom Item Fixed Discount

Add a custom fixed discount to a line item

For adding discounts that are not in the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_add
  • ref_id = 0
  • type = DISCOUNT_FIXED
Authorizations:
basic_authapikey_idapikey
path Parameters
item_id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

amount
required
string\d*(\.\d{0,5})?

Amount of money, including up to 5 decimal places. E.g 1.00 or 2.399

This is the amount of 1 unit.

name
required
string <= 32 characters

Name of line item discount

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "amount": "4.779",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Add a Custom Item Percent Discount

Add a custom percent discount to a line item

For adding discounts that are not in the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_add
  • ref_id = 0
  • type = DISCOUNT_PERCENT
Authorizations:
basic_authapikey_idapikey
path Parameters
item_id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

amount
required
string\d*(\.\d{0,5})?

Amount of money, including up to 5 decimal places. E.g 1.00 or 2.399

This is the amount of 1 unit.

name
required
string <= 32 characters

Name of line item discount

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "amount": "4.779",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Add an Item Fixed Discount

Add a fixed discount to a line item

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_add
  • type = DISCOUNT_FIXED
Authorizations:
basic_authapikey_idapikey
path Parameters
item_id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ref_id
required
string\d+

Unique ID of the inventory discount

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ref_id": "string",
  • "ringorder": "string",
  • "qty": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Add an Item Percent Discount

Add a percent discount to a line item

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_add
  • type = DISCOUNT_PERCENT
Authorizations:
basic_authapikey_idapikey
path Parameters
item_id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ref_id
required
string\d+

Unique ID of the inventory discount

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ref_id": "string",
  • "ringorder": "string",
  • "qty": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Remove an Item Discount

Remove a discount from a line item in the order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order item discount identifier

order_id
required
string

Unique ID of an order

item_id
required
string

Order item identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/order/item/discount/76789625' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Edit an Item Discount

Edit a line item discount

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order item discount identifier

order_id
required
string

Unique ID of an order

item_id
required
string

Order item identifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

ringorder
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "ringorder": "string",
  • "qty": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Order Item Modifiers

Order item modifier management. This is for managing item modifiers added to an item in an order. Item modifier can be added to an order using a custom item modifier or by referencing modifiers from the inventory system.

When referencing an item to apply a modifier, the item must be added to the order first. The item id within the order, not the inventory SKU id, is referenced when adding the modifier.

When operating on a item modifier, such as edit or delete, the id of the item modifier within the order is referenced. Not the modifier id within the inventory system if the inventory system was used.

Add a Custom Item Modifier

Add a custom modifier to a line item

For adding modifiers that are not in the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_add
  • ref_id = 0
  • type = ADDON
Authorizations:
basic_authapikey_idapikey
path Parameters
item_id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

amount
required
string\d*(\.\d{0,5})?

Amount of money, including up to 5 decimal places. E.g 1.00 or 2.399

This is the amount of 1 unit.

name
required
string <= 32 characters

Name of line item modifier

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "amount": "4.779",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

List Order Item Modifiers

List order item modifiers

The resulting report will contain these headers:

id, timestamp_ms, item_id, order_id, type, ringorder, ref_id, qty, amount, name, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = modifiers
Authorizations:
basic_authapikey_idapikey
path Parameters
item_id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

customer_id
string

Comma separated list of customer identifiers

ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to Monetra, an order number should be sent on all transactions.

Normally, an order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

type
object
Enum: "ORDER" "QUICK" "INVOICE"
Example: type=ORDER,QUICK

Comma separated list of order types

Flag values (comma separated):

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
object
Enum: "PENDING" "OPEN" "PARTIALPAID" "COMPLETE" "CANCEL" "FORCECLOSED"
Example: status=OPEN,PARTIALPAID

Comma separated list of order status

Flag values (comma separated):

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
  • PARTIALPAID - Order has been partially paid
  • COMPLETE - Order is complete
  • CANCEL - Order has been canceled
  • FORCECLOSED - Order was force closed
timestamp_create_bdate
string

Start of order created date range as a timestamp

timestamp_create_edate
string

End of order created date range as a timestamp

timestamp_close_bdate
string

Start of order closed date range as a timestamp

timestamp_close_edate
string

End of order closed date range as a timestamp

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/order/item/7584933567654/modifier' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add an Item Modifier

Add an item modifier to a line item

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_add
  • type = ADDON
Authorizations:
basic_authapikey_idapikey
path Parameters
item_id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ref_id
required
string\d+

Unique ID of the inventory modifier

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ref_id": "string",
  • "ringorder": "string",
  • "qty": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Remove an Item Modifier

Remove a modifier from a line item in the order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order item modifier identifier

order_id
required
string

Unique ID of an order

item_id
required
string

Order item identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/order/item/modifier/785903676' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get Item Modifier Detail

Gets details for the specified modifier

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = modifiers
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order item modifier identifier

item_id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/order/modifier/75849356543' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp_ms": "string",
  • "item_id": "string",
  • "order_id": "string",
  • "type": "ADDON",
  • "ringorder": "string",
  • "ref_id": "string",
  • "qty": "string",
  • "amount": "19.92",
  • "name": "string",
  • "is_deleted": "yes"
}

Edit an Item Modifier

Edit a line item modifier

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order item modifier identifier

order_id
required
string

Unique ID of an order

item_id
required
string

Order item identifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

ringorder
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "ringorder": "string",
  • "qty": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Order Payments

Allows associating payments to an order. As well as manging the payments applied to orders. Payments can be previous transactions made through Monetra or external payments (cash and check) that are being recorded for reporting purposes.

Add a Cash Payment

Add a cash payment to the order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = payment_add
  • tendertype = CASH
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

amount
required
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

tip
required
string\d+(\.\d{0,2})?

Tip amount

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "amount": "19.92",
  • "tip": "0.33"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Add a Check Payment

Add a check payment to the order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = payment_add
  • tendertype = CHECK
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

amount
required
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

tip
required
string\d+(\.\d{0,2})?

Tip amount

checknum
required
string\d+

Check number

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "amount": "19.92",
  • "tip": "0.33",
  • "checknum": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

List Payments

List order payments

Gets the Payments for the specified order.

The resulting report will contain these headers:

id, timestamp_ms, user, order_id, tendertype, amount, tip, status, ttid,
timestamp, cardtype, last4, cardholdername, checknum, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = payments
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

customer_id
string

Comma separated list of customer identifiers

ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to Monetra, an order number should be sent on all transactions.

Normally, an order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

type
object
Enum: "ORDER" "QUICK" "INVOICE"
Example: type=ORDER,QUICK

Comma separated list of order types

Flag values (comma separated):

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
object
Enum: "PENDING" "OPEN" "PARTIALPAID" "COMPLETE" "CANCEL" "FORCECLOSED"
Example: status=OPEN,PARTIALPAID

Comma separated list of order status

Flag values (comma separated):

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
  • PARTIALPAID - Order has been partially paid
  • COMPLETE - Order is complete
  • CANCEL - Order has been canceled
  • FORCECLOSED - Order was force closed
timestamp_create_bdate
string

Start of order created date range as a timestamp

timestamp_create_edate
string

End of order created date range as a timestamp

timestamp_close_bdate
string

Start of order closed date range as a timestamp

timestamp_close_edate
string

End of order closed date range as a timestamp

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/order/5784392456/payment' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add a Payment

Add a payment to the order

References an existing transaction.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = payment_add
  • tendertype = TXN
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ttid
required
string

Transaction identifier

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ttid": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Cancel a Payment

Cancels a cash or check payment associated with the order

A transaction that was applied to the order using a ttid cannot be canceled directly. It must be reversed which will automatically mark it as canceled in the order.

External payments, such as cash and check, that were made outside of Monetra are removed from the order using this operation. It is the responsibility of the merchant to take any further action that is necessary when canceling a payment. For example, providing cash to the customer if a cash payment was accepted.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = payment_cancel
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of a payment for an order

order_id
required
string

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/order/20245528771333405/payment/758493245430' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get Payment Detail

Gets details for the specified payment

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = payments
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of a payment for an order

order_id
required
string

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/order/payment/758493245430' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp_ms": "string",
  • "user": "string",
  • "order_id": "string",
  • "tendertype": "TXN",
  • "amount": "19.92",
  • "tip": "0.33",
  • "status": "PENDING",
  • "ttid": "string",
  • "timestamp": "string",
  • "cardtype": "VISA",
  • "last4": "string",
  • "cardholdername": "John Doe",
  • "checknum": "string",
  • "is_deleted": "yes"
}

Order Reports

Order reports allow reporting of not only orders but other systems that are utilized by orders. These reports offer insight into the use of orders to allow merchant to tailor their offerings, or meet other obligations (tip, and tax remittance).

Reports are about usage within orders. For example, the customer report allows determining how many, how often, and how much specific customers are spending.

Or the SKU activity report allows determining which SKUs are most or least popular.

Aging

Aging report for unpaid invoices grouped by customer

The resulting report will contain these headers:

customer_id, customer_display_name, current, 1-30, 31-60, 61-90,
91-120, 120+

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = aging
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string

Customer identifier

type
object
Enum: "ORDER" "QUICK" "INVOICE"
Example: type=ORDER,QUICK

Comma separated list of order types

Flag values (comma separated):

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/order/report/aging' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Customers

Customer summary

The resulting report will contain these headers:

customer_id, customer_display_name, count, total_amount

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = customersummary
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string

Customer identifier

order_id
string

Unique ID of an order

bdate
string

Start of date range

edate
string

End of date range

limit
string

Maximum number of rows to return

has_count
object
Enum: "yes" "no"
Example: has_count=yes

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/order/report/modifier?customer=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Item Discounts

Item discount summary

The resulting report will contain these headers:

discount_id, discount_name, usecase, category_id, category_name, count

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = itemdiscountsummary
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string

Order discount identifier

order_id
string

Unique ID of an order

bdate
string

Start of date range

edate
string

End of date range

limit
string

Maximum number of rows to return

has_count
object
Enum: "yes" "no"
Example: has_count=yes

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/order/report/discount/item?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Item Modifier Activity

Item Modifier activity

The resulting report will contain these headers:

modifier_id, modifier_name, modifierset_id, modifierset_name,
count

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = modifiersummary
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string

Order item modifier identifier

order_id
string

Unique ID of an order

bdate
string

Start of date range

edate
string

End of date range

limit
string

Maximum number of rows to return

has_count
object
Enum: "yes" "no"
Example: has_count=yes

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/order/report/modifier?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Order Discounts

Order discount summary

The resulting report will contain these headers:

discount_id, discount_name, usecase, category_id, category_name, count

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = orderdiscountsummary
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string

Order discount identifier

order_id
string

Unique ID of an order

bdate
string

Start of date range

edate
string

End of date range

limit
string

Maximum number of rows to return

has_count
object
Enum: "yes" "no"
Example: has_count=yes

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/order/report/discount/order?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Payments

Payment report grouped by user

The resulting report will contain these headers:

user, sale_amount, refund_amount

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = payments
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

order_in
string
tendertype
object
Enum: "TXN" "CASH" "CHECK"
Example: tendertype=TXN

Type of payment tender

Values:

  • TXN - Monetra transaction
  • CASH - Cash
  • CHECK - Check
bdate
string

Start of date range

edate
string

End of date range

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/order/report/payment?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Product Activity

Product activity

The resulting report will contain these headers:

product_id, product_name, category_id, category_name, count

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = productsummary
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string

Unique ID of the product

order_id
string

Unique ID of an order

bdate
string

Start of date range

edate
string

End of date range

limit
string

Maximum number of rows to return

has_count
object
Enum: "yes" "no"
Example: has_count=yes

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/order/report/product?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

SKU Activity

SKU activity

The resulting report will contain these headers:

sku_id, sku_name, product_id, product_name, category_id,
category_name, count

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = skusummary
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string

Unique ID of the SKU

order_id
string

Unique ID of an order

bdate
string

Start of date range

edate
string

End of date range

limit
string

Maximum number of rows to return

has_count
object
Enum: "yes" "no"
Example: has_count=yes

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/order/report/sku?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Tax History

Tax history report

The resulting report will contain these headers:

taxrate_id, taxrate_name, order_id, timestamp, amount

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = taxhistory
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string

Unique ID of the tax rate

order_id
string

Unique ID of an order

bdate
string

Start of date range

edate
string

End of date range

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/order/report/tax/history?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Tax Summary

Tax summary report

The resulting report will contain these headers:

taxrate_id, taxrate_name, amount

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = taxsummary
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string

Unique ID of the tax rate

order_id
string

Unique ID of an order

bdate
string

Start of date range

edate
string

End of date range

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/order/report/tax?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Tips

Tip report grouped by user

The resulting report will contain these headers:

user, sale_tip, refund_tip

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = tip
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

order_in
string
tendertype
object
Enum: "TXN" "CASH" "CHECK"
Example: tendertype=TXN

Type of payment tender

Values:

  • TXN - Monetra transaction
  • CASH - Cash
  • CHECK - Check
bdate
string

Start of date range

edate
string

End of date range

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/order/report/tip?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

User

User management

Accessing profiles

Users within the group will be able to access and process the profiles within the group they are in. Users can have a default profile set so they do not need to specify a profile with every transaction.

Additionally users can be locked to only allow processing with a specific profile. This allows a clerk to only process transactions for their work location while allowing someone like a floating manager to process at whichever store they happen to be at.

Change User Password

Change User Password

User's are able to change their own password provided they have the necessary permissions.

If changing another user's password, this can fail under the following conditions:

  • User whose password is being changed has greater permissions than the authenticated user
  • The RESET_PEER_PASSWD flag is not set

libmonetra KVS equivalent for endpoint

  • action_sys = user_passwd
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
id
string\d+

Conditional. User id of user to operate on, if not provided, user is required

Cannot be combined with:

  • user
user
string <= 128 characters

Conditional. Username of user to operate on, if not provided, id is required

Cannot be combined with:

  • id
pwd
string <= 256 characters

New password to set for user being edited

temporary
string
Enum: "yes" "no"

Whether the user's password is a temporary password

By default if changing another user's password, the password is temporary, meaning the user must change it immediately upon initial login. This may be set to no to make the password permanent, however this is only allowed if the user's password being modified is an UNATTENDED user. When changing a user's own password, it is always permanent and this flag is ignored.

Values:

  • yes - Password is temporary and required to be changed on first login
  • no - Password is not temporary and does not need to be changed on first login

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "user": "string",
  • "pwd": "string",
  • "temporary": "yes"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Delete User

Delete a user

Deleting a user can fail for the following conditions:

  • Cannot delete self
  • Cannot delete someone with greater perms than themselves

libmonetra KVS equivalent for endpoint

  • action_sys = user_del
Authorizations:
basic_authapikey_idapikey
query Parameters
id
string

Conditional. User id of user to operate on, if not provided, user is required

Cannot be combined with:

  • user
user
string

Conditional. Username of user to operate on, if not provided, id is required

Cannot be combined with:

  • id

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/user' \
  --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=' \
  -d '
    {
      "user": "james"
    }' \
  -H 'Content-Type: application/json; charset=utf-8'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

List Users

List users

The resulting report will contain these headers:

id, username, group_id, group_depth, status, flags, create_ts, upd_ts,
lastlogin_ts, pwchange_ts, login_fail_cnt, lock_ts, su_perms, sys_perms,
admin_perms, trans_perms, default_profile_id, name, mobilephone

status can be one of:

  • ACTIVE - good standing
  • DISABLED - administratively disabled
  • LOCKED - locked due to login failures

libmonetra KVS equivalent for endpoint

  • action_sys = user_list
Authorizations:
basic_authapikey_idapikey
query Parameters
id
string

Query a specific user id

Cannot be combined with:

  • user
user
string

Query a specific user by name

Cannot be combined with:

  • id
group_id
string

Query starting at a specific group id, if not specified, defaults to user's group id.

maxdepth
string

Maximum group depth to display

Default is unlimited. Specify 1 to see only self and children.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/user?user=james' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "report": {
    }
}

Edit User

Edits a user

If id is specified user can also be specified in order to change the username.

If editing self, cannot edit perms, or flags. Can edit other fields though.

libmonetra KVS equivalent for endpoint

  • action_sys = user_edit
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
id
string\d+

Conditional. User id of user to operate on, if not provided, user is required

Cannot be combined with:

  • user
user
string <= 128 characters

Conditional. Username of user to operate on, if not provided, id is required

Cannot be combined with:

  • id
default_profile_id
string\d+

Profile id of the default profile the user is assigned to use

So they can run transactions without specifying a profile.

If not specified, will auto-link to the profile at the same group level, if there is only one. If there are none or more than 1, will remain unlinked.

email
string <= 128 characters

email

flags
string
Enum: "UNATTENDED" "SELFVIEWONLY" "MFA" "ALLOW_UNLINKED_REFUND" "RESET_PEER_PASSWD"

Flag values (pipe separated):

  • UNATTENDED - Meant for system/application/integration accounts
  • SELFVIEWONLY - Cannot see anything about other users such as the users themselves nor any transactions other users have performed
  • MFA - The user is enabled for multifactor authentication. Cannot be enabled or disabled on a user unless the current user has the flag set, unless the group mandates MFA on users (in which case that takes precedence and cannot be disabled). Unattended users cannot have MFA enabled.
  • ALLOW_UNLINKED_REFUND - Allow refunds via key or card entry rather than requiring them be linked to a prior transaction. If this flag is not set, even when linked to a prior transaction it will ensure that the prior transaction is a SALE and the total amounts of the refunds for all linked never exceed the original total
  • RESET_PEER_PASSWD - The user is allowed to change the password of a peer that has less than or equal permissions
su_perms
string
Enum: "ALL" "IMPORTEXPORT" "MAINTENANCE" "P2PE_BDK_GENERATE" "P2PE_BDK_DEACTIVATE" "P2PE_BDK_LIST" "P2PE_BDK_EDIT" "P2PE_BDK_EXPORT" "P2PE_BDK_PRINT" "P2PE_BDK_KCV" "P2PE_DEVICE_PROVISION" "P2PE_DEVICE_DEACTIVATE" "P2PE_DEVICE_LIST" "P2PE_DEVICE_EDIT" "E2EE_KEY_GENERATE" "E2EE_KEY_EDIT" "E2EE_KEY_LIST" "E2EE_KEY_DEACTIVATE" "BIGBATCH_MANAGE" "BIGBATCH" "BIGBATCH_SETTLE" "PRODUCT_LICENSE" "PUSHNOTIFICATION" "TOKEN_EXPORT"

System restricted access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • IMPORTEXPORT - Allow importing and exporting database data
  • MAINTENANCE - Enable maintains mode to prevent transaction processing. Primarily used in conjunction with IMPORTEXPORT permission
  • P2PE_BDK_GENERATE - Generate a Base Derivation Key for P2PE device encryption
  • P2PE_BDK_DEACTIVATE - Deactivate a P2PE Base Derivation Key
  • P2PE_BDK_LIST - List P2PE Base Derivation Key
  • P2PE_BDK_EDIT - Edit a P2PE Base Derivation Key
  • P2PE_BDK_EXPORT - Export a P2PE Base Derivation Key for sharing with a Key Injection Facility
  • P2PE_BDK_PRINT - Print encrypted P2PE Base Derivation Key on a compatible printer. Only applies when keys are managed by an HSM
  • P2PE_BDK_KCV - P2PE Base Derivation Key Check Value
  • P2PE_DEVICE_PROVISION - Provision a device in Monetra that uses P2PE. Provisioning is required for Validated P2PE, non validated P2PW Monetra will auto provision devices on first use
  • P2PE_DEVICE_DEACTIVATE - Deactivate a P2PE Device
  • P2PE_DEVICE_LIST - List P2PE devices
  • P2PE_DEVICE_EDIT - Edit P2PE device
  • E2EE_KEY_GENERATE - Generate E2EE keys used for encrypted transport. Such a transaction export and import between multiple installations of Monetra
  • E2EE_KEY_EDIT - Edit E2EE keys used for encrypted transport.
  • E2EE_KEY_LIST - List E2EE keys used for encrypted transport.
  • E2EE_KEY_DEACTIVATE - Deactivate E2EE keys used for encrypted transport.
  • BIGBATCH_MANAGE - Manage Big Batch accounts
  • BIGBATCH - Big Batch Reporting
  • BIGBATCH_SETTLE - Settle Big Batch batches
  • PRODUCT_LICENSE - Manage products that have been registered with Monetra
  • PUSHNOTIFICATION - Manage push notification endpoints
  • TOKEN_EXPORT - Store account export
sys_perms
string
Enum: "ALL" "V8_COMPLEX_EMULATION" "GETPERMS" "GROUP_ADD" "GROUP_EDIT" "GROUP_MOVE" "GROUP_DEL" "GROUP_LIST" "USER_ADD" "USER_EDIT" "USER_MOVE" "USER_DEL" "USER_LIST" "USER_ENABLE" "USER_DISABLE" "USER_PASSWD" "USER_UNLOCK" "PROFILE_ADD" "PROFILE_EDIT" "PROFILE_MOVE" "PROFILE_DEL" "PROFILE_LIST" "PROFILE_STATS" "PROFILE_ENABLE" "PROFILE_DISABLE" "ROUTE_ADD" "ROUTE_EDIT" "ROUTE_DEL" "ROUTE_LIST" "ROUTE_FIELDS" "CRON" "INFO" "SETLOGGING" "REGISTER_CLIENT" "SKYLINK_MANAGE" "APIKEYS" "MFA_GENERATE" "MFA_RESET" "SECURITY_QUESTIONS"

System access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • V8_COMPLEX_EMULATION - Allow Monetra v8 protocol emulation. Allows equivalent v8 protocol actions to be used
  • GETPERMS - Get user permissions
  • GROUP_ADD - Create a group
  • GROUP_EDIT - Edit a group
  • GROUP_MOVE - Move a group to a different group
  • GROUP_DEL - Delete a group
  • GROUP_LIST - List groups
  • USER_ADD - Create a user
  • USER_EDIT - Edit a user
  • USER_MOVE - Move a user to a different group
  • USER_DEL - Delete a user
  • USER_LIST - List users
  • USER_ENABLE - Enable a user
  • USER_DISABLE - Disable a user
  • USER_PASSWD - Change a user's password. Includes self
  • USER_UNLOCK - Unlock a user
  • PROFILE_ADD - Add a profile
  • PROFILE_EDIT - Edit a profile
  • PROFILE_MOVE - Move a profile to a different group
  • PROFILE_DEL - Delete a profile
  • PROFILE_LIST - List profiles
  • PROFILE_STATS - Profile statics
  • PROFILE_ENABLE - Enable a profile
  • PROFILE_DISABLE - Disable a profile
  • ROUTE_ADD - Add a route
  • ROUTE_EDIT - Edit a route
  • ROUTE_DEL - Delete a route
  • ROUTE_LIST - List routes
  • ROUTE_FIELDS - Get processor specific fields for use with adding or editing a route
  • CRON - System task scheduler operations
  • INFO - Monetra information
  • SETLOGGING - Start / Stop an in memory logging buffer
  • REGISTER_CLIENT - Registers use of a product with Monetra
  • SKYLINK_MANAGE - Manage SkyLink product licences
  • APIKEYS - API key management
  • MFA_GENERATE - Enable or change MFA method
  • MFA_RESET - Reset MFA so it needs to be generated
  • SECURITY_QUESTIONS - User security questions
admin_perms
string
Enum: "REPORT_TRAN" "REPORT_TOTALS" "REPORT_CHARTDATA" "REPORT_QUEUE" "BATCH_CLEAR" "BATCH_SET" "BATCH_RESCIND" "BATCH_CLOSE" "TRAN_EDIT" "TRAN_NULLIFY" "TRAN_DETAIL" "TRAN_RECEIPT" "TRAN_IMPORT" "TRAN_EXPORT" "MERCH_INFO" "IMAGE_ADD" "IMAGE_DEL" "IMAGE_GET" "TOKEN_ADD" "TOKEN_EDIT" "TOKEN_DEL" "TOKEN_SCHEDULE" "TOKEN_LIST" "CUSTOMER_ADD" "CUSTOMER_EDIT" "CUSTOMER_DEL" "CUSTOMER_LIST" "TICKETREQUEST" "LEVEL3" "TRAN_EXPORT" "TRAN_IMPORT" "PRODMANAGE" "PRODLIST" "ORDERMANAGE" "ORDERLIST" "ORDERREPORT" "CARDDENYLIST" "P2PE" "STANDINKEY_GENERATE"

Administrative access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • REPORT_TRAN - Transaction and batch detail reports
  • REPORT_TOTALS - Transaction and batch total reports
  • REPORT_CHARTDATA - Card data breakdown for report views
  • REPORT_QUEUE - List queued transactions pending authorization
  • BATCH_CLEAR - Mark batch as settled without funding
  • BATCH_SET - Change batch number
  • BATCH_RESCIND - Unsettle a batch (can double charge customers)
  • BATCH_CLOSE - Close a batch so new transactions are not added but do not settle
  • TRAN_EDIT - Edit a transaction
  • TRAN_NULLIFY - Delete a previously-authorized transaction without any attempt to go online and remove an authorization hold. Similar to a void.
  • TRAN_DETAIL - Transaction details
  • TRAN_RECEIPT - Transaction receipts. Generating and sending receipts, and invoices
  • TRAN_IMPORT - Import transaction data from a different Monetra into this instance of Monetra
  • TRAN_EXPORT - Emport transaction data from Monetra into a different instance of Monetra
  • MERCH_INFO - Profile information
  • IMAGE_ADD - Store an image. Check, signature, etc
  • IMAGE_DEL - Delete an image. Check, signature, etc
  • IMAGE_GET - Get an image. Check, signature, etc
  • TOKEN_ADD - Store an account
  • TOKEN_EDIT - Edit a stored account
  • TOKEN_DEL - Delete a stored account
  • TOKEN_SCHEDULE - Manage recurring and installment payments
  • TOKEN_LIST - List stored accounts
  • CUSTOMER_ADD - Add a customer
  • CUSTOMER_EDIT - Edit a customer
  • CUSTOMER_DEL - Delete a customer
  • CUSTOMER_LIST - List customers
  • TICKETREQUEST - Request temporary cardshieldticket representing a customer's account
  • LEVEL3 - Level 3 line item operations
  • TRAN_EXPORT - Export transaction data to import into another Monetra
  • TRAN_IMPORT - Import transaction data into Monetra
  • PRODMANAGE - Manage products (sku, amount, etc) in the inventory system
  • PRODLIST - List product details in the inventory system
  • ORDERMANAGE - Manage orders and invoices
  • ORDERLIST - List orders and invoices
  • ORDERREPORT - Reports for orders and invoices
  • CARDDENYLIST - Manage the card deny list
  • P2PE - P2PE device management
  • STANDINKEY_GENERATE - Generate an encryption key used for encrypting account data as part of stand-in authorization
trans_perms
string
Enum: "VERIFYONLY" "SALE" "PREAUTH" "REVERSAL" "INCREMENTAL" "PREAUTHCOMPLETE" "FORCE" "CAPTURE" "VOID" "ADJUST" "REFUND" "ACTIVATE" "BALANCEINQ" "CASHOUT" "TOREVERSAL" "MERCHRETURN" "ISSUE" "TIP" "EBTFSSALE" "EBTFSRETURN" "EBTFSVOUCHER" "EBTFSBALANCE" "EBTCBSALE" "EBTCBCASH" "EBTCBBALANCE" "CHECKVERIFY" "CHECKCONVONLY" "CHECKCONVVRFY" "CHECKCONVGUAR" "CHECKCONVOVER" "CHECKIMAGEUPLOAD" "SETTLE" "SETTLERFR" "TERMLOAD" "INTERACMAC" "EMVCOMPLETE" "ALTPAYMENTINIT" "CARDTYPE"

Transaction access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • VERIFYONLY - Card verification
  • SALE - Purchase
  • PREAUTH - Authorization only (preauth)
  • REVERSAL - Reverse a transaction
  • INCREMENTAL - Incremental
  • PREAUTHCOMPLETE - Complete an authorization only (preauth) transaction
  • FORCE - Force purchase without online authorization
  • CAPTURE - Capture an un-captured transaction
  • VOID - Void a trasnaction
  • ADJUST - Adjust a transaction
  • REFUND - Refund
  • ACTIVATE - Activate a private label gift card
  • BALANCEINQ - Request account balance
  • CASHOUT - Remove all funds from a gift card in order to provide the customer with cash for the value
  • TOREVERSAL - Timeout reversal
  • MERCHRETURN - Merchandise return. Used by gift cards
  • ISSUE - Issue a gift card
  • TIP - Add a tip to a gift card
  • EBTFSSALE - Electronic Benefits Transfer food purchase
  • EBTFSRETURN - Electronic Benefits Transfer food refund
  • EBTFSVOUCHER - Electronic Benefits Transfer food voucher (paper food stamps) purchase
  • EBTFSBALANCE - Electronic Benefits Transfer food balance
  • EBTCBSALE - Electronic Benefits Transfer cash purchase
  • EBTCBCASH - Electronic Benefits Transfer cash withdrawal
  • EBTCBBALANCE - Electronic Benefits Transfer cash balance
  • CHECKVERIFY - Check verification only (without conversion)
  • CHECKCONVONLY - Check conversion only (without verification)
  • CHECKCONVVRFY - Check verification and conversion
  • CHECKCONVGUAR - Check conversation guarantee
  • CHECKCONVOVER - Convert a check with override
  • CHECKIMAGEUPLOAD - Upload check image
  • SETTLE - Settle
  • SETTLERFR - Request Settlement Status (limited processor support)
  • TERMLOAD - Terminal loading data
  • INTERACMAC - Interac MACing parameters
  • EMVCOMPLETE - EMV completion transaction
  • ALTPAYMENTINIT - Init an alternative payment method
  • CARDTYPE - Determine cardtype of presented account
name
string <= 128 characters

User's real name

phone_mobile
string <= 32 characters [-+0-9() .]*

Mobile phone

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "user": "string",
  • "default_profile_id": "string",
  • "email": "string",
  • "flags": "UNATTENDED",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "REPORT_TRAN",
  • "trans_perms": "VERIFYONLY",
  • "name": "string",
  • "phone_mobile": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Create User

Creates a user

Fail if there are explicitly specified perms and perms are greater than allowed.

libmonetra KVS equivalent for endpoint

  • action_sys = user_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
user
required
string <= 128 characters

User name of user to add

pwd
required
string <= 256 characters

Password to set for user being added

group_id
string\d+

Group user should be added to. If not specified, defaults to the same group as the current user

default_profile_id
string\d+

Profile id of the default profile the user is assigned to use

So they can run transactions without specifying a profile.

If not specified, will auto-link to the profile at the same group level, if there is only one. If there are none or more than 1, will remain unlinked.

email
string <= 128 characters

email

flags
string
Enum: "UNATTENDED" "SELFVIEWONLY" "MFA" "ALLOW_UNLINKED_REFUND" "RESET_PEER_PASSWD"

Flag values (pipe separated):

  • UNATTENDED - Meant for system/application/integration accounts
  • SELFVIEWONLY - Cannot see anything about other users such as the users themselves nor any transactions other users have performed
  • MFA - The user is enabled for multifactor authentication. Cannot be enabled or disabled on a user unless the current user has the flag set, unless the group mandates MFA on users (in which case that takes precedence and cannot be disabled). Unattended users cannot have MFA enabled.
  • ALLOW_UNLINKED_REFUND - Allow refunds via key or card entry rather than requiring them be linked to a prior transaction. If this flag is not set, even when linked to a prior transaction it will ensure that the prior transaction is a SALE and the total amounts of the refunds for all linked never exceed the original total
  • RESET_PEER_PASSWD - The user is allowed to change the password of a peer that has less than or equal permissions
su_perms
string
Enum: "ALL" "IMPORTEXPORT" "MAINTENANCE" "P2PE_BDK_GENERATE" "P2PE_BDK_DEACTIVATE" "P2PE_BDK_LIST" "P2PE_BDK_EDIT" "P2PE_BDK_EXPORT" "P2PE_BDK_PRINT" "P2PE_BDK_KCV" "P2PE_DEVICE_PROVISION" "P2PE_DEVICE_DEACTIVATE" "P2PE_DEVICE_LIST" "P2PE_DEVICE_EDIT" "E2EE_KEY_GENERATE" "E2EE_KEY_EDIT" "E2EE_KEY_LIST" "E2EE_KEY_DEACTIVATE" "BIGBATCH_MANAGE" "BIGBATCH" "BIGBATCH_SETTLE" "PRODUCT_LICENSE" "PUSHNOTIFICATION" "TOKEN_EXPORT"

System restricted access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • IMPORTEXPORT - Allow importing and exporting database data
  • MAINTENANCE - Enable maintains mode to prevent transaction processing. Primarily used in conjunction with IMPORTEXPORT permission
  • P2PE_BDK_GENERATE - Generate a Base Derivation Key for P2PE device encryption
  • P2PE_BDK_DEACTIVATE - Deactivate a P2PE Base Derivation Key
  • P2PE_BDK_LIST - List P2PE Base Derivation Key
  • P2PE_BDK_EDIT - Edit a P2PE Base Derivation Key
  • P2PE_BDK_EXPORT - Export a P2PE Base Derivation Key for sharing with a Key Injection Facility
  • P2PE_BDK_PRINT - Print encrypted P2PE Base Derivation Key on a compatible printer. Only applies when keys are managed by an HSM
  • P2PE_BDK_KCV - P2PE Base Derivation Key Check Value
  • P2PE_DEVICE_PROVISION - Provision a device in Monetra that uses P2PE. Provisioning is required for Validated P2PE, non validated P2PW Monetra will auto provision devices on first use
  • P2PE_DEVICE_DEACTIVATE - Deactivate a P2PE Device
  • P2PE_DEVICE_LIST - List P2PE devices
  • P2PE_DEVICE_EDIT - Edit P2PE device
  • E2EE_KEY_GENERATE - Generate E2EE keys used for encrypted transport. Such a transaction export and import between multiple installations of Monetra
  • E2EE_KEY_EDIT - Edit E2EE keys used for encrypted transport.
  • E2EE_KEY_LIST - List E2EE keys used for encrypted transport.
  • E2EE_KEY_DEACTIVATE - Deactivate E2EE keys used for encrypted transport.
  • BIGBATCH_MANAGE - Manage Big Batch accounts
  • BIGBATCH - Big Batch Reporting
  • BIGBATCH_SETTLE - Settle Big Batch batches
  • PRODUCT_LICENSE - Manage products that have been registered with Monetra
  • PUSHNOTIFICATION - Manage push notification endpoints
  • TOKEN_EXPORT - Store account export
sys_perms
string
Enum: "ALL" "V8_COMPLEX_EMULATION" "GETPERMS" "GROUP_ADD" "GROUP_EDIT" "GROUP_MOVE" "GROUP_DEL" "GROUP_LIST" "USER_ADD" "USER_EDIT" "USER_MOVE" "USER_DEL" "USER_LIST" "USER_ENABLE" "USER_DISABLE" "USER_PASSWD" "USER_UNLOCK" "PROFILE_ADD" "PROFILE_EDIT" "PROFILE_MOVE" "PROFILE_DEL" "PROFILE_LIST" "PROFILE_STATS" "PROFILE_ENABLE" "PROFILE_DISABLE" "ROUTE_ADD" "ROUTE_EDIT" "ROUTE_DEL" "ROUTE_LIST" "ROUTE_FIELDS" "CRON" "INFO" "SETLOGGING" "REGISTER_CLIENT" "SKYLINK_MANAGE" "APIKEYS" "MFA_GENERATE" "MFA_RESET" "SECURITY_QUESTIONS"

System access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • V8_COMPLEX_EMULATION - Allow Monetra v8 protocol emulation. Allows equivalent v8 protocol actions to be used
  • GETPERMS - Get user permissions
  • GROUP_ADD - Create a group
  • GROUP_EDIT - Edit a group
  • GROUP_MOVE - Move a group to a different group
  • GROUP_DEL - Delete a group
  • GROUP_LIST - List groups
  • USER_ADD - Create a user
  • USER_EDIT - Edit a user
  • USER_MOVE - Move a user to a different group
  • USER_DEL - Delete a user
  • USER_LIST - List users
  • USER_ENABLE - Enable a user
  • USER_DISABLE - Disable a user
  • USER_PASSWD - Change a user's password. Includes self
  • USER_UNLOCK - Unlock a user
  • PROFILE_ADD - Add a profile
  • PROFILE_EDIT - Edit a profile
  • PROFILE_MOVE - Move a profile to a different group
  • PROFILE_DEL - Delete a profile
  • PROFILE_LIST - List profiles
  • PROFILE_STATS - Profile statics
  • PROFILE_ENABLE - Enable a profile
  • PROFILE_DISABLE - Disable a profile
  • ROUTE_ADD - Add a route
  • ROUTE_EDIT - Edit a route
  • ROUTE_DEL - Delete a route
  • ROUTE_LIST - List routes
  • ROUTE_FIELDS - Get processor specific fields for use with adding or editing a route
  • CRON - System task scheduler operations
  • INFO - Monetra information
  • SETLOGGING - Start / Stop an in memory logging buffer
  • REGISTER_CLIENT - Registers use of a product with Monetra
  • SKYLINK_MANAGE - Manage SkyLink product licences
  • APIKEYS - API key management
  • MFA_GENERATE - Enable or change MFA method
  • MFA_RESET - Reset MFA so it needs to be generated
  • SECURITY_QUESTIONS - User security questions
admin_perms
string
Enum: "REPORT_TRAN" "REPORT_TOTALS" "REPORT_CHARTDATA" "REPORT_QUEUE" "BATCH_CLEAR" "BATCH_SET" "BATCH_RESCIND" "BATCH_CLOSE" "TRAN_EDIT" "TRAN_NULLIFY" "TRAN_DETAIL" "TRAN_RECEIPT" "TRAN_IMPORT" "TRAN_EXPORT" "MERCH_INFO" "IMAGE_ADD" "IMAGE_DEL" "IMAGE_GET" "TOKEN_ADD" "TOKEN_EDIT" "TOKEN_DEL" "TOKEN_SCHEDULE" "TOKEN_LIST" "CUSTOMER_ADD" "CUSTOMER_EDIT" "CUSTOMER_DEL" "CUSTOMER_LIST" "TICKETREQUEST" "LEVEL3" "TRAN_EXPORT" "TRAN_IMPORT" "PRODMANAGE" "PRODLIST" "ORDERMANAGE" "ORDERLIST" "ORDERREPORT" "CARDDENYLIST" "P2PE" "STANDINKEY_GENERATE"

Administrative access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • REPORT_TRAN - Transaction and batch detail reports
  • REPORT_TOTALS - Transaction and batch total reports
  • REPORT_CHARTDATA - Card data breakdown for report views
  • REPORT_QUEUE - List queued transactions pending authorization
  • BATCH_CLEAR - Mark batch as settled without funding
  • BATCH_SET - Change batch number
  • BATCH_RESCIND - Unsettle a batch (can double charge customers)
  • BATCH_CLOSE - Close a batch so new transactions are not added but do not settle
  • TRAN_EDIT - Edit a transaction
  • TRAN_NULLIFY - Delete a previously-authorized transaction without any attempt to go online and remove an authorization hold. Similar to a void.
  • TRAN_DETAIL - Transaction details
  • TRAN_RECEIPT - Transaction receipts. Generating and sending receipts, and invoices
  • TRAN_IMPORT - Import transaction data from a different Monetra into this instance of Monetra
  • TRAN_EXPORT - Emport transaction data from Monetra into a different instance of Monetra
  • MERCH_INFO - Profile information
  • IMAGE_ADD - Store an image. Check, signature, etc
  • IMAGE_DEL - Delete an image. Check, signature, etc
  • IMAGE_GET - Get an image. Check, signature, etc
  • TOKEN_ADD - Store an account
  • TOKEN_EDIT - Edit a stored account
  • TOKEN_DEL - Delete a stored account
  • TOKEN_SCHEDULE - Manage recurring and installment payments
  • TOKEN_LIST - List stored accounts
  • CUSTOMER_ADD - Add a customer
  • CUSTOMER_EDIT - Edit a customer
  • CUSTOMER_DEL - Delete a customer
  • CUSTOMER_LIST - List customers
  • TICKETREQUEST - Request temporary cardshieldticket representing a customer's account
  • LEVEL3 - Level 3 line item operations
  • TRAN_EXPORT - Export transaction data to import into another Monetra
  • TRAN_IMPORT - Import transaction data into Monetra
  • PRODMANAGE - Manage products (sku, amount, etc) in the inventory system
  • PRODLIST - List product details in the inventory system
  • ORDERMANAGE - Manage orders and invoices
  • ORDERLIST - List orders and invoices
  • ORDERREPORT - Reports for orders and invoices
  • CARDDENYLIST - Manage the card deny list
  • P2PE - P2PE device management
  • STANDINKEY_GENERATE - Generate an encryption key used for encrypting account data as part of stand-in authorization
trans_perms
string
Enum: "VERIFYONLY" "SALE" "PREAUTH" "REVERSAL" "INCREMENTAL" "PREAUTHCOMPLETE" "FORCE" "CAPTURE" "VOID" "ADJUST" "REFUND" "ACTIVATE" "BALANCEINQ" "CASHOUT" "TOREVERSAL" "MERCHRETURN" "ISSUE" "TIP" "EBTFSSALE" "EBTFSRETURN" "EBTFSVOUCHER" "EBTFSBALANCE" "EBTCBSALE" "EBTCBCASH" "EBTCBBALANCE" "CHECKVERIFY" "CHECKCONVONLY" "CHECKCONVVRFY" "CHECKCONVGUAR" "CHECKCONVOVER" "CHECKIMAGEUPLOAD" "SETTLE" "SETTLERFR" "TERMLOAD" "INTERACMAC" "EMVCOMPLETE" "ALTPAYMENTINIT" "CARDTYPE"

Transaction access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • VERIFYONLY - Card verification
  • SALE - Purchase
  • PREAUTH - Authorization only (preauth)
  • REVERSAL - Reverse a transaction
  • INCREMENTAL - Incremental
  • PREAUTHCOMPLETE - Complete an authorization only (preauth) transaction
  • FORCE - Force purchase without online authorization
  • CAPTURE - Capture an un-captured transaction
  • VOID - Void a trasnaction
  • ADJUST - Adjust a transaction
  • REFUND - Refund
  • ACTIVATE - Activate a private label gift card
  • BALANCEINQ - Request account balance
  • CASHOUT - Remove all funds from a gift card in order to provide the customer with cash for the value
  • TOREVERSAL - Timeout reversal
  • MERCHRETURN - Merchandise return. Used by gift cards
  • ISSUE - Issue a gift card
  • TIP - Add a tip to a gift card
  • EBTFSSALE - Electronic Benefits Transfer food purchase
  • EBTFSRETURN - Electronic Benefits Transfer food refund
  • EBTFSVOUCHER - Electronic Benefits Transfer food voucher (paper food stamps) purchase
  • EBTFSBALANCE - Electronic Benefits Transfer food balance
  • EBTCBSALE - Electronic Benefits Transfer cash purchase
  • EBTCBCASH - Electronic Benefits Transfer cash withdrawal
  • EBTCBBALANCE - Electronic Benefits Transfer cash balance
  • CHECKVERIFY - Check verification only (without conversion)
  • CHECKCONVONLY - Check conversion only (without verification)
  • CHECKCONVVRFY - Check verification and conversion
  • CHECKCONVGUAR - Check conversation guarantee
  • CHECKCONVOVER - Convert a check with override
  • CHECKIMAGEUPLOAD - Upload check image
  • SETTLE - Settle
  • SETTLERFR - Request Settlement Status (limited processor support)
  • TERMLOAD - Terminal loading data
  • INTERACMAC - Interac MACing parameters
  • EMVCOMPLETE - EMV completion transaction
  • ALTPAYMENTINIT - Init an alternative payment method
  • CARDTYPE - Determine cardtype of presented account
name
string <= 128 characters

User's real name

phone_mobile
string <= 32 characters [-+0-9() .]*

Mobile phone

Responses

Request samples

Content type
application/json
{
  • "user": "string",
  • "pwd": "string",
  • "group_id": "string",
  • "default_profile_id": "string",
  • "email": "string",
  • "flags": "UNATTENDED",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "REPORT_TRAN",
  • "trans_perms": "VERIFYONLY",
  • "name": "string",
  • "phone_mobile": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Disable User

Disable User that is enabled

Will return failure if user is disabled or locked.

Admistratively disables a user. The user cannot be used until enabled. This will not expire and the user must be manually enabled.

libmonetra KVS equivalent for endpoint

  • action_sys = user_disable
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
id
string\d+

Conditional. User id of user to operate on, if not provided, user is required

Cannot be combined with:

  • user
user
string <= 128 characters

Conditional. Username of user to operate on, if not provided, id is required

Cannot be combined with:

  • id

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "user": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Enable User

Enable User that was disabled

Will return failure if user is not currently disabled.

Admistratively enable a user. The user must have been previously disabled. Locked user's are not considered disabled and should be unlocked using the unlock action.

libmonetra KVS equivalent for endpoint

  • action_sys = user_enable
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
id
string\d+

Conditional. User id of user to operate on, if not provided, user is required

Cannot be combined with:

  • user
user
string <= 128 characters

Conditional. Username of user to operate on, if not provided, id is required

Cannot be combined with:

  • id

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "user": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Permissions

Gets the user's permissions

This is the permissions for the authenticating user. In order to get permissions for a specific user, use the "List Users" report filtering on the user in question.

This action should be used for password / API key verification if needing to verify before further processing take place.

libmonetra KVS equivalent for endpoint

  • action_sys = getperms
Authorizations:
basic_authapikey_idapikey

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/user/permissions' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "pass_expire_secs": "string",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "REPORT_TRAN",
  • "trans_perms": "VERIFYONLY"
}

Move User

Move a user to a different group

Moving to a different group can fail for the following conditions:

  • User perms exceed new group perms.
  • Authenticated user (the one doing the move) has lesser perms than user being moved.

libmonetra KVS equivalent for endpoint

  • action_sys = user_move
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
id
required
string\d+

User id

group_id
required
string\d+

Group identifier

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "group_id": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Unlock User

Unlock a locked user

Will return failure if user not locked.

Users are automatically locked after too many login failures. Locking is temporary and will expire automatically after a set amount of time. The unlock action unlocks the user without having to wait for the lock time period to elapse.

libmonetra KVS equivalent for endpoint

  • action_sys = user_unlock
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
id
string\d+

Conditional. User id of user to operate on, if not provided, user is required

Cannot be combined with:

  • user
user
string <= 128 characters

Conditional. Username of user to operate on, if not provided, id is required

Cannot be combined with:

  • id

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "user": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

MFA

User multi factor authentication management

Multi Factor Authentication (MFA) is supported using a variety of methods. See "Generating" for more information about each method. Also see the "MFA Code" section under the main "Authentication" information.

MFA can be enabled for any user at any time. Groups can mandate that all users within the group and in any subgroup must enable MFA.

This section is for managing MFA not generating an MFA code. MFA code generation is an out of band process.

Generate Multi Factor Authentication

Generate (or replace) the existing Multi Factor Authentication mechanism

This requires the full username and password, an APIKey cannot be used to call this function. If MFA is already set up on the account, the existing MFA code must also be provided.

phone_mobile or email can be provided if the corresponding type is chosen to explictly set where the code should be sent. It is not required if the user account already has these configured.

When an action is attempted that requires MFA but an MFA code is not provided an msoft_code=ACCT_MFA_REQUIRED will be returned. If sms or email codes methods were chosen, an sms or email will automatically be trigered to send the MFA code to the user.

If the user does not already have the MFA user flag, it will be automatically added to the account.

libmonetra KVS equivalent for endpoint

  • action_sys = mfa_generate
  • mfa_generate = totp
Authorizations:
basic_auth
Request Body schema: application/json
type
required
string
Enum: "TOTP_APP" "TOTP_SMS" "TOTP_EMAIL"

Values:

  • TOTP_APP - Using external application, such as Google Authenticator, Authy, or Last Pass Authenticator
  • TOTP_SMS - Send TOTP-based text messages with 6 digit code to phone_mobile configured on user account
  • TOTP_EMAIL - TOTP-based email messages with 6 digit code to email configured on user account
phone_mobile
string <= 32 characters [-+0-9() .]*

Mobile phone

email
string <= 128 characters

email

Responses

Request samples

Content type
application/json
{
  • "type": "TOTP_APP",
  • "phone_mobile": "string",
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "key": "string"
}

Generate Multi Factor Authentication Cookie

MFA timed bypass with authentication cookie

It is desirable for many web interfaces to not constantly prompt for MFA, but instead let a user choose that they are on a private trusted device and to store a cookie on the system for a duration that can be used in place of MFA.

A real MFA code is required to request a cookie that will be valid for the desired duration, specified in seconds. The maximum duration allowed to be specified is 30 days (2592000s), minimum is 15 minutes (900s), though periods less than 24hrs may be a questionable use.

The cookie will need to be presented instead of the MFA code, and will be passed in the same API field of mfa_code, just as the TOTP code normally is.

This is NOT an API key, it still requires the valid username and password to be specified when using it. This is purely an MFA code.

A single user account may have up to 5 generated cookies that are valid at any time, if a new one is requested and the limit is exceeded, it will replace the old one. (multiples are allowed to allow logins from multiple devices or browsers).

The cookie should be stored in a browser cookie for web UIs (perhaps encrypted, but implementation dependent)

Generally, upon logging into a web system, an integrator should generate a temporary auto-extending api key. The cookie can be used for this purpose.

If the cookie is expired, the user will only get the msoft_code=ACCT_MFA_INVALID response and it will be treated as an error so a validity period should also be tracked by the cookie so as to not cause authentication failures that could lead to blacklisting.

libmonetra KVS equivalent for endpoint

  • action_sys = mfa_generate
  • mfa_generate = cookie
Authorizations:
basic_auth
Request Body schema: application/json
expire_s
required
string\d+

Number of seconds this cookie is requested to be valid for

The valid range is 15 minutes to 30 days (900s - 2592000s). Generally an expiration period will be 24hrs or more.

Responses

Request samples

Content type
application/json
{
  • "expire_s": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "key": "string",
  • "expire_ts": "string"
}

Reset Multi Factor Authentication

Reset Multi Factor Authentication so it needs to be generated

MFA will remain enabled requiring the user to generate an MFA key.

user or id must be provided to reset the MFA for the specified user. MFA self reset is not allowed. Self reset requres the user to utilize the 3-step self reset process.

Subsequent operations will return the msoft_code=MFA_GENERATE indicating MFA needs to be generated.

libmonetra KVS equivalent for endpoint

  • action_sys = mfa_reset
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
id
string\d+

Conditional. User id of user to operate on, if not provided, user will be used if it was provided

Cannot be combined with:

  • user
user
string <= 128 characters

Conditional. Username of user to operate on, if not provided, id will be used if it was provided

Cannot be combined with:

  • id

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "user": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Self Reset

User self password and MFA reset management. Users are able to initiate a reset request for their password and MFA tokens when they've forgotten one or the other.

In order to do this, they must have security questions on file and know the answers. They also must have a phone number for SMS or an email on file because part of the process involves sending them a verification code.

The reset processes are multi-step with, as indicated, out of band verification of the user.

List Security Questions

List security questions

libmonetra KVS equivalent for endpoint

  • action_sys = security_questions
  • security_questions = list
Authorizations:
basic_authapikey_idapikey

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/user/security_questions' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "question1": "string",
  • "question2": "string",
  • "question3": "string",
  • "created_ts": "string",
  • "upd_ts": "string"
}

Edit Security Questions

Edit security questions

libmonetra KVS equivalent for endpoint

  • action_sys = security_questions
  • security_questions = edit
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
question1
string [ 3 .. 128 ] characters .{3,128}

Security question

question2
string [ 3 .. 128 ] characters .{3,128}

Security question

question3
string [ 3 .. 128 ] characters .{3,128}

Security question

answer1
string

Security answer

answer2
string

Security answer

answer3
string

Security answer

Responses

Request samples

Content type
application/json
{
  • "question1": "string",
  • "question2": "string",
  • "question3": "string",
  • "answer1": "string",
  • "answer2": "string",
  • "answer3": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Create Security Questions

Create user's security questions

  • Operates only on the logged-in user
  • User must be a normal attended user
  • Unattended users are not allowed
  • Questions may not be duplicates nor contain the username
  • Answers may not be duplicates nor contain the username or password, and must be at least 3 alpha-numeric characters (excluding whitespace and punctuation)

libmonetra KVS equivalent for endpoint

  • action_sys = security_questions
  • security_questions = add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
question1
required
string [ 3 .. 128 ] characters .{3,128}

Security question

question2
required
string [ 3 .. 128 ] characters .{3,128}

Security question

question3
required
string [ 3 .. 128 ] characters .{3,128}

Security question

answer1
required
string

Security answer

answer2
required
string

Security answer

answer3
required
string

Security answer

Responses

Request samples

Content type
application/json
{
  • "question1": "string",
  • "question2": "string",
  • "question3": "string",
  • "answer1": "string",
  • "answer2": "string",
  • "answer3": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Self MFA Reset - Step 1: Code

User self-reset of multi factor authentication

This is a multi-step process consisting of several steps.

  1. code
  2. security_questions
  3. reset

This relies on a one-time use verification code to initiate the reset attempt which will be emailed or sent via SMS to the user. This code is then entered into a follow-up request to retrieve the user's security questions. The final follow-up will pass the same verification code and all 3 security question answers.

The reset operation may be initiated at most 3 times in a 24hr period. The emailed or sms code may only be used once for each step of the reset operation.

The user is required to authenticate using their username and mfa.

If the user does not have security questions configured this action will fail with an error. Also, the user must have an email or phone number capable of receiving sms messages on file (based on the method chosen for receiving the security code).

libmonetra KVS equivalent for endpoint

  • action_sys = auth_reset
  • auth_reset = mfa
  • phase = code
Authorizations:
basic_auth
query Parameters
method
required
object
Enum: "EMAIL" "SMS"
Example: method=EMAIL

Values:

  • EMAIL - Send reset code by email
  • SMS - send reset code by sms

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/user/self/reset/mfa/code?reset_method=email' --basic -u 'test_retail:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Self MFA Reset - Step 2: Security Questions

Retrieve security questions for a user for self password reset

libmonetra KVS equivalent for endpoint

  • action_sys = auth_reset
  • auth_reset = mfa
  • phase = security_questions
Authorizations:
basic_auth
Request Body schema: application/json
reset_code
required
string

Self reset authentication code sent to the user via email or sms

Responses

Request samples

Content type
application/json
{
  • "reset_code": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "question1": "string",
  • "question2": "string",
  • "question3": "string"
}

Self MFA Reset - Step 3: Reset

Request the finalization of the self MFA reset operation

libmonetra KVS equivalent for endpoint

  • action_sys = auth_reset
  • auth_reset = mfa
  • phase = reset
Authorizations:
basic_auth
Request Body schema: application/json
reset_code
required
string

Self reset authentication code sent to the user via email or sms

answer1
required
string

Security answer

answer2
required
string

Security answer

answer3
required
string

Security answer

Responses

Request samples

Content type
application/json
{
  • "reset_code": "string",
  • "answer1": "string",
  • "answer2": "string",
  • "answer3": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Self Password Reset - Step 1: Code

User self-reset of password

This is a multi-step process consisting of several steps.

  1. code
  2. security_questions
  3. reset

This relies on a one-time use verification code to initiate the reset attempt which will be emailed or sent via SMS to the user. This code is then entered into a follow-up request to retrieve the user's security questions and an indicator stating if the user has MFA enabled and configured. The final follow-up will pass the same verification code, all 3 security question answers, and possibly the mfa_code if the account has MFA enabled.

The reset operation may be initiated at most 3 times in a 24hr period. The emailed or sms code may only be used once for each step of the reset operation.

Password resets require the username of the user requesting the reset. The user's password is not used for authentication in any of the three steps. For ReST neither API Key or Basic authentication is used. Instead the authentication parameters are passed in the request itself per the requirements of each step.

If the user does not have security questions configured this action will fail silently without error. Also, the user must have an email or phone number capable of receiving sms messages on file (based on the method chosen for receiving the security code).

libmonetra KVS equivalent for endpoint

  • action_sys = auth_reset
  • auth_reset = password
  • phase = code
Authorizations:
None
query Parameters
username
required
string

The username to perform a reset operation on

method
required
object
Enum: "EMAIL" "SMS"
Example: method=EMAIL

Values:

  • EMAIL - Send reset code by email
  • SMS - send reset code by sms

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/user/self/reset/password/code?username=user1&reset_method=email'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Self Password Reset - Step 2: Security Questions

Retrieve security questions for a user for self password reset

libmonetra KVS equivalent for endpoint

  • action_sys = auth_reset
  • auth_reset = password
  • phase = security_questions
Authorizations:
None
Request Body schema: application/json
username
required
string

The username to perform a reset operation on

reset_code
required
string

Self reset authentication code sent to the user via email or sms

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "reset_code": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "question1": "string",
  • "question2": "string",
  • "question3": "string",
  • "mfa_enabled": "yes"
}

Self Password Reset - Step 3: Reset

Request the finalization of the self password reset operation

libmonetra KVS equivalent for endpoint

  • action_sys = auth_reset
  • auth_reset = password
  • phase = reset
Authorizations:
None
Request Body schema: application/json
username
required
string

The username to perform a reset operation on

reset_code
required
string

Self reset authentication code sent to the user via email or sms

answer1
required
string

Security answer

answer2
required
string

Security answer

answer3
required
string

Security answer

pwd
required
string <= 256 characters

Password

mfa_code
required
string

If mfa_enabled was true, then the current mfa code (either from APP, EMAIL or SMS). Cannot be an MFA cookie

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "reset_code": "string",
  • "answer1": "string",
  • "answer2": "string",
  • "answer3": "string",
  • "pwd": "string",
  • "mfa_code": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

API Keys

API keys are used to provide an alternative authentication method for users and Point of Sale (POS) systems. This will allow a user to disassociate their username and password from authentication.

API keys are composed of two parts. A public key id and a private key secret. The key secret must be protected.

API keys can also be created specifically for profiles and are intended for use by POS systems that use external user management. A profile API key has functionality only allowing payment transactions. Other operations are restricted.

Profile API keys allow a POS or other system to not be linked to a user for processing transactions. That way if the user is disabled or removed the system will continue to operate.

Whereas a user API key can be created with any permissions already afforded to the user. It is possible to create user API keys with further lower permissions than the user currently has.

API keys can be configured for limited duration, after which the specific key will no longer function. There is also an EXTEND_ON_USE flag which can extend the life of the key on use.

Some intended uses for API keys:

iFrame

The iFrame currently uses HMAC authentication to verify the request is being generated by a valid user. A profile API key can be generated and used instead of a username and password for authentication.

POS

A POS system with external user management can be configured to use a profile API key to unlink the system from a specific user. The POS will be able to process transactions without having an "unattended" user that needs a password stored somewhere.

Web Interface and Mobile Apps

One way a web interface or mobile app could operate is by having the user login with their username and password, then request an API key representing the user. The integration would not store the username and password. Instead it would store the API key and further operations would be performed using the API key. An expiration combined with the EXTEND_ON_USE flag is recommended for this scenario.

Remove API Key

Deletes an API Key

libmonetra KVS equivalent for endpoint

  • action_sys = apikeys
  • apikeys = del
Authorizations:
basic_authapikey_idapikey
path Parameters
apikey_id
required
string

API key id

Used in conjunction with apikey_secret

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/apikey/U123' --basic -u 'test_retail:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

API Key Detail

Get API Keys Details

libmonetra KVS equivalent for endpoint

  • action_sys = apikeys
  • apikeys = list
Authorizations:
basic_authapikey_idapikey
path Parameters
apikey_id
required
string

API key id

Used in conjunction with apikey_secret

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/apikey/U123' --basic -u 'test_retail:publ1ct3st'

Response samples

Content type
application/json
{
  • "apikey_id": "string",
  • "type": "user",
  • "group_id": "string",
  • "name": "string",
  • "user_id": "string",
  • "profile_id": "string",
  • "flags": "EXTEND_ON_USE",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "REPORT_TRAN",
  • "trans_perms": "VERIFYONLY",
  • "created_uid": "string",
  • "created_ts": "string",
  • "last_used_ts": "string",
  • "expire_ts": "string",
  • "extend_sec": "string",
  • "descr": "string"
}

List API Keys

List API Keys

The resulting report will contain these headers:

apikey_id, type, group_id, name, user_id, profile_id, flags, su_perms, sys_perms,
admin_perms, trans_perms, created_uid, created_ts, last_used_ts, expire_ts,
extend_sec, descr

libmonetra KVS equivalent for endpoint

  • action_sys = apikeys
  • apikeys = list
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

user_id
string

User identifier

group_id
string

Group identifier

name
string

API Key name

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/apikey' --basic -u 'test_retail:publ1ct3st'

Response samples

Content type
application/json
{
  • "report": {
    }
}

Create API Key

Creates an API Key

Up to 100 API keys can be created per user and per profile

libmonetra KVS equivalent for endpoint

  • action_sys = apikeys
  • apikeys = add
Authorizations:
basic_auth
Request Body schema: application/json
type
required
string
Enum: "user" "profile"

Type of API Key

Values:

  • user - Key represents a user. Uses the current user that is authenticated
  • profile - key represents a profile. Uses the profile_id specified, or if none, the defaultprofile id for the current user.
name
required
string <= 256 characters

API Key name

descr
string <= 128 characters

Description of the key and its intended use

flags
string
Enum: "EXTEND_ON_USE" "ALLOW_UNLINKED_REFUNDS"

flags controlling behavior

Values:

  • EXTEND_ON_USE - On use of the key, it's expiration will be extended. Expiration of the key will become now plus the value of expire_sec provided during key creation.
  • ALLOW_UNLINKED_REFUNDS - Allow the API key to perform unlinked refunds. Necessary when generating a Profile API Key if a profile key is intended to issue unlinked refunds. The user creating the key is required to have the ALLOW_UNLINKED_REFUND user flag set in order to enable this API key flag.
su_perms
string
Enum: "ALL" "IMPORTEXPORT" "MAINTENANCE" "P2PE_BDK_GENERATE" "P2PE_BDK_DEACTIVATE" "P2PE_BDK_LIST" "P2PE_BDK_EDIT" "P2PE_BDK_EXPORT" "P2PE_BDK_PRINT" "P2PE_BDK_KCV" "P2PE_DEVICE_PROVISION" "P2PE_DEVICE_DEACTIVATE" "P2PE_DEVICE_LIST" "P2PE_DEVICE_EDIT" "E2EE_KEY_GENERATE" "E2EE_KEY_EDIT" "E2EE_KEY_LIST" "E2EE_KEY_DEACTIVATE" "BIGBATCH_MANAGE" "BIGBATCH" "BIGBATCH_SETTLE" "PRODUCT_LICENSE" "PUSHNOTIFICATION" "TOKEN_EXPORT"

System restricted access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • IMPORTEXPORT - Allow importing and exporting database data
  • MAINTENANCE - Enable maintains mode to prevent transaction processing. Primarily used in conjunction with IMPORTEXPORT permission
  • P2PE_BDK_GENERATE - Generate a Base Derivation Key for P2PE device encryption
  • P2PE_BDK_DEACTIVATE - Deactivate a P2PE Base Derivation Key
  • P2PE_BDK_LIST - List P2PE Base Derivation Key
  • P2PE_BDK_EDIT - Edit a P2PE Base Derivation Key
  • P2PE_BDK_EXPORT - Export a P2PE Base Derivation Key for sharing with a Key Injection Facility
  • P2PE_BDK_PRINT - Print encrypted P2PE Base Derivation Key on a compatible printer. Only applies when keys are managed by an HSM
  • P2PE_BDK_KCV - P2PE Base Derivation Key Check Value
  • P2PE_DEVICE_PROVISION - Provision a device in Monetra that uses P2PE. Provisioning is required for Validated P2PE, non validated P2PW Monetra will auto provision devices on first use
  • P2PE_DEVICE_DEACTIVATE - Deactivate a P2PE Device
  • P2PE_DEVICE_LIST - List P2PE devices
  • P2PE_DEVICE_EDIT - Edit P2PE device
  • E2EE_KEY_GENERATE - Generate E2EE keys used for encrypted transport. Such a transaction export and import between multiple installations of Monetra
  • E2EE_KEY_EDIT - Edit E2EE keys used for encrypted transport.
  • E2EE_KEY_LIST - List E2EE keys used for encrypted transport.
  • E2EE_KEY_DEACTIVATE - Deactivate E2EE keys used for encrypted transport.
  • BIGBATCH_MANAGE - Manage Big Batch accounts
  • BIGBATCH - Big Batch Reporting
  • BIGBATCH_SETTLE - Settle Big Batch batches
  • PRODUCT_LICENSE - Manage products that have been registered with Monetra
  • PUSHNOTIFICATION - Manage push notification endpoints
  • TOKEN_EXPORT - Store account export
sys_perms
string
Enum: "ALL" "V8_COMPLEX_EMULATION" "GETPERMS" "GROUP_ADD" "GROUP_EDIT" "GROUP_MOVE" "GROUP_DEL" "GROUP_LIST" "USER_ADD" "USER_EDIT" "USER_MOVE" "USER_DEL" "USER_LIST" "USER_ENABLE" "USER_DISABLE" "USER_PASSWD" "USER_UNLOCK" "PROFILE_ADD" "PROFILE_EDIT" "PROFILE_MOVE" "PROFILE_DEL" "PROFILE_LIST" "PROFILE_STATS" "PROFILE_ENABLE" "PROFILE_DISABLE" "ROUTE_ADD" "ROUTE_EDIT" "ROUTE_DEL" "ROUTE_LIST" "ROUTE_FIELDS" "CRON" "INFO" "SETLOGGING" "REGISTER_CLIENT" "SKYLINK_MANAGE" "APIKEYS" "MFA_GENERATE" "MFA_RESET" "SECURITY_QUESTIONS"

System access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • V8_COMPLEX_EMULATION - Allow Monetra v8 protocol emulation. Allows equivalent v8 protocol actions to be used
  • GETPERMS - Get user permissions
  • GROUP_ADD - Create a group
  • GROUP_EDIT - Edit a group
  • GROUP_MOVE - Move a group to a different group
  • GROUP_DEL - Delete a group
  • GROUP_LIST - List groups
  • USER_ADD - Create a user
  • USER_EDIT - Edit a user
  • USER_MOVE - Move a user to a different group
  • USER_DEL - Delete a user
  • USER_LIST - List users
  • USER_ENABLE - Enable a user
  • USER_DISABLE - Disable a user
  • USER_PASSWD - Change a user's password. Includes self
  • USER_UNLOCK - Unlock a user
  • PROFILE_ADD - Add a profile
  • PROFILE_EDIT - Edit a profile
  • PROFILE_MOVE - Move a profile to a different group
  • PROFILE_DEL - Delete a profile
  • PROFILE_LIST - List profiles
  • PROFILE_STATS - Profile statics
  • PROFILE_ENABLE - Enable a profile
  • PROFILE_DISABLE - Disable a profile
  • ROUTE_ADD - Add a route
  • ROUTE_EDIT - Edit a route
  • ROUTE_DEL - Delete a route
  • ROUTE_LIST - List routes
  • ROUTE_FIELDS - Get processor specific fields for use with adding or editing a route
  • CRON - System task scheduler operations
  • INFO - Monetra information
  • SETLOGGING - Start / Stop an in memory logging buffer
  • REGISTER_CLIENT - Registers use of a product with Monetra
  • SKYLINK_MANAGE - Manage SkyLink product licences
  • APIKEYS - API key management
  • MFA_GENERATE - Enable or change MFA method
  • MFA_RESET - Reset MFA so it needs to be generated
  • SECURITY_QUESTIONS - User security questions
admin_perms
string
Enum: "REPORT_TRAN" "REPORT_TOTALS" "REPORT_CHARTDATA" "REPORT_QUEUE" "BATCH_CLEAR" "BATCH_SET" "BATCH_RESCIND" "BATCH_CLOSE" "TRAN_EDIT" "TRAN_NULLIFY" "TRAN_DETAIL" "TRAN_RECEIPT" "TRAN_IMPORT" "TRAN_EXPORT" "MERCH_INFO" "IMAGE_ADD" "IMAGE_DEL" "IMAGE_GET" "TOKEN_ADD" "TOKEN_EDIT" "TOKEN_DEL" "TOKEN_SCHEDULE" "TOKEN_LIST" "CUSTOMER_ADD" "CUSTOMER_EDIT" "CUSTOMER_DEL" "CUSTOMER_LIST" "TICKETREQUEST" "LEVEL3" "TRAN_EXPORT" "TRAN_IMPORT" "PRODMANAGE" "PRODLIST" "ORDERMANAGE" "ORDERLIST" "ORDERREPORT" "CARDDENYLIST" "P2PE" "STANDINKEY_GENERATE"

Administrative access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • REPORT_TRAN - Transaction and batch detail reports
  • REPORT_TOTALS - Transaction and batch total reports
  • REPORT_CHARTDATA - Card data breakdown for report views
  • REPORT_QUEUE - List queued transactions pending authorization
  • BATCH_CLEAR - Mark batch as settled without funding
  • BATCH_SET - Change batch number
  • BATCH_RESCIND - Unsettle a batch (can double charge customers)
  • BATCH_CLOSE - Close a batch so new transactions are not added but do not settle
  • TRAN_EDIT - Edit a transaction
  • TRAN_NULLIFY - Delete a previously-authorized transaction without any attempt to go online and remove an authorization hold. Similar to a void.
  • TRAN_DETAIL - Transaction details
  • TRAN_RECEIPT - Transaction receipts. Generating and sending receipts, and invoices
  • TRAN_IMPORT - Import transaction data from a different Monetra into this instance of Monetra
  • TRAN_EXPORT - Emport transaction data from Monetra into a different instance of Monetra
  • MERCH_INFO - Profile information
  • IMAGE_ADD - Store an image. Check, signature, etc
  • IMAGE_DEL - Delete an image. Check, signature, etc
  • IMAGE_GET - Get an image. Check, signature, etc
  • TOKEN_ADD - Store an account
  • TOKEN_EDIT - Edit a stored account
  • TOKEN_DEL - Delete a stored account
  • TOKEN_SCHEDULE - Manage recurring and installment payments
  • TOKEN_LIST - List stored accounts
  • CUSTOMER_ADD - Add a customer
  • CUSTOMER_EDIT - Edit a customer
  • CUSTOMER_DEL - Delete a customer
  • CUSTOMER_LIST - List customers
  • TICKETREQUEST - Request temporary cardshieldticket representing a customer's account
  • LEVEL3 - Level 3 line item operations
  • TRAN_EXPORT - Export transaction data to import into another Monetra
  • TRAN_IMPORT - Import transaction data into Monetra
  • PRODMANAGE - Manage products (sku, amount, etc) in the inventory system
  • PRODLIST - List product details in the inventory system
  • ORDERMANAGE - Manage orders and invoices
  • ORDERLIST - List orders and invoices
  • ORDERREPORT - Reports for orders and invoices
  • CARDDENYLIST - Manage the card deny list
  • P2PE - P2PE device management
  • STANDINKEY_GENERATE - Generate an encryption key used for encrypting account data as part of stand-in authorization
trans_perms
string
Enum: "VERIFYONLY" "SALE" "PREAUTH" "REVERSAL" "INCREMENTAL" "PREAUTHCOMPLETE" "FORCE" "CAPTURE" "VOID" "ADJUST" "REFUND" "ACTIVATE" "BALANCEINQ" "CASHOUT" "TOREVERSAL" "MERCHRETURN" "ISSUE" "TIP" "EBTFSSALE" "EBTFSRETURN" "EBTFSVOUCHER" "EBTFSBALANCE" "EBTCBSALE" "EBTCBCASH" "EBTCBBALANCE" "CHECKVERIFY" "CHECKCONVONLY" "CHECKCONVVRFY" "CHECKCONVGUAR" "CHECKCONVOVER" "CHECKIMAGEUPLOAD" "SETTLE" "SETTLERFR" "TERMLOAD" "INTERACMAC" "EMVCOMPLETE" "ALTPAYMENTINIT" "CARDTYPE"

Transaction access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • VERIFYONLY - Card verification
  • SALE - Purchase
  • PREAUTH - Authorization only (preauth)
  • REVERSAL - Reverse a transaction
  • INCREMENTAL - Incremental
  • PREAUTHCOMPLETE - Complete an authorization only (preauth) transaction
  • FORCE - Force purchase without online authorization
  • CAPTURE - Capture an un-captured transaction
  • VOID - Void a trasnaction
  • ADJUST - Adjust a transaction
  • REFUND - Refund
  • ACTIVATE - Activate a private label gift card
  • BALANCEINQ - Request account balance
  • CASHOUT - Remove all funds from a gift card in order to provide the customer with cash for the value
  • TOREVERSAL - Timeout reversal
  • MERCHRETURN - Merchandise return. Used by gift cards
  • ISSUE - Issue a gift card
  • TIP - Add a tip to a gift card
  • EBTFSSALE - Electronic Benefits Transfer food purchase
  • EBTFSRETURN - Electronic Benefits Transfer food refund
  • EBTFSVOUCHER - Electronic Benefits Transfer food voucher (paper food stamps) purchase
  • EBTFSBALANCE - Electronic Benefits Transfer food balance
  • EBTCBSALE - Electronic Benefits Transfer cash purchase
  • EBTCBCASH - Electronic Benefits Transfer cash withdrawal
  • EBTCBBALANCE - Electronic Benefits Transfer cash balance
  • CHECKVERIFY - Check verification only (without conversion)
  • CHECKCONVONLY - Check conversion only (without verification)
  • CHECKCONVVRFY - Check verification and conversion
  • CHECKCONVGUAR - Check conversation guarantee
  • CHECKCONVOVER - Convert a check with override
  • CHECKIMAGEUPLOAD - Upload check image
  • SETTLE - Settle
  • SETTLERFR - Request Settlement Status (limited processor support)
  • TERMLOAD - Terminal loading data
  • INTERACMAC - Interac MACing parameters
  • EMVCOMPLETE - EMV completion transaction
  • ALTPAYMENTINIT - Init an alternative payment method
  • CARDTYPE - Determine cardtype of presented account
expire_sec
required
string\d+|infinite

How long the API key should be valid.

Can be a numeric whole number of seconds or they key word infinite to indicate the key should never expire. Once a key has expired, it can no longer be used.

Minimum allowed value is 30 indicating the key will only be valid for 30 seconds.

Will be used as the extend time when combined with the extend_on_use flag.

profile_id
string\d+

Profile ID the key should represent instead of the user.

Can only be present when type=profile and is not valid when type=user

Responses

Request samples

Content type
application/json
{
  • "type": "user",
  • "name": "string",
  • "descr": "string",
  • "flags": "EXTEND_ON_USE",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "REPORT_TRAN",
  • "trans_perms": "VERIFYONLY",
  • "expire_sec": "3600",
  • "profile_id": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "apikey_id": "string",
  • "apikey_secret": "string"
}

Boarding Groups

All user, and profiles are contained in a Hierarchical system comprised of Groups. Each group is a level in the hierarchy and groups can be contained within groups. The hierarchical system controls the 'view' that users have access to.

A user at a higher level group can view anything they have permissions for within their and any lower level group.

Profiles, users, and push notifications are all contained within a group.

Groups can have permissions set on the group itself. User's within the group will not be able to perform actions with higher permissions than the group.

Example flow for adding a merchant

  • Create a group for the merchant
  • Create users under the group for the merchant's personnel
  • Create a profile for the merchant's stores
    • Add processing routes to each profile

Users within the group will be able to access and process the profiles within the group they are in. Users can have a default profile set so they do not need to specify a profile with every transaction.

Additionally users can be locked to only allow processing with a specific profile. This allows a clerk to only process transactions for their work location while allowing someone like a floating manager to process at whichever store they happen to be at.

List Groups

List groups

The resulting report will contain these headers:

id, name, parent_group_id, flags, create_ts, upd_ts, su_perms, sys_perms, admin_perms, trans_perms

When using JSON ouput the the groups under the specified group will be placed in a groups array. Each object in the arrary contains the above group headers. If include_users is specified then a users list will be included in the output. The user objects within the array will include the same fields as "Get User Details". If include_profiles is specified then a profiles list will be included in the output. The user objects within the array will include the same fields as "Get Profile Details".

libmonetra KVS equivalent for endpoint

  • action_sys = group_list
Authorizations:
basic_authapikey_idapikey
query Parameters
name
string

Query for specific group name

Cannot be combined with:

  • id
id
string

Group id

Cannot be combined with:

  • name
json
object
Enum: "yes" "no"
Example: json=yes

Output the data in a hierarchical json format instead of CSV

Values:

  • yes - Output in JSON format instead of CSV
  • no - Do not output in JSON format
flags
object
Enum: "MODIFY_SELF" "SHARE_TOKENS" "PUSH_NOTIFICATION" "ACCOUNT_UPDATER" "WHITELABEL_BRANDING" "REQUIRE_MFA"
Example: flags=MODIFY_SELF

Flag values (pipe separated):

  • MODIFY_SELF - Users can modify the group they are part of
  • SHARE_TOKENS - Share tokenized cards across all profiles under this group
  • PUSH_NOTIFICATION - Send push notifications for transactions under this group. Requires pushnotification_id to be set.
  • ACCOUNT_UPDATER - Automatically update stored accounts when the card number changes (requires SHARE_TOKENS). Uses an external card updater service. Not all card issuers participate and submit card account updates to the program
  • WHITELABEL_BRANDING - The group is white label branding the service and branding should reflect this
  • REQUIRE_MFA - Multi Factor Authentication is required for all user accounts
ancestor_of
string

Group ID to list ancestors of (including specified group id)

maxdepth
string

Maximum group depth to display

Default is unlimited. Specify 1 to see only self and children.

include_users
object
Enum: "yes" "no"
Example: include_users=yes

Include users in output. Can only be specified with JSON output.

Values:

  • yes - Include users in output
  • no - Do not include users in output
include_profiles
object
Enum: "yes" "no"
Example: include_profiles=yes

Include profiles in output. Can only be specified with JSON output.

Values:

  • yes - Include profiles in output
  • no - Do not include profiles in output
include_token_stats
object
Enum: "yes" "no"
Example: include_token_stats=yes

Include tokekn statistics in output

Values:

  • yes - Include token statistics in output
  • no - Do not include tokekn statistics in output

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/boarding/group' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "report": {
    }
}

Create a Group

Creates a Group

libmonetra KVS equivalent for endpoint

  • action_sys = group_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
name
required
string

Group name

flags
string
Enum: "MODIFY_SELF" "SHARE_TOKENS" "PUSH_NOTIFICATION" "ACCOUNT_UPDATER" "WHITELABEL_BRANDING" "REQUIRE_MFA"

Flag values (pipe separated):

  • MODIFY_SELF - Users can modify the group they are part of
  • SHARE_TOKENS - Share tokenized cards across all profiles under this group
  • PUSH_NOTIFICATION - Send push notifications for transactions under this group. Requires pushnotification_id to be set.
  • ACCOUNT_UPDATER - Automatically update stored accounts when the card number changes (requires SHARE_TOKENS). Uses an external card updater service. Not all card issuers participate and submit card account updates to the program
  • WHITELABEL_BRANDING - The group is white label branding the service and branding should reflect this
  • REQUIRE_MFA - Multi Factor Authentication is required for all user accounts
parent_group_id
string\d+

ID of parent group

If not specified, defaults to the immediate group the user is part of.

su_perms
string
Enum: "ALL" "IMPORTEXPORT" "MAINTENANCE" "P2PE_BDK_GENERATE" "P2PE_BDK_DEACTIVATE" "P2PE_BDK_LIST" "P2PE_BDK_EDIT" "P2PE_BDK_EXPORT" "P2PE_BDK_PRINT" "P2PE_BDK_KCV" "P2PE_DEVICE_PROVISION" "P2PE_DEVICE_DEACTIVATE" "P2PE_DEVICE_LIST" "P2PE_DEVICE_EDIT" "E2EE_KEY_GENERATE" "E2EE_KEY_EDIT" "E2EE_KEY_LIST" "E2EE_KEY_DEACTIVATE" "BIGBATCH_MANAGE" "BIGBATCH" "BIGBATCH_SETTLE" "PRODUCT_LICENSE" "PUSHNOTIFICATION" "TOKEN_EXPORT"

System restricted access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • IMPORTEXPORT - Allow importing and exporting database data
  • MAINTENANCE - Enable maintains mode to prevent transaction processing. Primarily used in conjunction with IMPORTEXPORT permission
  • P2PE_BDK_GENERATE - Generate a Base Derivation Key for P2PE device encryption
  • P2PE_BDK_DEACTIVATE - Deactivate a P2PE Base Derivation Key
  • P2PE_BDK_LIST - List P2PE Base Derivation Key
  • P2PE_BDK_EDIT - Edit a P2PE Base Derivation Key
  • P2PE_BDK_EXPORT - Export a P2PE Base Derivation Key for sharing with a Key Injection Facility
  • P2PE_BDK_PRINT - Print encrypted P2PE Base Derivation Key on a compatible printer. Only applies when keys are managed by an HSM
  • P2PE_BDK_KCV - P2PE Base Derivation Key Check Value
  • P2PE_DEVICE_PROVISION - Provision a device in Monetra that uses P2PE. Provisioning is required for Validated P2PE, non validated P2PW Monetra will auto provision devices on first use
  • P2PE_DEVICE_DEACTIVATE - Deactivate a P2PE Device
  • P2PE_DEVICE_LIST - List P2PE devices
  • P2PE_DEVICE_EDIT - Edit P2PE device
  • E2EE_KEY_GENERATE - Generate E2EE keys used for encrypted transport. Such a transaction export and import between multiple installations of Monetra
  • E2EE_KEY_EDIT - Edit E2EE keys used for encrypted transport.
  • E2EE_KEY_LIST - List E2EE keys used for encrypted transport.
  • E2EE_KEY_DEACTIVATE - Deactivate E2EE keys used for encrypted transport.
  • BIGBATCH_MANAGE - Manage Big Batch accounts
  • BIGBATCH - Big Batch Reporting
  • BIGBATCH_SETTLE - Settle Big Batch batches
  • PRODUCT_LICENSE - Manage products that have been registered with Monetra
  • PUSHNOTIFICATION - Manage push notification endpoints
  • TOKEN_EXPORT - Store account export
sys_perms
string
Enum: "ALL" "V8_COMPLEX_EMULATION" "GETPERMS" "GROUP_ADD" "GROUP_EDIT" "GROUP_MOVE" "GROUP_DEL" "GROUP_LIST" "USER_ADD" "USER_EDIT" "USER_MOVE" "USER_DEL" "USER_LIST" "USER_ENABLE" "USER_DISABLE" "USER_PASSWD" "USER_UNLOCK" "PROFILE_ADD" "PROFILE_EDIT" "PROFILE_MOVE" "PROFILE_DEL" "PROFILE_LIST" "PROFILE_STATS" "PROFILE_ENABLE" "PROFILE_DISABLE" "ROUTE_ADD" "ROUTE_EDIT" "ROUTE_DEL" "ROUTE_LIST" "ROUTE_FIELDS" "CRON" "INFO" "SETLOGGING" "REGISTER_CLIENT" "SKYLINK_MANAGE" "APIKEYS" "MFA_GENERATE" "MFA_RESET" "SECURITY_QUESTIONS"

System access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • V8_COMPLEX_EMULATION - Allow Monetra v8 protocol emulation. Allows equivalent v8 protocol actions to be used
  • GETPERMS - Get user permissions
  • GROUP_ADD - Create a group
  • GROUP_EDIT - Edit a group
  • GROUP_MOVE - Move a group to a different group
  • GROUP_DEL - Delete a group
  • GROUP_LIST - List groups
  • USER_ADD - Create a user
  • USER_EDIT - Edit a user
  • USER_MOVE - Move a user to a different group
  • USER_DEL - Delete a user
  • USER_LIST - List users
  • USER_ENABLE - Enable a user
  • USER_DISABLE - Disable a user
  • USER_PASSWD - Change a user's password. Includes self
  • USER_UNLOCK - Unlock a user
  • PROFILE_ADD - Add a profile
  • PROFILE_EDIT - Edit a profile
  • PROFILE_MOVE - Move a profile to a different group
  • PROFILE_DEL - Delete a profile
  • PROFILE_LIST - List profiles
  • PROFILE_STATS - Profile statics
  • PROFILE_ENABLE - Enable a profile
  • PROFILE_DISABLE - Disable a profile
  • ROUTE_ADD - Add a route
  • ROUTE_EDIT - Edit a route
  • ROUTE_DEL - Delete a route
  • ROUTE_LIST - List routes
  • ROUTE_FIELDS - Get processor specific fields for use with adding or editing a route
  • CRON - System task scheduler operations
  • INFO - Monetra information
  • SETLOGGING - Start / Stop an in memory logging buffer
  • REGISTER_CLIENT - Registers use of a product with Monetra
  • SKYLINK_MANAGE - Manage SkyLink product licences
  • APIKEYS - API key management
  • MFA_GENERATE - Enable or change MFA method
  • MFA_RESET - Reset MFA so it needs to be generated
  • SECURITY_QUESTIONS - User security questions
admin_perms
string
Enum: "REPORT_TRAN" "REPORT_TOTALS" "REPORT_CHARTDATA" "REPORT_QUEUE" "BATCH_CLEAR" "BATCH_SET" "BATCH_RESCIND" "BATCH_CLOSE" "TRAN_EDIT" "TRAN_NULLIFY" "TRAN_DETAIL" "TRAN_RECEIPT" "TRAN_IMPORT" "TRAN_EXPORT" "MERCH_INFO" "IMAGE_ADD" "IMAGE_DEL" "IMAGE_GET" "TOKEN_ADD" "TOKEN_EDIT" "TOKEN_DEL" "TOKEN_SCHEDULE" "TOKEN_LIST" "CUSTOMER_ADD" "CUSTOMER_EDIT" "CUSTOMER_DEL" "CUSTOMER_LIST" "TICKETREQUEST" "LEVEL3" "TRAN_EXPORT" "TRAN_IMPORT" "PRODMANAGE" "PRODLIST" "ORDERMANAGE" "ORDERLIST" "ORDERREPORT" "CARDDENYLIST" "P2PE" "STANDINKEY_GENERATE"

Administrative access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • REPORT_TRAN - Transaction and batch detail reports
  • REPORT_TOTALS - Transaction and batch total reports
  • REPORT_CHARTDATA - Card data breakdown for report views
  • REPORT_QUEUE - List queued transactions pending authorization
  • BATCH_CLEAR - Mark batch as settled without funding
  • BATCH_SET - Change batch number
  • BATCH_RESCIND - Unsettle a batch (can double charge customers)
  • BATCH_CLOSE - Close a batch so new transactions are not added but do not settle
  • TRAN_EDIT - Edit a transaction
  • TRAN_NULLIFY - Delete a previously-authorized transaction without any attempt to go online and remove an authorization hold. Similar to a void.
  • TRAN_DETAIL - Transaction details
  • TRAN_RECEIPT - Transaction receipts. Generating and sending receipts, and invoices
  • TRAN_IMPORT - Import transaction data from a different Monetra into this instance of Monetra
  • TRAN_EXPORT - Emport transaction data from Monetra into a different instance of Monetra
  • MERCH_INFO - Profile information
  • IMAGE_ADD - Store an image. Check, signature, etc
  • IMAGE_DEL - Delete an image. Check, signature, etc
  • IMAGE_GET - Get an image. Check, signature, etc
  • TOKEN_ADD - Store an account
  • TOKEN_EDIT - Edit a stored account
  • TOKEN_DEL - Delete a stored account
  • TOKEN_SCHEDULE - Manage recurring and installment payments
  • TOKEN_LIST - List stored accounts
  • CUSTOMER_ADD - Add a customer
  • CUSTOMER_EDIT - Edit a customer
  • CUSTOMER_DEL - Delete a customer
  • CUSTOMER_LIST - List customers
  • TICKETREQUEST - Request temporary cardshieldticket representing a customer's account
  • LEVEL3 - Level 3 line item operations
  • TRAN_EXPORT - Export transaction data to import into another Monetra
  • TRAN_IMPORT - Import transaction data into Monetra
  • PRODMANAGE - Manage products (sku, amount, etc) in the inventory system
  • PRODLIST - List product details in the inventory system
  • ORDERMANAGE - Manage orders and invoices
  • ORDERLIST - List orders and invoices
  • ORDERREPORT - Reports for orders and invoices
  • CARDDENYLIST - Manage the card deny list
  • P2PE - P2PE device management
  • STANDINKEY_GENERATE - Generate an encryption key used for encrypting account data as part of stand-in authorization
trans_perms
string
Enum: "VERIFYONLY" "SALE" "PREAUTH" "REVERSAL" "INCREMENTAL" "PREAUTHCOMPLETE" "FORCE" "CAPTURE" "VOID" "ADJUST" "REFUND" "ACTIVATE" "BALANCEINQ" "CASHOUT" "TOREVERSAL" "MERCHRETURN" "ISSUE" "TIP" "EBTFSSALE" "EBTFSRETURN" "EBTFSVOUCHER" "EBTFSBALANCE" "EBTCBSALE" "EBTCBCASH" "EBTCBBALANCE" "CHECKVERIFY" "CHECKCONVONLY" "CHECKCONVVRFY" "CHECKCONVGUAR" "CHECKCONVOVER" "CHECKIMAGEUPLOAD" "SETTLE" "SETTLERFR" "TERMLOAD" "INTERACMAC" "EMVCOMPLETE" "ALTPAYMENTINIT" "CARDTYPE"

Transaction access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • VERIFYONLY - Card verification
  • SALE - Purchase
  • PREAUTH - Authorization only (preauth)
  • REVERSAL - Reverse a transaction
  • INCREMENTAL - Incremental
  • PREAUTHCOMPLETE - Complete an authorization only (preauth) transaction
  • FORCE - Force purchase without online authorization
  • CAPTURE - Capture an un-captured transaction
  • VOID - Void a trasnaction
  • ADJUST - Adjust a transaction
  • REFUND - Refund
  • ACTIVATE - Activate a private label gift card
  • BALANCEINQ - Request account balance
  • CASHOUT - Remove all funds from a gift card in order to provide the customer with cash for the value
  • TOREVERSAL - Timeout reversal
  • MERCHRETURN - Merchandise return. Used by gift cards
  • ISSUE - Issue a gift card
  • TIP - Add a tip to a gift card
  • EBTFSSALE - Electronic Benefits Transfer food purchase
  • EBTFSRETURN - Electronic Benefits Transfer food refund
  • EBTFSVOUCHER - Electronic Benefits Transfer food voucher (paper food stamps) purchase
  • EBTFSBALANCE - Electronic Benefits Transfer food balance
  • EBTCBSALE - Electronic Benefits Transfer cash purchase
  • EBTCBCASH - Electronic Benefits Transfer cash withdrawal
  • EBTCBBALANCE - Electronic Benefits Transfer cash balance
  • CHECKVERIFY - Check verification only (without conversion)
  • CHECKCONVONLY - Check conversion only (without verification)
  • CHECKCONVVRFY - Check verification and conversion
  • CHECKCONVGUAR - Check conversation guarantee
  • CHECKCONVOVER - Convert a check with override
  • CHECKIMAGEUPLOAD - Upload check image
  • SETTLE - Settle
  • SETTLERFR - Request Settlement Status (limited processor support)
  • TERMLOAD - Terminal loading data
  • INTERACMAC - Interac MACing parameters
  • EMVCOMPLETE - EMV completion transaction
  • ALTPAYMENTINIT - Init an alternative payment method
  • CARDTYPE - Determine cardtype of presented account
pushnotification_id
string\d+

Push notification id

group_custom_customer_fields
string
object (_boarding_group_group_contact)

Group contact information

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "flags": "MODIFY_SELF",
  • "parent_group_id": "string",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "REPORT_TRAN",
  • "trans_perms": "VERIFYONLY",
  • "pushnotification_id": "string",
  • "group_custom_customer_fields": "string",
  • "group_contact": {
    }
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Remove a Group

Delete a Group

libmonetra KVS equivalent for endpoint

  • action_sys = group_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Group id

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/boarding/group/123' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Group Detail

Get Group Detail

libmonetra KVS equivalent for endpoint

  • action_sys = group_list
  • json = no
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Group id

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/boarding/group/123' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "parent_group_id": "string",
  • "flags": "MODIFY_SELF",
  • "create_ts": "string",
  • "upd_ts": "string",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "REPORT_TRAN",
  • "trans_perms": "VERIFYONLY"
}

Edit a Group

Edit a Group

libmonetra KVS equivalent for endpoint

  • action_sys = group_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Group id

Request Body schema: application/json
addperm_propagate
string
Default: "no"
Enum: "yes" "no"

Propagate permission changes

If any of sys, admin, or trans permissions is being added to a group, whether it should be recursively propagated to all child groups and users.

Defaults to no if not provided.

Values:

  • yes - Propagate permissions
  • no - Do not propagate permissions
addperm_su_perms_mask
string

System restricted permissions that should not be propagated

A mask of system restricted permissions on a group or user required to propagate a new permission. Will not apply if the user or group doesn't meet the criteria.

Used in conjunction with addperm_propagate=yes.

addperm_sys_perms_mask
string

System permissions that should not be propagated

A mask of system permissions on a group or user required to propagate a new permission. Will not apply if the user or group doesn't meet the criteria.

Used in conjunction with addperm_propagate=yes.

addperm_admin_perms_mask
string

Administrative permissions that should not be propagated

A mask of administrative permissions on a group or user required to propagate a new permission. Will not apply if the user or group doesn't meet the criteria.

Used in conjunction with addperm_propagate=yes.

addperm_trans_perms_mask
string

Transaction permissions that should not be propagated

A mask of transaction permissions on a group or user required to propagate a new permission. Will not apply if the user or group doesn't meet the criteria.

Used in conjunction with addperm_propagate=yes.

name
string

Group name

flags
string
Enum: "MODIFY_SELF" "SHARE_TOKENS" "PUSH_NOTIFICATION" "ACCOUNT_UPDATER" "WHITELABEL_BRANDING" "REQUIRE_MFA"

Flag values (pipe separated):

  • MODIFY_SELF - Users can modify the group they are part of
  • SHARE_TOKENS - Share tokenized cards across all profiles under this group
  • PUSH_NOTIFICATION - Send push notifications for transactions under this group. Requires pushnotification_id to be set.
  • ACCOUNT_UPDATER - Automatically update stored accounts when the card number changes (requires SHARE_TOKENS). Uses an external card updater service. Not all card issuers participate and submit card account updates to the program
  • WHITELABEL_BRANDING - The group is white label branding the service and branding should reflect this
  • REQUIRE_MFA - Multi Factor Authentication is required for all user accounts
su_perms
string
Enum: "ALL" "IMPORTEXPORT" "MAINTENANCE" "P2PE_BDK_GENERATE" "P2PE_BDK_DEACTIVATE" "P2PE_BDK_LIST" "P2PE_BDK_EDIT" "P2PE_BDK_EXPORT" "P2PE_BDK_PRINT" "P2PE_BDK_KCV" "P2PE_DEVICE_PROVISION" "P2PE_DEVICE_DEACTIVATE" "P2PE_DEVICE_LIST" "P2PE_DEVICE_EDIT" "E2EE_KEY_GENERATE" "E2EE_KEY_EDIT" "E2EE_KEY_LIST" "E2EE_KEY_DEACTIVATE" "BIGBATCH_MANAGE" "BIGBATCH" "BIGBATCH_SETTLE" "PRODUCT_LICENSE" "PUSHNOTIFICATION" "TOKEN_EXPORT"

System restricted access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • IMPORTEXPORT - Allow importing and exporting database data
  • MAINTENANCE - Enable maintains mode to prevent transaction processing. Primarily used in conjunction with IMPORTEXPORT permission
  • P2PE_BDK_GENERATE - Generate a Base Derivation Key for P2PE device encryption
  • P2PE_BDK_DEACTIVATE - Deactivate a P2PE Base Derivation Key
  • P2PE_BDK_LIST - List P2PE Base Derivation Key
  • P2PE_BDK_EDIT - Edit a P2PE Base Derivation Key
  • P2PE_BDK_EXPORT - Export a P2PE Base Derivation Key for sharing with a Key Injection Facility
  • P2PE_BDK_PRINT - Print encrypted P2PE Base Derivation Key on a compatible printer. Only applies when keys are managed by an HSM
  • P2PE_BDK_KCV - P2PE Base Derivation Key Check Value
  • P2PE_DEVICE_PROVISION - Provision a device in Monetra that uses P2PE. Provisioning is required for Validated P2PE, non validated P2PW Monetra will auto provision devices on first use
  • P2PE_DEVICE_DEACTIVATE - Deactivate a P2PE Device
  • P2PE_DEVICE_LIST - List P2PE devices
  • P2PE_DEVICE_EDIT - Edit P2PE device
  • E2EE_KEY_GENERATE - Generate E2EE keys used for encrypted transport. Such a transaction export and import between multiple installations of Monetra
  • E2EE_KEY_EDIT - Edit E2EE keys used for encrypted transport.
  • E2EE_KEY_LIST - List E2EE keys used for encrypted transport.
  • E2EE_KEY_DEACTIVATE - Deactivate E2EE keys used for encrypted transport.
  • BIGBATCH_MANAGE - Manage Big Batch accounts
  • BIGBATCH - Big Batch Reporting
  • BIGBATCH_SETTLE - Settle Big Batch batches
  • PRODUCT_LICENSE - Manage products that have been registered with Monetra
  • PUSHNOTIFICATION - Manage push notification endpoints
  • TOKEN_EXPORT - Store account export
sys_perms
string
Enum: "ALL" "V8_COMPLEX_EMULATION" "GETPERMS" "GROUP_ADD" "GROUP_EDIT" "GROUP_MOVE" "GROUP_DEL" "GROUP_LIST" "USER_ADD" "USER_EDIT" "USER_MOVE" "USER_DEL" "USER_LIST" "USER_ENABLE" "USER_DISABLE" "USER_PASSWD" "USER_UNLOCK" "PROFILE_ADD" "PROFILE_EDIT" "PROFILE_MOVE" "PROFILE_DEL" "PROFILE_LIST" "PROFILE_STATS" "PROFILE_ENABLE" "PROFILE_DISABLE" "ROUTE_ADD" "ROUTE_EDIT" "ROUTE_DEL" "ROUTE_LIST" "ROUTE_FIELDS" "CRON" "INFO" "SETLOGGING" "REGISTER_CLIENT" "SKYLINK_MANAGE" "APIKEYS" "MFA_GENERATE" "MFA_RESET" "SECURITY_QUESTIONS"

System access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • V8_COMPLEX_EMULATION - Allow Monetra v8 protocol emulation. Allows equivalent v8 protocol actions to be used
  • GETPERMS - Get user permissions
  • GROUP_ADD - Create a group
  • GROUP_EDIT - Edit a group
  • GROUP_MOVE - Move a group to a different group
  • GROUP_DEL - Delete a group
  • GROUP_LIST - List groups
  • USER_ADD - Create a user
  • USER_EDIT - Edit a user
  • USER_MOVE - Move a user to a different group
  • USER_DEL - Delete a user
  • USER_LIST - List users
  • USER_ENABLE - Enable a user
  • USER_DISABLE - Disable a user
  • USER_PASSWD - Change a user's password. Includes self
  • USER_UNLOCK - Unlock a user
  • PROFILE_ADD - Add a profile
  • PROFILE_EDIT - Edit a profile
  • PROFILE_MOVE - Move a profile to a different group
  • PROFILE_DEL - Delete a profile
  • PROFILE_LIST - List profiles
  • PROFILE_STATS - Profile statics
  • PROFILE_ENABLE - Enable a profile
  • PROFILE_DISABLE - Disable a profile
  • ROUTE_ADD - Add a route
  • ROUTE_EDIT - Edit a route
  • ROUTE_DEL - Delete a route
  • ROUTE_LIST - List routes
  • ROUTE_FIELDS - Get processor specific fields for use with adding or editing a route
  • CRON - System task scheduler operations
  • INFO - Monetra information
  • SETLOGGING - Start / Stop an in memory logging buffer
  • REGISTER_CLIENT - Registers use of a product with Monetra
  • SKYLINK_MANAGE - Manage SkyLink product licences
  • APIKEYS - API key management
  • MFA_GENERATE - Enable or change MFA method
  • MFA_RESET - Reset MFA so it needs to be generated
  • SECURITY_QUESTIONS - User security questions
admin_perms
string
Enum: "REPORT_TRAN" "REPORT_TOTALS" "REPORT_CHARTDATA" "REPORT_QUEUE" "BATCH_CLEAR" "BATCH_SET" "BATCH_RESCIND" "BATCH_CLOSE" "TRAN_EDIT" "TRAN_NULLIFY" "TRAN_DETAIL" "TRAN_RECEIPT" "TRAN_IMPORT" "TRAN_EXPORT" "MERCH_INFO" "IMAGE_ADD" "IMAGE_DEL" "IMAGE_GET" "TOKEN_ADD" "TOKEN_EDIT" "TOKEN_DEL" "TOKEN_SCHEDULE" "TOKEN_LIST" "CUSTOMER_ADD" "CUSTOMER_EDIT" "CUSTOMER_DEL" "CUSTOMER_LIST" "TICKETREQUEST" "LEVEL3" "TRAN_EXPORT" "TRAN_IMPORT" "PRODMANAGE" "PRODLIST" "ORDERMANAGE" "ORDERLIST" "ORDERREPORT" "CARDDENYLIST" "P2PE" "STANDINKEY_GENERATE"

Administrative access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • REPORT_TRAN - Transaction and batch detail reports
  • REPORT_TOTALS - Transaction and batch total reports
  • REPORT_CHARTDATA - Card data breakdown for report views
  • REPORT_QUEUE - List queued transactions pending authorization
  • BATCH_CLEAR - Mark batch as settled without funding
  • BATCH_SET - Change batch number
  • BATCH_RESCIND - Unsettle a batch (can double charge customers)
  • BATCH_CLOSE - Close a batch so new transactions are not added but do not settle
  • TRAN_EDIT - Edit a transaction
  • TRAN_NULLIFY - Delete a previously-authorized transaction without any attempt to go online and remove an authorization hold. Similar to a void.
  • TRAN_DETAIL - Transaction details
  • TRAN_RECEIPT - Transaction receipts. Generating and sending receipts, and invoices
  • TRAN_IMPORT - Import transaction data from a different Monetra into this instance of Monetra
  • TRAN_EXPORT - Emport transaction data from Monetra into a different instance of Monetra
  • MERCH_INFO - Profile information
  • IMAGE_ADD - Store an image. Check, signature, etc
  • IMAGE_DEL - Delete an image. Check, signature, etc
  • IMAGE_GET - Get an image. Check, signature, etc
  • TOKEN_ADD - Store an account
  • TOKEN_EDIT - Edit a stored account
  • TOKEN_DEL - Delete a stored account
  • TOKEN_SCHEDULE - Manage recurring and installment payments
  • TOKEN_LIST - List stored accounts
  • CUSTOMER_ADD - Add a customer
  • CUSTOMER_EDIT - Edit a customer
  • CUSTOMER_DEL - Delete a customer
  • CUSTOMER_LIST - List customers
  • TICKETREQUEST - Request temporary cardshieldticket representing a customer's account
  • LEVEL3 - Level 3 line item operations
  • TRAN_EXPORT - Export transaction data to import into another Monetra
  • TRAN_IMPORT - Import transaction data into Monetra
  • PRODMANAGE - Manage products (sku, amount, etc) in the inventory system
  • PRODLIST - List product details in the inventory system
  • ORDERMANAGE - Manage orders and invoices
  • ORDERLIST - List orders and invoices
  • ORDERREPORT - Reports for orders and invoices
  • CARDDENYLIST - Manage the card deny list
  • P2PE - P2PE device management
  • STANDINKEY_GENERATE - Generate an encryption key used for encrypting account data as part of stand-in authorization
trans_perms
string
Enum: "VERIFYONLY" "SALE" "PREAUTH" "REVERSAL" "INCREMENTAL" "PREAUTHCOMPLETE" "FORCE" "CAPTURE" "VOID" "ADJUST" "REFUND" "ACTIVATE" "BALANCEINQ" "CASHOUT" "TOREVERSAL" "MERCHRETURN" "ISSUE" "TIP" "EBTFSSALE" "EBTFSRETURN" "EBTFSVOUCHER" "EBTFSBALANCE" "EBTCBSALE" "EBTCBCASH" "EBTCBBALANCE" "CHECKVERIFY" "CHECKCONVONLY" "CHECKCONVVRFY" "CHECKCONVGUAR" "CHECKCONVOVER" "CHECKIMAGEUPLOAD" "SETTLE" "SETTLERFR" "TERMLOAD" "INTERACMAC" "EMVCOMPLETE" "ALTPAYMENTINIT" "CARDTYPE"

Transaction access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • VERIFYONLY - Card verification
  • SALE - Purchase
  • PREAUTH - Authorization only (preauth)
  • REVERSAL - Reverse a transaction
  • INCREMENTAL - Incremental
  • PREAUTHCOMPLETE - Complete an authorization only (preauth) transaction
  • FORCE - Force purchase without online authorization
  • CAPTURE - Capture an un-captured transaction
  • VOID - Void a trasnaction
  • ADJUST - Adjust a transaction
  • REFUND - Refund
  • ACTIVATE - Activate a private label gift card
  • BALANCEINQ - Request account balance
  • CASHOUT - Remove all funds from a gift card in order to provide the customer with cash for the value
  • TOREVERSAL - Timeout reversal
  • MERCHRETURN - Merchandise return. Used by gift cards
  • ISSUE - Issue a gift card
  • TIP - Add a tip to a gift card
  • EBTFSSALE - Electronic Benefits Transfer food purchase
  • EBTFSRETURN - Electronic Benefits Transfer food refund
  • EBTFSVOUCHER - Electronic Benefits Transfer food voucher (paper food stamps) purchase
  • EBTFSBALANCE - Electronic Benefits Transfer food balance
  • EBTCBSALE - Electronic Benefits Transfer cash purchase
  • EBTCBCASH - Electronic Benefits Transfer cash withdrawal
  • EBTCBBALANCE - Electronic Benefits Transfer cash balance
  • CHECKVERIFY - Check verification only (without conversion)
  • CHECKCONVONLY - Check conversion only (without verification)
  • CHECKCONVVRFY - Check verification and conversion
  • CHECKCONVGUAR - Check conversation guarantee
  • CHECKCONVOVER - Convert a check with override
  • CHECKIMAGEUPLOAD - Upload check image
  • SETTLE - Settle
  • SETTLERFR - Request Settlement Status (limited processor support)
  • TERMLOAD - Terminal loading data
  • INTERACMAC - Interac MACing parameters
  • EMVCOMPLETE - EMV completion transaction
  • ALTPAYMENTINIT - Init an alternative payment method
  • CARDTYPE - Determine cardtype of presented account
pushnotification_id
string\d+

Push notification id

group_custom_customer_fields
string
object (_boarding_group_group_contact)

Group contact information

Responses

Request samples

Content type
application/json
{
  • "addperm_propagate": "yes",
  • "addperm_su_perms_mask": "string",
  • "addperm_sys_perms_mask": "string",
  • "addperm_admin_perms_mask": "string",
  • "addperm_trans_perms_mask": "string",
  • "name": "string",
  • "flags": "MODIFY_SELF",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "REPORT_TRAN",
  • "trans_perms": "VERIFYONLY",
  • "pushnotification_id": "string",
  • "group_custom_customer_fields": "string",
  • "group_contact": {
    }
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Move a Group

Move a Group from one parent to another

libmonetra KVS equivalent for endpoint

  • action_sys = group_move
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Group id

parent_group_id
required
string

New parent group the specified group should be under

Responses

Request samples 

curl -X PATCH 'https://testbox.monetra.com/api/v2/boarding/group/123/move/456' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=' -d ''

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Push Notifications

Push notifications of transaction processing allows merchants to receive notification about tranactions in near real time. Push notifications can be configured to send information based on various criteria.

Push notification are HTTPS-POST requests to an integrator defined endpoint using JSON data as the transfer format. Push events are run on a timer to limit load on the system, transactions are sent every 30-or-so seconds per endpoint, therefore notification format is an array of transactions.

The endpoint must return a 200 HTTP response code in order to accept the data received. Any other response, or the inability to connect, will result in the notification being re-attempted at a later time.

End points optionally support authentication that can be configured with the endpoint. The authentication data will be sent by Monetra to the integrator's endpoint in order for the integrator to verify the data is being sent by Monetra.

Format

The output format is a JSON array of transactions, aggregated per endpoint every 30 seconds, only if there is data to send.

{
    "transactions" : [
        {
            "user": "123456789:pos",
            "ttid": "912314155123456",
            "action": "sale",
            "ts": "1567172149",
            "txnstatus": "CAPTURED|ONLINE|SENSITIVEDATA",
            "tranflags": "HASAVS|DATAKEYED|NSF|PARTIALAUTH",
            "entrymode": "M",
            "merchant": {
                "indcode": "R",
                "proc": "VITAL"
            },
            "request": {
                "amount": "12.00",
                "account": "1881",
                "expdate": "0520",
                "zip": "32606",
                "ordernum": "1234",
                "cardholdername": "John Doe",
                "laneid": "1",
                "tax": "1.00",
                "merch_custom_fields": {
                    "myfield": "field data",
                    "anotherfield": "more data",
                    "...": "..."
                },
                "...": "..."
            },
            "response": {
                "code": "AUTH",
                "phard_code": "SUCCESS",
                "msoft_code": "INT_SUCCESS",
                "authamount": "11.00",
                "verbiage": "PARTIAL APPROVAL",
                "auth": "123456",
                "avs": "GOOD",
                "cv": "GOOD",
                "cardtype": "VISA",
                "item": "1234",
                "batch": "123",
                "pclevel": "2",
                "cardlevel": "VISA_BUSINESS",
                "...": "..."
            },
            "interchange": {
                "transid": "123456789012345",
                "...": "..."
            },
        },
        { ... }
    ]
}

Additional key value pairs may be present. Due to addintion data bein gadded to Monetra, by configuration of the endpoint, or through custom transaction fields. Integrators should read the data they are interested in and ignore anything remaining.

List Push Notification Endpoints

List push notification endpoints

The resulting report will contain these headers:

id, display_name, url, eventflags, authtype

libmonetra KVS equivalent for endpoint

  • action_su = pushnotification
  • pushnotification = list
Authorizations:
basic_authapikey_idapikey

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/boarding/pushnotification' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "report": {
    }
}

Create a Push Notification Endpoint

Creates a push notification endpoint

libmonetra KVS equivalent for endpoint

  • action_su = pushnotification
  • pushnotification = add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
display_name
required
string <= 2048 characters

Push notification endpoint name

url
required
string <= 2048 characters

URL where the notification data should be sent

authtype
string
Default: "NONE"
Enum: "NONE" "BASIC"

Type of authentication Monetra will use to authenticate with the endpoint

Values:

  • NONE - No authentication data is sent with the notification
  • BASIC - HTTP Basic Authentication is send with the notification
eventflags
string
Enum: "AUTH" "VERIFY" "SETTLE" "EDIT" "VOID" "DECLINED" "CREDIT" "DEBIT" "GIFT" "ACH" "EBT" "INTERCHANGE"

Type of events and cards that should trigger notification

Flag values (pipe separated):

  • AUTH - Receive authorization events
  • VERIFY - Receive verification events
  • SETTLE - Receive settlement events
  • EDIT - Receive transaction modification events
  • VOID - Receive reversal and void events
  • DECLINED - Receive declined events
  • CREDIT - Receive events for credit card type
  • DEBIT - Receive events for debit card type
  • GIFT - Receive events for gift card type
  • ACH - Receive events for ACH card type
  • EBT - Receive events for EBT card type
  • INTERCHANGE - Receive raw interchange data
authname
string

Name of the authenication data

authdata
string[a-zA-Z0-9+/\n]+={0,2}[\n]*

Authentication data

Data used by the authtype to send to the end point.

Data must be base64 encoded.

When BASIC authentication is used, the value before base 64 encoding must be formatted as username:password the server this end point will communicate with expects to receive.

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "url": "string",
  • "authtype": "NONE",
  • "eventflags": "AUTH",
  • "authname": "string",
  • "authdata": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Remove a Push Notification Endpoint

Removes a push notification endpoint

libmonetra KVS equivalent for endpoint

  • action_su = pushnotification
  • pushnotification = del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Push notification id

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/boarding/pushnotification/567898765' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Push Notification Endpoint Details

Push notification endpoint details

libmonetra KVS equivalent for endpoint

  • action_su = pushnotification
  • pushnotification = list
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Push notification id

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/boarding/pushnotification/567898765' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "id": "string",
  • "display_name": "string",
  • "url": "string",
  • "eventflags": "AUTH",
  • "authtype": "NONE"
}

Edit a Push Notification Endpoint

Edits a push notification endpoint

libmonetra KVS equivalent for endpoint

  • action_su = pushnotification
  • pushnotification = edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Push notification id

Request Body schema: application/json
display_name
string <= 128 characters

Push notification endpoint name

url
string

URL where the notification data should be sent

authtype
string
Default: "NONE"
Enum: "NONE" "BASIC"

Type of authentication Monetra will use to authenticate with the endpoint

Values:

  • NONE - No authentication data is sent with the notification
  • BASIC - HTTP Basic Authentication is send with the notification
eventflags
string
Enum: "AUTH" "VERIFY" "SETTLE" "EDIT" "VOID" "DECLINED" "CREDIT" "DEBIT" "GIFT" "ACH" "EBT" "INTERCHANGE"

Type of events and cards that should trigger notification

Flag values (pipe separated):

  • AUTH - Receive authorization events
  • VERIFY - Receive verification events
  • SETTLE - Receive settlement events
  • EDIT - Receive transaction modification events
  • VOID - Receive reversal and void events
  • DECLINED - Receive declined events
  • CREDIT - Receive events for credit card type
  • DEBIT - Receive events for debit card type
  • GIFT - Receive events for gift card type
  • ACH - Receive events for ACH card type
  • EBT - Receive events for EBT card type
  • INTERCHANGE - Receive raw interchange data
authname
string

Name of the authenication data

authdata
string[a-zA-Z0-9+/\n]+={0,2}[\n]*

Authentication data

Data used by the authtype to send to the end point.

Data must be base64 encoded.

When BASIC authentication is used, the value before base 64 encoding must be formatted as username:password the server this end point will communicate with expects to receive.

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "url": "string",
  • "authtype": "NONE",
  • "eventflags": "AUTH",
  • "authname": "string",
  • "authdata": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Profile list for a Push Notification Endpoint

Get profiles for push notification endpoint

Provides a list of all profiles attached to a specific push notification endpoint.

The resulting report will contain these headers:

profile_id, display_name, endpoint_id, endpoint_url

libmonetra KVS equivalent for endpoint

  • action_su = pushnotification
  • pushnotification = listprofiles
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Push notification id

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/boarding/pushnotification/567898765/profiles' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "report": {
    }
}

List Profiles for Push Notification Endpoints

List profiles for push notification endpoints

Provides a list of all profiles that are attached to any push notification endpoint.

The resulting report will contain these headers:

profile_id, display_name, endpoint_id, endpoint_url

libmonetra KVS equivalent for endpoint

  • action_su = pushnotification
  • pushnotification = listprofiles
Authorizations:
basic_authapikey_idapikey

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/boarding/pushnotification/profiles' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "report": {
    }
}

Profiles

Profiles define a "merchant", the terminal configuration, and processing options. The "merchant" is often defined as a store. Since there are store specific information, such as address, that can be defined for operations like receipt printing.

A profile will contain routes which define transaction routing for authorization and settlement. For example, a profile may have different routes (processors) for credit, gift and ACH.

List Profiles

List profiles

The resulting report will contain these headers:

id, profile_name, group_id, group_depth, flags, status, indcode, create_ts,
upd_ts, notify_email, custom_trans_fields, req_trans_fields, vanity_url_prefix,
tokengroup_id, pushnotification_id, whitelabelgroup_id, fraudautodeny,
emv_termcaps, emv_testmode, emv_contact_nocvm_limit, emv_ctls_nocvm_limit,
countrycode, currencycode, name, descr, addr1, addr2, addr3, phone, email, url,
tz, lang, cashback, cashbackmax, cashback_purchmin, tippercent,
msr_nosig_limit, enc_provider, l3_commoditycode, l3_description, l3_productcode

libmonetra KVS equivalent for endpoint

  • action_sys = profile_list
Authorizations:
basic_authapikey_idapikey
query Parameters
group_id
string

Group identifier

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/boarding/profile' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "report": {
    }
}

Create a Profile

Creates a Profile

libmonetra KVS equivalent for endpoint

  • action_sys = profile_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
group_id
string\d+

Group ID

If not specified, defaults to the same group as the current user.

profile_name
string <= 128 characters

Name for profile

Internal name within the system

Not required to be unique

name
required
string <= 128 characters

Name for profile

Not required to be unique

Used for displaying to customers

Not required to be unique

Will be copied into profile_name if provided and profile_name is empty

notify_email
string <= 2048 characters

List of email addresses for notifications (e.g. settlement emails)

flags
string
Enum: "ENCRYPTEDONLY" "EMVSUPRESSSIG" "EMVPIN_STANDIN_ALLOWED" "EMVODA_NONE_STANDIN_ALLOWED" "DEBIT_STANDIN_ALLOWED" "PREPOP_LEVEL3" "PREPOP_TAX" "ACCOUNT_UPDATER" "RECEIVE_RECEIPTS_DETAIL" "RECEIVE_RECEIPTS_RECURRING" "RECEIVE_RECEIPTS_INVOICE" "RECURRING_SKIPMISSED" "ORDERS_REQ_LEVEL3" "RATEQUAL_NONTAX" "ALLOW_INVOICE_SMS" "ALLOW_INVOICING" "DISABLE_MSR_ENTRY" "CARDDENYLIST_CHECK" "CARDDENYLIST_DECLINE"

Merchant flags

Flags can be combined into a pipe ('|') separate list.

Flag values (pipe separated):

  • ENCRYPTEDONLY - Account data will only be accepted if it is encrypted. Clear account data will be rejected
  • EMVSUPRESSSIG - Inform a payment device never prompt for signature for EMV transactions
  • EMVPIN_STANDIN_ALLOWED - Allow stand-in authorizations for EMV when online PIN is entered
  • EMVODA_NONE_STANDIN_ALLOWED - Allow stand-in authorizations for EMV when ODA not performed
  • DEBIT_STANDIN_ALLOWED - Allow stand-in authorizations for debit cards
  • PREPOP_LEVEL3 - Automatically populate Level 3 transaction data (if configured) at settlement for transactions that are Level 3 capable but do not have Level 3 line items
  • PREPOP_TAX - Automatically populate tax information (if configured) at settlement for transactions
  • ACCOUNT_UPDATER - Automatically update stored accounts when the card number changes. Uses an external card updater service. Not all card issuers participate and submit card account updates to the program
  • RECEIVE_RECEIPTS_DETAIL - Merchant should receive merchant receipt copies by email for receipt actions. Sent to notify_email. The following conditions must be met receive receipt emails. + This flag must be enabled. + The merchant profile must have a name configured. + The profile must have a public reply email configured. + The profile must have notify_email configured.
  • RECEIVE_RECEIPTS_RECURRING - Merchant should receive merchant receipt copies by email for recurring transactions. Sent to notify_email. The following conditions must be met receive receipt emails. + This flag must be enabled. + The merchant profile must have a name configured. + The profile must have a public reply email configured. + The profile must have notify_email configured.
  • RECEIVE_RECEIPTS_INVOICE - Merchant should receive merchant receipt copies by email for paid invoices (NOT ORDER/QUICK). Sent to notify_email. The following conditions must be met receive receipt emails. + This flag must be enabled. + The merchant profile must have a name configured. + The profile must have a public reply email configured. + The profile must have notify_email configured.
  • RECURRING_SKIPMISSED - Skip missed recurring payments when enabling previously disabled payment. If this is not set all payments between the last payment and now will be attempted.
  • ORDERS_REQ_LEVEL3 - Requires level3 data on orders. Only supported on Retail, Moto, and Ecomm.
  • RATEQUAL_NONTAX - Force Best Rate Qualification for Non Taxable transactions
  • ALLOW_INVOICE_SMS - Merchant is allowed to send SMS message for invoices. This is not automatic, it allows SMS to be used.
  • ALLOW_INVOICING - Merchant is allowed to create invoices and products
  • DISABLE_MSR_ENTRY - Don't accept MSR (swipe) entry
  • CARDDENYLIST_CHECK - Check card deny list before online auth before attempting the transaction
  • CARDDENYLIST_DECLINE - Add to card decline list on issuer decline
custom_trans_fields
string <= 1024 characters

Comma delimited list of merchant-custom fields

req_trans_fields
string <= 1024 characters

Comma delimited list of fields that are required for transactions to process

req_order_fields
string <= 1024 characters

Comma delimited list of fields that are required for orders to process

vanity_url_prefix
string <= 1024 characters

Used for invoicing, the url prefix for the merchant. Unique system-wide

indcode
required
string
Enum: "R" "E" "M" "R" "H" "AF" "G" "RS"

Industry transactions will take place as

Values:

  • R - Retail
  • E - eCommerce
  • M - Mail Order / Telephone Order
  • R - Restaurant
  • H - Lodging
  • AF - Autofuel
  • G - Grocery
  • RS - Retail Self Service
fraudautodeny
string
Enum: "NEVER" "DENY_AVSZIP" "DENY_AVSSTREET" "DENY_CV" "DENY_NOAUTO"

Fraud Check Auto Denial with Reversal

Fraud Check Auto Denial with Reversal allows a merchant to specify what conditions should trigger an automatic reversal (and thus returning a denial to the clerk or customer) even if the issuer otherwise approved the transaction. This allows the merchant to automatically reject transactions with bad AVS or CID data without needing to code such logic within their own systems. The conditions used to trigger this logic may be specified on a global level, but also overwritten on a per-merchant basis via the Merchant Profile. Performing the auto-deny logic can also be enabled or disabled on a per-transaction basis via the fraudautodeny transaction parameter with a boolean value.

If a merchants whats to use this functionality, the recommended setting is DENY_AVSZIP|DENY_CV.

Flag values (pipe separated):

  • NEVER - Forces returning the raw processing institution/issuerresult for every transaction. This flag cannot be used with any other flags.
  • DENY_AVSZIP - Deny on AVS zipcode failure (or complete AVS failure)
  • DENY_AVSSTREET - Deny on AVS street failure (or complete AVS failure). NOTE: this is not recommended. Street failures are quite common due to different ways an address can be written. For example, '4th St' will not match and cause a failure if 'Fourth Street' was sent. This matching often results in a large number of false positives
  • DENY_CV - Deny on CV/CID/CVV2/CVC2 failure
  • DENY_NOAUTO - Only perform avs auto-denial when the fraudautodeny transaction parameter is passed with a boolean value of true.
emv_termcaps
string
Enum: "NOSIG" "ONLINEPIN" "NOOFFLINEPIN" "CASHBACK" "PINBYPASSCREDIT" "PINBYPASSUSDEBIT"

Capabilities of the EMV terminal being used

These options should correspond to device certifications.

Flag values (pipe separated):

  • NOSIG - Don't request signature
  • ONLINEPIN - Device can accept online PIN verification
  • NOOFFLINEPIN - Don't request offline PIN verification
  • CASHBACK - Cashback is allowed
  • PINBYPASSCREDIT - Credit cards can bypass PIN entry
  • PINBYPASSUSDEBIT - US issued debit cards can bypass PIN entry. They will be run as credit instead.
emv_testmode
string
Default: "no"
Enum: "yes" "no"

Whether the terminal is operation in a test environment.

If this setting does not correspond type of card (test vs production) being used, it will result in transaction failures

Values:

  • yes - Device is operating in a test environment
  • no - Device is not operating in a test environment
emv_contact_nocvm_limit
string\d+

Transactions for amounts under this limit will not request Card Holder Verification (pin, signature, etc) when the contact interface is used

emv_ctls_nocvm_limit
string\d+

Transactions for amounts under this limit will not request Card Holder Verification (pin, signature, etc) when the contactless interface is used

countrycode
string\d{3}
Default: "840"

ISO 3166-1 numeric country code where processing is taking place

currencycode
string\d{3}
Default: "840"

ISO 4217 numeric currency code

The currency of the merchant the transaction will be processing as

external_id
string

External ID for the profile

descr
string <= 512 characters

Description of the profile

addr1
string <= 512 characters

Address of merchant location

Line 1

addr2
string <= 512 characters

Address of merchant location

Line 2

addr3
string <= 512 characters

Address of merchant location

Line 3

phone
string[-+0-9() .]*

Phone number of the merchant location

This will be shown to customers

email
string

Email address of the merchant location

This will be shown to customers

url
string

Merchant's website URL

This will be shown to customers

tz
string

Timezone of the merchant and where they will be accepting transactions.

Use 'System Information Timezones' to get a list of supported timezones that can be specified. Default is the system timezone if not set.

lang
string
Enum: "EN" "FR" "ES"

Default language used at the merchant's location

Interfaces displayed to the merchnat and customer will attempt to use this language.

Values:

  • EN - English
  • FR - French
  • ES - Spanish
cashback
string(?i)(\d+|\||O)*

Merchant allows cashback and this is a pipe ('|') delimited list of whole number to prompt. Or the letter 'O' for Other (user prompting)

cashbackmax
string\d+

Maximum amount allowed to be requested by a customer for cashback

cashback_purchmin
string\d+

Minimum transaction amount required to allow a customer cashback

tippercent
string(?i)(\d+|\||O)*

Merchant accepts tips and this is a pipe ('|') delimited list of whole percentages to prompt. Or the letter 'O' for Other (user prompting)

msr_nosig_limit
string\d+

Transactions for amounts under this limit will not request signagure when the MSR interface is used

enc_provider
string

Name of external encryption provider to use (e.g. bluefin)

Must have ENCRYPTEDONLY flag. External providers require a direct relationship and devices must be received from the provider. If in doubt, do not set this.

l3_commoditycode
string[0-9a-zA-Z]{8,12}

Contains an international description code of the individual good or service being supplied

Required if PREPOP_LEVEL3 or ORDERS_REQ_LEVEL3 are enabled.

The acquiring bank or processor should provide the merchant an updated listing of currently defined codes. Please note that this is different from the 4-character summary commodity code. Codes can be found online at http://www.unspsc.org

The code itself will not be validated; only the format is validated.

l3_productcode
string[0-9a-zA-Z ]{1,12}

Merchant-defined code for the item being purchased, such as a UPC #, SKU #, or Item #

Required if PREPOP_LEVEL3 or ORDERS_REQ_LEVEL3.

l3_description
string[0-9a-zA-Z ]{1,26}

Merchant-defined description of the item or service being sold

Required if PREPOP_LEVEL3 or ORDERS_REQ_LEVEL3.

This is a free-form field.

tax_rate_autopop
string(\d?\d?\.?\d?\d?)|NT

Amount of tax to apply to transactions when tax is not provided.

Default tax rate for location. Required if PREPOP_TAX

txn_export_key
string

Public key for transaction export when using the Transaction Export action

Export key, in this format:

ID returned from P2EE provision request followed by pipe separator (|) followed by RSA public key data, including standard start and end sentinels (i.e., -----{BEGIN|END} PUBLIC KEY-----) and keeping newlines intact.

Responses

Request samples

Content type
application/json
{
  • "group_id": "string",
  • "profile_name": "string",
  • "name": "string",
  • "notify_email": "string",
  • "flags": "ENCRYPTEDONLY",
  • "custom_trans_fields": "string",
  • "req_trans_fields": "string",
  • "req_order_fields": "string",
  • "vanity_url_prefix": "string",
  • "indcode": "R",
  • "fraudautodeny": "NEVER",
  • "emv_termcaps": "NOSIG",
  • "emv_testmode": "yes",
  • "emv_contact_nocvm_limit": "string",
  • "emv_ctls_nocvm_limit": "string",
  • "countrycode": "840",
  • "currencycode": "840",
  • "external_id": "string",
  • "descr": "string",
  • "addr1": "string",
  • "addr2": "string",
  • "addr3": "string",
  • "phone": "string",
  • "email": "string",
  • "url": "string",
  • "tz": "string",
  • "lang": "EN",
  • "cashback": "string",
  • "cashbackmax": "string",
  • "cashback_purchmin": "string",
  • "tippercent": "string",
  • "msr_nosig_limit": "string",
  • "enc_provider": "string",
  • "l3_commoditycode": "string",
  • "l3_productcode": "string",
  • "l3_description": "string",
  • "tax_rate_autopop": "string",
  • "txn_export_key": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Disable Profile

Disable Profile that is enabled

Will return failure if profile is not currently enabled.

libmonetra KVS equivalent for endpoint

  • action_sys = profile_disable
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Merchant profile identifier

Responses

Request samples 

curl -X PATCH 'https://testbox.monetra.com/api/v2/boarding/profile/974893/disable' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Remove a Profile

Delete a Profile

libmonetra KVS equivalent for endpoint

  • action_sys = profile_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Merchant profile identifier

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/boarding/profile/974893' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Profile Details

Profile details

libmonetra KVS equivalent for endpoint

  • action_sys = profile_list
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Merchant profile identifier

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/boarding/profile/974893' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "id": "string",
  • "profile_name": "string",
  • "name": "string",
  • "group_id": "string",
  • "group_depth": "string",
  • "flags": "MODIFY_SELF",
  • "status": "ACTIVE",
  • "indcode": "R",
  • "create_ts": "string",
  • "upd_ts": "string",
  • "notify_email": "string",
  • "custom_trans_fields": "string",
  • "req_trans_fields": "string",
  • "custom_order_fields": "string",
  • "req_order_fields": "string",
  • "vanity_url_prefix": "string",
  • "tokengroup_id": "string",
  • "tokengroup_name": "string",
  • "pushnotification_id": "string",
  • "whitelabelgroup_id": "string",
  • "fraudautodeny": "NEVER",
  • "emv_termcaps": "NOSIG",
  • "emv_testmode": "yes",
  • "emv_contact_nocvm_limit": "string",
  • "emv_ctls_nocvm_limit": "string",
  • "countrycode": "string",
  • "currencycode": "string",
  • "descr": "string",
  • "addr1": "string",
  • "addr2": "string",
  • "addr3": "string",
  • "phone": "string",
  • "email": "string",
  • "external_id": "string",
  • "url": "string",
  • "tz": "string",
  • "lang": "EN",
  • "cashback": "string",
  • "cashbackmax": "string",
  • "cashback_purchmin": "string",
  • "tippercent": "string",
  • "msr_nosig_limit": "string",
  • "enc_provider": "string",
  • "l3_commoditycode": "string",
  • "l3_description": "string",
  • "l3_productcode": "string",
  • "tax_rate_autopop": "string"
}

Edit a Profile

Edits a Profile

libmonetra KVS equivalent for endpoint

  • action_sys = profile_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Merchant profile identifier

Request Body schema: application/json
name
string <= 128 characters

Name for profile

Not required to be unique

Used for displaying to customers

Not required to be unique

Will be copied into profile_name if provided and profile_name is empty

profile_name
string <= 128 characters

Name for profile

Internal name within the system

Not required to be unique

notify_email
string <= 2048 characters

List of email addresses for notifications (e.g. settlement emails)

flags
string
Enum: "ENCRYPTEDONLY" "EMVSUPRESSSIG" "EMVPIN_STANDIN_ALLOWED" "EMVODA_NONE_STANDIN_ALLOWED" "DEBIT_STANDIN_ALLOWED" "PREPOP_LEVEL3" "PREPOP_TAX" "ACCOUNT_UPDATER" "RECEIVE_RECEIPTS_DETAIL" "RECEIVE_RECEIPTS_RECURRING" "RECEIVE_RECEIPTS_INVOICE" "RECURRING_SKIPMISSED" "ORDERS_REQ_LEVEL3" "RATEQUAL_NONTAX" "ALLOW_INVOICE_SMS" "ALLOW_INVOICING" "DISABLE_MSR_ENTRY" "CARDDENYLIST_CHECK" "CARDDENYLIST_DECLINE"

Merchant flags

Flags can be combined into a pipe ('|') separate list.

Flag values (pipe separated):

  • ENCRYPTEDONLY - Account data will only be accepted if it is encrypted. Clear account data will be rejected
  • EMVSUPRESSSIG - Inform a payment device never prompt for signature for EMV transactions
  • EMVPIN_STANDIN_ALLOWED - Allow stand-in authorizations for EMV when online PIN is entered
  • EMVODA_NONE_STANDIN_ALLOWED - Allow stand-in authorizations for EMV when ODA not performed
  • DEBIT_STANDIN_ALLOWED - Allow stand-in authorizations for debit cards
  • PREPOP_LEVEL3 - Automatically populate Level 3 transaction data (if configured) at settlement for transactions that are Level 3 capable but do not have Level 3 line items
  • PREPOP_TAX - Automatically populate tax information (if configured) at settlement for transactions
  • ACCOUNT_UPDATER - Automatically update stored accounts when the card number changes. Uses an external card updater service. Not all card issuers participate and submit card account updates to the program
  • RECEIVE_RECEIPTS_DETAIL - Merchant should receive merchant receipt copies by email for receipt actions. Sent to notify_email. The following conditions must be met receive receipt emails. + This flag must be enabled. + The merchant profile must have a name configured. + The profile must have a public reply email configured. + The profile must have notify_email configured.
  • RECEIVE_RECEIPTS_RECURRING - Merchant should receive merchant receipt copies by email for recurring transactions. Sent to notify_email. The following conditions must be met receive receipt emails. + This flag must be enabled. + The merchant profile must have a name configured. + The profile must have a public reply email configured. + The profile must have notify_email configured.
  • RECEIVE_RECEIPTS_INVOICE - Merchant should receive merchant receipt copies by email for paid invoices (NOT ORDER/QUICK). Sent to notify_email. The following conditions must be met receive receipt emails. + This flag must be enabled. + The merchant profile must have a name configured. + The profile must have a public reply email configured. + The profile must have notify_email configured.
  • RECURRING_SKIPMISSED - Skip missed recurring payments when enabling previously disabled payment. If this is not set all payments between the last payment and now will be attempted.
  • ORDERS_REQ_LEVEL3 - Requires level3 data on orders. Only supported on Retail, Moto, and Ecomm.
  • RATEQUAL_NONTAX - Force Best Rate Qualification for Non Taxable transactions
  • ALLOW_INVOICE_SMS - Merchant is allowed to send SMS message for invoices. This is not automatic, it allows SMS to be used.
  • ALLOW_INVOICING - Merchant is allowed to create invoices and products
  • DISABLE_MSR_ENTRY - Don't accept MSR (swipe) entry
  • CARDDENYLIST_CHECK - Check card deny list before online auth before attempting the transaction
  • CARDDENYLIST_DECLINE - Add to card decline list on issuer decline
custom_trans_fields
string <= 1024 characters

Comma delimited list of merchant-custom fields

req_trans_fields
string <= 1024 characters

Comma delimited list of fields that are required for transactions to process

req_order_fields
string <= 1024 characters

Comma delimited list of fields that are required for orders to process

vanity_url_prefix
string <= 1024 characters

Used for invoicing, the url prefix for the merchant. Unique system-wide

indcode
string
Enum: "R" "E" "M" "R" "H" "AF" "G" "RS"

Industry transactions will take place as

Values:

  • R - Retail
  • E - eCommerce
  • M - Mail Order / Telephone Order
  • R - Restaurant
  • H - Lodging
  • AF - Autofuel
  • G - Grocery
  • RS - Retail Self Service
fraudautodeny
string
Enum: "NEVER" "DENY_AVSZIP" "DENY_AVSSTREET" "DENY_CV" "DENY_NOAUTO"

Fraud Check Auto Denial with Reversal

Fraud Check Auto Denial with Reversal allows a merchant to specify what conditions should trigger an automatic reversal (and thus returning a denial to the clerk or customer) even if the issuer otherwise approved the transaction. This allows the merchant to automatically reject transactions with bad AVS or CID data without needing to code such logic within their own systems. The conditions used to trigger this logic may be specified on a global level, but also overwritten on a per-merchant basis via the Merchant Profile. Performing the auto-deny logic can also be enabled or disabled on a per-transaction basis via the fraudautodeny transaction parameter with a boolean value.

If a merchants whats to use this functionality, the recommended setting is DENY_AVSZIP|DENY_CV.

Flag values (pipe separated):

  • NEVER - Forces returning the raw processing institution/issuerresult for every transaction. This flag cannot be used with any other flags.
  • DENY_AVSZIP - Deny on AVS zipcode failure (or complete AVS failure)
  • DENY_AVSSTREET - Deny on AVS street failure (or complete AVS failure). NOTE: this is not recommended. Street failures are quite common due to different ways an address can be written. For example, '4th St' will not match and cause a failure if 'Fourth Street' was sent. This matching often results in a large number of false positives
  • DENY_CV - Deny on CV/CID/CVV2/CVC2 failure
  • DENY_NOAUTO - Only perform avs auto-denial when the fraudautodeny transaction parameter is passed with a boolean value of true.
emv_termcaps
string
Enum: "NOSIG" "ONLINEPIN" "NOOFFLINEPIN" "CASHBACK" "PINBYPASSCREDIT" "PINBYPASSUSDEBIT"

Capabilities of the EMV terminal being used

These options should correspond to device certifications.

Flag values (pipe separated):

  • NOSIG - Don't request signature
  • ONLINEPIN - Device can accept online PIN verification
  • NOOFFLINEPIN - Don't request offline PIN verification
  • CASHBACK - Cashback is allowed
  • PINBYPASSCREDIT - Credit cards can bypass PIN entry
  • PINBYPASSUSDEBIT - US issued debit cards can bypass PIN entry. They will be run as credit instead.
emv_testmode
string
Default: "no"
Enum: "yes" "no"

Whether the terminal is operation in a test environment.

If this setting does not correspond type of card (test vs production) being used, it will result in transaction failures

Values:

  • yes - Device is operating in a test environment
  • no - Device is not operating in a test environment
emv_contact_nocvm_limit
string\d+

Transactions for amounts under this limit will not request Card Holder Verification (pin, signature, etc) when the contact interface is used

emv_ctls_nocvm_limit
string\d+

Transactions for amounts under this limit will not request Card Holder Verification (pin, signature, etc) when the contactless interface is used

countrycode
string\d{3}
Default: "840"

ISO 3166-1 numeric country code where processing is taking place

currencycode
string\d{3}
Default: "840"

ISO 4217 numeric currency code

The currency of the merchant the transaction will be processing as

external_id
string

External ID for the profile

descr
string <= 512 characters

Description of the profile

addr1
string <= 512 characters

Address of merchant location

Line 1

addr2
string <= 512 characters

Address of merchant location

Line 2

addr3
string <= 512 characters

Address of merchant location

Line 3

phone
string[-+0-9() .]*

Phone number of the merchant location

This will be shown to customers

email
string

Email address of the merchant location

This will be shown to customers

url
string

Merchant's website URL

This will be shown to customers

tz
string

Timezone of the merchant and where they will be accepting transactions.

Use 'System Information Timezones' to get a list of supported timezones that can be specified. Default is the system timezone if not set.

lang
string
Enum: "EN" "FR" "ES"

Default language used at the merchant's location

Interfaces displayed to the merchnat and customer will attempt to use this language.

Values:

  • EN - English
  • FR - French
  • ES - Spanish
cashback
string(?i)(\d+|\||O)*

Merchant allows cashback and this is a pipe ('|') delimited list of whole number to prompt. Or the letter 'O' for Other (user prompting)

cashbackmax
string\d+

Maximum amount allowed to be requested by a customer for cashback

cashback_purchmin
string\d+

Minimum transaction amount required to allow a customer cashback

tippercent
string(?i)(\d+|\||O)*

Merchant accepts tips and this is a pipe ('|') delimited list of whole percentages to prompt. Or the letter 'O' for Other (user prompting)

msr_nosig_limit
string\d+

Transactions for amounts under this limit will not request signagure when the MSR interface is used

enc_provider
string

Name of external encryption provider to use (e.g. bluefin)

Must have ENCRYPTEDONLY flag. External providers require a direct relationship and devices must be received from the provider. If in doubt, do not set this.

l3_commoditycode
string[0-9a-zA-Z]{8,12}

Contains an international description code of the individual good or service being supplied

Required if PREPOP_LEVEL3 or ORDERS_REQ_LEVEL3 are enabled.

The acquiring bank or processor should provide the merchant an updated listing of currently defined codes. Please note that this is different from the 4-character summary commodity code. Codes can be found online at http://www.unspsc.org

The code itself will not be validated; only the format is validated.

l3_productcode
string[0-9a-zA-Z ]{1,12}

Merchant-defined code for the item being purchased, such as a UPC #, SKU #, or Item #

Required if PREPOP_LEVEL3 or ORDERS_REQ_LEVEL3.

l3_description
string[0-9a-zA-Z ]{1,26}

Merchant-defined description of the item or service being sold

Required if PREPOP_LEVEL3 or ORDERS_REQ_LEVEL3.

This is a free-form field.

tax_rate_autopop
string(\d?\d?\.?\d?\d?)|NT

Amount of tax to apply to transactions when tax is not provided.

Default tax rate for location. Required if PREPOP_TAX

txn_export_key
string

Public key for transaction export when using the Transaction Export action

Export key, in this format:

ID returned from P2EE provision request followed by pipe separator (|) followed by RSA public key data, including standard start and end sentinels (i.e., -----{BEGIN|END} PUBLIC KEY-----) and keeping newlines intact.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "profile_name": "string",
  • "notify_email": "string",
  • "flags": "ENCRYPTEDONLY",
  • "custom_trans_fields": "string",
  • "req_trans_fields": "string",
  • "req_order_fields": "string",
  • "vanity_url_prefix": "string",
  • "indcode": "R",
  • "fraudautodeny": "NEVER",
  • "emv_termcaps": "NOSIG",
  • "emv_testmode": "yes",
  • "emv_contact_nocvm_limit": "string",
  • "emv_ctls_nocvm_limit": "string",
  • "countrycode": "840",
  • "currencycode": "840",
  • "external_id": "string",
  • "descr": "string",
  • "addr1": "string",
  • "addr2": "string",
  • "addr3": "string",
  • "phone": "string",
  • "email": "string",
  • "url": "string",
  • "tz": "string",
  • "lang": "EN",
  • "cashback": "string",
  • "cashbackmax": "string",
  • "cashback_purchmin": "string",
  • "tippercent": "string",
  • "msr_nosig_limit": "string",
  • "enc_provider": "string",
  • "l3_commoditycode": "string",
  • "l3_productcode": "string",
  • "l3_description": "string",
  • "tax_rate_autopop": "string",
  • "txn_export_key": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Enable Profile

Enable Profile that was disabled

Will return failure if profile is not currently disabled.

libmonetra KVS equivalent for endpoint

  • action_sys = profile_enable
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Merchant profile identifier

Responses

Request samples 

curl -X PATCH 'https://testbox.monetra.com/api/v2/boarding/profile/974893/enable' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Profile Card Configuration

Gets the profile's card configuration

The resulting report will contain these headers:

cardtype, auth_proc, settle_proc, auth_merchid, settle_merchid, auth_route_id,
settle_route_id, indcode, trantypes, emv, mac_required, gift_binrange,
can_standin, auth_procfeatures, settle_procfeatures

libmonetra KVS equivalent for endpoint

  • action_admin = merch_info
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/boarding/profile/configuration/card' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Get Profile Terminal Configuration

Gets the profile's terminal configuration

libmonetra KVS equivalent for endpoint

  • action_admin = merch_info
  • merch_info = termparams
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

fetch_logo
object
Enum: "yes" "no"
Example: fetch_logo=yes

Values:

  • yes - Reterive merchant logo image
  • no - Do not reterive merchant logo image

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/boarding/profile/configuration/terminal' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "name": "string",
  • "addr1": "string",
  • "addr2": "string",
  • "addr3": "string",
  • "phone": "string",
  • "email": "string",
  • "url": "string",
  • "countrycode": "string",
  • "currencycode": "string",
  • "indcode": "R",
  • "lang": "EN",
  • "cashback": "string",
  • "cashback_purchmin": "string",
  • "cashbackmax": "string",
  • "tippercent": "string",
  • "l3_description": "string",
  • "l3_commoditycode": "string",
  • "l3_productcode": "string",
  • "tax_rate": "string",
  • "custom_fields": "string",
  • "req_fields": "string",
  • "flags": "ENCRYPTEDONLY",
  • "merch_logo": "string",
  • "merch_logo_type": "PNG"
}

Move a Profile

Move a Profile from one group to another

libmonetra KVS equivalent for endpoint

  • action_sys = profile_move
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Merchant profile identifier

Request Body schema: application/json
group_id
required
string\d+

Group identifier

Responses

Request samples

Content type
application/json
{
  • "group_id": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Routes

Routes define where authorization and settlement requests should be sent for processing. Routes are based on card type, and authorization vs settlement. Routes are tied to profiles.

It is common for merchants to have a single route for all cards, authorization and settlement.

The routes correspond to the processor the merchant is using and includes the processor specific configuration values.

Route Summary

Lists a summary of the routes for a profile

route_id, proc, cardtypes, mode

libmonetra KVS equivalent for endpoint

  • action_sys = route_list
  • route_list = summary
Authorizations:
basic_authapikey_idapikey
path Parameters
profile_id
required
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/boarding/profile/974893/route' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "report": {
    }
}

Create a Route

Creates a Route

Routes provide configuration for how to process specific card types. Every profile needs at least one route in order to "route" transactions.

Profiles can have multiple routes differentiated by cardtype and mode. Multiple routes can be configured as long as any given card type is not specified in multiple routes with the same mode.

For example:

Correct
Cardtype Visa -> route 0 Auth
Cardtype Visa -> route 1 Settle

Error
Cardtype Visa -> route 0 Auth
Cardtype Visa -> route 1 Both

Note: The route_id is specific to the profile_id, and not globally unique.

Routes are specific to processors and have additional fields that must be retrieved by getting the list of "Processor Fields" for the specified proc. Processor specific fields will be additionally sent as required by the processor.

libmonetra KVS equivalent for endpoint

  • action_sys = route_add
Authorizations:
basic_authapikey_idapikey
path Parameters
profile_id
required
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Request Body schema: application/json
proc
required
string

Processor name as specified by 'Processor List' report under the proc column

mode
required
string
Enum: "AUTH" "SETTLE" "BOTH"

Determines where the route is specify to authorization or settlement

Flag values (pipe separated):

  • AUTH - Route should be used for authorization
  • SETTLE - Route should be used for settlement
  • BOTH - Alias for AUTH|SETTLE
cardtypes
required
string
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "BML" "GIFT" "VISADEBIT" "MCDEBIT" "OTHERDEBIT" "EBT" "CHECK" "INTERAC" "CUP" "PAYPALEC" "ACH"

Cardtypes

Pipe (|) separated.

Cardtype support is dependant on the processor. Not all processor support all cardtypes.

Flag values (pipe separated):

  • VISA - Visa credit
  • MC - Mastercard credit
  • AMEX - American Express credit
  • DISC - Discover credit
  • DINERS - Diners credit
  • JCB - JCB credit. Formerly Japan Credit Bureau
  • BML - Bill me later
  • GIFT - Private label Gift. Not cards backed by a credit card brand such as Visa, Mastercard, etc.
  • VISADEBIT - Visa debit
  • MCDEBIT - Mastercard debit
  • OTHERDEBIT - Debit not Visa or Mastercard
  • EBT - Electronic Benefits Transfer
  • CHECK - Paper checks
  • INTERAC - Interac (Canadian debit)
  • CUP - China Union Pay credit
  • PAYPALEC - PayPal Express Checkout token
  • ACH - Bank transfer
route_id
string\d+

If wanted to assign a specific route id, may pass one between 0 and 32767. Otherwise will auto-assign lowest possible value and return

emv_entrymodes
string
Enum: "VISA_CONTACT" "VISA_CONTACTLESS" "MC_CONTACT" "MC_CONTACTLESS" "AMEX_CONTACT" "AMEX_CONTACTLESS" "DISC_CONTACT" "DISC_CONTACTLESS" "JCB_CONTACT" "JCB_CONTACTLESS" "INTERAC_CONTACT" "INTERAC_CONTACTLESS" "CUP_CONTACT" "CUP_CONTACTLESS" "USDEBIT_CONTACT" "USDEBIT_CONTACTLESS" "INTLDEBIT_CONTACT" "INTLDEBIT_CONTACTLESS"

EMV Interfaces specific cards types can use

Pipe (|) separated.

EMV Entry Mode support is dependant on the processor. Not all processor support all entry modes for all cardtypes

Flag values (pipe separated):

  • VISA_CONTACT - Visa credit contact interface
  • VISA_CONTACTLESS - Visa credit contactless interface
  • MC_CONTACT - Mastercard credit contact interface
  • MC_CONTACTLESS - Mastercard credit contactless interface
  • AMEX_CONTACT - American Express credit contact interface
  • AMEX_CONTACTLESS - American Express credit contactless interface
  • DISC_CONTACT - Discover credit contact interface
  • DISC_CONTACTLESS - Discover credit contactless interface
  • JCB_CONTACT - JCB credit contact interface
  • JCB_CONTACTLESS - JCB credit contactless interface
  • INTERAC_CONTACT - Interac (Canadian) debit contact interface
  • INTERAC_CONTACTLESS - Interac (Canadian) debit contactless interface
  • CUP_CONTACT - China Union Pay credit contact interface
  • CUP_CONTACTLESS - China Union Pay credit contactless interface
  • USDEBIT_CONTACT - United States debit contact interface
  • USDEBIT_CONTACTLESS - United States debit contactless interface
  • INTLDEBIT_CONTACT - International debit contact interface. Does not not include Interac.
  • INTLDEBIT_CONTACTLESS - International debit contactless interface. Does not not include Interac.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "proc": "string",
  • "mode": "AUTH",
  • "cardtypes": "VISA|MC",
  • "route_id": "string",
  • "emv_entrymodes": "VISA_CONTACT|SVISA_CONTACTLESS|MC_CONTACT",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "route_id": "string"
}

Remove a Route

Deletes a Route

libmonetra KVS equivalent for endpoint

  • action_sys = route_del
Authorizations:
basic_authapikey_idapikey
path Parameters
profile_id
required
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

route_id
required
string

Processing route

More than one route ID may be associated with a profile. This can happen when split-routing is in use. The specific ID for the route being operated on must be specified in requests that accept route_id.

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/boarding/profile/974893/route/0' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Route Detail

Configuration details for a specific profile route

Will output as key/value pairs. Will return entries for proc, cardtypes, mode, emv_entrymodes as well as any parameters found in a "Processing Fields" request.

libmonetra KVS equivalent for endpoint

  • action_sys = route_list
  • route_list = detail
Authorizations:
basic_authapikey_idapikey
path Parameters
profile_id
required
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

route_id
required
string

Processing route

More than one route ID may be associated with a profile. This can happen when split-routing is in use. The specific ID for the route being operated on must be specified in requests that accept route_id.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/boarding/profile/974893/route' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "property1": "string",
  • "property2": "string"
}

Edit a Route

Edits a Route

libmonetra KVS equivalent for endpoint

  • action_sys = route_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
profile_id
required
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

route_id
required
string

Processing route

More than one route ID may be associated with a profile. This can happen when split-routing is in use. The specific ID for the route being operated on must be specified in requests that accept route_id.

Request Body schema: application/json
proc
string

Processor name as specified by 'Processor List' report under the proc column

mode
string
Enum: "AUTH" "SETTLE" "BOTH"

Determines where the route is specify to authorization or settlement

Flag values (pipe separated):

  • AUTH - Route should be used for authorization
  • SETTLE - Route should be used for settlement
  • BOTH - Alias for AUTH|SETTLE
cardtypes
string
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "BML" "GIFT" "VISADEBIT" "MCDEBIT" "OTHERDEBIT" "EBT" "CHECK" "INTERAC" "CUP" "PAYPALEC" "ACH"

Cardtypes

Pipe (|) separated.

Cardtype support is dependant on the processor. Not all processor support all cardtypes.

Flag values (pipe separated):

  • VISA - Visa credit
  • MC - Mastercard credit
  • AMEX - American Express credit
  • DISC - Discover credit
  • DINERS - Diners credit
  • JCB - JCB credit. Formerly Japan Credit Bureau
  • BML - Bill me later
  • GIFT - Private label Gift. Not cards backed by a credit card brand such as Visa, Mastercard, etc.
  • VISADEBIT - Visa debit
  • MCDEBIT - Mastercard debit
  • OTHERDEBIT - Debit not Visa or Mastercard
  • EBT - Electronic Benefits Transfer
  • CHECK - Paper checks
  • INTERAC - Interac (Canadian debit)
  • CUP - China Union Pay credit
  • PAYPALEC - PayPal Express Checkout token
  • ACH - Bank transfer
emv_entrymodes
string
Enum: "VISA_CONTACT" "VISA_CONTACTLESS" "MC_CONTACT" "MC_CONTACTLESS" "AMEX_CONTACT" "AMEX_CONTACTLESS" "DISC_CONTACT" "DISC_CONTACTLESS" "JCB_CONTACT" "JCB_CONTACTLESS" "INTERAC_CONTACT" "INTERAC_CONTACTLESS" "CUP_CONTACT" "CUP_CONTACTLESS" "USDEBIT_CONTACT" "USDEBIT_CONTACTLESS" "INTLDEBIT_CONTACT" "INTLDEBIT_CONTACTLESS"

EMV Interfaces specific cards types can use

Pipe (|) separated.

EMV Entry Mode support is dependant on the processor. Not all processor support all entry modes for all cardtypes

Flag values (pipe separated):

  • VISA_CONTACT - Visa credit contact interface
  • VISA_CONTACTLESS - Visa credit contactless interface
  • MC_CONTACT - Mastercard credit contact interface
  • MC_CONTACTLESS - Mastercard credit contactless interface
  • AMEX_CONTACT - American Express credit contact interface
  • AMEX_CONTACTLESS - American Express credit contactless interface
  • DISC_CONTACT - Discover credit contact interface
  • DISC_CONTACTLESS - Discover credit contactless interface
  • JCB_CONTACT - JCB credit contact interface
  • JCB_CONTACTLESS - JCB credit contactless interface
  • INTERAC_CONTACT - Interac (Canadian) debit contact interface
  • INTERAC_CONTACTLESS - Interac (Canadian) debit contactless interface
  • CUP_CONTACT - China Union Pay credit contact interface
  • CUP_CONTACTLESS - China Union Pay credit contactless interface
  • USDEBIT_CONTACT - United States debit contact interface
  • USDEBIT_CONTACTLESS - United States debit contactless interface
  • INTLDEBIT_CONTACT - International debit contact interface. Does not not include Interac.
  • INTLDEBIT_CONTACTLESS - International debit contactless interface. Does not not include Interac.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "proc": "string",
  • "mode": "AUTH",
  • "cardtypes": "VISA|MC",
  • "emv_entrymodes": "VISA_CONTACT|SVISA_CONTACTLESS|MC_CONTACT",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Processors

Information about processors used for setting up routes.

Allow determine which processors are available to Monetra and the processor specific fields that are needed when setting up a route for a given processor.

Processor List

List processors currently enabled

The resulting report will contain these headers:

proc, active, cardtypes, emv_entrymodes,
credit_trantypes, debit_trantypes, ebt_trantypes,
gift_trantypes, check_trantypes, supported_conns,
supported_modes, supported_industries, displayname,
helpdesk_phone, version, features

libmonetra KVS equivalent for endpoint

  • action_sys = route_fields
  • route_fields = proclist
Authorizations:
basic_authapikey_idapikey
query Parameters
proc
string

Processor proc name

Used to filter only a single processor

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/boarding/route/processor' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "report": {
    }
}

Processor Specific Fields

Processor specific route fields

Routes specify processors and every processor has additional processor specific route fields. This report will provide all of the fields unique to the processor that apply to the route.

The resulting report will contain these headers:

name, req_credit, req_debit, req_gift, req_ebt, req_dial, req_ip, req_https,
req_ssl, req_other, req_auth, req_settle, len_min, len_max, field_type,
submitteronly, displayname, desc

Example for "loopback" processor emulator:

{
    "report": [
        {
            "name": "ZIPCODE",
            "req_credit": "Yes",
            "req_debit": "Yes",
            "req_gift": "Yes",
            "req_ebt": "Yes",
            "req_dial": "No",
            "req_ip": "Yes",
            "req_https": "Yes",
            "req_ssl": "Yes",
            "req_other": "Yes",
            "req_auth": "No",
            "req_settle": "No",
            "len_min": "5",
            "len_max": "9",
            "field_type": "VAR_TYPE_ALPHANUM",
            "submitteronly": "No",
            "displayname": "Zipcode",
            "desc": "Five or Nine digit zipcode of merchant location (US). Six Alpha numeric for Canada. No dashes"
        },
        {
            "name": "BINRANGE",
            "req_credit": "No",
            "req_debit": "No",
            "req_gift": "No",
            "req_ebt": "No",
            "req_dial": "No",
            "req_ip": "No",
            "req_https": "No",
            "req_ssl": "No",
            "req_other": "No",
            "req_auth": "No",
            "req_settle": "No",
            "len_min": "1",
            "len_max": "100",
            "field_type": "VAR_TYPE_BINRANGE",
            "submitteronly": "No",
            "displayname": "Gift Bin Range",
            "desc": "Only supply if not using default bin range of 6006 or 6276. Specify as MIN1-MAX1;MIN2-MAX2 etc."
        },
        {
            "name": "AMOUNTCHECKS",
            "req_credit": "No",
            "req_debit": "No",
            "req_gift": "No",
            "req_ebt": "No",
            "req_dial": "No",
            "req_ip": "No",
            "req_https": "No",
            "req_ssl": "No",
            "req_other": "No",
            "req_auth": "No",
            "req_settle": "No",
            "len_min": "1",
            "len_max": "5",
            "field_type": "VAR_TYPE_BOOLEAN_DEF_TRUE",
            "submitteronly": "No",
            "displayname": "Amount Checks",
            "desc": "Boolean. Whether or not to perform amount triggers. Defaults to True."
        },
        {
            "name": "SETTLEDELAY",
            "req_credit": "No",
            "req_debit": "No",
            "req_gift": "No",
            "req_ebt": "No",
            "req_dial": "No",
            "req_ip": "No",
            "req_https": "No",
            "req_ssl": "No",
            "req_other": "No",
            "req_auth": "No",
            "req_settle": "No",
            "len_min": "1",
            "len_max": "5",
            "field_type": "VAR_TYPE_NUM_ONLY",
            "submitteronly": "No",
            "displayname": "Settle Delay",
            "desc": "Delay in milliseconds between each packet when simulating settlement. Defaults to 50 ms (1/20 second)."
        },
        {
            "name": "GENINTERCHANGE",
            "req_credit": "No",
            "req_debit": "No",
            "req_gift": "No",
            "req_ebt": "No",
            "req_dial": "No",
            "req_ip": "No",
            "req_https": "No",
            "req_ssl": "No",
            "req_other": "No",
            "req_auth": "No",
            "req_settle": "No",
            "len_min": "1",
            "len_max": "5",
            "field_type": "VAR_TYPE_BOOLEAN_DEF_FALSE",
            "submitteronly": "No",
            "displayname": "Interchange",
            "desc": "Generate fake interchange data. This should be used with care because it will allow loopback generated transaction to be settled with a real procesor. Default is false."
        },
        {
            "name": "STRICTVALIDATE",
            "req_credit": "No",
            "req_debit": "No",
            "req_gift": "No",
            "req_ebt": "No",
            "req_dial": "No",
            "req_ip": "No",
            "req_https": "No",
            "req_ssl": "No",
            "req_other": "No",
            "req_auth": "No",
            "req_settle": "No",
            "len_min": "1",
            "len_max": "5",
            "field_type": "VAR_TYPE_BOOLEAN_DEF_TRUE",
            "submitteronly": "No",
            "displayname": "Strict Validation",
            "desc": "Strictly validate interchange data. Requires data that is considered optional but will downgrade if not present."
        },
        {
            "name": "TOKENIZATION",
            "req_credit": "No",
            "req_debit": "No",
            "req_gift": "No",
            "req_ebt": "No",
            "req_dial": "No",
            "req_ip": "No",
            "req_https": "No",
            "req_ssl": "No",
            "req_other": "No",
            "req_auth": "No",
            "req_settle": "No",
            "len_min": "1",
            "len_max": "5",
            "field_type": "VAR_TYPE_BOOLEAN_DEF_FALSE",
            "submitteronly": "No",
            "displayname": "Tokenization",
            "desc": "Return a simulated token from a processor E2E tokenization system. Used instead of the gateway token system at increased cost to the merchant."
        },
        {
            "name": "EMVTESTTOOL",
            "req_credit": "No",
            "req_debit": "No",
            "req_gift": "No",
            "req_ebt": "No",
            "req_dial": "No",
            "req_ip": "No",
            "req_https": "No",
            "req_ssl": "No",
            "req_other": "No",
            "req_auth": "No",
            "req_settle": "No",
            "len_min": "1",
            "len_max": "100",
            "field_type": "VAR_TYPE_ALPHANUM",
            "submitteronly": "No",
            "displayname": "EMV Test Tool",
            "desc": "EMV Test tool being used: \"collis\", \"icc\", \"b2\". Provides hints to work around took specific quirks."
        }
    ]
}

libmonetra KVS equivalent for endpoint

  • action_sys = route_fields
  • route_fields = procfields
Authorizations:
basic_authapikey_idapikey
path Parameters
proc
required
string

Processor name as specified by 'Processor List' report under the proc column

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/boarding/route/processor/{proc}' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "report": {
    }
}

Big Batch Accounts

This section deals with the administration and management of Big Batch settlement through the Big Batch Aggregator subsystem, which enables an integrator to aggregate batches from multiple Merchant Users and settle them as one unit.

The basic concept behind Big Batch aggregation is that one administrative user will combine separate batches from multiple merchants into one Big Batch file, which will be sent to the processor as a single unit.

To achieve this, a Big Batch Aggregation account must first be set up. Multiple Big Batch Merchants will settle into the aggregation. The merchant profile's settle route will settle into the Big Batch Merchant account.

Settle flow will look like this

Profile -> settle route -> big batch merchant -> big batch aggrgation -> processor

The Big Batch Aggregation Account settles all batches that have been collected for all merchants setting into the aggrgation. When a profile settles into Big Batch strict validation checks will take place to ensure transactions contain all requred data.

Delete a Big Batch Aggregation

Delete a Big Batch Aggregation Account

libmonetra KVS equivalent for endpoint

  • action_su = bigbatch_manage
  • bigbatch_manage = delacct
Authorizations:
basic_authapikey_idapikey
path Parameters
bbacctid
required
string

ID of big batch aggregation account

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/boarding/bigbatch/678956786' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Big Batch Aggregation Details

Get the information for a big batch aggregation account

libmonetra KVS equivalent for endpoint

  • action_su = bigbatch_manage
  • bigbatch_manage = getacct
Authorizations:
basic_authapikey_idapikey
path Parameters
bbacctid
required
string

ID of big batch aggregation account

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/bigbatch/account/{bbacctid}' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "descr": "string",
  • "email": "string",
  • "proc": "string"
}

Edit a Big Batch Aggregation

Edits a Big Batch Aggregation Account

libmonetra KVS equivalent for endpoint

  • action_su = bigbatch_manage
  • bigbatch_manage = editacct
Authorizations:
basic_authapikey_idapikey
path Parameters
bbacctid
required
string

ID of big batch aggregation account

Request Body schema: application/json
descr
string <= 128 characters

Description of the big batch account

email
string <= 128 characters

Notification email for events like settlement

Responses

Request samples

Content type
application/json
{
  • "descr": "string",
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

List Big Batch Aggregations

List big batch aggregation accounts

The resulting report will contain these headers:

bbacctid, proc, descr, num_merchants

libmonetra KVS equivalent for endpoint

  • action_su = bigbatch_manage
  • bigbatch_manage = listacct
Authorizations:
basic_authapikey_idapikey
query Parameters
bbacctid
string

ID of big batch aggregation account

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/bigbatch' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "report": {
    }
}

Create a Big Batch Aggregation

Creates a Big Batch Aggregation Account

libmonetra KVS equivalent for endpoint

  • action_su = bigbatch_manage
  • bigbatch_manage = addacct
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
proc
required
string

Processor name as specified by 'Processor List' report under the proc column

descr
required
string <= 128 characters

Description of the big batch account

email
string <= 128 characters

Notification email for events like settlement

Responses

Request samples

Content type
application/json
{
  • "proc": "string",
  • "descr": "string",
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "bbacctid": "string"
}

Big Batch Merchants

Big batch merchant management

Delete a Big Batch Merchant

Delete a Big Batch Merchant

libmonetra KVS equivalent for endpoint

  • action_su = bigbatch_manage
  • bigbatch_manage = delmerch
Authorizations:
basic_authapikey_idapikey
path Parameters
bbmerchid
required
string

ID of big batch merchant

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/boarding/bigbatch/merchant/963789563' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Big Batch Merchant Details

Get the information for a big batch merchant

libmonetra KVS equivalent for endpoint

  • action_su = bigbatch_manage
  • bigbatch_manage = getmerch
Authorizations:
basic_authapikey_idapikey
path Parameters
bbmerchid
required
string

ID of big batch merchant

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/bigbatch/merchant/{bbmerchid}' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "indcode": "R",
  • "authtoken": "string",
  • "proc": "string",
  • "emv_entrymodes": "VISA_CONTACT|SVISA_CONTACTLESS|MC_CONTACT",
  • "emv_termcaps": "NOSIG",
  • "cardtypes": "VISA|MC",
  • "bbacctid": "string",
  • "descr": "string",
  • "property1": "string",
  • "property2": "string"
}

Edit a Big Batch Merchant

Edits a big batch merchant

If a bbacctid is specified it will move the merchant to a different big batch aggregation account.

libmonetra KVS equivalent for endpoint

  • action_su = bigbatch_manage
  • bigbatch_manage = editmerch
Authorizations:
basic_authapikey_idapikey
path Parameters
bbmerchid
required
string

ID of big batch merchant

Request Body schema: application/json
bbacctid
string\d+

ID of big batch aggregation account

proc
string

Processor name as specified by 'Processor List' report under the proc column

descr
string <= 128 characters

Description of the big batch account

cardtypes
string
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "BML" "GIFT" "VISADEBIT" "MCDEBIT" "OTHERDEBIT" "EBT" "CHECK" "INTERAC" "CUP" "PAYPALEC" "ACH"

Cardtypes

Pipe (|) separated.

Cardtype support is dependant on the processor. Not all processor support all cardtypes.

Flag values (pipe separated):

  • VISA - Visa credit
  • MC - Mastercard credit
  • AMEX - American Express credit
  • DISC - Discover credit
  • DINERS - Diners credit
  • JCB - JCB credit. Formerly Japan Credit Bureau
  • BML - Bill me later
  • GIFT - Private label Gift. Not cards backed by a credit card brand such as Visa, Mastercard, etc.
  • VISADEBIT - Visa debit
  • MCDEBIT - Mastercard debit
  • OTHERDEBIT - Debit not Visa or Mastercard
  • EBT - Electronic Benefits Transfer
  • CHECK - Paper checks
  • INTERAC - Interac (Canadian debit)
  • CUP - China Union Pay credit
  • PAYPALEC - PayPal Express Checkout token
  • ACH - Bank transfer
emv_entrymodes
string
Enum: "VISA_CONTACT" "VISA_CONTACTLESS" "MC_CONTACT" "MC_CONTACTLESS" "AMEX_CONTACT" "AMEX_CONTACTLESS" "DISC_CONTACT" "DISC_CONTACTLESS" "JCB_CONTACT" "JCB_CONTACTLESS" "INTERAC_CONTACT" "INTERAC_CONTACTLESS" "CUP_CONTACT" "CUP_CONTACTLESS" "USDEBIT_CONTACT" "USDEBIT_CONTACTLESS" "INTLDEBIT_CONTACT" "INTLDEBIT_CONTACTLESS"

EMV Interfaces specific cards types can use

Pipe (|) separated.

EMV Entry Mode support is dependant on the processor. Not all processor support all entry modes for all cardtypes

Flag values (pipe separated):

  • VISA_CONTACT - Visa credit contact interface
  • VISA_CONTACTLESS - Visa credit contactless interface
  • MC_CONTACT - Mastercard credit contact interface
  • MC_CONTACTLESS - Mastercard credit contactless interface
  • AMEX_CONTACT - American Express credit contact interface
  • AMEX_CONTACTLESS - American Express credit contactless interface
  • DISC_CONTACT - Discover credit contact interface
  • DISC_CONTACTLESS - Discover credit contactless interface
  • JCB_CONTACT - JCB credit contact interface
  • JCB_CONTACTLESS - JCB credit contactless interface
  • INTERAC_CONTACT - Interac (Canadian) debit contact interface
  • INTERAC_CONTACTLESS - Interac (Canadian) debit contactless interface
  • CUP_CONTACT - China Union Pay credit contact interface
  • CUP_CONTACTLESS - China Union Pay credit contactless interface
  • USDEBIT_CONTACT - United States debit contact interface
  • USDEBIT_CONTACTLESS - United States debit contactless interface
  • INTLDEBIT_CONTACT - International debit contact interface. Does not not include Interac.
  • INTLDEBIT_CONTACTLESS - International debit contactless interface. Does not not include Interac.
emv_termcaps
string
Enum: "NOSIG" "ONLINEPIN" "NOOFFLINEPIN" "CASHBACK" "PINBYPASSCREDIT" "PINBYPASSUSDEBIT"

Capabilities of the EMV terminal being used

These options should correspond to device certifications.

Flag values (pipe separated):

  • NOSIG - Don't request signature
  • ONLINEPIN - Device can accept online PIN verification
  • NOOFFLINEPIN - Don't request offline PIN verification
  • CASHBACK - Cashback is allowed
  • PINBYPASSCREDIT - Credit cards can bypass PIN entry
  • PINBYPASSUSDEBIT - US issued debit cards can bypass PIN entry. They will be run as credit instead.
resetauthtoken
string
Default: "no"
Enum: "yes" "no"

Values:

  • yes - Reset and return a new authentication token
  • no - Do not reset authentication token

Responses

Request samples

Content type
application/json
{
  • "bbacctid": "string",
  • "proc": "string",
  • "descr": "string",
  • "cardtypes": "VISA|MC",
  • "emv_entrymodes": "VISA_CONTACT|SVISA_CONTACTLESS|MC_CONTACT",
  • "emv_termcaps": "NOSIG",
  • "resetauthtoken": "yes"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "authtoken": "string"
}

List Big Batch Merchants

List big batch merchants

The resulting report will contain these headers:

bbacctid, bbmerchid, descr

libmonetra KVS equivalent for endpoint

  • action_su = bigbatch_manage
  • bigbatch_manage = listmerch
Authorizations:
basic_authapikey_idapikey
path Parameters
bbacctid
required
string

ID of big batch aggregation account

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/bigbatch/merchant' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "report": {
    }
}

Create a Big Batch Merchant

Add a new Big Batch Merchant

The configuration parameters proc, cardtypes, emv_entrymodes, emv_termcaps must match the settlement route that will settle into this big batch merchant account.

The bbmerchid and authtoken returned in the response will be used to link the settle route of the profile to the newly created Big Batch Merchant.

libmonetra KVS equivalent for endpoint

  • action_su = bigbatch_manage
  • bigbatch_manage = addmerch
Authorizations:
basic_authapikey_idapikey
path Parameters
bbacctid
required
string

ID of big batch aggregation account

Request Body schema: application/json
proc
required
string

Processor name as specified by 'Processor List' report under the proc column

descr
required
string <= 128 characters

Description of the big batch account

cardtypes
required
string
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "BML" "GIFT" "VISADEBIT" "MCDEBIT" "OTHERDEBIT" "EBT" "CHECK" "INTERAC" "CUP" "PAYPALEC" "ACH"

Cardtypes

Pipe (|) separated.

Cardtype support is dependant on the processor. Not all processor support all cardtypes.

Flag values (pipe separated):

  • VISA - Visa credit
  • MC - Mastercard credit
  • AMEX - American Express credit
  • DISC - Discover credit
  • DINERS - Diners credit
  • JCB - JCB credit. Formerly Japan Credit Bureau
  • BML - Bill me later
  • GIFT - Private label Gift. Not cards backed by a credit card brand such as Visa, Mastercard, etc.
  • VISADEBIT - Visa debit
  • MCDEBIT - Mastercard debit
  • OTHERDEBIT - Debit not Visa or Mastercard
  • EBT - Electronic Benefits Transfer
  • CHECK - Paper checks
  • INTERAC - Interac (Canadian debit)
  • CUP - China Union Pay credit
  • PAYPALEC - PayPal Express Checkout token
  • ACH - Bank transfer
emv_entrymodes
string
Enum: "VISA_CONTACT" "VISA_CONTACTLESS" "MC_CONTACT" "MC_CONTACTLESS" "AMEX_CONTACT" "AMEX_CONTACTLESS" "DISC_CONTACT" "DISC_CONTACTLESS" "JCB_CONTACT" "JCB_CONTACTLESS" "INTERAC_CONTACT" "INTERAC_CONTACTLESS" "CUP_CONTACT" "CUP_CONTACTLESS" "USDEBIT_CONTACT" "USDEBIT_CONTACTLESS" "INTLDEBIT_CONTACT" "INTLDEBIT_CONTACTLESS"

EMV Interfaces specific cards types can use

Pipe (|) separated.

EMV Entry Mode support is dependant on the processor. Not all processor support all entry modes for all cardtypes

Flag values (pipe separated):

  • VISA_CONTACT - Visa credit contact interface
  • VISA_CONTACTLESS - Visa credit contactless interface
  • MC_CONTACT - Mastercard credit contact interface
  • MC_CONTACTLESS - Mastercard credit contactless interface
  • AMEX_CONTACT - American Express credit contact interface
  • AMEX_CONTACTLESS - American Express credit contactless interface
  • DISC_CONTACT - Discover credit contact interface
  • DISC_CONTACTLESS - Discover credit contactless interface
  • JCB_CONTACT - JCB credit contact interface
  • JCB_CONTACTLESS - JCB credit contactless interface
  • INTERAC_CONTACT - Interac (Canadian) debit contact interface
  • INTERAC_CONTACTLESS - Interac (Canadian) debit contactless interface
  • CUP_CONTACT - China Union Pay credit contact interface
  • CUP_CONTACTLESS - China Union Pay credit contactless interface
  • USDEBIT_CONTACT - United States debit contact interface
  • USDEBIT_CONTACTLESS - United States debit contactless interface
  • INTLDEBIT_CONTACT - International debit contact interface. Does not not include Interac.
  • INTLDEBIT_CONTACTLESS - International debit contactless interface. Does not not include Interac.
emv_termcaps
string
Enum: "NOSIG" "ONLINEPIN" "NOOFFLINEPIN" "CASHBACK" "PINBYPASSCREDIT" "PINBYPASSUSDEBIT"

Capabilities of the EMV terminal being used

These options should correspond to device certifications.

Flag values (pipe separated):

  • NOSIG - Don't request signature
  • ONLINEPIN - Device can accept online PIN verification
  • NOOFFLINEPIN - Don't request offline PIN verification
  • CASHBACK - Cashback is allowed
  • PINBYPASSCREDIT - Credit cards can bypass PIN entry
  • PINBYPASSUSDEBIT - US issued debit cards can bypass PIN entry. They will be run as credit instead.

Responses

Request samples

Content type
application/json
{
  • "proc": "string",
  • "descr": "string",
  • "cardtypes": "VISA|MC",
  • "emv_entrymodes": "VISA_CONTACT|SVISA_CONTACTLESS|MC_CONTACT",
  • "emv_termcaps": "NOSIG"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "bbmerchid": "string",
  • "authtoken": "string"
}

Big Batch Batches

Big batch batch management

Clear a Big Batch Batch

Marks the batch as settled within Monetra without ever requesting funding

The transaction data in the batch is not sent to the processing institution. This should only be used if the processing institution has accepted the batch, but Monetra did not receive the response.

This must only be used after the processing institution has confirmed they've received the batch and they've instructed not sending it again.

WARNING: This function should be used with extreme caution as clearing a batch which the processing institution has not received will prevent funding of those transactions in the batch. It is imperative confirmation by the processor of funding will take place before using this action.

libmonetra KVS equivalent for endpoint

  • action_su = bigbatch
  • bigbatch = forcesettle
Authorizations:
basic_authapikey_idapikey
path Parameters
bbbatchid
required
string

Batch number for a batch in a big batch aggregation

Responses

Request samples 

curl -X POST 'https://testbox.monetra.com/api/v2/bigbatch/batch/99/settle/clear' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

List Big Batch Batches

List big batch batches

Lists batches for an aggregation.

The resulting report will contain these headers:

bbacctid, bbbatchid, state, settlets, num_trans, amount_trans,
num_level3, num_merchant_batches

libmonetra KVS equivalent for endpoint

  • action_su = bigbatch
  • bigbatch = list
Authorizations:
basic_authapikey_idapikey
path Parameters
bbacctid
required
string

ID of big batch aggregation account

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/bigbatch/batch' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "report": {
    }
}

List Big Batch Failed Transactions

List failed transactions in settled aggregation batches

Transactions that fail during settlement have different effects on the batch depending on whether the batch was transmitted with the online protocol or the Big Batch protocol. When a batch is settled using the online protocol, a failed transaction will cause the entire batch to be rejected. The merchant will then need to determine the cause of the failure (possibly by working with the processor) and correct the issue before attempting the settlement again. No money will move until the entire batch is correct and successfully submitted.

Big Batch settlement is different. When a batch is settled using the Big Batch protocol, the batch will be approved or rejected based on considerations other than transactions. If everything is correct with the submission, then the batch will be approved. At this point, if an individual transaction fails, then it will not affect anything else in the batch. That is, money will move for the transactions that were settled successfully, but no money will move for the failed transactions. If there are failed transactions in a Big Batch, then a merchant will need to determine the cause of the failure (possibly by working with the processor) and correct the issue, and then resettle those transactions.

This request can be used to determine which of the transactions in the settled batch failed. This request is only relevant for processors that return a settlement response indicating the status of individual transactions. Some processors provide external reports instead of providing the information back to Monetra as part of the settlement itself.

The resulting report will contain these headers:

bbacctid, bbmerchid, bbbatchid, batchnum, submit_ts, ttid, trantype,
cardtype, amount

libmonetra KVS equivalent for endpoint

  • action_su = bigbatch
  • bigbatch = listfailedtrans
Authorizations:
basic_authapikey_idapikey
query Parameters
bbacctid
string

ID of big batch aggregation account

bbmerchid
string

ID of big batch merchant

bbbatchid
string

Batch number for a batch in a big batch aggregation

batchnum
string

Merchant batch number

Requires:

  • bbmerchid

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/bigbatch/batch/failed' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "report": {
    }
}

List Big Batch Merchant Batches

List big batch merchant batches

List a merchant's batches that have settled into aggregation batches.

The resulting report will contain these headers:

bbmerchid, bbbatchid, batchnum, submit_ts, state, settlets, num_trans, amount_trans

libmonetra KVS equivalent for endpoint

  • action_su = bigbatch
  • bigbatch = listmerchbatches
Authorizations:
basic_authapikey_idapikey
path Parameters
bbmerchid
required
string

ID of big batch merchant

query Parameters
state
object
Enum: "OPEN" "CLOSED" "PENDING" "ATTEMPTED" "SETTLED" "FORCESETTLED"
Example: state=OPEN

Big batch batch state

Flag values (pipe separated):

  • OPEN - Merchant batches can be added to an aggregation batch. The batch is eligible for settlement.
  • CLOSED - Merchant batches can not be added to an aggregation batch. The batch is eligible for settlement.
  • PENDING - Settlement is in progress, and the batch is locked
  • ATTEMPTED - Batch upload was attempted, but there was a communication error. Must be manually resubmitted for settlement
  • SETTLED - Batch was settled successfully
  • FORCESETTLED - Batch was manually settled offline. Will not be funded.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/bigbatch/batch/merchant/567867897' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "report": {
    }
}

List Merchant Batches in an Aggregation Batch

List the big batch merchant batches that are in an aggregation batch

List all the merchant batches that have settled into the aggregation batch.

The resulting report will contain these headers:

bbmerchid, bbbatchid, batchnum, submit_ts, state, settlets, num_trans, amount_trans

libmonetra KVS equivalent for endpoint

  • action_su = bigbatch
  • bigbatch = listmerchbatches
Authorizations:
basic_authapikey_idapikey
path Parameters
bbbatchid
required
string

Batch number for a batch in a big batch aggregation

query Parameters
state
object
Enum: "OPEN" "CLOSED" "PENDING" "ATTEMPTED" "SETTLED" "FORCESETTLED"
Example: state=OPEN

Big batch batch state

Flag values (pipe separated):

  • OPEN - Merchant batches can be added to an aggregation batch. The batch is eligible for settlement.
  • CLOSED - Merchant batches can not be added to an aggregation batch. The batch is eligible for settlement.
  • PENDING - Settlement is in progress, and the batch is locked
  • ATTEMPTED - Batch upload was attempted, but there was a communication error. Must be manually resubmitted for settlement
  • SETTLED - Batch was settled successfully
  • FORCESETTLED - Batch was manually settled offline. Will not be funded.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/bigbatch/batch/67' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "report": {
    }
}

Remove Merchant Batch From an Aggregation Batch

Remove a merchant batch from an aggregation

Remove a big batch merchant's batch from the aggregate big batch. This does not delete any transactions or from the profile that is associated with the big batch merchant. The profile could unsettled and settle the batch into the big batch aggregation again.

libmonetra KVS equivalent for endpoint

  • action_su = bigbatch
  • bigbatch = purgemerchbatch
Authorizations:
basic_authapikey_idapikey
path Parameters
bbacctid
required
string

ID of big batch aggregation account

bbmerchid
required
string

ID of big batch merchant

bbbatchid
required
string

Batch number for a batch in a big batch aggregation

batch
required
string

The batch number associated with the transaction

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/bigbatch/56789/batch/7/merchant/6789865578/batch/19' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Request a Big Batch Batch Status

Request status of the batch from the processor. The batch is not settled. This should be used to determine the status of a batch that has already been settled.

libmonetra KVS equivalent for endpoint

  • action_su = bigbatch_settle
  • rfr = yes
Authorizations:
basic_authapikey_idapikey
path Parameters
bbbatchid
required
string

Batch number for a batch in a big batch aggregation

Responses

Request samples 

curl -X POST 'https://testbox.monetra.com/api/v2/bigbatch/batch/201/settle/rfr' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS"
}

Settle a Big Batch Batch

Send an aggregated Big Batch online for settlement with the processor

libmonetra KVS equivalent for endpoint

  • action_su = bigbatch_settle
Authorizations:
basic_authapikey_idapikey
path Parameters
bbbatchid
required
string

Batch number for a batch in a big batch aggregation

Request Body schema: application/json
resubmit
string
Default: "no"
Enum: "yes" "no"

Values:

  • yes - Batch is being resubmitted for settlement. This will override processor duplicate batch checking
  • no - Batch is not a resubmission

Responses

Request samples

Content type
application/json
{
  • "resubmit": "yes"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS"
}

P2PE BDK

Base Derivation Key (BDK) can be though of as the master decryption key for encrypted account data coming from a payment terminal.

When using P2PE a BDK needs to be created by Monetra which is then shared with a Key Injection Facility (KIF). The KIF typically sells payment terminals or can accept ones sent to them. They load the device with a device specific key based on the BDK. Only the BDK can decrypt data loaded with a derived device key.

When the device encrypts account data, it first creates a session key using it's device key. The data is sent to Monetra with some metadata who, using the BDK, can derive the device and session key in order to decrypt the account data.

It is imperative the BDK is protected!

A BDK can be exported because it must be shared with a KIF in order to allow devices to encrypt account data. The Export of BDKs from the system uses RSA public key encryption. However, many KIFs do not support receiving the BDK in this manner. Typically they require splitting and dual control of the BDK. Follow the instructions of the KIF on how they require receiving the BDK.

Deactivate a BDK

Deactivates a Base Derivation Key

Note: Dual authentication is required for this operation. See the "Dual Authentication" section for details on how to send the second user's authentication information.

Once deactivated no devices injected with an encryption key base don the BDK will be able to process transactions. The payment server will no longer be able to decrypt transaction data that is encrypted once the BDK is deactivated.

Once deactivated the BDK cannot be reactivated.

libmonetra KVS equivalent for endpoint

  • action_su = p2pe_bdk_deactivate
Authorizations:
basic_authdual_control
path Parameters
id
required
string

BDK id

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/p2pe/bdk/124435' --basic -u 'test_retail:publ1ct3st' -H 'X-MFA-CODE: 123456' -H 'X-DUAL-Authorization: Basic YWRtaW4yOlMzY1IzdCE=' -H 'X-DUAL-MFA-CODE: 987654'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Edit BDK

Edit a BDK metadata

libmonetra KVS equivalent for endpoint

  • action_su = p2pe_bdk_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

BDK id

Request Body schema: application/json
descr
required
string

Description of the BDK and it's use

For example:

  • test vs production key
  • Name of KIF the key is being shared with
  • If the key should be only used for a specific customer

Responses

Request samples

Content type
application/json
{
  • "descr": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Export a BDK

Export a Base Derivation Key

Note: Dual authentication is required for this operation. See the "Dual Authentication" section for details on how to send the second user's authentication information.

libmonetra KVS equivalent for endpoint

  • action_su = p2pe_bdk_export
Authorizations:
basic_authdual_control
path Parameters
id
required
string

BDK id

Request Body schema: application/json
rsapublickey
required
string

RSA public key

Responses

Request samples

Content type
application/json
{
  • "rsapublickey": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "key": "string"
}

List BDKs

List BDKs

The resulting report will contain these headers:

keyid, ksid, keytype, is_hsm, flags, provision_allowed, num_devices, descr

libmonetra KVS equivalent for endpoint

  • action_su = p2pe_bdk_list
Authorizations:
basic_authapikey_idapikey

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/p2pe/bdk' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Generate BDK

Generate a new BDK suitable for sharing with a key injection facility

Note: Dual authentication is required for this operation. See the "Dual Authentication" section for details on how to send the second user's authentication information.

libmonetra KVS equivalent for endpoint

  • action_su = p2pe_bdk_generate
  • keytype = dukptext
Authorizations:
basic_authdual_control
Request Body schema: application/json
flags
string
Enum: "NOAUTOPROVISION" "LOCKTOPROFILE" "AUTODISABLE" "TRACKEVENTS"

Pipe (|) separated list of flags that describe how devices should be treated

Flag values (pipe separated):

  • NOAUTOPROVISION - Do not autoprovison devices. They must be provisioned manually
  • LOCKTOPROFILE - Lock the device to the profile it was provised (manually or automatically) so that it cannot be used with any other profile
  • AUTODISABLE - Automatically disable devices that are not working properly. For example, if a device sends an e_id with clear account data
  • TRACKEVENTS - Track detailed device events. Required for validated P2PE
descr
string

Description of the BDK and it's use

For example:

  • test vs production key
  • Name of KIF the key is being shared with
  • If the key should be only used for a specific customer

Responses

Request samples

Content type
application/json
{
  • "flags": "NOAUTOPROVISION",
  • "descr": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Get BDK Key Check Value

Gets the key check value for a BDK

Used for verification of a BDK when sharing with an external party

libmonetra KVS equivalent for endpoint

  • action_su = p2pe_bdk_kcv
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

BDK id or a KSN from a device which will be used to reference the associated BDK

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/p2pe/bdk/124435/kcv' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "kcv": "string"
}

Print a BDK as Key Components

Export a BDK by printing to a printer attached to an HSM

Only BDKs stored within an HSM can be printed. The HSM must support printing and the printer must be connected to the HSM.

Note: Dual authentication is required for this operation. See the "Dual Authentication" section for details on how to send the second user's authentication information.

libmonetra KVS equivalent for endpoint

  • action_su = p2pe_bdk_print
Authorizations:
basic_authdual_control
path Parameters
id
required
string

BDK id

Request Body schema: application/json
hsm_serialnum
required
string

Serial number of HSM to send the request to

flags
string
Enum: "KSIDFMT1" "KSIDFMT2"

Flags controlling printer behavior

Flag values (pipe separated):

  • KSIDFMT1 - Format 1
  • KSIDFMT2 - Format 2

Responses

Request samples

Content type
application/json
{
  • "hsm_serialnum": "string",
  • "flags": "KSIDFMT1"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

P2PE Devices

It is recommended that all physical payment terminals encrypt account data and do not output clear data when possible. This reduces exposure of account data and provides more security around its handling.

Validated and non-validated P2PE

There are two type of P2PE, validated and non-validated. At the core level of encrypting card data, these are the same. Both use the same encryption standard and handle the device in the same way.

With one caveat on the device. Validated P2PE requires Secure Reading and Exchange (SRED) devices. The PCI council defines what qualifies as SRED. While SRED is a requirement for Validated P2PE, SRED devices can still be used in a non-validated environment. Further Device vendors will disclose whether a device is SRED or not and many only produce SRED devices.

While the underlying technology is the same for Validated and non-validated there are business requirements for Validated P2PE. For example, devices need to be inspected quarterly and logged. The "Add Device Event Note" action handles this.

To qualify as Validated P2PE the environment must be audited by a PCI auditor capable of certifying Validated P2PE solutions. Even though Monetra provides all the core technology for Validated P2PE, the entire solution must be audited. Additionally, there are aspects outside of Monetra that a validated P2PE solution needs to utilize. Monetra only provides one aspect of the system.

Get Device Events

Get logged device events

The resulting report will contain these headers:

ksn, serial_num, ts, type, notes, monetra_username, approval_user

libmonetra KVS equivalent for endpoint

  • action_admin = p2pe
  • p2pe = listevents
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string

Device id

serial_num
string

Device serial number

bdate
string

Start of date range

edate
string

End of date range

type
object
Enum: "PROVISION" "ACTIVATED" "DIS_ACTIVITY" "DIS_COMPROMISE" "DIS_OTHER" "ENABLED" "INSPECTION" "NOTES" "SOFTWARECHANGE" "DECOMMISSION"
Example: type=PROVISION

Pipe (|) separated list of flags that describe type of P2PE events

Flag values (pipe separated):

  • PROVISION - Device was provisioned
  • ACTIVATED - Device was activated
  • DIS_ACTIVITY - Device disabled due to suspicious activity
  • DIS_COMPROMISE - Device disabled due to compromised
  • DIS_OTHER - Device disabled for other reason
  • ENABLED - Device enabled
  • INSPECTION - Device inspected
  • NOTES - Notes added/changed
  • SOFTWARECHANGE - Device software changed. Typically due to upgraded firmware version
  • DECOMMISSION - Device decommissioned

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/p2pe/device/event' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Device Event Note

Add a device event with a note about the event

Device ID (KSN) or serial number can be used to reference the device.

libmonetra KVS equivalent for endpoint

  • action_admin = p2pe
  • p2pe = addeventnote
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
id
string

Device id

serial_num
string

Device serial number

type
string
Default: "note"
Enum: "note" "quarterly_inspection"

Type of note being added

Values:

  • note - Generic note
  • quarterly_inspection - Quarterly inspection
notes
required
string <= 1024 characters

General free-form information

approval_user
string

Person approving the operation

Free form and is typically a username or person's name

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "serial_num": "string",
  • "type": "note",
  • "notes": "string",
  • "approval_user": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Deactivate a Device

Deactivates a device

Once deactivated the device can no longer be used.

This is different than disabling a device. Disable is temporary and deactivate is permanent. A device should be deactivated if it is taken out of service and will never be used again. For example, it is damaged and inoperable or found to be tampered.

libmonetra KVS equivalent for endpoint

  • action_su = p2pe_device_deactivate
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Device id

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/p2pe/device/5678765' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Edit device

Edit a device metadata

libmonetra KVS equivalent for endpoint

  • action_su = p2pe_device_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Device id

Request Body schema: application/json
descr
required
string <= 128 characters

description

Responses

Request samples

Content type
application/json
{
  • "descr": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Disable Device

Disable a device

Disabled devices can be re-enabled at a later time.

Device ID (KSN) or serial number can be used to reference the device.

libmonetra KVS equivalent for endpoint

  • action_admin = p2pe
  • p2pe = disabledevice
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
id
string

Device id

serial_num
string

Device serial number

reason
string
Default: "other"
Enum: "other" "possible_compromise"

Reason device is disabled

Values:

  • other - Generic reason
  • possible_compromise - Device was possibly compromised
notes
string <= 1024 characters

General free-form information

approval_user
string

Person approving the operation

Free form and is typically a username or person's name

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "serial_num": "string",
  • "reason": "other",
  • "notes": "string",
  • "approval_user": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Enable Device

Enable a device

Enable a device that was previously disabled.

Device ID (KSN) or serial number can be used to reference the device.

libmonetra KVS equivalent for endpoint

  • action_admin = p2pe
  • p2pe = enabledevice
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
id
string

Device id

serial_num
string

Device serial number

notes
string <= 1024 characters

General free-form information

approval_user
string

Person approving the operation

Free form and is typically a username or person's name

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "serial_num": "string",
  • "notes": "string",
  • "approval_user": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

List All P2PE Devices

List All P2PE devices

Lists all devices for the system.

The resulting report will contain these headers:

id, keytype, is_hsm, flags, devicetype, serial_num, descr, create_ts, last_ts,
last_username, is_disabled, consec_failures, device_manuf, device_model,
device_manuf_sn, device_app, device_appver, device_kernver

libmonetra KVS equivalent for endpoint

  • action_su = p2pe_device_list
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Limit search to the specified profile id

id
string

P2PE key id

serial_num
string

Device serial number

bdate
string

Start of date range

edate
string

End of date range

last_used_ts
string

Key last used before the specified time as a timestamp

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/p2pe/device/all' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

List P2PE Devices

List P2PE devices

The resulting report will contain these headers:

id, keytype, is_hsm, flags, devicetype, serial_num, descr, create_ts, last_ts,
last_username, is_disabled, consec_failures, device_manuf, device_model,
device_manuf_sn, device_app, device_appver, device_kernver

libmonetra KVS equivalent for endpoint

  • action_admin = p2pe
  • p2pe = list
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string

P2PE key id

serial_num
string

Device serial number

bdate
string

Start of date range

edate
string

End of date range

last_used_ts
string

Key last used before the specified time as a timestamp

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/p2pe/device' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Provision a Device

Provision a device

Typically used with validated P2PE devices which must be provisioned in the system before they can be used.

Provisioning a P2PE device before use is one requirement of validated P2PE. Validated P2PE requirements are complex and outside the scope of this operation.

If a BDK was created with the NOAUTOPROVISION flag, this operation must be used before a device can process transactions.

libmonetra KVS equivalent for endpoint

  • action_su = p2pe_device_provision
  • id = P2PE
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

notes
required
string

For device logging, this may be provisioning notes

serial_num
required
string

Device serial number

approval_user
string

Person approving the operation

Free form and is typically a username or person's name

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "notes": "string",
  • "serial_num": "string",
  • "approval_user": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

E2EE Keys

E2EE keys are different than P2PE used by payment terminals. E2EE is for encryption outside of a device. Whereas P2PE relates to encryption of data coming out of a device.

The two main uses of E2EE key management is standin and transaction export key generation. These are used to secure sensitive account data, but they are not used by a payment terminal. Rather they are used by software.

List Standin Keys

List standin keys

The resulting report will contain these headers:

id, keytype, is_hsm, flags, devicetype, serial_num, descr, create_ts, last_ts,
last_username, profile_id, is_disabled, consec_failures, device_manuf,
device_model, device_manuf_sn, device_app, device_appver, device_kernver

libmonetra KVS equivalent for endpoint

  • action_su = e2ee_key_list
  • keytype = RSA-AES
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Limit search to the specified profile id

id
string

Standin key id

serial_num
string

Device serial number

bdate
string

Start of date range

edate
string

End of date range

last_used_ts
string

Key last used before the specified time as a timestamp

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/e2ee/key/standin' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Generate Standin Encryption Key

Generate a new standin encryption key

Standin keys are used for encrypting data that will be standin approved and the transaction data stored for a period of time.

When the payment server is offline an application can choose whether it wants to approve the transaction standin and upload the transaction data when the payment server is accessible at some point in the future.

Standin authorizations can be declined by the issuer when uploaded to the payment server. The merchant is taking a risk when standin authorizing and may not receive funds for the transaction. There is little a merchant can do in this case as they've accepted liability for receiving declines when standin transactions are sent for authorization at a later time.

There are a number of profile flags that control the desired behavior of how an integrating application handles standin authorizations. These flags should be evaluated as a means to reduce risk to the merchant.

It's also advised that policies are put in place surrounding eligibility for standin authorizations. Such as but not limited to:

  • Length of time standin authorizations will be accepted without being able to reach the payment server
  • Transaction amount
  • Total amount standin approved that is pending upload

Also, certain types of transactions are ineligible for standin authorization. For example, several EMV card responses indicate standin should not be performed for the transaction.

When approving the application will generate an AES-256 encryption key. This local key will be used to encrypt call transaction data. The AES key will then be encrypted using the standin key returned by the payment server.

All sensitive KVS will have the value encrypted. The data will be base64 encoded. The key will be prefixed with e_. For example, renamed to e_<KEY NAME>. Keys that already start with e_ must be encrypted and an additional e_ prefixed. You will have e_e_<KEY NAME> in this situation. Wrapped keys are required for the payment server to know which keys need to be decrypted.

And e_id parameter needs to be sent with the request and will take the form: CARDSHIELD|<STANDIN KEY ID>|<ENCRYPTED AES KEY DATA BASE64 ENCODED>.

Example flow:

  • Generate standin key
    • Key ID and RSA Public key will be returned
  • When standin authorizing
    • Generate AES-256 encryption key
    • Take sensitive data (values) that needs to be stored and encrypt with the AES-256 key
    • Prefix all keys that have values encrypted with the AES key with e_ even if it already has e_ prefixed
    • Send e_id parameter with encryption information

Example transaction data:

  • Data
    • account = "5...5"
    • expdate = "1229"
    • amount = "100.00"
  • Standin stored data
    • e_account = "Gtahjge/2daga="
    • e_expdate = "yUGeuyhjage678agea"
    • amount = "100.00"
    • e_id = "CARDSHIELD|12456789|F675DGEwese=="

Standin keys should be generated on a regular basis. Keys are only valid for 2 weeks. It's advisable to generate a new key every week. It's not recommended to standin authorize transactions for longer than a week while not being able to uploaded any to the payment server.

libmonetra KVS equivalent for endpoint

  • action_admin = standinkey_generate
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string",
  • "key": "string"
}

Generate Transaction Export Key

Create a RSA key for transaction import

The payment receiving a transaction will generate the transaction encryption key. A key id and RSA public key will be returned. These will be provided to the payment server that will be exporting transactions and be set in the profile's txn_export_key parameter. The value will take the form <ID>|<PUBLIC KEY> as returned by this operation.

libmonetra KVS equivalent for endpoint

  • action_su = e2ee_key_generate
  • keytype = RSA
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string",
  • "key": "string"
}

Licensing

Licensing

Deactivate Software Product

Deactivates a software product registered with the system

libmonetra KVS equivalent for endpoint

  • action_su = product_license
  • product_license = deactivate
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

ID of software product

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/system/licensing/software/12543' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Linked Software Count

Gets the count of linked software products

libmonetra KVS equivalent for endpoint

  • action_su = product_license
  • product_license = count
Authorizations:
basic_authapikey_idapikey

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/licensing/software/count' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "uniterm_count": "string",
  • "uniterm_hold": "string",
  • "uniterm_limit": "string",
  • "admin_count": "string",
  • "admin_hold": "string",
  • "admin_limit": "string",
  • "client_count": "string",
  • "client_hold": "string",
  • "client_limit": "string"
}

Get Linked Software List

Gets a list of linked software products registered with the system

Applies to a single profile.

The resulting report will contain these headers:

id, product, active, producttype, serialnum, last_access_ts, last_access_username

libmonetra KVS equivalent for endpoint

  • action_su = product_license
  • product_license = list
Authorizations:
basic_authapikey_idapikey
query Parameters
license_active
string
product
object
Enum: "uniterm" "admin" "client"
Example: product=uniterm

Software product

Values:

  • uniterm - UniTerm
  • admin - Administrator GUI
  • client - Client GUI
bdate
string

Start of date range

edate
string

End of date range

id
string

ID of software product

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/licensing/software' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Get System License Information

Gets information about the software license

Can only be called by a user in the top level group. Users in any sub-group cannot access this information.

libmonetra KVS equivalent for endpoint

  • action_sys = info
  • info = licinfo
Authorizations:
basic_authapikey_idapikey

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/licensing' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "admincount": "string",
  • "annual_trans_limit": "string",
  • "cardshielddevices": "string",
  • "clientcount": "string",
  • "compname": "string",
  • "flags": "string",
  • "license_id": "string",
  • "licensecount": "string",
  • "max_version": "string",
  • "merchant_restrictions": "string",
  • "num_profiles": "string",
  • "os": "string",
  • "partner_id": "string",
  • "required_modules": "string",
  • "unitermcount": "string"
}

P2PE Device Count Per Profile

List P2PE Key count per profile

The resulting report will contain these headers:

profile_id, p2pe_devices, nonp2pe_devices

libmonetra KVS equivalent for endpoint

  • action_su = product_license
  • product_license = p2pe_profile_count
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Limit search to the specified profile id

bdate
string

Start of date range

edate
string

End of date range

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/licensing/p2pe/count/profile' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

P2PE Key Count

Gets the count of P2PE Keys

libmonetra KVS equivalent for endpoint

  • action_su = product_license
  • product_license = p2pe_count
Authorizations:
basic_authapikey_idapikey

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/licensing/p2pe/count' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "p2pe_count": "string",
  • "p2pe_hold": "string",
  • "p2pe_limit": "string"
}

Deactivate SkyLink Device

Deactivates a SkyLink device

When deactivated the license seat used by that device will be immediately available for use by another installation.

libmonetra KVS equivalent for endpoint

  • action_sys = skylink_manage
  • skylink_manage = deactivate
Authorizations:
basic_authapikey_idapikey
path Parameters
device_id
required
string

ID of registered SkyLink device

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/system/licensing/skylink/12543' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get SkyLink Device List

Gets a list devices registered for SkyLink

The resulting report will contain these headers:

device_id, active, deactivated_ts, last_used_user, last_used_ts, version, name,
manuf, model, os, osver, deactivation_cnt

libmonetra KVS equivalent for endpoint

  • action_sys = skylink_manage
  • skylink_manage = list
Authorizations:
basic_authapikey_idapikey
query Parameters
show_deactivated
object
Enum: "yes" "no"
Example: show_deactivated=yes

Show deactivated devices

Values:

  • yes - Include deactived devices
  • no - Do not include deactived devices

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/licensing/skylink' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Get SkyLink Limit

Get the current number SkyLink instances used with a profile

libmonetra KVS equivalent for endpoint

  • action_sys = skylink_manage
  • skylink_manage = getlimit
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/licensing/skylink/limit' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "limit": "string"
}

Set SkyLink Limit

Set the maximum number of SkyLink instances that can be used with a profile

libmonetra KVS equivalent for endpoint

  • action_sys = skylink_manage
  • skylink_manage = setlimit
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

limit
required
string\d+

Maximum number of SkyLink devices

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "limit": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get SkyLink Max Limit During Time Period

Gets the highest limit set across a period of time

Will show results for all profiles visible to the caller

The resulting report will contain these headers:

profile_id, limit

libmonetra KVS equivalent for endpoint

  • action_sys = skylink_manage
  • skylink_manage = limitmax
Authorizations:
basic_authapikey_idapikey
query Parameters
bdate
string

Start of date range

edate
string

End of date range

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/licensing/skylink/limit/max' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Get SkyLink Set Limit History

Get history of limit changes for SkyLink

Applies to a single profile.

The resulting report will contain these headers:

ts, is_current, limit, request_user

libmonetra KVS equivalent for endpoint

  • action_sys = skylink_manage
  • skylink_manage = limithistory
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

show_deactivated
object
Enum: "yes" "no"
Example: show_deactivated=yes

Show deactivated devices

Values:

  • yes - Include deactived devices
  • no - Do not include deactived devices

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/licensing/skylink/limit/history' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

System

System operations

Get Allowed Actions

Get allowed actions

Monetra may have license restrictions in place limiting what actions can be used with Monetra. This provides a list of all actions that can be performed.

If a type is ALL then there is no restriction in place for that action type.

A user will still need permissions to use allowed actions.

libmonetra KVS equivalent for endpoint

  • action_sys = info
  • info = trantypes
Authorizations:
basic_authapikey_idapikey

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/actions' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "sys": "string",
  • "admin": "string",
  • "trans": "string"
}

Get Mainance Level

Gets Current Maintenance Level

libmonetra KVS equivalent for endpoint

  • action_sys = info
  • info = maintenance
Authorizations:
basic_authapikey_idapikey

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/maintenance' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "response": "string",
  • "maintenance": "NONE"
}

Set Maintenance Level

Set the system maintains level

Restrict Monetra actions that can be performed during maintenance operations. Typically used during upgrades to block transactions that could not process during that time.

libmonetra KVS equivalent for endpoint

  • action_su = maintenance
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
level
required
string
Enum: "NONE" "LIMITED" "STRICT"

Values:

  • NONE - Open up everything for processing. No restrictions.
  • LIMITED - Disable add/edit/delete group/profile/route/user requests and settlement requests but allows standard transactions
  • STRICT - Disallow any requests besides Set Maintenance Level, Import Database, and Export Database

Responses

Request samples

Content type
application/json
{
  • "level": "NONE"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Software Versions

Get software versions

Monetra is comprised of the product itself as well as many modules that perform different actions. This report lists the version of Monetra as well as all product modules.

The resulting report will contain these headers:

name, displayname, type, version

libmonetra KVS equivalent for endpoint

  • action_sys = info
  • info = versions
Authorizations:
basic_authapikey_idapikey

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/versions ' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Get Supported Country Codes

Get available country codes

The resulting report will contain these headers:

name, iso_alpha3, iso_numeric, iana

libmonetra KVS equivalent for endpoint

  • action_sys = info
  • info = countrycodes
Authorizations:
basic_authapikey_idapikey

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/countrycodes' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Get Supported Currency Codes

Get available currency codes

The resulting report will contain these headers:

name, iso_alpha, iso_numeric, exponent

libmonetra KVS equivalent for endpoint

  • action_sys = info
  • info = currencycodes
Authorizations:
basic_authapikey_idapikey

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/currencycodes' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Get Supported Timezones

Get available timezones

Timezones are used when configuring profiles. This will retrieve a list of all timezones supported by Monetra that can be used when configuring a profile.

The resulting report will contain these headers:

timezone

libmonetra KVS equivalent for endpoint

  • action_sys = info
  • info = timezones
Authorizations:
basic_authapikey_idapikey

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/timezones' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Logging

Logging

Retrieve a Log Buffer

Retrieve an in-memory log buffer

This stops and retrieves an in-memory log buffer that was started. The buffer can only be retrieved once.

libmonetra KVS equivalent for endpoint

  • action_sys = setlogging
  • setlogging = getbuffer
Authorizations:
basic_authapikey_idapikey
path Parameters
bufferid
required
string

ID of a log buffer

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/logging/buffer/6789876567' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "buffer": "string"
}

Set System Log Level

Set the current log output levels

This overrides the log levels that were set in main.conf at startup. The changes persist until shutdown (or until this action is run again).

NonPCI compliant log levels cannot be enabled.

libmonetra KVS equivalent for endpoint

  • action_sys = setlogging
  • setlogging = level
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
debug
required
string
Enum: "INIT" "CONF" "WARN" "INFO" "TRAN" "TRAN_DETAIL" "TRAN_TRACE" "CONN" "PROC" "PROC_DETAIL" "PROC_TRACE" "TRACE_IN" "TRACE_OUT" "SQL" "ERROR" "CRIT" "DEBUG" "DEV" "SQLDEV"

Log levels

Log levels can be PCI and nonPCI complained. PCI compliant levels are sanitized and will not output information considered sensitive by PCI. This includes data such as account numbers.

nonPCI compliant levels can output sensitive data. They are typically used for limited debugging purposes. nonPCI levels cannot be written to disk. They can only be used in conjunction with buffered, in memory, logging.

Those tagged as Rstrct will not output sensitive data, but is restricted none-the-less.

Values:

  • INIT - PCI - Basic initialization info, such as Monetra version
  • CONF - PCI - Show configuration and startup details
  • WARN - PCI - Warnings such as misconfiguration, etc.
  • INFO - PCI - Uncategorized short information (like stats maybe)
  • TRAN - PCI - Basic information on when a transaction enters the queue and is finished
  • TRAN_DETAIL - PCI - Basic incoming parameters as parsed (with sensitive data removed), same for outgoing response parameters. Probably will imply INFO.
  • TRAN_TRACE - NonPCI - Parsed incoming transaction requests unobscured, same with outgoing responses
  • CONN - PCI - Log connection details such as IP address, when it is opened, closed, etc.
  • PROC - PCI - Log connection info to processors and details when they process a transaction
  • PROC_DETAIL - PCI - Log more detailed, sanitized, information such as the sanitized traces.
  • PROC_TRACE - NonPCI - Non-sanitized version of PROC_DETAIL, just prints ASCII representation of protocol. Not as useful as TRACE_OUT for binary protocols.
  • TRACE_IN - NonPCI - Raw trace of data in and out from client connections
  • TRACE_OUT - NonPCI - Raw trace of data between Monetra and the processors
  • SQL - Rstrct - SQL Statements
  • ERROR - PCI - Any significant error condition
  • CRIT - PCI - A critical/significant error which must not be ignored as it will severely affect the running system
  • DEBUG - NonPCI - Ungrouped Debug data, very verbose
  • DEV - NonPCI - Very verbose debug information in place for development of new features. These should not exist in a production release.
  • SQLDEV - NonPCI - Formatted SQL messages with placeholders replaced with data. Developer-level debugging information.

Responses

Request samples

Content type
application/json
{
  • "debug": "INIT"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Start Buffered Logging

Capture log to an in-memory buffer

The only way to read a log with levels that are out of PCI compliance is by using an in-memory buffer. This allows for temporary logging without changing the log levels written to disk.

Buffers are only available for a maximum of 10 minutes.

libmonetra KVS equivalent for endpoint

  • action_sys = setlogging
  • bufferid = yes
  • setlogging = buffer
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
debug
required
string
Enum: "INIT" "CONF" "WARN" "INFO" "TRAN" "TRAN_DETAIL" "TRAN_TRACE" "CONN" "PROC" "PROC_DETAIL" "PROC_TRACE" "TRACE_IN" "TRACE_OUT" "SQL" "ERROR" "CRIT" "DEBUG" "DEV" "SQLDEV"

Log levels

Log levels can be PCI and nonPCI complained. PCI compliant levels are sanitized and will not output information considered sensitive by PCI. This includes data such as account numbers.

nonPCI compliant levels can output sensitive data. They are typically used for limited debugging purposes. nonPCI levels cannot be written to disk. They can only be used in conjunction with buffered, in memory, logging.

Those tagged as Rstrct will not output sensitive data, but is restricted none-the-less.

Values:

  • INIT - PCI - Basic initialization info, such as Monetra version
  • CONF - PCI - Show configuration and startup details
  • WARN - PCI - Warnings such as misconfiguration, etc.
  • INFO - PCI - Uncategorized short information (like stats maybe)
  • TRAN - PCI - Basic information on when a transaction enters the queue and is finished
  • TRAN_DETAIL - PCI - Basic incoming parameters as parsed (with sensitive data removed), same for outgoing response parameters. Probably will imply INFO.
  • TRAN_TRACE - NonPCI - Parsed incoming transaction requests unobscured, same with outgoing responses
  • CONN - PCI - Log connection details such as IP address, when it is opened, closed, etc.
  • PROC - PCI - Log connection info to processors and details when they process a transaction
  • PROC_DETAIL - PCI - Log more detailed, sanitized, information such as the sanitized traces.
  • PROC_TRACE - NonPCI - Non-sanitized version of PROC_DETAIL, just prints ASCII representation of protocol. Not as useful as TRACE_OUT for binary protocols.
  • TRACE_IN - NonPCI - Raw trace of data in and out from client connections
  • TRACE_OUT - NonPCI - Raw trace of data between Monetra and the processors
  • SQL - Rstrct - SQL Statements
  • ERROR - PCI - Any significant error condition
  • CRIT - PCI - A critical/significant error which must not be ignored as it will severely affect the running system
  • DEBUG - NonPCI - Ungrouped Debug data, very verbose
  • DEV - NonPCI - Very verbose debug information in place for development of new features. These should not exist in a production release.
  • SQLDEV - NonPCI - Formatted SQL messages with placeholders replaced with data. Developer-level debugging information.
buffer_size
string

Maximum size of the buffer, in bytes (default 1 MB)

filter_user
string

Restricts the log to capture activity for only the specified username

Responses

Request samples

Content type
application/json
{
  • "debug": "INIT",
  • "buffer_size": "string",
  • "filter_user": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "bufferid": "string"
}

System Scheduler

System scheduler operations

Create Automated Account Updater

The Account Updater subsystem allows merchants to retrieve updated card numbers and expiration dates for customer accounts (whether due to a card being lost or stolen, or simply a new card being issued).

Account updater must be configured on the payment server in order to work. An agreement with a supported account updater service is required. Further, the ACCOUNT_UPDATER group flag must be enabled. Tokens owned by the group will be eligible for update.

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = add
  • type = account_updater
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*

Responses

Request samples

Content type
application/json
{
  • "sched": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Create Automated Big Batch History Purge

Purges historical Big Batch data from the database for all Big Batch Users

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = add
  • type = purgebbhist
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Create Automated Big Batch Settlement

Automatic big batch settlement

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = add
  • type = bigbatchsettle
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
bbacctid
required
string\d+

ID of big batch aggregation account

sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*

Responses

Request samples

Content type
application/json
{
  • "bbacctid": "string",
  • "sched": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Create Automated Canceled Order Purge

Deletes orders that have been canceled for longer than the configured time

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = add
  • type = ordercancelpurge
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Create Automated Completed Order Purge

Deletes orders that have been completed and are older than the configured time

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = add
  • type = ordercompletepurge
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Create Automated Deleted Expired Tokens

Purge tokens with expired cards

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = add
  • type = purgeexpired
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_months
string\d+

Represents the number of months after a card has expired that it should be kept on file

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_months": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Create Automated Deleted Product Purge

Purge deleted products

When products are deleted the product record is retained in order to facilitate restoring the product in case it was deleted by accident.

Purges deleted products that were deleted after the configured time span.

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = add
  • type = productpurge
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Create Automated Historic Token Account Data Purge

Purge historic token account data

Account update retains the previous account information when a token is updated in case the old account information needs to be restored. For example, a bad update of a card number from the update service. The previous account number is saved and can be restored to the token.

Purge any previous account data for tokens that have been updated. Tokens are not deleted, only historic account data for tokens.

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = add
  • type = purge_account_updater
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Create Automated History Purge

Clear failed, voided, and settled transactions from the history

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = add
  • type = purgehist
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Create Automated Open Order Purge

Deletes orders that have been open for longer than the configured time

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = add
  • type = orderopenpurge
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Create Automated Order Synchronization History Purge

Deletes historic orders synchronization records for longer than the configured time

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = add
  • type = ordersyncpurge
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Create Automated Pending Order Purge

Deletes orders that have been pending for longer than the configured time

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = add
  • type = orderpendingpurge
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Create Automated Secure Account Data

Clear sensitive data from the transaction history

This will remove PCI-protected data like account information from the transaction history while keeping the record intact.

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = add
  • type = securehist
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Create Automated Settlement

Automatic batch settlement

Settle batches in the open or closed state automatically.

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = add
  • type = settle
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "sched": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Create Automated Uncaptured Transaction Purge

Purges all uncaptured transactions

Preauthorizations and purchases which were sent with capture=no that haven't been completed after keep_days.

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = add
  • type = purgeuncaptured
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Delete a Scheduled Task

Delete a scheduled task

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

ID of scheduled task

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/system/schedule/567865678' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Edit Automated Account Updater

Edit an account update scheduled task

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

ID of scheduled task

Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*

Responses

Request samples

Content type
application/json
{
  • "sched": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Edit Automated Big Batch History Purge

Edit a purge of historic transaction data scheduled task

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

ID of scheduled task

Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Edit Automated Big Batch Settlement

Edit a big batch settlement scheduled task

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

ID of scheduled task

Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*

Responses

Request samples

Content type
application/json
{
  • "sched": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Edit Automated Canceled Order Purge

Edit a canceld order purge scheduled task

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

ID of scheduled task

Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Edit Automated Completed Order Purge

Edit a completed order purge scheduled task

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

ID of scheduled task

Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Edit Automated Deleted Expired Tokens

Edit a purge of expired tokens scheduled task

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

ID of scheduled task

Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_months
string\d+

Represents the number of months after a card has expired that it should be kept on file

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_months": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Edit Automated Deleted Product Purge

Edit a deleted product purge scheduled task

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

ID of scheduled task

Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Edit Automated Historic Token Account Data Purge

Edit a historic token account data purge scheduled task

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

ID of scheduled task

Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Edit Automated History Purge

Edit a purge of transaction history scheduled task

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

ID of scheduled task

Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Edit Automated Open Order Purge

Edit an open order purge scheduled task

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

ID of scheduled task

Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Edit Automated Order Synchronization History Purge

Edit an order synchronization history purge scheduled task

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

ID of scheduled task

Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Edit Automated Pending Order Purge

Edit a pending order purge scheduled task

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

ID of scheduled task

Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Edit Automated Secure Account Data

Edit a clearing of sensitive transaction data scheduled task

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

ID of scheduled task

Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Edit Automated Settlement

Edit a settlement scheduled task

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

ID of scheduled task

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "sched": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Edit Automated Uncaptured Transaction Purge

Edit a purge of uncaptured transactions scheduled task

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

ID of scheduled task

Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "string",
  • "keep_days": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

List Scheduled Tasks

List scheduled tasks

The resulting report will contain these headers:

id, type, profile_id, sched, last_ts, next_ts, keep_days

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = list
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/schedule' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Run an Automated Task

Runs an automated task immediately

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = run_task
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

ID of scheduled task

Responses

Request samples 

curl -X PATCH 'https://testbox.monetra.com/api/v2/system/schedule/567865678/run' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

System Statistics

System statistics operations

Get Account Updater Statistics

Get statistics for account updater

The resulting report will contain these headers:

user, group_id, update_count

libmonetra KVS equivalent for endpoint

  • action_sys = profile_stats
  • profile_stats = accountupdater
Authorizations:
basic_authapikey_idapikey
query Parameters
bdate
required
string

Start of date range

edate
required
string

End of date range

group_id
string

Group identifier

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/stats/account_updater' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Get Order Statistics

Get statistics for orders

The resulting report will contain these headers:

profile_id, quickorder_count, order_count, invoice_count

libmonetra KVS equivalent for endpoint

  • action_sys = profile_stats
  • profile_stats = orders
Authorizations:
basic_authapikey_idapikey
query Parameters
bdate
string

Start of date range

edate
string

End of date range

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/stats/orders' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Get Profile Statistics

Get statistics for profiles

The resulting report will contain these headers:

profile_id, totaltransNum, totaltransAmount, totalAuthNum, totalAuthAmount,
totalReturnNum, totalReturnAmount

libmonetra KVS equivalent for endpoint

  • action_sys = profile_stats
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
required
string

Profile ID for statics

bdate
string

Start of date range

edate
string

End of date range

totalsonly
object
Enum: "yes" "no"
Example: totalsonly=yes

Only include totals

Values:

  • yes - Only include totals
  • no - Include details

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/stats/profile' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Data Import / Export

System data import and export operations

Database Export

Export data from the database

Exporting data is normally used when upgrading the payment server to a new version that has a different DB schema. It is also used when moving the payment server to a different system and upgrading at the payment server at the same time.

Data export can take a long time depending on how much data is in the DB. Export stages can be specified to export data in chunks that can be imported in chunks. This can reduce downtime by allowing stages with larger amount of data to be imported later.

Historic data is typically the largest stage and is not needed for transaction processing. Importing stages 1 and 2 will allow transactions to start processing on the new system while the rest of the data is being brought over.

If stages is not provides a full export will take place.

See the "Set Maintenance Level" operation which is used with the export process.

libmonetra KVS equivalent for endpoint

  • action_su = importexport
  • importexport = export
Authorizations:
basic_authapikey_idapikey
query Parameters
file
required
string

Import / Export file path

File path to the file that holds the exported database data. On import this is the path where the file should be located and named. On export this is the exported datat that should be loaded later.

This is a full file path including filename. The file is located on the system running the payment server. It cannot be on the user's system. This is a local to the payment server process.

If moving servers the export file must be transfered to the new system running the payment server.

stages
string

Export stages

Can be a single numeric value that specifies the stage. Or a range of stages. E.g. stages=1, or stages=2-3.

Stages:

  • 1 Groups / profiles / user accounts
  • 2 P2PE / E2EE keys and devices
  • 3 Secure stored data (tokens, recurring, etc)
  • 4 Non-historic data (unsettled transactions, etc)
  • 5 Historic data (settled batches, failed transactions, etc)
hsm_cardshield_export
object
Enum: "yes" "no"
Example: hsm_cardshield_export=yes

Export HSM protected keys

Indicates whether or not to export keys from an HSM (if an HSM is in use) rather than keeping them as HSM protected keys.

Default is no if not specified. This should only be used if exporting data in order to remove the use of an HSM.

Values:

  • yes - Export HSM protected keys
  • no - Do not export HSM protected keys

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/database?file=/tmp/db.import' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "key": "string"
}

Database Import

Import data from an export file into the database

The database must be empty for a full import. Merging data into a database with existing data is not supported. You must start with an empty DB before starting the import process.

A partial import when using multiple export stages must have the import happen in the stage order. For example, stage 4 cannot be imported before stage 3.

libmonetra KVS equivalent for endpoint

  • action_su = importexport
  • importexport = import
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
file
required
string

Import / Export file path

File path to the file that holds the exported database data. On import this is the path where the file should be located and named. On export this is the exported datat that should be loaded later.

This is a full file path including filename. The file is located on the system running the payment server. It cannot be on the user's system. This is a local to the payment server process.

If moving servers the export file must be transfered to the new system running the payment server.

key
required
string[A-Z0-9]+

Encryption key protecting exported DB data

The key is a hex encoded string. It will be generated by the payment server during export and must be provided during the import.

A unique key is generated per export. If staged export is used, each stage will have a different encryption key.

Responses

Request samples

Content type
application/json
{
  • "file": "string",
  • "key": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Transaction Export

Export the record of a specified transaction

Exporting/importing transaction data is used to facilitate the concept of an "overhead authorization system", meaning one system authorizes a transaction that a different store will settle. This section details the steps needed to transfer the transaction data from one payment server instance to another.

Consider this example: A company has one website and multiple physical stores. There is a payment server instance running for the website's Ecommerce shopping cart as well as one for each of the stores. A customer can place an order through the website that will be fulfilled by one of the stores. The Ecommerce instance of the payment server will handle the actual authorization, but the fulfilling store needs the transaction details for bookkeeping purposes. In this example, the Ecommerce payment server instance would carry out the sale and then encrypt and export the unsettled transaction data. It would then send that data to the store fulfilling the order, which would import and decrypt the data. At this point, the physical store would have the record of the sale as if it had authorized the transaction itself. If the transaction was captured, it will be added to the open batch and settled at this store.

The transaction data will be returned encrypted. Continuing with the example above, the physical stores would each create a RSA public/private key pair. This is done either internally by provisioning an E2EE RSA key pair or if managed externally, by creating an RSA key pair manually. If done internally, then the private key will be securely stored in Monetra. If done externally, then the path to the private key will need to be set in txn_import_key in main.conf. In both cases, the public key will be sent to the Ecommerce instance, which will then add it to the associated profile in the txn_export_key configuration parameter.

libmonetra KVS equivalent for endpoint

  • action_admin = tran_export
  • txnexport = encrypted
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

Responses

Request samples 

curl -X POST 'https://testbox.monetra.com/api/v2/system/transaction/{ttid}' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "txnexportdata": "string"
}

Transaction Import

Import a transaction from a previously-exported packet

This will generate a new ttid that is specific to the destination account The import will assign a different ttid within this importing payment server than the ttid from the exporting payment server.

libmonetra KVS equivalent for endpoint

  • action_admin = tran_import
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
txndata
required
string

Base64-encoded export data packet, as obtained from a Transaction Export

Responses

Request samples

Content type
application/json
{
  • "txndata": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "ttid": "string"
}