logo
API docs by Redocly

Monetra (2.3.2)

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

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

Parameters

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

Empty vs not Present

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

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

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

$0.00 Amounts

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

Extra Parameters

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

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

Examples

Payload Samples

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

cURL

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

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

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.

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.

Bin Ranges

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

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

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

Multiple ranges are joined together with semicolons (;).

Format Req Spec Description
min_prefix Y N Minimum prefix that the account number must start with
max_prefix O NS Maximum prefix that the account number can start with. Must be the same number of digits as min_prefix.
min_len O N Minimum number of digits the account number must have
max_len O NS Maximum number of digits the account number can have
cardtype O A Card type to match
pclevel O N Card level to match. Note that the range is from 0 to 2.

Example ranges:

Range Meaning
30 Match all accounts that start with 30
30-33 Match all accounts that start with a value between 30 and 33
30-33:15 Match all accounts that start with a value between 30 and 33 and are exactly 15 digits long
30-33:15-18 Match all accounts that start with a value between 30 and 33 and are between 15 and 18 digits long
30-33:15-18:DISC Match only Discover cards that start with a value between 30 and 33 and are between 15 and 18 digits long
0-9::VISA:2 Match only Visa Purchase cards
4;30-33:15-18:DISC Match any account that starts with 4 and Discover cards that start with a value between 30 and 33 and are between 15 and 18 digits long
0-9::VISA:2;0-9::MC:2 Match only Visa and Mastercard Purchase cards

Interchange Rates

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

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

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

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

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

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

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

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

Transactions

Transaction operations

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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

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*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "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": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "account": "XXXXXXXXXXXX1234",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "ttid": "96748596765467"
}

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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

Transaction identifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

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": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "account": "XXXXXXXXXXXX1234",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "ttid": "96748596765467"
}

Balance

Balance inquiry

Applies to:

  • Credit
  • Debit
  • Gift

libmonetra KVS equivalent for endpoint

  • action_trans = balanceinq
Authorizations:
basic_auth(apikey_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
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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    },
  • "verification": {
    },
  • "tokenize": "no",
  • "matching_token": "yes",
  • "rcpt": "yes",
  • "rcpt_user_notes": "Review your order at http://..."
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "account": "XXXXXXXXXXXX1234",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "balance": "12.00",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "token": "6789656783904467894"
}

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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

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 in seconds 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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "priority": "normal",
  • "timeout": "30",
  • "rcpt": "yes",
  • "rcpt_user_notes": "Review your order at http://...",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "account": "XXXXXXXXXXXX1234",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "ttid": "96748596765467"
}

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 instead.

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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

property name*
additional property
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "authamount": "6.50",
  • "balance": "12.00",
  • "account": "XXXXXXXXXXXX1234",
  • "cof_authamount": "19.22",
  • "cof_transid": "930734056218579",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "token": "6789656783904467894",
  • "carddenylist_id": "67898765",
  • "ttid": "96748596765467"
}

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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

property name*
additional property
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "authamount": "6.50",
  • "balance": "12.00",
  • "account": "XXXXXXXXXXXX1234",
  • "cof_authamount": "19.22",
  • "cof_transid": "930734056218579",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "token": "6789656783904467894",
  • "carddenylist_id": "67898765",
  • "ttid": "96748596765467"
}

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_auth(apikey_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.

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": "78965743785967",
  • "account_data": {
    },
  • "tokenize": "no",
  • "matching_token": "yes"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "account": "XXXXXXXXXXXX1234",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "token": "6789656783904467894"
}

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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "amount": "19.92",
  • "tax": "1.29",
  • "nsf": "yes",
  • "lodging": {
    },
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "rcpt": "yes",
  • "rcpt_user_notes": "Review your order at http://...",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "authamount": "6.50",
  • "balance": "12.00",
  • "account": "XXXXXXXXXXXX1234",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "ttid": "96748596765467"
}

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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

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 in seconds 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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "shipping": {
    },
  • "zip": "32606",
  • "lodging": {
    },
  • "lane": {
    },
  • "money": {
    },
  • "order": {
    },
  • "priority": "normal",
  • "timeout": "30",
  • "tokenize": "no",
  • "matching_token": "yes",
  • "rcpt": "yes",
  • "rcpt_user_notes": "Review your order at http://...",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "account": "XXXXXXXXXXXX1234",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "batch": "47",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "authamount": "6.50",
  • "cof_authamount": "19.22",
  • "cof_transid": "930734056218579",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "token": "6789656783904467894",
  • "ttid": "96748596765467"
}

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 instead.

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_auth(apikey_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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

property name*
additional property
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "authamount": "6.50",
  • "balance": "12.00",
  • "account": "XXXXXXXXXXXX1234",
  • "cof_authamount": "19.22",
  • "cof_transid": "930734056218579",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "token": "6789656783904467894",
  • "ttid": "96748596765467"
}

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_auth(apikey_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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

property name*
additional property
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "authamount": "6.50",
  • "balance": "12.00",
  • "account": "XXXXXXXXXXXX1234",
  • "cof_authamount": "19.22",
  • "cof_transid": "930734056218579",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "token": "6789656783904467894",
  • "carddenylist_id": "67898765",
  • "ttid": "96748596765467"
}

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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

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

expdate
string = 4 characters (0[1-9]|1[1-2])\d{2}

Expiration date of the card (MMYY format)

Optional and typically unnecessary to send. The expiration date will be loaded from the refereed ttid and thus does not need to be specified.

There are some instances where a different expiration date than what was recorded with the original authorization needs to be specified. Specifically, when the card has expired between the time of the authorization and the refund.

For example, card expires on 12/2021. An authorization was made 11/2021. Then the customers return the item 1/2022 necessitating a refund. The refund would fail due to the card being expired. However, the customer since received a new card with a new expiration date but retained the same card number. The new expdate would need to be specified here in order to perform the refund.

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 in seconds 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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "money": {
    },
  • "order": {
    },
  • "pin_data": {
    },
  • "expdate": "0129",
  • "recurring_data": {
    },
  • "priority": "normal",
  • "timeout": "30",
  • "tokenize": "no",
  • "matching_token": "yes",
  • "rcpt": "yes",
  • "rcpt_user_notes": "Review your order at http://...",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "authamount": "6.50",
  • "balance": "12.00",
  • "account": "XXXXXXXXXXXX1234",
  • "cof_authamount": "19.22",
  • "cof_transid": "930734056218579",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "token": "6789656783904467894",
  • "ttid": "96748596765467"
}

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_auth(apikey_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 in seconds 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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

ttid
string

Identifier for transaction to refund

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    },
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "money": {
    },
  • "order": {
    },
  • "pin_data": {
    },
  • "recurring_data": {
    },
  • "priority": "normal",
  • "timeout": "30",
  • "tokenize": "no",
  • "matching_token": "yes",
  • "rcpt": "yes",
  • "rcpt_user_notes": "Review your order at http://...",
  • "ttid": "96748596765467",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "authamount": "6.50",
  • "balance": "12.00",
  • "account": "XXXXXXXXXXXX1234",
  • "cof_authamount": "19.22",
  • "cof_transid": "930734056218579",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "token": "6789656783904467894",
  • "ttid": "96748596765467"
}

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_auth(apikey_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*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    },
  • "verification": {
    },
  • "tokenize": "no",
  • "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": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "account": "XXXXXXXXXXXX1234",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "token": "6789656783904467894",
  • "carddenylist_id": "67898765"
}

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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

Transaction identifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

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": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "account": "XXXXXXXXXXXX1234",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "ttid": "96748596765467"
}

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_auth(apikey_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.

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

Merchant descriptor parameters

object

Merchant lane parameters

object

Order detail parameters

object

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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    },
  • "pin": "AE86DE23D2276C3B",
  • "cv": "123",
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "order": {
    },
  • "processing_options": {
    },
  • "amount": "19.92",
  • "nsf": "yes",
  • "rcpt": "yes",
  • "rcpt_user_notes": "Review your order at http://..."
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "draft_locator_id": "24FDBDD0902",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "authamount": "6.50",
  • "balance": "12.00",
  • "account": "XXXXXXXXXXXX1234",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "ttid": "96748596765467"
}

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_auth(apikey_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.

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

Merchant descriptor parameters

object

Merchant lane parameters

object

Order detail 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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    },
  • "pin": "AE86DE23D2276C3B",
  • "cv": "123",
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "order": {
    },
  • "processing_options": {
    },
  • "rcpt": "yes",
  • "rcpt_user_notes": "Review your order at http://..."
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "draft_locator_id": "24FDBDD0902",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "authamount": "6.50",
  • "balance": "12.00",
  • "account": "XXXXXXXXXXXX1234",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "ttid": "96748596765467"
}

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_auth(apikey_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.

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

Merchant descriptor parameters

object

Merchant lane parameters

object

Order detail 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
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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    },
  • "pin": "AE86DE23D2276C3B",
  • "cv": "123",
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "order": {
    },
  • "processing_options": {
    },
  • "amount": "19.92",
  • "nsf": "yes",
  • "rcpt": "yes",
  • "rcpt_user_notes": "Review your order at http://..."
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "draft_locator_id": "24FDBDD0902",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "authamount": "6.50",
  • "balance": "12.00",
  • "account": "XXXXXXXXXXXX1234",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "ttid": "96748596765467"
}

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_auth(apikey_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 in seconds 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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    },
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "money": {
    },
  • "order": {
    },
  • "priority": "normal",
  • "timeout": "30",
  • "rcpt": "yes",
  • "rcpt_user_notes": "Review your order at http://...",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "draft_locator_id": "24FDBDD0902",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "authamount": "6.50",
  • "balance": "12.00",
  • "account": "XXXXXXXXXXXX1234",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "ttid": "96748596765467"
}

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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

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 in seconds 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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "money": {
    },
  • "order": {
    },
  • "priority": "normal",
  • "timeout": "30",
  • "rcpt": "yes",
  • "rcpt_user_notes": "Review your order at http://...",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "draft_locator_id": "24FDBDD0902",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "authamount": "6.50",
  • "balance": "12.00",
  • "account": "XXXXXXXXXXXX1234",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "ttid": "96748596765467"
}

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_auth(apikey_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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    },
  • "pin_data": {
    },
  • "rcpt": "yes",
  • "rcpt_user_notes": "Review your order at http://...",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "draft_locator_id": "24FDBDD0902",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "account": "XXXXXXXXXXXX1234",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "balance": "12.00",
  • "timestamp": "2022-05-24 15:06:13 -0400"
}

EBT Cash Purchase

Debit funds from a Cash account

libmonetra KVS equivalent for endpoint

  • action_trans = ebtcbsale
Authorizations:
basic_auth(apikey_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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

property name*
additional property
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "draft_locator_id": "24FDBDD0902",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "authamount": "6.50",
  • "balance": "12.00",
  • "account": "XXXXXXXXXXXX1234",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "carddenylist_id": "67898765",
  • "ttid": "96748596765467"
}

EBT Food Balance

Get the balance on a Food account

libmonetra KVS equivalent for endpoint

  • action_trans = ebtfsbalance
Authorizations:
basic_auth(apikey_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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    },
  • "pin_data": {
    },
  • "rcpt": "yes",
  • "rcpt_user_notes": "Review your order at http://...",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "draft_locator_id": "24FDBDD0902",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "account": "XXXXXXXXXXXX1234",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "balance": "12.00",
  • "timestamp": "2022-05-24 15:06:13 -0400"
}

EBT Food Purchase

Debit funds from a Food account

libmonetra KVS equivalent for endpoint

  • action_trans = ebtfssale
Authorizations:
basic_auth(apikey_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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

property name*
additional property
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "draft_locator_id": "24FDBDD0902",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "authamount": "6.50",
  • "balance": "12.00",
  • "account": "XXXXXXXXXXXX1234",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "carddenylist_id": "67898765",
  • "ttid": "96748596765467"
}

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_auth(apikey_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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

property name*
additional property
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "draft_locator_id": "24FDBDD0902",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "authamount": "6.50",
  • "balance": "12.00",
  • "account": "XXXXXXXXXXXX1234",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "carddenylist_id": "67898765",
  • "ttid": "96748596765467"
}

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_auth(apikey_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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    },
  • "verification": {
    },
  • "shipping": {
    },
  • "health": {
    },
  • "lodging": {
    },
  • "merchant_descriptors": {
    },
  • "money": {
    },
  • "order": {
    },
  • "lane": {
    },
  • "processing_options": {
    },
  • "tokenize": "no",
  • "matching_token": "yes",
  • "rcpt": "yes",
  • "rcpt_user_notes": "Review your order at http://...",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "draft_locator_id": "24FDBDD0902",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "cardtype": "VISA",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "ttid": "96748596765467"
}

Check Conversion With Guarantee

Convert a check with a guarantee on funds

libmonetra KVS equivalent for endpoint

  • action_trans = checkconvguar
Authorizations:
basic_auth(apikey_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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    },
  • "verification": {
    },
  • "shipping": {
    },
  • "health": {
    },
  • "lodging": {
    },
  • "merchant_descriptors": {
    },
  • "money": {
    },
  • "order": {
    },
  • "lane": {
    },
  • "processing_options": {
    },
  • "tokenize": "no",
  • "matching_token": "yes",
  • "rcpt": "yes",
  • "rcpt_user_notes": "Review your order at http://...",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "draft_locator_id": "24FDBDD0902",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "cardtype": "VISA",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "ttid": "96748596765467"
}

Check Conversion With Override

Convert a check with override

This overrides a previous failure.

libmonetra KVS equivalent for endpoint

  • action_trans = checkconvover
Authorizations:
basic_auth(apikey_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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    },
  • "verification": {
    },
  • "shipping": {
    },
  • "health": {
    },
  • "lodging": {
    },
  • "merchant_descriptors": {
    },
  • "money": {
    },
  • "order": {
    },
  • "lane": {
    },
  • "processing_options": {
    },
  • "tokenize": "no",
  • "matching_token": "yes",
  • "rcpt": "yes",
  • "rcpt_user_notes": "Review your order at http://...",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "draft_locator_id": "24FDBDD0902",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "cardtype": "VISA",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "ttid": "96748596765467"
}

Check Conversion With Verification

Convert a check with verification

libmonetra KVS equivalent for endpoint

  • action_trans = checkconvonly
Authorizations:
basic_auth(apikey_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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    },
  • "verification": {
    },
  • "shipping": {
    },
  • "health": {
    },
  • "lodging": {
    },
  • "merchant_descriptors": {
    },
  • "money": {
    },
  • "order": {
    },
  • "lane": {
    },
  • "processing_options": {
    },
  • "tokenize": "no",
  • "matching_token": "yes",
  • "rcpt": "yes",
  • "rcpt_user_notes": "Review your order at http://...",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "draft_locator_id": "24FDBDD0902",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "cardtype": "VISA",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "ttid": "96748596765467"
}

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_auth(apikey_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.
rcpt_user_notes
string

Arbitrary user-specified notes to include in the cust_notes and merch_notes receipt sections. Saved for reprints.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    },
  • "lane": {
    },
  • "processing_options": {
    },
  • "rcpt": "yes",
  • "rcpt_user_notes": "Review your order at http://...",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "draft_locator_id": "24FDBDD0902",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "cardtype": "VISA",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "ttid": "96748596765467"
}

Alternate Payment Methods

Handle alternative payment methods

Some payment methods require a unique multipart flow which requires user interaction outside of a standard payment request.

For example, PayPal Express Checkout requires the merchant to initalize a payment request, then direct the customer to PayPal where they can authorize the request. At which point the merchant can perform a purchase or preauth if the merchant has authorized the charge to take place.

Initialize PayPal Express Checkout

Start a PayPal Express Checkout payment

Express Checkout allows one time purchases as well as setting up optional "billing agreements". A billing agreement is a long term use token associated with the customer's account which can be stored for later transactions. It is equivalent to tokenizing a credit card. A merchant wishing to use billing agreements should prompt the customer before initiating the altpaymentinit action whether they want to create one or not. The customer is not given a choice on the PayPal authorization page and not all customers will want to start a billing agreement.

Billing Agreements can be tokenized by Monetra using the tokenize=yes parameter with purchases or preauth. One time use tokens cannot be tokenized. In which case the agreement is stored in the account vault and a Monetra token is returned. This token is used the same as any other token.

Note, the customer can at any time go into their PayPal account and revoke any previously authorized billing agreements.

Processing Flow

With PayPal Express Checkout, one of three flows will be utilized.

One time payment:

  1. Perform altpaymentinit action which will generate a one time use token for subsequent operations
  2. Direct the customer to PayPal providing the token returned by altpaymentinit. The customer customer will approve charge
  3. Perform purchase / preauth using the one time use token

Generate billing agreement token:

  1. Perform altpaymentinit action which will generate a one time use token for subsequent operations. This will include the flag stating a billing agreement is being requited by the merchant
  2. Direct the customer to PayPal providing the token returned by altpaymentinit. The customer customer will approve setting up a billing agreement as part of the transaction
  3. Perform purchase / preauth using the one time use token. A billing agreement token will be generated that can be stored for later transactions

Use already existing generated billing agreement token:

  1. Perform purchase/ preauth using the billing agreement token

Directing the customer to PayPal for Authorization

The customer will be sent to the following URL with the one time use token returned by altpaymentinit passed in the URL as the '' parameter.

https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=<ONE_TIME_USE_TOKEN>

Upon authorizing or declining, the customer's browser will be redirected to either the returnurl or cancelurl that was provided in the altpaymentinit request. The redirect should be back to the merchant's web site and the redirect will provide the merchant with the one time use token that triggered the redirect. The merchant will know whether the customer has approved or declined the request based on the response from PayPal. At which point the merchant will know if they should move forward with the purchase or preauth step.

Using One Time Use and Billing Agreement Tokens with Purchase and Preauth

When using an Express Checkout token with purchase or preauth it is passed in the account field. It needs to be formatting in the following way.

  • One time use token from altpaymentinit = 'PAYPAL|TOKEN|'. E.g. "PAYPAL|TOKEN|EC-9R462081MR2007401".
  • Billing agreement from a previous transaction = 'PAYPAL|AGREEMENT|'. E.g. "PAYPAL|AGREEMENT|B-78C87045GR954054G".

libmonetra KVS equivalent for endpoint

  • action_trans = altpaymentinit
  • altpaymentinit = paypal
Authorizations:
basic_auth(apikey_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.

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.

returnurl
required
string

URL to the merchant's website the alternate payment method should redirect the customer to once they've completed the alternate method steps

cancelurl
required
string

URL to the merchant's website the alternate payment method should redirect the customer to if they cancel the alternate method process

ordernum
string <= 128 characters [0-9a-zA-Z]+

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.

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.

email
string

Customer's email

logoimg
string

URL to merchant logo that should be shown

brandname
string

Company brand name to show

billingagreement
string
Default: "no"
Enum: "yes" "no"

Wether to generate a billing agreement with the customer

Values:

  • yes - Initialize requesting a billing agreement with the customer
  • no - Do not request a billing agreement with the customer
billingagreementdescr
string

Description of billing agreement to show to customer

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "amount": "19.92",
  • "returnurl": "https://url",
  • "cancelurl": "https://url",
  • "ordernum": "A13DDES345",
  • "email": "customer@email",
  • "logoimg": "https://url",
  • "brandname": "string",
  • "billingagreement": "no",
  • "billingagreementdescr": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "draft_locator_id": "24FDBDD0902",
  • "altpmtid": "EC-9R462081MR2007401"
}

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_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

Cannot be combined with:

  • ttid
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: ttid=96748596765467

Transaction identifier

Cannot be combined with:

  • order_id
payment_id
string
Example: payment_id=987653645678

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": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "account": "XXXXXXXXXXXX1234",
  • "abaroute": "267084131",
  • "checknum": "45678",
  • "accounttype": "PERSONAL|CHECKING",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "cof_transid": "930734056218579",
  • "cof_authamount": "19.22",
  • "installment_num": "17",
  • "installment_total": "149",
  • "recurring": "recurring",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "shipcountry": "840",
  • "shipzip": "32789",
  • "zip": "32606",
  • "action": "SALE",
  • "orig_code": "AUTH",
  • "orig_msoft_code": "INT_SUCCESS",
  • "orig_phard_code": "SUCCESS",
  • "orig_reqamount": "155.34",
  • "orig_verbiage": "Transaction approved",
  • "merch_name": "Pizza Palace",
  • "merch_addr1": "777 77th Ct",
  • "merch_addr2": "Jacksonville FL",
  • "merch_addr3": "32789",
  • "merch_phone": "555-555-5555",
  • "merch_email": "merchant@email",
  • "merch_url": "https://url",
  • "merch_proc": "loopback",
  • "custref": "55",
  • "ordernum": "A13DDES345",
  • "amount": "19.92",
  • "cashbackamount": "20.00",
  • "currency": "124",
  • "examount": "0.33",
  • "surchargeamount": "1.25",
  • "tax": "1.29",
  • "discountamount": "100.00",
  • "dutyamount": "5.07",
  • "freightamount": "225.82",
  • "bdate": "-6 months",
  • "edate": "now",
  • "excharges": "GIFT|MINI",
  • "rate": "12.00",
  • "roomnum": "5143",
  • "descmerch": "Pizza Palace LLC",
  • "descloc": "Store CA 543",
  • "clerkid": "Doe-1553",
  • "stationid": "7",
  • "laneid": "4",
  • "comments": "Extra beef",
  • "divisionnum": "PAYROLL",
  • "expdate": "0129",
  • "healthcare": "no",
  • "reversible": "yes",
  • "reversal_reason": "CLERKVOID",
  • "offline_decline": "...",
  • "tranflags": "CAPTURED|ONLINE|SENSITIVEDATA",
  • "txnstatus": "COMPLETE|ONLINE|SENSITIVEDATA",
  • "last_modified_ts": "1653422816",
  • "order_id": "58445676543",
  • "payment_id": "987653645678",
  • "order_cash_discount": "12.37",
  • "order_cash_price": "142.97",
  • "order_noncash_price": "155.34",
  • "order_tip": "0.50",
  • "order_total": "155.34",
  • "order_tax": "2.44",
  • "order_discount": "5.22",
  • "detail_order_notes": "Extra pickles",
  • "trans": "...",
  • "line_items": "...",
  • "ttid": "96748596765467",
  • "draft_locator_id": "24FDBDD0902",
  • "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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

Transaction identifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

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": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "account": "XXXXXXXXXXXX1234",
  • "abaroute": "267084131",
  • "checknum": "45678",
  • "accounttype": "PERSONAL|CHECKING",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "cof_transid": "930734056218579",
  • "cof_authamount": "19.22",
  • "installment_num": "17",
  • "installment_total": "149",
  • "recurring": "recurring",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "shipcountry": "840",
  • "shipzip": "32789",
  • "zip": "32606",
  • "action": "SALE",
  • "orig_code": "AUTH",
  • "orig_msoft_code": "INT_SUCCESS",
  • "orig_phard_code": "SUCCESS",
  • "orig_reqamount": "155.34",
  • "orig_verbiage": "Transaction approved",
  • "merch_name": "Pizza Palace",
  • "merch_addr1": "777 77th Ct",
  • "merch_addr2": "Jacksonville FL",
  • "merch_addr3": "32789",
  • "merch_phone": "555-555-5555",
  • "merch_email": "merchant@email",
  • "merch_url": "https://url",
  • "merch_proc": "loopback",
  • "custref": "55",
  • "ordernum": "A13DDES345",
  • "amount": "19.92",
  • "cashbackamount": "20.00",
  • "currency": "124",
  • "examount": "0.33",
  • "surchargeamount": "1.25",
  • "tax": "1.29",
  • "discountamount": "100.00",
  • "dutyamount": "5.07",
  • "freightamount": "225.82",
  • "bdate": "-6 months",
  • "edate": "now",
  • "excharges": "GIFT|MINI",
  • "rate": "12.00",
  • "roomnum": "5143",
  • "descmerch": "Pizza Palace LLC",
  • "descloc": "Store CA 543",
  • "clerkid": "Doe-1553",
  • "stationid": "7",
  • "laneid": "4",
  • "comments": "Extra beef",
  • "divisionnum": "PAYROLL",
  • "expdate": "0129",
  • "healthcare": "no",
  • "reversible": "yes",
  • "reversal_reason": "CLERKVOID",
  • "offline_decline": "...",
  • "tranflags": "CAPTURED|ONLINE|SENSITIVEDATA",
  • "txnstatus": "COMPLETE|ONLINE|SENSITIVEDATA",
  • "last_modified_ts": "1653422816",
  • "order_id": "58445676543",
  • "payment_id": "987653645678",
  • "order_cash_discount": "12.37",
  • "order_cash_price": "142.97",
  • "order_noncash_price": "155.34",
  • "order_tip": "0.50",
  • "order_total": "155.34",
  • "order_tax": "2.44",
  • "order_discount": "5.22",
  • "detail_order_notes": "Extra pickles",
  • "trans": "...",
  • "line_items": "...",
  • "ttid": "96748596765467",
  • "draft_locator_id": "24FDBDD0902",
  • "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_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

payment_id
required
string
Example: 987653645678

Unique ID of a payment for an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

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": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "account": "XXXXXXXXXXXX1234",
  • "abaroute": "267084131",
  • "checknum": "45678",
  • "accounttype": "PERSONAL|CHECKING",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "cof_transid": "930734056218579",
  • "cof_authamount": "19.22",
  • "installment_num": "17",
  • "installment_total": "149",
  • "recurring": "recurring",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "shipcountry": "840",
  • "shipzip": "32789",
  • "zip": "32606",
  • "action": "SALE",
  • "orig_code": "AUTH",
  • "orig_msoft_code": "INT_SUCCESS",
  • "orig_phard_code": "SUCCESS",
  • "orig_reqamount": "155.34",
  • "orig_verbiage": "Transaction approved",
  • "merch_name": "Pizza Palace",
  • "merch_addr1": "777 77th Ct",
  • "merch_addr2": "Jacksonville FL",
  • "merch_addr3": "32789",
  • "merch_phone": "555-555-5555",
  • "merch_email": "merchant@email",
  • "merch_url": "https://url",
  • "merch_proc": "loopback",
  • "custref": "55",
  • "ordernum": "A13DDES345",
  • "amount": "19.92",
  • "cashbackamount": "20.00",
  • "currency": "124",
  • "examount": "0.33",
  • "surchargeamount": "1.25",
  • "tax": "1.29",
  • "discountamount": "100.00",
  • "dutyamount": "5.07",
  • "freightamount": "225.82",
  • "bdate": "-6 months",
  • "edate": "now",
  • "excharges": "GIFT|MINI",
  • "rate": "12.00",
  • "roomnum": "5143",
  • "descmerch": "Pizza Palace LLC",
  • "descloc": "Store CA 543",
  • "clerkid": "Doe-1553",
  • "stationid": "7",
  • "laneid": "4",
  • "comments": "Extra beef",
  • "divisionnum": "PAYROLL",
  • "expdate": "0129",
  • "healthcare": "no",
  • "reversible": "yes",
  • "reversal_reason": "CLERKVOID",
  • "offline_decline": "...",
  • "tranflags": "CAPTURED|ONLINE|SENSITIVEDATA",
  • "txnstatus": "COMPLETE|ONLINE|SENSITIVEDATA",
  • "last_modified_ts": "1653422816",
  • "order_id": "58445676543",
  • "payment_id": "987653645678",
  • "order_cash_discount": "12.37",
  • "order_cash_price": "142.97",
  • "order_noncash_price": "155.34",
  • "order_tip": "0.50",
  • "order_total": "155.34",
  • "order_tax": "2.44",
  • "order_discount": "5.22",
  • "detail_order_notes": "Extra pickles",
  • "trans": "...",
  • "line_items": "...",
  • "ttid": "96748596765467",
  • "draft_locator_id": "24FDBDD0902",
  • "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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

Transaction identifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: email=email@email

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_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

payment_id
required
string
Example: 987653645678

Unique ID of a payment for an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: email=email@email

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_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: email=email@email

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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

Transaction identifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

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_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

payment_id
required
string
Example: 987653645678

Unique ID of a payment for an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

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_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: sms=555-555-5555

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: acct=5454

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
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

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
Example: clerkid=Doe-1553

Identifier for the clerk running the transaction

comments
string
Example: comments=Extra beef

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.

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
Example: last_modified_bdate=-9 days

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
Example: last_modified_edate=-4 days

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: acct=5454

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
Example: batch=47

The batch number associated with the transaction

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

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
Example: clerkid=Doe-1553

Identifier for the clerk running the transaction

comments
string
Example: comments=Extra beef

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.

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
Example: ttid=96748596765467

Transaction identifier

ttid_ref
string

TTID of a linked transaction. Used for things like refunds by TTID to refernece the original transaction that was refunded.

order_id
string
Example: order_id=7654323456

Order ID from the Monetra order system this tranaction should be associated with

token
string
Example: token=6789656783904467894

Filter based on token. Can be yes to only show tokens, no to not show any tokens, or a stored account 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
Example: last_modified_bdate=-9 days

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
Example: last_modified_edate=-4 days

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
Example: user=user19

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

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
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
route_id
string
Example: route_id=0

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.

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
tranflags
object
Enum: "HASAVS" "CAVVFULL" "CAVVBAD" "DATATRACK1" "DATATRACK2" "DATAKEYED" "DATAMICR" "CARDNOTPRESENT" "ADVANCEDEPOSIT" "NONTAXABLE" "RFID" "NSF" "RECURRING" "RECURRING_FIRST" "INSTALLMENT" "PINLESS" "HEALTHCARE" "SNF_APPROVED" "SNF_DENY" "ACCT_BUSINESS" "PARTIALAUTH" "NOSHOW" "RFIDCAPABLE" "DIGITAL_GOODS" "PROC_E2E" "CNP_ECOMM" "CARDSHIELD_E2E" "ICC" "EMV_FALLBACK" "EMV_OFFLINE" "DEBTREPAYMENT" "PROC_TOKEN" "MOBILEINAPP" "CARDONFILE" "STANDIN" "PINBYPASS" "ENCPROV_E2E" "INCREMENTAL" "ACCT_SAVINGS" "EMV_FALLBACK_NOAID" "HOSTEDPAGE"
Example: tranflags=CAPTURED|ONLINE|SENSITIVEDATA

Pipe (|) separated list of flags that describe the parameters that went into the transaction. When filtering this will include any transactions that contain these flags.

Flag values (pipe separated):

  • HASAVS - AVS data was sent
  • CAVVFULL - CAVV data was sent
  • CAVVBAD - Non-participant CAVV
  • DATATRACK1 - Magstripe Track 1 data sent
  • DATATRACK2 - Magstripe Track 2 data sent
  • DATAKEYED - Keyed account data sent
  • DATAMICR - MICR account data sent
  • CARDNOTPRESENT - Card was not present
  • ADVANCEDEPOSIT - Advance deposit transaction
  • NONTAXABLE - Non-taxable transaction
  • RFID - Contactless read
  • NSF - Insufficient funds (partial) auth allowed indicator
  • RECURRING - Recurring Payment
  • RECURRING_FIRST - Recurring Payment. First payment indicator
  • INSTALLMENT - Installment Payment
  • PINLESS - PINless debit
  • HEALTHCARE - Health benefits transaction
  • SNF_APPROVED - Transaction was stored and then subsequently authorized with host
  • SNF_DENY - Transaction was stored and then subsequently denied by the host
  • ACCT_BUSINESS - Business account specified
  • PARTIALAUTH - The transaction was only partially approved by the processing institution
  • NOSHOW - No Show indicator for Lodging
  • RFIDCAPABLE - Device is RFID capable, but transaction didn't come in via RFID
  • DIGITAL_GOODS - Goods were digital (electronically delivered), not physical. Only applies to E-commerce
  • PROC_E2E - Processor-level end-to-end was used
  • CNP_ECOMM - Card Not Present - E-commerce. For industries such as Restaurant and Lodging
  • CARDSHIELD_E2E - Monetra CardShield e2e was used
  • ICC - ICC data was provided
  • EMV_FALLBACK - EMV fallback was specified
  • EMV_OFFLINE - EMV Offline authorization
  • DEBTREPAYMENT - Debt Repayment indicator
  • PROC_TOKEN - The account number on file is really a processor token
  • MOBILEINAPP - Mobile In-App payment
  • CARDONFILE - Card on file (recurring=cardonfile), not automatic, customer-initiated
  • STANDIN - Transaction was stored and approved standin
  • PINBYPASS - EMV PIN Bypass
  • ENCPROV_E2E - External Encryption Provider E2E was used
  • INCREMENTAL - One or or incrementals was performed
  • ACCT_SAVINGS - Savings account if specified
  • EMV_FALLBACK_NOAID - Transaction was EMV fallback to MSR due to card AID not supported by the terminal
  • HOSTEDPAGE - Transaction ran though the hosted payment page
not_tranflags
object
Enum: "HASAVS" "CAVVFULL" "CAVVBAD" "DATATRACK1" "DATATRACK2" "DATAKEYED" "DATAMICR" "CARDNOTPRESENT" "ADVANCEDEPOSIT" "NONTAXABLE" "RFID" "NSF" "RECURRING" "RECURRING_FIRST" "INSTALLMENT" "PINLESS" "HEALTHCARE" "SNF_APPROVED" "SNF_DENY" "ACCT_BUSINESS" "PARTIALAUTH" "NOSHOW" "RFIDCAPABLE" "DIGITAL_GOODS" "PROC_E2E" "CNP_ECOMM" "CARDSHIELD_E2E" "ICC" "EMV_FALLBACK" "EMV_OFFLINE" "DEBTREPAYMENT" "PROC_TOKEN" "MOBILEINAPP" "CARDONFILE" "STANDIN" "PINBYPASS" "ENCPROV_E2E" "INCREMENTAL" "ACCT_SAVINGS" "EMV_FALLBACK_NOAID" "HOSTEDPAGE"
Example: not_tranflags=CAPTURED|ONLINE|SENSITIVEDATA

Pipe (|) separated list of flags that describe the parameters that went into the transaction. When filtering this will exclude any transactions that contain these flags.

Flag values (pipe separated):

  • HASAVS - AVS data was sent
  • CAVVFULL - CAVV data was sent
  • CAVVBAD - Non-participant CAVV
  • DATATRACK1 - Magstripe Track 1 data sent
  • DATATRACK2 - Magstripe Track 2 data sent
  • DATAKEYED - Keyed account data sent
  • DATAMICR - MICR account data sent
  • CARDNOTPRESENT - Card was not present
  • ADVANCEDEPOSIT - Advance deposit transaction
  • NONTAXABLE - Non-taxable transaction
  • RFID - Contactless read
  • NSF - Insufficient funds (partial) auth allowed indicator
  • RECURRING - Recurring Payment
  • RECURRING_FIRST - Recurring Payment. First payment indicator
  • INSTALLMENT - Installment Payment
  • PINLESS - PINless debit
  • HEALTHCARE - Health benefits transaction
  • SNF_APPROVED - Transaction was stored and then subsequently authorized with host
  • SNF_DENY - Transaction was stored and then subsequently denied by the host
  • ACCT_BUSINESS - Business account specified
  • PARTIALAUTH - The transaction was only partially approved by the processing institution
  • NOSHOW - No Show indicator for Lodging
  • RFIDCAPABLE - Device is RFID capable, but transaction didn't come in via RFID
  • DIGITAL_GOODS - Goods were digital (electronically delivered), not physical. Only applies to E-commerce
  • PROC_E2E - Processor-level end-to-end was used
  • CNP_ECOMM - Card Not Present - E-commerce. For industries such as Restaurant and Lodging
  • CARDSHIELD_E2E - Monetra CardShield e2e was used
  • ICC - ICC data was provided
  • EMV_FALLBACK - EMV fallback was specified
  • EMV_OFFLINE - EMV Offline authorization
  • DEBTREPAYMENT - Debt Repayment indicator
  • PROC_TOKEN - The account number on file is really a processor token
  • MOBILEINAPP - Mobile In-App payment
  • CARDONFILE - Card on file (recurring=cardonfile), not automatic, customer-initiated
  • STANDIN - Transaction was stored and approved standin
  • PINBYPASS - EMV PIN Bypass
  • ENCPROV_E2E - External Encryption Provider E2E was used
  • INCREMENTAL - One or or incrementals was performed
  • ACCT_SAVINGS - Savings account if specified
  • EMV_FALLBACK_NOAID - Transaction was EMV fallback to MSR due to card AID not supported by the terminal
  • HOSTEDPAGE - Transaction ran though the hosted payment page

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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"
Example: txnstatus=DECLINED|UNCAPTURED|CAPTURED|COMPLETE

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)
acct
string
Example: acct=5454

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
Example: batch=47

The batch number associated with the transaction

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

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
Example: clerkid=Doe-1553

Identifier for the clerk running the transaction

comments
string
Example: comments=Extra beef

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.

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
Example: ttid=96748596765467

Transaction identifier

ttid_ref
string

TTID of a linked transaction. Used for things like refunds by TTID to refernece the original transaction that was refunded.

order_id
string
Example: order_id=7654323456

Order ID from the Monetra order system this tranaction should be associated with

token
string
Example: token=6789656783904467894

Filter based on token. Can be yes to only show tokens, no to not show any tokens, or a stored account 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
Example: last_modified_bdate=-9 days

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
Example: last_modified_edate=-4 days

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
Example: user=user19

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

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
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
route_id
string
Example: route_id=0

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.

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
tranflags
object
Enum: "HASAVS" "CAVVFULL" "CAVVBAD" "DATATRACK1" "DATATRACK2" "DATAKEYED" "DATAMICR" "CARDNOTPRESENT" "ADVANCEDEPOSIT" "NONTAXABLE" "RFID" "NSF" "RECURRING" "RECURRING_FIRST" "INSTALLMENT" "PINLESS" "HEALTHCARE" "SNF_APPROVED" "SNF_DENY" "ACCT_BUSINESS" "PARTIALAUTH" "NOSHOW" "RFIDCAPABLE" "DIGITAL_GOODS" "PROC_E2E" "CNP_ECOMM" "CARDSHIELD_E2E" "ICC" "EMV_FALLBACK" "EMV_OFFLINE" "DEBTREPAYMENT" "PROC_TOKEN" "MOBILEINAPP" "CARDONFILE" "STANDIN" "PINBYPASS" "ENCPROV_E2E" "INCREMENTAL" "ACCT_SAVINGS" "EMV_FALLBACK_NOAID" "HOSTEDPAGE"
Example: tranflags=CAPTURED|ONLINE|SENSITIVEDATA

Pipe (|) separated list of flags that describe the parameters that went into the transaction. When filtering this will include any transactions that contain these flags.

Flag values (pipe separated):

  • HASAVS - AVS data was sent
  • CAVVFULL - CAVV data was sent
  • CAVVBAD - Non-participant CAVV
  • DATATRACK1 - Magstripe Track 1 data sent
  • DATATRACK2 - Magstripe Track 2 data sent
  • DATAKEYED - Keyed account data sent
  • DATAMICR - MICR account data sent
  • CARDNOTPRESENT - Card was not present
  • ADVANCEDEPOSIT - Advance deposit transaction
  • NONTAXABLE - Non-taxable transaction
  • RFID - Contactless read
  • NSF - Insufficient funds (partial) auth allowed indicator
  • RECURRING - Recurring Payment
  • RECURRING_FIRST - Recurring Payment. First payment indicator
  • INSTALLMENT - Installment Payment
  • PINLESS - PINless debit
  • HEALTHCARE - Health benefits transaction
  • SNF_APPROVED - Transaction was stored and then subsequently authorized with host
  • SNF_DENY - Transaction was stored and then subsequently denied by the host
  • ACCT_BUSINESS - Business account specified
  • PARTIALAUTH - The transaction was only partially approved by the processing institution
  • NOSHOW - No Show indicator for Lodging
  • RFIDCAPABLE - Device is RFID capable, but transaction didn't come in via RFID
  • DIGITAL_GOODS - Goods were digital (electronically delivered), not physical. Only applies to E-commerce
  • PROC_E2E - Processor-level end-to-end was used
  • CNP_ECOMM - Card Not Present - E-commerce. For industries such as Restaurant and Lodging
  • CARDSHIELD_E2E - Monetra CardShield e2e was used
  • ICC - ICC data was provided
  • EMV_FALLBACK - EMV fallback was specified
  • EMV_OFFLINE - EMV Offline authorization
  • DEBTREPAYMENT - Debt Repayment indicator
  • PROC_TOKEN - The account number on file is really a processor token
  • MOBILEINAPP - Mobile In-App payment
  • CARDONFILE - Card on file (recurring=cardonfile), not automatic, customer-initiated
  • STANDIN - Transaction was stored and approved standin
  • PINBYPASS - EMV PIN Bypass
  • ENCPROV_E2E - External Encryption Provider E2E was used
  • INCREMENTAL - One or or incrementals was performed
  • ACCT_SAVINGS - Savings account if specified
  • EMV_FALLBACK_NOAID - Transaction was EMV fallback to MSR due to card AID not supported by the terminal
  • HOSTEDPAGE - Transaction ran though the hosted payment page
not_tranflags
object
Enum: "HASAVS" "CAVVFULL" "CAVVBAD" "DATATRACK1" "DATATRACK2" "DATAKEYED" "DATAMICR" "CARDNOTPRESENT" "ADVANCEDEPOSIT" "NONTAXABLE" "RFID" "NSF" "RECURRING" "RECURRING_FIRST" "INSTALLMENT" "PINLESS" "HEALTHCARE" "SNF_APPROVED" "SNF_DENY" "ACCT_BUSINESS" "PARTIALAUTH" "NOSHOW" "RFIDCAPABLE" "DIGITAL_GOODS" "PROC_E2E" "CNP_ECOMM" "CARDSHIELD_E2E" "ICC" "EMV_FALLBACK" "EMV_OFFLINE" "DEBTREPAYMENT" "PROC_TOKEN" "MOBILEINAPP" "CARDONFILE" "STANDIN" "PINBYPASS" "ENCPROV_E2E" "INCREMENTAL" "ACCT_SAVINGS" "EMV_FALLBACK_NOAID" "HOSTEDPAGE"
Example: not_tranflags=CAPTURED|ONLINE|SENSITIVEDATA

Pipe (|) separated list of flags that describe the parameters that went into the transaction. When filtering this will exclude any transactions that contain these flags.

Flag values (pipe separated):

  • HASAVS - AVS data was sent
  • CAVVFULL - CAVV data was sent
  • CAVVBAD - Non-participant CAVV
  • DATATRACK1 - Magstripe Track 1 data sent
  • DATATRACK2 - Magstripe Track 2 data sent
  • DATAKEYED - Keyed account data sent
  • DATAMICR - MICR account data sent
  • CARDNOTPRESENT - Card was not present
  • ADVANCEDEPOSIT - Advance deposit transaction
  • NONTAXABLE - Non-taxable transaction
  • RFID - Contactless read
  • NSF - Insufficient funds (partial) auth allowed indicator
  • RECURRING - Recurring Payment
  • RECURRING_FIRST - Recurring Payment. First payment indicator
  • INSTALLMENT - Installment Payment
  • PINLESS - PINless debit
  • HEALTHCARE - Health benefits transaction
  • SNF_APPROVED - Transaction was stored and then subsequently authorized with host
  • SNF_DENY - Transaction was stored and then subsequently denied by the host
  • ACCT_BUSINESS - Business account specified
  • PARTIALAUTH - The transaction was only partially approved by the processing institution
  • NOSHOW - No Show indicator for Lodging
  • RFIDCAPABLE - Device is RFID capable, but transaction didn't come in via RFID
  • DIGITAL_GOODS - Goods were digital (electronically delivered), not physical. Only applies to E-commerce
  • PROC_E2E - Processor-level end-to-end was used
  • CNP_ECOMM - Card Not Present - E-commerce. For industries such as Restaurant and Lodging
  • CARDSHIELD_E2E - Monetra CardShield e2e was used
  • ICC - ICC data was provided
  • EMV_FALLBACK - EMV fallback was specified
  • EMV_OFFLINE - EMV Offline authorization
  • DEBTREPAYMENT - Debt Repayment indicator
  • PROC_TOKEN - The account number on file is really a processor token
  • MOBILEINAPP - Mobile In-App payment
  • CARDONFILE - Card on file (recurring=cardonfile), not automatic, customer-initiated
  • STANDIN - Transaction was stored and approved standin
  • PINBYPASS - EMV PIN Bypass
  • ENCPROV_E2E - External Encryption Provider E2E was used
  • INCREMENTAL - One or or incrementals was performed
  • ACCT_SAVINGS - Savings account if specified
  • EMV_FALLBACK_NOAID - Transaction was EMV fallback to MSR due to card AID not supported by the terminal
  • HOSTEDPAGE - Transaction ran though the hosted payment page

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: acct=5454

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
Example: batch=47

The batch number associated with the transaction

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

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
Example: clerkid=Doe-1553

Identifier for the clerk running the transaction

comments
string
Example: comments=Extra beef

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.

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
Example: ttid=96748596765467

Transaction identifier

ttid_ref
string

TTID of a linked transaction. Used for things like refunds by TTID to refernece the original transaction that was refunded.

order_id
string
Example: order_id=7654323456

Order ID from the Monetra order system this tranaction should be associated with

token
string
Example: token=6789656783904467894

Filter based on token. Can be yes to only show tokens, no to not show any tokens, or a stored account 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
Example: last_modified_bdate=-9 days

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
Example: last_modified_edate=-4 days

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
Example: user=user19

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

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
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
route_id
string
Example: route_id=0

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.

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
tranflags
object
Enum: "HASAVS" "CAVVFULL" "CAVVBAD" "DATATRACK1" "DATATRACK2" "DATAKEYED" "DATAMICR" "CARDNOTPRESENT" "ADVANCEDEPOSIT" "NONTAXABLE" "RFID" "NSF" "RECURRING" "RECURRING_FIRST" "INSTALLMENT" "PINLESS" "HEALTHCARE" "SNF_APPROVED" "SNF_DENY" "ACCT_BUSINESS" "PARTIALAUTH" "NOSHOW" "RFIDCAPABLE" "DIGITAL_GOODS" "PROC_E2E" "CNP_ECOMM" "CARDSHIELD_E2E" "ICC" "EMV_FALLBACK" "EMV_OFFLINE" "DEBTREPAYMENT" "PROC_TOKEN" "MOBILEINAPP" "CARDONFILE" "STANDIN" "PINBYPASS" "ENCPROV_E2E" "INCREMENTAL" "ACCT_SAVINGS" "EMV_FALLBACK_NOAID" "HOSTEDPAGE"
Example: tranflags=CAPTURED|ONLINE|SENSITIVEDATA

Pipe (|) separated list of flags that describe the parameters that went into the transaction. When filtering this will include any transactions that contain these flags.

Flag values (pipe separated):

  • HASAVS - AVS data was sent
  • CAVVFULL - CAVV data was sent
  • CAVVBAD - Non-participant CAVV
  • DATATRACK1 - Magstripe Track 1 data sent
  • DATATRACK2 - Magstripe Track 2 data sent
  • DATAKEYED - Keyed account data sent
  • DATAMICR - MICR account data sent
  • CARDNOTPRESENT - Card was not present
  • ADVANCEDEPOSIT - Advance deposit transaction
  • NONTAXABLE - Non-taxable transaction
  • RFID - Contactless read
  • NSF - Insufficient funds (partial) auth allowed indicator
  • RECURRING - Recurring Payment
  • RECURRING_FIRST - Recurring Payment. First payment indicator
  • INSTALLMENT - Installment Payment
  • PINLESS - PINless debit
  • HEALTHCARE - Health benefits transaction
  • SNF_APPROVED - Transaction was stored and then subsequently authorized with host
  • SNF_DENY - Transaction was stored and then subsequently denied by the host
  • ACCT_BUSINESS - Business account specified
  • PARTIALAUTH - The transaction was only partially approved by the processing institution
  • NOSHOW - No Show indicator for Lodging
  • RFIDCAPABLE - Device is RFID capable, but transaction didn't come in via RFID
  • DIGITAL_GOODS - Goods were digital (electronically delivered), not physical. Only applies to E-commerce
  • PROC_E2E - Processor-level end-to-end was used
  • CNP_ECOMM - Card Not Present - E-commerce. For industries such as Restaurant and Lodging
  • CARDSHIELD_E2E - Monetra CardShield e2e was used
  • ICC - ICC data was provided
  • EMV_FALLBACK - EMV fallback was specified
  • EMV_OFFLINE - EMV Offline authorization
  • DEBTREPAYMENT - Debt Repayment indicator
  • PROC_TOKEN - The account number on file is really a processor token
  • MOBILEINAPP - Mobile In-App payment
  • CARDONFILE - Card on file (recurring=cardonfile), not automatic, customer-initiated
  • STANDIN - Transaction was stored and approved standin
  • PINBYPASS - EMV PIN Bypass
  • ENCPROV_E2E - External Encryption Provider E2E was used
  • INCREMENTAL - One or or incrementals was performed
  • ACCT_SAVINGS - Savings account if specified
  • EMV_FALLBACK_NOAID - Transaction was EMV fallback to MSR due to card AID not supported by the terminal
  • HOSTEDPAGE - Transaction ran though the hosted payment page
not_tranflags
object
Enum: "HASAVS" "CAVVFULL" "CAVVBAD" "DATATRACK1" "DATATRACK2" "DATAKEYED" "DATAMICR" "CARDNOTPRESENT" "ADVANCEDEPOSIT" "NONTAXABLE" "RFID" "NSF" "RECURRING" "RECURRING_FIRST" "INSTALLMENT" "PINLESS" "HEALTHCARE" "SNF_APPROVED" "SNF_DENY" "ACCT_BUSINESS" "PARTIALAUTH" "NOSHOW" "RFIDCAPABLE" "DIGITAL_GOODS" "PROC_E2E" "CNP_ECOMM" "CARDSHIELD_E2E" "ICC" "EMV_FALLBACK" "EMV_OFFLINE" "DEBTREPAYMENT" "PROC_TOKEN" "MOBILEINAPP" "CARDONFILE" "STANDIN" "PINBYPASS" "ENCPROV_E2E" "INCREMENTAL" "ACCT_SAVINGS" "EMV_FALLBACK_NOAID" "HOSTEDPAGE"
Example: not_tranflags=CAPTURED|ONLINE|SENSITIVEDATA

Pipe (|) separated list of flags that describe the parameters that went into the transaction. When filtering this will exclude any transactions that contain these flags.

Flag values (pipe separated):

  • HASAVS - AVS data was sent
  • CAVVFULL - CAVV data was sent
  • CAVVBAD - Non-participant CAVV
  • DATATRACK1 - Magstripe Track 1 data sent
  • DATATRACK2 - Magstripe Track 2 data sent
  • DATAKEYED - Keyed account data sent
  • DATAMICR - MICR account data sent
  • CARDNOTPRESENT - Card was not present
  • ADVANCEDEPOSIT - Advance deposit transaction
  • NONTAXABLE - Non-taxable transaction
  • RFID - Contactless read
  • NSF - Insufficient funds (partial) auth allowed indicator
  • RECURRING - Recurring Payment
  • RECURRING_FIRST - Recurring Payment. First payment indicator
  • INSTALLMENT - Installment Payment
  • PINLESS - PINless debit
  • HEALTHCARE - Health benefits transaction
  • SNF_APPROVED - Transaction was stored and then subsequently authorized with host
  • SNF_DENY - Transaction was stored and then subsequently denied by the host
  • ACCT_BUSINESS - Business account specified
  • PARTIALAUTH - The transaction was only partially approved by the processing institution
  • NOSHOW - No Show indicator for Lodging
  • RFIDCAPABLE - Device is RFID capable, but transaction didn't come in via RFID
  • DIGITAL_GOODS - Goods were digital (electronically delivered), not physical. Only applies to E-commerce
  • PROC_E2E - Processor-level end-to-end was used
  • CNP_ECOMM - Card Not Present - E-commerce. For industries such as Restaurant and Lodging
  • CARDSHIELD_E2E - Monetra CardShield e2e was used
  • ICC - ICC data was provided
  • EMV_FALLBACK - EMV fallback was specified
  • EMV_OFFLINE - EMV Offline authorization
  • DEBTREPAYMENT - Debt Repayment indicator
  • PROC_TOKEN - The account number on file is really a processor token
  • MOBILEINAPP - Mobile In-App payment
  • CARDONFILE - Card on file (recurring=cardonfile), not automatic, customer-initiated
  • STANDIN - Transaction was stored and approved standin
  • PINBYPASS - EMV PIN Bypass
  • ENCPROV_E2E - External Encryption Provider E2E was used
  • INCREMENTAL - One or or incrementals was performed
  • ACCT_SAVINGS - Savings account if specified
  • EMV_FALLBACK_NOAID - Transaction was EMV fallback to MSR due to card AID not supported by the terminal
  • HOSTEDPAGE - Transaction ran though the hosted payment page

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: bdate=-6 months

Start of date range

edate
required
string
Example: edate=now

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: bdate=-6 months

Start of date range

edate
required
string
Example: edate=now

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: bdate=-6 months

Start of date range

edate
required
string
Example: edate=now

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.

Add Line Item

Adds Level 3 line item to an unsettled transaction

libmonetra KVS equivalent for endpoint

  • action_admin = level3
  • level3 = add
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

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": "78965743785967",
  • "commoditycode": "50301700",
  • "description": "Pickles",
  • "productcode": "7456",
  • "qty": "1",
  • "unit": "1",
  • "unitprice": "0.25",
  • "discountamount": "2.53",
  • "discountrate": "4.05",
  • "amount": "1.51"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

Transaction identifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

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

Delete Line Item

Deletes Level 3 line item from an unsettled transaction

libmonetra KVS equivalent for endpoint

  • action_admin = level3
  • level3 = del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

Transaction identifier

l3id
required
string
Example: 56789673

ID associated with the Level 3 line item

query Parameters
profile_id
string
Example: profile_id=78965743785967

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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

Transaction identifier

l3id
required
string
Example: 56789673

ID associated with the Level 3 line item

query Parameters
profile_id
string
Example: profile_id=78965743785967

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": "56789673",
  • "ttid": "96748596765467",
  • "commoditycode": "50301700",
  • "description": "Pickles",
  • "productcode": "7456",
  • "qty": "1",
  • "unit": "1",
  • "unitprice": "0.25",
  • "discountamount": "2.53",
  • "discountrate": "4.05",
  • "amount": "1.51"
}

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_auth(apikey_idapikey)
path Parameters
batch
required
string
Example: 47

The batch number associated with the transaction

route_id
required
string
Example: 0

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

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_auth(apikey_idapikey)
path Parameters
batch
required
string
Example: 47

The batch number associated with the transaction

route_id
required
string
Example: 0

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

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: batch=47

The batch number associated with the transaction

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: batch=47

The batch number associated with the transaction

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

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_auth(apikey_idapikey)
path Parameters
batch
required
string
Example: 47

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": "78965743785967",
  • "newbatch": "string",
  • "route_id": "0"
}

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_auth(apikey_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": "78965743785967",
  • "batch": "47",
  • "route_id": "0"
}

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_auth(apikey_idapikey)
path Parameters
batch
required
string
Example: 47

The batch number associated with the transaction

route_id
required
string
Example: 0

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

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_auth(apikey_idapikey)
path Parameters
batch
required
string
Example: 47

The batch number associated with the transaction

route_id
required
string
Example: 0

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

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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

Transaction identifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

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": "78965743785967",
  • "image": "..."
}

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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

Transaction identifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

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": "78965743785967",
  • "image": "..."
}

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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

Transaction identifier

query Parameters
image_format
object
Enum: "TIFF" "PNG" "PBM"
Example: image_format=PNG

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_auth(apikey_idapikey)
query Parameters
batch
string
Example: batch=47

The batch number associated with the transaction

status
object
Enum: "unsettled" "settled"
Example: status=unsettled

Transaction status

Values:

  • unsettled - Unsettled
  • settled - Settled
bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

image_format
object
Enum: "TIFF" "PNG" "PBM"
Example: image_format=PNG

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.

Edit Account

Edits a stored account

libmonetra KVS equivalent for endpoint

  • action_admin = token_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
token
required
string
Example: 6789656783904467894

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.

status
string
Enum: "enabled" "disabled" "au_disabled"

Token status

Values:

  • enabled - The token is enabled
  • disabled - The token is disabled
  • au_disabled - The token is disabled due to account updater
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.

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

cust_regdate
string

E-commerce only

Discover. If a customer has registered with the merchant's website, this is the registration date.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "status": "enabled",
  • "account_data": {
    },
  • "street": "1st St",
  • "zip": "32606",
  • "clientref": "55",
  • "matching_token": "no",
  • "customer_id": "56789687564",
  • "cof_transid": "67898768",
  • "cof_authamount": "76.42",
  • "descr": "description of some kind",
  • "cust_regdate": "2023-04-01"
}

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_auth(apikey_idapikey)
path Parameters
token
required
string
Example: 6789656783904467894

Referent to the account data that's been stored

query Parameters
profile_id
string
Example: profile_id=78965743785967

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": "6789656783904467894",
  • "tokengroup_id": "654356543",
  • "create_profile_id": "654765436",
  • "create_ts": "2022-05-24 15:06:13 -0400",
  • "update_ts": "2022-05-24 15:06:13 -0400",
  • "type": "NORMAL",
  • "flags": "ACCT_BUSINESS",
  • "status": "enabled",
  • "cardtype": "VISA",
  • "abaroute": "267084131",
  • "account": "XXXXXXXXXXXX1234",
  • "expdate": "0129",
  • "cardholdername": "John Doe",
  • "descr": "string",
  • "clientref": "55",
  • "customer_id": "56789687564",
  • "street": "91st St",
  • "zip": "32606",
  • "descmerch": "Pizza Palace LLC",
  • "descloc": "Store CA 543"
}

Remove Account

Permanently removes a stored account from the vault

libmonetra KVS equivalent for endpoint

  • action_admin = token_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
token
required
string
Example: 6789656783904467894

Referent to the account data that's been stored

query Parameters
profile_id
string
Example: profile_id=78965743785967

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

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_auth(apikey_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": "...",
  • "group_id": "36789654543"
}

Response samples

Content type
application/json
{
  • "datablock": "..."
}

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_auth(apikey_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, cust_regdate

libmonetra KVS equivalent for endpoint

  • action_admin = token_list
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: clientref=55

Reference number associated with the customer

id
string
Example: id=56789687564

Customer identifier

expdate_end
string
Example: expdate_end=1022

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
Example: account=5454

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_auth(apikey_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.

ttid
string

Transaction identifier of previously authorized transaction to load account data from

Cannot be combined with:

  • account_data
  • carddenylist_id
carddenylist_id
string\d+

ID in the card deny/allow list

Cannot be combined with:

  • account_data
  • ttid
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

cust_regdate
string

E-commerce only

Discover. If a customer has registered with the merchant's website, this is the registration date.

descr
string <= 128 characters

Description of the account

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    },
  • "ttid": "96748596765467",
  • "carddenylist_id": "67898765",
  • "street": "1st St",
  • "zip": "32606",
  • "clientref": "55",
  • "matching_token": "no",
  • "customer_id": "56789687564",
  • "cof_transid": "67898768",
  • "cof_authamount": "76.42",
  • "cust_regdate": "2023-04-01",
  • "descr": "description of some kind"
}

Response samples

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

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.

Add Installment Payment

Adds an installment payment

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = add
  • type = installment
Authorizations:
basic_auth(apikey_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.

status
string
Enum: "active" "disabled"

Schedule active status

Values:

  • active - The schedule is active
  • disabled - The schedule is disabled
property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "customer_id": "56789687564",
  • "token": "765432767",
  • "clientref": "55",
  • "cof_transid": "67898768",
  • "cof_authamount": "76.42",
  • "descr": "description of some kind",
  • "bdate": "-6 months",
  • "installment_total": "149",
  • "frequency": "monthly",
  • "amount": "19.92",
  • "status": "active",
  • "property1": "string",
  • "property2": "string"
}

Response samples

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

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: clientref=55

Reference number associated with the customer

customer_id
string
Example: customer_id=56789687564

Customer identifier, numeric only

expdate_end
string
Example: expdate_end=1022

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
Example: account=5454

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 Recurring Payment

Adds a recurring payment

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = add
  • type = recurring
Authorizations:
basic_auth(apikey_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.

status
string
Enum: "active" "disabled"

Schedule active status

Values:

  • active - The schedule is active
  • disabled - The schedule is disabled
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*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "status": "active",
  • "token": "765432767",
  • "clientref": "55",
  • "cof_transid": "67898768",
  • "cof_authamount": "76.42",
  • "descr": "description of some kind",
  • "bdate": "-6 months",
  • "edate": "now",
  • "frequency": "monthly",
  • "amount": "19.92",
  • "property1": "string",
  • "property2": "string"
}

Response samples

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

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: clientref=55

Reference number associated with the customer

customer_id
string
Example: customer_id=56789687564

Customer identifier, numeric only

expdate_end
string
Example: expdate_end=1022

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
Example: account=5454

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

Edit Installment Payment

Edits a stored installment payment

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = edit
  • type = installment
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 565432

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.

status
string
Enum: "active" "disabled"

Schedule active status

Values:

  • active - The schedule is active
  • disabled - The schedule is disabled
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*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "status": "active",
  • "customer_id": "56789687564",
  • "token": "6789656783904467894",
  • "clientref": "55",
  • "cof_transid": "67898768",
  • "cof_authamount": "76.42",
  • "descr": "description of some kind",
  • "bdate": "-6 months",
  • "installment_total": "149",
  • "frequency": "monthly",
  • "amount": "19.92",
  • "property1": "string",
  • "property2": "string"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 565432

Schedule ID

query Parameters
profile_id
string
Example: profile_id=78965743785967

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": "565432",
  • "token": "765432767",
  • "create_ts": "2022-05-24 15:06:13 -0400",
  • "update_ts": "2022-05-24 15:06:13 -0400",
  • "type": "NORMAL",
  • "flags": "ACCT_BUSINESS",
  • "status": "ACTIVE",
  • "cardtype": "VISA",
  • "account": "XXXXXXXXXXXX1234",
  • "cardholdername": "John Doe",
  • "bdate": "-6 months",
  • "edate": "now",
  • "installment_total": "149",
  • "amount": "19.92",
  • "last_run": "2022-05-24 15:06:13 -0400",
  • "last_run_success": "2022-05-24 15:06:13 -0400",
  • "last_run_ttid": "214372416680781",
  • "next_run": "2022-06-24 15:06:13 -0400",
  • "installment_num": "17",
  • "total_paid": "155.34",
  • "notes": "This is a note",
  • "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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 565432

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.

skipmissed
string
Default: "no"
Enum: "yes" "no"

Whether missed payments should be skipped

By default, when activating an inactive recurring schedule all missed payment (while inactive) will be charged. This is to deal with situations where service was rendered but payment failed and previous payments need to be made now that the schedule is able to run again.

A common scenario is a card closed due to fraud and the merchant not having been provided the new card information. It's not unusable for a customer to forget to update all merchants they have recurring payments with.

Automatically charging missed payments makes it easier for the merchant so they don't have to determine how many payments were missed and manually charge each one.

Sending this parameter as no will disable charging missed payments. This is necessary if the merchant has manually accepted payment for missed payments. Or if they haven't provided service during the time the schedule as inactive.

Values:

  • yes - Do not charge missed payments
  • no - Charge missed payments
status
string
Enum: "active" "disabled"

Schedule active status

Values:

  • active - The schedule is active
  • disabled - The schedule is disabled
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*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "skipmissed": "no",
  • "status": "active",
  • "token": "765432767",
  • "clientref": "55",
  • "cof_transid": "67898768",
  • "cof_authamount": "76.42",
  • "descr": "description of some kind",
  • "bdate": "-6 months",
  • "edate": "now",
  • "frequency": "monthly",
  • "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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 565432

Schedule ID

query Parameters
profile_id
string
Example: profile_id=78965743785967

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": "565432",
  • "token": "765432767",
  • "create_ts": "2022-05-24 15:06:13 -0400",
  • "update_ts": "2022-05-24 15:06:13 -0400",
  • "type": "NORMAL",
  • "flags": "ACCT_BUSINESS",
  • "status": "ACTIVE",
  • "cardtype": "VISA",
  • "account": "XXXXXXXXXXXX1234",
  • "cardholdername": "John Doe",
  • "bdate": "-6 months",
  • "edate": "now",
  • "frequency": "monthly",
  • "amount": "19.92",
  • "last_run": "2022-05-24 15:06:13 -0400",
  • "last_run_success": "2022-05-24 15:06:13 -0400",
  • "last_run_ttid": "214372416680781",
  • "next_run": "2022-06-24 15:06:13 -0400",
  • "total_paid": "155.34",
  • "notes": "This is a note",
  • "property1": "string",
  • "property2": "string"
}

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

token
string
Example: token=6789656783904467894

Referent to the account data that's been stored

customer_id
string
Example: customer_id=56789687564

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 565432

Schedule ID

query Parameters
profile_id
string
Example: profile_id=78965743785967

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. Card deny list entries are shared among the token sharing group. Entries indicate accounts that are problematic and should no longer be transacted with.

Accounts can be added to the deny list in a number of ways:

  • Manually
  • Automatically when a transaction is online declined and one of the following applies:
    • The CARDDENYLIST_DECLINE profile flag is set to yes and the transaction carddenylist_decline flag does not override it with no
    • The transaction includes the carddenylist_decline flag set to yes
  • Automatically when a fraud check fails

Accounts can be checked if they are on the card deny list two different ways:

  • Manually
  • Automatically when a transaction is attempted and one of the following applies:
    • The CARDDENYLIST_CHECK profile flag is set to yes and the transaction carddenylist_check flag does not override it with no
    • A transaction includes the carddenylist_check flag set to yes

Add to Deny List

Add a card to the deny list

libmonetra KVS equivalent for endpoint

  • action_admin = carddenylist
  • carddenylist = add
Authorizations:
basic_auth(apikey_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.

reason_code
string
Default: "UNSPECIFIED"
Enum: "UNSPECIFIED" "DECLINE" "TESTCARD" "CHARGEBACK" "FRAUDCHECK"

Reason an account was added to the deny list

Values:

  • UNSPECIFIED - Manual or API entry with no reason specified
  • DECLINE - Due to decline
  • TESTCARD - Identified as a test card
  • CHARGEBACK - Due to receiving a chargeback
  • FRAUDCHECK - Due to a fraud check failing
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.
comment
string

Arbitrary comment related to deny list entry

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    },
  • "reason_code": "CHARGEBACK",
  • "expire": "+90 days",
  • "comment": "ACH payment bounced"
}

Response samples

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

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

libmonetra KVS equivalent for endpoint

  • action_admin = carddenylist
  • carddenylist = list
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: expdate_bdate=-5 months

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
Example: expdate_edate=-2 months

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
Example: added_bdate=-5 months

Used to filter report by added date range. This is the beginning date of the added date rate to match.

added_edate
string
Example: added_edate=-2 months

Used to filter report by added date range. This is the ending date of the added date range to match.

last_seen_bdate
string
Example: last_seen_bdate=-5 months

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
Example: last_seen_edate=-2 months

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
Example: expire_bdate=-5 months

Used to filter report by expire date range

Expiration is when the entry in the list will be removed.

Corresponds expire parameter sent with an add operation. This is the beginning of the expire range to match."

expire_edate
string
Example: expire_edate=-2 months

Used to filter report by expire date range

Expiration is when the entry in the list should be removed.

Corresponds expire parameter sent with an add operation. This is the ending 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": "..."
}

Check 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_auth(apikey_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.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    }
}

Response samples

Content type
application/json
{
  • "id": "167643643",
  • "last4": "5454",
  • "expdate": "0129",
  • "cardtype": "VISA",
  • "added": "2022-05-24 15:06:13 -0400",
  • "last_seen": "2022-05-24 15:06:13 -0400",
  • "expire": "+90 days",
  • "cardholdername": "John Doe",
  • "reason_code": "CHARGEBACK",
  • "comment": "ACH payment bounced"
}

Get Deny List Entry

Account detail for a card on the card deny list

libmonetra KVS equivalent for endpoint

  • action_admin = carddenylist
  • carddenylist = list
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
carddenylist_id
required
string
Example: 67898765

ID in the card deny/allow list

query Parameters
profile_id
string
Example: profile_id=78965743785967

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": "167643643",
  • "last4": "5454",
  • "expdate": "0129",
  • "cardtype": "VISA",
  • "added": "2022-05-24 15:06:13 -0400",
  • "last_seen": "2022-05-24 15:06:13 -0400",
  • "expire": "+90 days",
  • "cardholdername": "John Doe",
  • "reason_code": "CHARGEBACK",
  • "comment": "ACH payment bounced"
}

Remove from Deny List

Remove a card from the deny list

libmonetra KVS equivalent for endpoint

  • action_admin = carddenylist
  • carddenylist = remove
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
carddenylist_id
required
string
Example: 67898765

ID in the card deny/allow list

query Parameters
profile_id
string
Example: profile_id=78965743785967

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

Card Allow List

The card allow list is an internal, merchant maintained, list of cards or ACH accounts. Card allow list entries are shared among the token sharing group. Entries indicate accounts that are known good and should skip fraud checks and automatic deny list entry.

Accounts can be added to the allow list:

  • Manually
  • Automatically for a short period when a fraud screening check passes

Accounts can be checked if they are on the allow list:

  • Manually
  • Automatically before attempting automated fraud screening checks

Add to Allow List

Add a card to the allow list

libmonetra KVS equivalent for endpoint

  • action_admin = cardallowlist
  • cardallowlist = add
Authorizations:
basic_auth(apikey_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.

reason_code
string
Default: "UNSPECIFIED"
Enum: "UNSPECIFIED" "FRAUDCHECK"

Reason an account was added to the allow list

Values:

  • UNSPECIFIED - Manual or API entry with no reason specified
  • FRAUDCHECK - An automated fraud check passed
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.
comment
string

Arbitrary comment related to allow list entry

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    },
  • "reason_code": "UNSPECIFIED",
  • "expire": "+90 days",
  • "comment": "false positive on fraud check"
}

Response samples

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

List Allow List

Lists accounts on the card allow list

The resulting report will contain these headers:

id, last4, expdate, cardtype, added, last_seen,
expire, cardholdername, reason_code, comment

libmonetra KVS equivalent for endpoint

  • action_admin = cardallowlist
  • cardallowlist = list
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: expdate_bdate=-5 months

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
Example: expdate_edate=-2 months

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
Example: added_bdate=-5 months

Used to filter report by added date range. This is the beginning date of the added date rate to match.

added_edate
string
Example: added_edate=-2 months

Used to filter report by added date range. This is the ending date of the added date range to match.

last_seen_bdate
string
Example: last_seen_bdate=-5 months

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
Example: last_seen_edate=-2 months

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
Example: expire_bdate=-5 months

Used to filter report by expire date range

Expiration is when the entry in the list will be removed.

Corresponds expire parameter sent with an add operation. This is the beginning of the expire range to match."

expire_edate
string
Example: expire_edate=-2 months

Used to filter report by expire date range

Expiration is when the entry in the list should be removed.

Corresponds expire parameter sent with an add operation. This is the ending of the expire range to match."

Responses

Request samples 

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

Response samples

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

Check Allow List

Check if account is on the card allow 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 = cardallowlist
  • cardallowlist = list
Authorizations:
basic_auth(apikey_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.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    }
}

Response samples

Content type
application/json
{
  • "id": "167643643",
  • "last4": "5454",
  • "expdate": "0129",
  • "cardtype": "VISA",
  • "added": "2022-05-24 15:06:13 -0400",
  • "last_seen": "2022-05-24 15:06:13 -0400",
  • "expire": "+90 days",
  • "cardholdername": "John Doe",
  • "reason_code": "UNSPECIFIED",
  • "comment": "false positive on fraud check"
}

Get Allow List Entry

Account detail for a card on the card allow list

libmonetra KVS equivalent for endpoint

  • action_admin = cardallowlist
  • cardallowlist = list
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
cardallowlist_id
required
string
Example: 67898765

ID in the card allow list

query Parameters
profile_id
string
Example: profile_id=78965743785967

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/allow/143432' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "167643643",
  • "last4": "5454",
  • "expdate": "0129",
  • "cardtype": "VISA",
  • "added": "2022-05-24 15:06:13 -0400",
  • "last_seen": "2022-05-24 15:06:13 -0400",
  • "expire": "+90 days",
  • "cardholdername": "John Doe",
  • "reason_code": "UNSPECIFIED",
  • "comment": "false positive on fraud check"
}

Remove from Allow List

Remove a card from the allow list

libmonetra KVS equivalent for endpoint

  • action_admin = cardallowlist
  • cardallowlist = remove
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
cardallowlist_id
required
string
Example: 67898765

ID in the card allow list

query Parameters
profile_id
string
Example: profile_id=78965743785967

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

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.

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_auth(apikey_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*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "display_name": "James Dean",
  • "name_company": "Dean Industries",
  • "name_prefix": "Mr.",
  • "name_first": "James",
  • "name_middle": "Byron",
  • "name_last": "Dean",
  • "name_suffix": "string",
  • "phone_work": "555-555-5555",
  • "phone_home": "555-555-5555",
  • "phone_mobile": "555-555-5555",
  • "phone_fax": "555-555-5555",
  • "email": "email@email",
  • "website": "https://web",
  • "business_id": "XX-XXXXXXX",
  • "accounting_id": "1474",
  • "notes": "This is a note",
  • "flags": "EMAIL_RECEIPT_RECURRING",
  • "property1": "string",
  • "property2": "string"
}

Response samples

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

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56789687564

Customer identifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

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

Edit Customer

Edits an existing customer

libmonetra KVS equivalent for endpoint

  • action_admin = customer_edit
  • customer_edit = customer
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56789687564

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*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "display_name": "James Dean",
  • "name_company": "Dean Industries",
  • "name_prefix": "Mr.",
  • "name_first": "James",
  • "name_middle": "Byron",
  • "name_last": "Dean",
  • "name_suffix": "string",
  • "phone_work": "555-555-5555",
  • "phone_home": "555-555-5555",
  • "phone_mobile": "555-555-5555",
  • "phone_fax": "555-555-5555",
  • "email": "email@email",
  • "website": "https://web",
  • "business_id": "XX-XXXXXXX",
  • "accounting_id": "1474",
  • "notes": "This is a note",
  • "flags": "EMAIL_RECEIPT_RECURRING",
  • "default_token": "44975464745966",
  • "default_billing_id": "648563845659663",
  • "default_shipping_id": "84569365",
  • "property1": "string",
  • "property2": "string"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56789687564

Customer identifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

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": "56789687564",
  • "tokengroup_id": "654356543",
  • "create_profile_id": "654765436",
  • "ts_created": "2022-05-24 15:06:13 -0400",
  • "ts_modified": "2022-05-24 15:06:13 -0400",
  • "flags": "EMAIL_RECEIPT_RECURRING",
  • "display_name": "James Dean",
  • "name_company": "Dean Industries",
  • "name_prefix": "Mr.",
  • "name_first": "James",
  • "name_middle": "Byron",
  • "name_last": "Dean",
  • "name_suffix": "string",
  • "phone_work": "555-555-5555",
  • "phone_home": "555-555-5555",
  • "phone_mobile": "555-555-5555",
  • "phone_fax": "555-555-5555",
  • "email": "email@email",
  • "website": "https://web",
  • "business_id": "XX-XXXXXXX",
  • "accounting_id": "1474",
  • "notes": "This is a note",
  • "default_billing_id": "648563845659663",
  • "default_shipping_id": "84569365",
  • "default_token": "44975464745966",
  • "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"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56789687564

Customer identifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

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

Add Customer Address

Adds an address to a customer

libmonetra KVS equivalent for endpoint

  • action_admin = customer_add
  • customer_add = customer_address
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
customer_id
required
string
Example: 56789687564

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*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "display_name": "James Dean",
  • "address1": "673 2nd St",
  • "address2": "STE 4",
  • "city": "Winter Haven",
  • "state": "FL",
  • "country": "USA",
  • "postal_code": "33839",
  • "delivery_notes": "Don't ring bell",
  • "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": "67899767789"
}

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_auth(apikey_idapikey)
path Parameters
customer_id
required
string
Example: 56789687564

Customer identifier, numeric only

query Parameters
profile_id
string
Example: profile_id=78965743785967

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

Delete Customer Address

Deletes a customer's address

libmonetra KVS equivalent for endpoint

  • action_admin = customer_del
  • customer_del = customer_address
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
customer_id
required
string
Example: 56789687564

Customer identifier, numeric only

id
required
string
Example: 67899767789

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

Edit Customer Address

Edits an existing customer's address

libmonetra KVS equivalent for endpoint

  • action_admin = customer_edit
  • customer_edit = customer_address
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
customer_id
required
string
Example: 56789687564

Customer identifier, numeric only

id
required
string
Example: 67899767789

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*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "display_name": "James Dean",
  • "address1": "673 2nd St",
  • "address2": "STE 4",
  • "city": "Winter Haven",
  • "state": "FL",
  • "country": "USA",
  • "postal_code": "33839",
  • "delivery_notes": "Don't ring bell",
  • "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"
}

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_auth(apikey_idapikey)
path Parameters
customer_id
required
string
Example: 56789687564

Customer identifier, numeric only

id
required
string
Example: 67899767789

Customer address identifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

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": "67899767789",
  • "customer_id": "56789687564",
  • "display_name": "James Dean",
  • "address1": "673 2nd St",
  • "address2": "STE 4",
  • "city": "Winter Haven",
  • "state": "FL",
  • "country": "USA",
  • "postal_code": "33839",
  • "delivery_notes": "Don't ring bell",
  • "property1": "string",
  • "property2": "string"
}

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_auth(apikey_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": "78965743785967",
  • "bulk": "{ ... }"
}

Response samples

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

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

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_auth(apikey_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": "78965743785967",
  • "name": "Fruit",
  • "description": "Fruits",
  • "sortorder": "7"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "567896543",
  • "timestamp_ms": "1653340525"
}

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: name=Fruit

Name of the category

timestamp_ms
string
Example: timestamp_ms=1653408007

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

Delete Category

Delete an inventory category

The category must be empty.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = category_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 567896543

Unique ID of the category

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: timestamp_ms=1653340525

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

Edit Category

Edit an inventory category

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = category_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 567896543

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": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "name": "Fruit",
  • "description": "Fruits",
  • "sortorder": "7"
}

Response samples

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

Get Category Detail

Gets details for the specified category

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = category
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 567896543

Unique ID of the category

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: timestamp_ms=1653408007

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": "567896543",
  • "name": "Fruit",
  • "timestamp_ms": "1653340525",
  • "description": "Fruits",
  • "sortorder": "7",
  • "is_deleted": "no"
}

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.

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_auth(apikey_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": "78965743785967",
  • "category_id": "567896543",
  • "name": "$5 Off",
  • "description": "$5 off promotion",
  • "type": "fixed",
  • "usecase": "order",
  • "amount": "5.00",
  • "sortorder": "7"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "834678965675",
  • "timestamp_ms": "1653340525"
}

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: name=$5 Off

Name of the discount

category_id
string
Example: category_id=567896543

Unique ID of the product category

timestamp_ms
string
Example: timestamp_ms=1653408007

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

Delete Discount

Delete an inventory category discount

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = discount_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 834678965675

Unique ID of the discount

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: timestamp_ms=1653340525

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

Edit Discount

Edit an inventory category discount

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = discount_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 834678965675

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": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "name": "$5 Off",
  • "description": "$5 off promotion",
  • "type": "fixed",
  • "usecase": "order",
  • "amount": "5.00",
  • "sortorder": "7"
}

Response samples

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

Get Discount Detail

Gets details for the specified discount

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = discount
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 834678965675

Unique ID of the discount

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: timestamp_ms=1653408007

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": "834678965675",
  • "name": "$5 Off",
  • "timestamp_ms": "1653340525",
  • "category_id": "567896543",
  • "amount": "5.00",
  • "type": "fixed",
  • "usecase": "order",
  • "description": "$5 off promotion",
  • "sortorder": "7",
  • "is_deleted": "no"
}

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.

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_auth(apikey_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": "78965743785967",
  • "name": "Large pizza",
  • "category_id": "567896543",
  • "description": "A really big pizza",
  • "taxrates": "5654367654",
  • "modifiersets": "65789837657843,1456543456,14567876543",
  • "req_modifiersets": "6578943,456543",
  • "commoditycode": "50301700",
  • "unit": "1",
  • "sortorder": "7",
  • "image_data": "ABC="
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "6789646596763",
  • "timestamp_ms": "1653340525"
}

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: name=Large pizza

Name of the product

category_id
string
Example: category_id=567896543

Unique ID of the product category

timestamp_ms
string
Example: timestamp_ms=1653408007

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=no

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

Delete Product

Delete an inventory product

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = product_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 6789646596763

Unique ID of the product

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: timestamp_ms=1653340525

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

Edit Product

Edit an inventory product

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = product_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 6789646596763

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": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "name": "Large pizza",
  • "category_id": "567896543",
  • "description": "A really big pizza",
  • "taxrates": "5654367654",
  • "modifiersets": "65789837657843,1456543456,14567876543",
  • "req_modifiersets": "6578943,456543",
  • "commoditycode": "50301700",
  • "unit": "1",
  • "sortorder": "7",
  • "image_data": "ABC="
}

Response samples

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

Get Product Detail

Gets details for the specified product

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = product
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 6789646596763

Unique ID of the product

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: timestamp_ms=1653408007

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=no

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": "6789646596763",
  • "name": "Large pizza",
  • "timestamp_ms": "1653340525",
  • "category_id": "567896543",
  • "taxrates": "5654367654",
  • "modifiersets": "65789837657843,1456543456,14567876543",
  • "fractional_qty": "no",
  • "description": "A really big pizza",
  • "commoditycode": "50301700",
  • "unit": "1",
  • "req_modifiersets": "6578943,456543",
  • "sortorder": "7",
  • "image_type": "PNG",
  • "image_data": "ABC=",
  • "is_deleted": "no"
}

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.

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_auth(apikey_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": "78965743785967",
  • "product_id": "6789646596763",
  • "name": "Large hand tossed",
  • "price": "25.00",
  • "inventory": "unlimited",
  • "barcode": "015000071356",
  • "description": "Large hand tossed pizza",
  • "sortorder": "7"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "5784936543",
  • "timestamp_ms": "1653340525"
}

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: name=Large hand tossed

Name of the SKU

product_id
string
Example: product_id=6789646596763

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
Example: timestamp_ms=1653408007

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

Delete SKU

Delete an inventory product SKU

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = sku_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 5784936543

Unique ID of the SKU

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: timestamp_ms=1653340525

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

Edit SKU

Edit an inventory product SKU

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = sku_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 5784936543

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": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "name": "Large hand tossed",
  • "price": "25.00",
  • "inventory": "unlimited",
  • "barcode": "015000071356",
  • "description": "Large hand tossed pizza",
  • "sortorder": "7"
}

Response samples

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

Get SKU Detail

Gets details for the specified SKU

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = sku
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 5784936543

Unique ID of the SKU

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: timestamp_ms=1653408007

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": "5784936543",
  • "name": "Large hand tossed",
  • "timestamp_ms": "1653340525",
  • "product_id": "6789646596763",
  • "inventory": "unlimited",
  • "price": "25.00",
  • "in_stock": "yes",
  • "inventory_timestamp_ms": "1653421798000",
  • "barcode": "015000071356",
  • "description": "Large hand tossed pizza",
  • "sortorder": "7",
  • "is_deleted": "no"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 5784936543

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": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "cnt": "17"
}

Response samples

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

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.

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_auth(apikey_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": "78965743785967",
  • "name": "Toppings",
  • "description": "Pizza toppings",
  • "multiselect": "no",
  • "maxselect": "5"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "6756394857674839",
  • "timestamp_ms": "1653340525"
}

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: name=Toppings

Name of the modifier set

timestamp_ms
string
Example: timestamp_ms=1653408007

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

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 6756394857674839

Unique ID of the modifier set

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: timestamp_ms=1653340525

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

Edit Modifier Set

Edit an inventory modifier set

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifierset_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 6756394857674839

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": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "name": "Toppings",
  • "description": "Pizza toppings",
  • "multiselect": "no",
  • "maxselect": "5"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 6756394857674839

Unique ID of the modifier set

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: timestamp_ms=1653408007

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": "6756394857674839",
  • "name": "Toppings",
  • "timestamp_ms": "1653340525",
  • "description": "Pizza toppings",
  • "multiselect": "no",
  • "maxselect": "5",
  • "is_deleted": "no"
}

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.

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_auth(apikey_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": "78965743785967",
  • "modifierset_id": "6756394857674839",
  • "name": "Pepperoni",
  • "description": "Pepperoni pizza topping",
  • "price": "25.00",
  • "unit": "1",
  • "sortorder": "7"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "6789646596763",
  • "timestamp_ms": "1653340525"
}

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: name=Pepperoni

Name of the modifier

modifierset_id
string
Example: modifierset_id=6756394857674839

Unique ID of the modifier set

timestamp_ms
string
Example: timestamp_ms=1653408007

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

Delete Modifier

Delete an inventory modifier

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifier_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 39836566395734

Unique ID of the modifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: timestamp_ms=1653340525

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

Edit Modifier

Edit an inventory modifier

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifier_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 39836566395734

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": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "name": "Pepperoni",
  • "description": "Pepperoni pizza topping",
  • "price": "25.00",
  • "unit": "1",
  • "sortorder": "7"
}

Response samples

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

Get Modifier Detail

Gets details for the specified modifier

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = modifier
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 39836566395734

Unique ID of the modifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: timestamp_ms=1653408007

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": "39836566395734",
  • "name": "Pepperoni",
  • "timestamp_ms": "1653340525",
  • "modifierset_id": "6756394857674839",
  • "price": "25.00",
  • "description": "Pepperoni pizza topping",
  • "unit": "1",
  • "sortorder": "7",
  • "is_deleted": "no"
}

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.

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_auth(apikey_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": "78965743785967",
  • "name": "County tax",
  • "percentage": "1.254",
  • "default": "yes",
  • "roundmethod": "normal",
  • "sortorder": "7"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "65748376543",
  • "timestamp_ms": "1653340525"
}

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: name=County tax

Name of the tax rate

timestamp_ms
string
Example: timestamp_ms=1653408007

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

Delete Tax Rate

Delete an inventory tax rate

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = taxrate_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 65748376543

Unique ID of the tax rate

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: timestamp_ms=1653340525

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

Edit Tax Rate

Edit an inventory tax rate

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = taxrate_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 65748376543

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": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "name": "County tax",
  • "percentage": "1.254",
  • "default": "yes",
  • "roundmethod": "normal",
  • "sortorder": "7"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 65748376543

Unique ID of the tax rate

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: timestamp_ms=1653408007

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": "65748376543",
  • "name": "County tax",
  • "timestamp_ms": "1653340525",
  • "percentage": "1.254",
  • "default": "yes",
  • "roundmethod": "normal",
  • "sortorder": "7",
  • "is_deleted": "no"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 58445676543

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": "78965743785967",
  • "cancel_reason": "RETURN",
  • "timestamp_ms": "1653340525"
}

Response samples

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

Create an Order or Invoice

Create an order or invoice

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = order_add
Authorizations:
basic_auth(apikey_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 [0-9a-zA-Z]+

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.

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.

Max file size is 512 KB.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "type": "INVOICE",
  • "status": "OPEN",
  • "flags": "NOTIP",
  • "merch_status": "PREPARING",
  • "customer_id": "56789687564",
  • "ordernum": "A13DDES345",
  • "ponumber": "P4567",
  • "allowed_cardtypes": "VISA|MC|DISC",
  • "invoice_date": "+2 days",
  • "invoice_due": "+45 days",
  • "notes": "Gift wrap all items in order",
  • "total_tax_override": "0.07",
  • "ship_name": "Robert Redford",
  • "ship_address1": "244 90th Pl",
  • "ship_address2": "Unit 42",
  • "ship_city": "Orlando",
  • "ship_state": "FL",
  • "ship_zip": "32789",
  • "ship_country": "USA",
  • "ship_notes": "Leave with security",
  • "invoice_filename": "Invoice_Dean_4875.pdf",
  • "invoice_data": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "58445676543",
  • "timestamp_ms": "1653340525"
}

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: customer_id=54345,567043,31567

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.

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
Example: timestamp_create_bdate=1653406830

Start of order created date range as a timestamp

timestamp_create_edate
string
Example: timestamp_create_edate=1653406830

End of order created date range as a timestamp

timestamp_close_bdate
string
Example: timestamp_close_bdate=1653406830

Start of order closed date range as a timestamp

timestamp_close_edate
string
Example: timestamp_close_edate=1653406830

End of order closed date range as a timestamp

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

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
Example: timestamp_ms=1653408007

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

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 58445676543

Order identifier, numeric only

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: timestamp_ms=1653340525

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

Edit an Order or Invoice

Edit and order or invoice

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = order_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 58445676543

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 [0-9a-zA-Z]+

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.

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.

Max file size is 512 KB.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "type": "INVOICE",
  • "status": "OPEN",
  • "flags": "NOTIP",
  • "merch_status": "PREPARING",
  • "customer_id": "56789687564",
  • "ordernum": "A13DDES345",
  • "ponumber": "P4567",
  • "allowed_cardtypes": "VISA|MC|DISC",
  • "invoice_date": "+2 days",
  • "invoice_due": "+45 days",
  • "notes": "Gift wrap all items in order",
  • "total_tax_override": "0.07",
  • "ship_name": "Robert Redford",
  • "ship_address1": "244 90th Pl",
  • "ship_address2": "Unit 42",
  • "ship_city": "Orlando",
  • "ship_state": "FL",
  • "ship_zip": "32789",
  • "ship_country": "USA",
  • "ship_notes": "Leave with security",
  • "invoice_filename": "Invoice_Dean_4875.pdf",
  • "invoice_data": "string",
  • "timestamp_ms": "1653340525"
}

Response samples

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

Get Order Detail

Gets details for the specified order

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = orders
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 58445676543

Order identifier, numeric only

query Parameters
profile_id
string
Example: profile_id=78965743785967

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=no

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
Example: timestamp_ms=1653408007

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": "58445676543",
  • "timestamp_ms": "1653340525",
  • "user": "benny",
  • "id_base62": "1dPwZv08nt",
  • "type": "INVOICE",
  • "flags": "NOTIP",
  • "status": "OPEN",
  • "cancel_reason": "RETURN",
  • "merch_status": "PREPARING",
  • "customer_id": "56789687564",
  • "customer_display_name": "James Dean",
  • "ordernum": "A13DDES345",
  • "ponumber": "P4567",
  • "allowed_cardtypes": "VISA|MC|DISC",
  • "securitytoken": "x4TIeLxv",
  • "timestamp_create": "2022-05-24 15:06:13 -0400",
  • "timestamp_close": "2022-05-24 15:06:13 -0400",
  • "timestamp_sent": "2022-05-24 15:06:13 -0400",
  • "timestamp_viewed": "2022-05-24 15:06:13 -0400",
  • "invoice_date": "+2 days",
  • "invoice_due": "+45 days",
  • "taxrates": "5654367654",
  • "taxamounts": "1.02,0.49,0.22",
  • "total_amount": "155.34",
  • "total_tax": "5.04",
  • "total_discount": "15.00",
  • "total_paid": "155.34",
  • "total_tip": "0.50",
  • "total_amount_cash": "142.97",
  • "total_amount_noncash": "155.34",
  • "notes": "Gift wrap all items in order",
  • "total_tax_override": "0.07",
  • "ship_name": "Robert Redford",
  • "ship_address1": "244 90th Pl",
  • "ship_address2": "Unit 42",
  • "ship_city": "Orlando",
  • "ship_state": "FL",
  • "ship_zip": "32789",
  • "ship_country": "USA",
  • "ship_notes": "Leave with security",
  • "invoice_filename": "Invoice_Dean_4875.pdf",
  • "invoice_data": "string",
  • "is_deleted": "no"
}

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_auth(apikey_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": "78965743785967",
  • "bulk": "{ ... }"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

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": "78965743785967",
  • "ringorder": "2",
  • "qty": "1",
  • "amount": "199.95",
  • "taxrates": "5654367654",
  • "name": "Employee discount",
  • "productcode": "7456",
  • "commoditycode": "50301700",
  • "unit": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

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": "78965743785967",
  • "ringorder": "2",
  • "qty": "1",
  • "amount": "199.95",
  • "taxrates": "5654367654",
  • "name": "Employee discount",
  • "productcode": "7456",
  • "commoditycode": "50301700",
  • "unit": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

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": "78965743785967",
  • "ref_id": "765432",
  • "ringorder": "2",
  • "qty": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

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": "78965743785967",
  • "ref_id": "765432",
  • "ringorder": "2",
  • "qty": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

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

Edit a Discount

Edit a discount for an order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 67876547364567

Order discount identifier

order_id
required
string
Example: 58445676543

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": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "ringorder": "2",
  • "qty": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

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

Remove a Discount

Remove a discount form an order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 67876547364567

Order discount identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: timestamp_ms=1653340525

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

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_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

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": "78965743785967",
  • "ringorder": "2",
  • "qty": "1",
  • "amount": "199.95",
  • "taxrates": "5654367654",
  • "name": "Colored Pencils",
  • "productcode": "7456",
  • "commoditycode": "50301700",
  • "unit": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

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": "78965743785967",
  • "ref_id": "86956395206",
  • "ringorder": "2",
  • "qty": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: customer_id=54345,567043,31567

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.

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
Example: timestamp_create_bdate=1653406830

Start of order created date range as a timestamp

timestamp_create_edate
string
Example: timestamp_create_edate=1653406830

End of order created date range as a timestamp

timestamp_close_bdate
string
Example: timestamp_close_bdate=1653406830

Start of order closed date range as a timestamp

timestamp_close_edate
string
Example: timestamp_close_edate=1653406830

End of order closed date range as a timestamp

timestamp_ms
string
Example: timestamp_ms=1653408007

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

Edit an Item

Edit a line item for an order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

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": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "ringorder": "2",
  • "qty": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

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.

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
Example: timestamp_ms=1653408007

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": "58445676543",
  • "timestamp_ms": "1653340525",
  • "type": "ADDON",
  • "ringorder": "2",
  • "ref_id": "476543",
  • "qty": "1",
  • "amount": "19.92",
  • "total_modifiers": "string",
  • "total_mod_disc": "string",
  • "total_ord_disc": "string",
  • "taxrates": "5654367654",
  • "name": "Colored Pencils",
  • "productcode": "7456",
  • "commoditycode": "50301700",
  • "unit": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products",
  • "is_deleted": "no"
}

Remove an Item

Remove a line item form an order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: timestamp_ms=1653340525

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

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_auth(apikey_idapikey)
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

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": "78965743785967",
  • "ringorder": "2",
  • "qty": "1",
  • "amount": "199.95",
  • "name": "10% off"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

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": "78965743785967",
  • "ringorder": "2",
  • "qty": "1",
  • "amount": "199.95",
  • "name": "10% off"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

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": "78965743785967",
  • "ref_id": "15676543",
  • "ringorder": "2",
  • "qty": "1"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

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": "78965743785967",
  • "ref_id": "15676543",
  • "ringorder": "2",
  • "qty": "1"
}

Response samples

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

Edit an Item Discount

Edit a line item discount

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 24566437

Order item discount identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

item_id
required
string
Example: 785676543

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": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "ringorder": "2",
  • "qty": "1"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 24566437

Order item discount identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

item_id
required
string
Example: 785676543

Order item identifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: timestamp_ms=1653340525

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

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_auth(apikey_idapikey)
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

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": "78965743785967",
  • "ringorder": "2",
  • "qty": "1",
  • "amount": "199.95",
  • "name": "Extra veggies"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

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": "78965743785967",
  • "ref_id": "46789525",
  • "ringorder": "2",
  • "qty": "1"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: customer_id=54345,567043,31567

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.

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
Example: timestamp_create_bdate=1653406830

Start of order created date range as a timestamp

timestamp_create_edate
string
Example: timestamp_create_edate=1653406830

End of order created date range as a timestamp

timestamp_close_bdate
string
Example: timestamp_close_bdate=1653406830

Start of order closed date range as a timestamp

timestamp_close_edate
string
Example: timestamp_close_edate=1653406830

End of order closed date range as a timestamp

timestamp_ms
string
Example: timestamp_ms=1653408007

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

Edit an Item Modifier

Edit a line item modifier

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 63676598

Order item modifier identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

item_id
required
string
Example: 785676543

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": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "ringorder": "2",
  • "qty": "1"
}

Response samples

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

Get Item Modifier Detail

Gets details for the specified modifier

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = modifiers
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 63676598

Order item modifier identifier

item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: timestamp_ms=1653408007

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": "63676598",
  • "timestamp_ms": "1653340525",
  • "item_id": "785676543",
  • "order_id": "58445676543",
  • "type": "ADDON",
  • "ringorder": "2",
  • "ref_id": "6786567",
  • "qty": "1",
  • "amount": "19.92",
  • "name": "Pepperoni",
  • "is_deleted": "no"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 63676598

Order item modifier identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

item_id
required
string
Example: 785676543

Order item identifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: timestamp_ms=1653340525

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

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_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

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": "78965743785967",
  • "amount": "19.92",
  • "tip": "0.33"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

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": "78965743785967",
  • "amount": "19.92",
  • "tip": "0.33",
  • "checknum": "45678"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

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": "78965743785967",
  • "ttid": "96748596765467"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: customer_id=54345,567043,31567

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.

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
Example: timestamp_create_bdate=1653406830

Start of order created date range as a timestamp

timestamp_create_edate
string
Example: timestamp_create_edate=1653406830

End of order created date range as a timestamp

timestamp_close_bdate
string
Example: timestamp_close_bdate=1653406830

Start of order closed date range as a timestamp

timestamp_close_edate
string
Example: timestamp_close_edate=1653406830

End of order closed date range as a timestamp

timestamp_ms
string
Example: timestamp_ms=1653408007

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

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 987653645678

Unique ID of a payment for an order

order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

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

Get Payment Detail

Gets details for the specified payment

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = payments
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 987653645678

Unique ID of a payment for an order

order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

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": "987653645678",
  • "timestamp_ms": "1653340525",
  • "user": "benny",
  • "order_id": "58445676543",
  • "tendertype": "TXN",
  • "amount": "19.92",
  • "tip": "0.33",
  • "status": "OPEN",
  • "ttid": "96748596765467",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "cardtype": "VISA",
  • "last4": "5454",
  • "cardholdername": "John Doe",
  • "checknum": "45678",
  • "is_deleted": "no"
}

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: id=56789687564

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: id=56789687564

Customer identifier

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

limit
string
Example: limit=4

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: id=67876547364567

Order discount identifier

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

limit
string
Example: limit=4

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: id=63676598

Order item modifier identifier

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

limit
string
Example: limit=4

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: id=67876547364567

Order discount identifier

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

limit
string
Example: limit=4

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: id=6789646596763

Unique ID of the product

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

limit
string
Example: limit=4

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: id=5784936543

Unique ID of the SKU

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

limit
string
Example: limit=4

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: id=65748376543

Unique ID of the tax rate

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: id=65748376543

Unique ID of the tax rate

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

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

Hosted Paypage

The hosted payment page is a page provided by Monetra associated with a profile which can take blind payments. Anyone with the link (which is not in any way specific to the customer) can make a payment.

Typically, when using the hosted payment page, customers will be asked to enter a customer identifier for the payment. Such as an invoice number, customer number, patient number, etc. Since this is free form and provided by the customer, with no validation, there is a high likelihood of incorrect information being entered. Regular reconciliation with manual matching of payments to customers is necessary.

This is not a recommended method to request payments from customers. While this method of payment is popular with many merchants due to its ease of deployment, it should be avoided if possible. This payment method is ideally suited for one off semi-anonymous donations.

Alternatives

It's highly recommended one of the alternatives below are used instead of the hosted payment page. The hosted payment page should only be used in limited circumstances.

Secure iFrame

Using Monetra's secure iFrame is a good choice and allows the merchant to integrate payment information collection directly into their web site. The payment information is sent directly to Monetra and is never handled by the merchant's web server.

This prevents credit card data from ever touching the merchant's systems, while allowing customers to complete seamless ecommerce transactions on the merchant's website.

This is ideal for merchants using a shopping cart style checkout. Or who have their own invoice billing system.

Invoice system

Monetra supports an integrated invoice system. This allows the creation of invoices which can then be sent to the customer. The customer can be sent a link to pay the invoice. The customer will interact solely with Monetra for paying the invoice. Thereby ensuring the merchant never has to collect payment information directly.

Due to each customer having a unique payment link there is no confusion about which customer is making a payment. Also, the merchant can be automatically notified about successfully paid invoices. Further, it is very easy to see which invoices are outstanding or have been paid.

This is a secure payment method and allows detailed information about the order. It can be used in conduction with external invoicing systems for the payment portion. The merchant's invoice system will generate the invoice which can then be attached as a PDF to the Monetra's invoice. Monetra's invoice will be sent to the customer who will then make their payment and receive their invoice PDF that was generated by the merchant's system. Reconciliation is still necessary to mark invoices as paid in the merchant's system.

Merchants who use an invoice instead of checkout payment flow are ideal candidates for this method. Especially those who either do not have their own invoice system or who do not want payments going through their invoice system.

Possible fraud

Another major issue with using the hosted payment page is the potential for fraud. The page is not unique to a customer or order, nor are payments authenticated. This can lead to abuse of the page to facilitate fraud.

Mitigation measures

To prevent this several fraud methods prevention rules must be in place for each page:

  1. The maximum number of transactions that are allowed within a single calendar day.
  2. The maximum amount of money that can be submitted per payment.
  3. The maximum total aggregate amount of money that can be collected by the page within a single calendar day.
  4. The page is protected by a captcha.

The totals for each of these is tracked on a per attempt basis. Regardless if the payment is authorized or declined.

In all cases the merchant will be charged standard transaction fees and can incur a large number of chargebacks.

If fraud is a concern, the iFrame or invoice or another secure system should be used.

Types of fraud

This is a non-exhaustive list of the types of fraud that can take place when a hosted payment page is abused.

Carding

In this case, a fraudster will use the page to test stolen credit cards. The fraudster will use the outcome of approved or declined to determine if the card information they have is valid. Approved cards are valid and declined cards are not.

Fee abuse

Attackers know that merchants pay processing fees for each payment. They also know that merchant's are charged when a customer wins a chargeback dispute. Which is nearly 100% of the time in stolen card situations. Further, the merchant will most likely need to issue refunds for the fraudulent transactions which also have a fee to process.

The goal is to cause harm to the merchant through a monetary loss. This loss can be signification, especially for smaller merchants.

Damage to reputation

If a merchant accepts fraudulent payments the merchant's reputation may be damaged. The merchant is often blamed for not taking adequate steps in order to protect the public and prevent fraud form occurring. Anger toward the merchant can be compounded if there are a large number of fraudulent charges. Trust in the merchant may be reduced which can result in potential customers deciding to use the merchant's competitors.

Processing account closure

There are multiple entities that can be involved in payment processing. For example, gateway, processor, card brand. Each of these entities have fraud tolerance levels associated with their merchants. If the amount of fraud associated with a merchant exceeds these limits one or more of these entities may discontinue service to the merchant.

This will cause disruption to the merchant because they will be unable to accept payments for a period of time. They will need to establish a new processing account with another provider. This could entail integration work if the merchant needs to use a different gateway which uses a different processing protocol. Leading to more time the merchant will be unable to accept payments.

Further, merchants who have their processing accounts closed due to excessive fraud may be viewed as higher risk by other processing companies. They may find it difficult to open a new account or potentially need to pay higher fees.

Amount alteration

The page can have the amount specified either as a fixed amount associated with the page configuration, an amount passed into the page as a parameter by the merchant, or editable by the customer. When editable, the amount is either passed into the page by the merchant or left empty for the customer to fill in.

In cases where the amount is not configured for the page as a fixed amount, and the amount is not set as editable. The merchant must provide the amount was a parameter. In this situation the amount used to run the payment is the amount submitted by the page. While the amount is not editable, this is visually only. The customer an use a developer tool, that is built into nearly all web browsers, and still edit the amount. There is no way to prevent this.

It is imperative when payments are reconciled, not only the customer identifier but also the amount is verified. If the amount is not verified during reconciliation, the customer may be able to pay less than requested and still have their "invoice" considered fully paid.

Pre-filled data

Fields on the page can be pre-filled when the page is requested. This is useful if some information is already known. Such as an order number. This prevents the customer from having to type this information into the form.

Payment information cannot be pre-filled because the merchant should not have that information. Otherwise use of the hosted payment page would be unnecessary.

Merchant custom fields as well as the following can be passed into the page as either query arguments with a GET request or as body parameters with a POST request.

  • amount
  • cardholdername
  • street
  • zip
  • email
  • comments
  • ordernum
  • custref

If a field is not listed as shown on the page, and is passed into the page as a parameter, the field and it's value will be present when the form is submitted. A field does not have to be listed as shown to be pre-filled and received as part of the payment.

Note, providing any field that is not a merchant customer field or in the above list will result in an error.

Customer email

Customers are required to provide an email address which will automatically generate an email for approved transactions.

Page error codes

The page does not provide descriptive error text and instead provides error codes. The customer not the merchant is the one using the page making a number of possible errors not something the customer would care to know the details. The possible error codes are as follows

  • F902 - Failed to load failure page template
  • F903 - Failed to run failure page template
  • F904 - Failed to load result page template
  • F905 - Failed to run result page template
  • P401 - Redirect URL missing
  • L600 - Failed to load page template
  • L601 - Failed to run page template
  • P444 - Request parse failed
  • E300 - Generic failure
  • C100 - Network error getting captcha response
  • C101 - HTTP response error getting captcha response
  • C200 - Failed to parse captcha response JSON
  • C201 - Captcha response was not successful
  • C202 - Captcha indicates incorrect action
  • C203 - Captcha challenge time outside allowed window
  • C204 - Captcha score lower than minimum allowed
  • P600 - Page id does not exist
  • D599 - Could not load page configuration
  • D460 - Restriction failed
  • D462 - Required field data missing or not shown and editable
  • D463 - Required field data missing
  • D464 - Input parameter not allowed
  • D465 - Amount should not be specified
  • D466 - Input parameter not allowed
  • D467 - Missing amount and not customer editable
  • C205 - System not configured for captcha
  • C206 - Captcha response not present in data
  • C207 - Customer's IP not present in data
  • C208 - Captcha verification request could not be created
  • C209 - Captcha verification request failed to send

Create a hosted paypage page

Create a hosted paypage page

This defines the page configuration and how it will act when presented to the customer.

libmonetra KVS equivalent for endpoint

  • action_admin = hosted_paypage
  • hosted_paypage = add
Authorizations:
basic_auth(apikey_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.

descr
string

Description of the page to know what it is used for

trantype
required
string
Enum: "sale" "preauth"

Transaction type the paypage should use for authorization

Values:

  • sale - Purchase transaction
  • preauth - Preauthorization transaction. Will need to be completed to receive funds
allowed_cardtypes
string
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "GIFT" "CUP" "ACH"

Allowed Cardtypes

Pipe (|) separated.

Cardtypes that can be accepted on the hosted paypage page. If not specified, all cardtypes supported by the profile will be allowed.

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
  • GIFT - Private label Gift. Not cards backed by a credit card brand such as Visa, Mastercard, etc.
  • CUP - China Union Pay credit
  • ACH - Bank transfer
amount
string\d*(\.\d{0,2})?

Fixed amount the hosted paypage should always use

The customer will not be able to change the amount and an amount cannot be passed in as a parameter when requesting the page to be displayed.

fields_shown
string

Fields that should be shown on the hosted paypage

Payment information fields do not need to be defined here because they are always shown.

Comma delimited list of field names.

Fields allowed:

  • comments
  • ordernum
  • custref

Additionally merchant custom fields can be included in this list.

Shown fields can be used to allow customers to enter additional information. Such as an order number. It can also be used to display information to the customer. If a field is not marked as editable.

fields_editable
string

Fields that should be editable on the hosted paypage

Payment information fields do not need to be defined here because they are always shown.

Comma delimited list of field names. Only applied to fields that are shown. amount must be included here if the amount should be editable.

If the amount is fixed, it cannot be edited. Otherwise, if amount is not editiable it must be passed into the page upon request.

fields_required
string

Fields that should be requried on the hosted paypage

Payment information fields do not need to be defined here because they are always required.

Comma delimited list of field names. If a field is not listed as shown or editable, the field and value must be passed to the page when it is requested. Either as query arguments or POST arguments.

fields_returned
string

Fields that should be returned as part of the redirect back to the merchant after page processing

Comma delimited list of field names.

This is response fields that Monetra will return from purchase or pre-authorization requests. Only some response fields can be returned.

Response fields that can be returned:

  • code
  • msoft_code
  • phard_code
  • auth
  • issuer_decline
  • timestamp
  • ttid

Some input parameters can be returned.

Request fields that can be returend:

  • amount
  • cardholdername
  • street
  • zip
  • email
  • comments
  • ordernum
  • custref

Additionally merchant custom fields as defined on the profile can be returned as part of the response if they were provided as part of the request.

These fields and their value will be returned as query arguments with the GET request to the merchant's web site. Note that these fields will be visible to the customer in the redirect URL. Also, note the customer could refresh the page causing multiple GET requests to be submitted. This should be used for informational purposes and not as a way to determine if a payment was made.

fee_type
string
Enum: "none" "percent" "amount"

Fee type (if any) that should be assessed as part of the payment

Values:

  • none - No fee will be accessed
  • percent - Fee is a percentage
  • amount - Fee is a fixed dollar amount
fee_title
string

Description of the fee to show the customer

The text should be short can clear that a fee is being accessed. If a title is not provided a default title of "Processing fee" will be used.

This field is only used if a fee is being accessed.

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

Fee to be assessed if use of the hosted payment page charges a fee.

The fee can be up to 2 decimal digits. The type of fee, percent or fixed amount, is determined by the fee_type parameter.

Percentages are percentage values and should not be normalized to a decimal.

E.g values:

  • 1 = 1%
  • 10 = 10%
  • 2.54 = 2.54%

Fixed amounts are fixed amounts of dollars and cents.

E.g values:

  • 1 = $1
  • 10 = $10
  • 2.54 = $2.54
max_count
required
string

Maximum number of transactions that can be processed within a day.

This is to prevent abuse of the hosted paypage page and prevent fraudulent actives, such as carding. If this number of transactions (attempted, authorized, or declined) is exceeded, the page will not process any further requests that day.

If set to 0, then no transactions can process for the page and effectively disables its use.

The maximum should be based on the estimated number of transactions that will be processed per day.

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

Maximum amount of a single transaction that can be processed by the page

This is to prevent abuse of the hosted paypage page and prevent fraudulent actives, such as attempting to have large fees accessed by initiating fraudulent charges that will be disputed later.

If set to 0, then no transactions can process for the page and effectively disables its use.

The maximum should be based on the estimated largest transaction amount that will be processed by the page.

If a fixed page amount is configured, this should be set to the same value.

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

Maximum amount of all attempted transactions that can be processed within a day

This is the total of all the amounts of attempted transactions once added together. For example, txn a for $4, txn b for $9, txn c for $12 = a total of $25. If the maximum is set to $15 then txn c would not be accepted because it would exceed the maximum total amount.

This is to prevent abuse of the hosted paypage page and prevent fraudulent actives, such as attempting to have large fees accessed by initiating fraudulent charges that will be disputed later.

If set to 0, then no transactions can process for the page and effectively disables its use.

The maximum should be based on the estimated total amount of attempted payments. The total is based on attempted, authorized, and declined transactions.

redirect_url
string

URL to redirect the customer to after processing

This should be a URL to the merchant's web site. Any returned fields will be added to the URL as query parameters when redirecting the customer.

terms_url
required
string

URL to the merchant's terms and conditions

privacy_url
required
string

URL to the merchant's privacy policy

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "descr": "$50 donation button",
  • "trantype": "sale",
  • "allowed_cardtypes": "VISA|MC",
  • "amount": "19.92",
  • "fields_shown": "string",
  • "fields_editable": "string",
  • "fields_required": "string",
  • "fields_returned": "string",
  • "fee_type": "none",
  • "fee_title": "Processing Fee",
  • "fee_value": "19.92",
  • "max_count": "1000",
  • "max_amount": "51.48",
  • "max_total_amount": "19500.77",
  • "redirect_url": "string",
  • "terms_url": "string",
  • "privacy_url": "string"
}

Response samples

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

List Hosted Paypage Pages

List hosted paypage pages

The resulting report will contain these headers:

id, profile_id, group_id, descr, trantype, fee_type, amount, fields_shown,
fields_editable, fields_returned, max_count, max_amount,
max_total_amount, total_count, total_amount, last_payment_ts,
redirect_url, terms_url, privacy_url, fee_value, fee_title

libmonetra KVS equivalent for endpoint

  • action_admin = hosted_paypage
  • hosted_paypage = list
Authorizations:
basic_auth(apikey_idapikey)

Responses

Request samples 

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

Response samples

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

Delete an Hosted Payment Page

Delete a payment page configuration

Once deleted the page will no longer be usable.

libmonetra KVS equivalent for endpoint

  • action_admin = hosted_paypage
  • hosted_paypage = del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 987653645678

Unique ID of a hosted paypage page

Responses

Request samples 

curl -X DELETE 'https://testbox.monetra.com/api/v2/paypage/hosted/767562957658' --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 a hosted paypage page

Edit a hosted paypage page

libmonetra KVS equivalent for endpoint

  • action_admin = hosted_paypage
  • hosted_paypage = edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 987653645678

Unique ID of a hosted paypage page

Request Body schema: application/json
descr
string

Description of the page to know what it is used for

trantype
string
Enum: "sale" "preauth"

Transaction type the paypage should use for authorization

Values:

  • sale - Purchase transaction
  • preauth - Preauthorization transaction. Will need to be completed to receive funds
allowed_cardtypes
string
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "GIFT" "CUP" "ACH"

Allowed Cardtypes

Pipe (|) separated.

Cardtypes that can be accepted on the hosted paypage page. If not specified, all cardtypes supported by the profile will be allowed.

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
  • GIFT - Private label Gift. Not cards backed by a credit card brand such as Visa, Mastercard, etc.
  • CUP - China Union Pay credit
  • ACH - Bank transfer
amount
string\d*(\.\d{0,2})?

Fixed amount the hosted paypage should always use

The customer will not be able to change the amount and an amount cannot be passed in as a parameter when requesting the page to be displayed.

fields_shown
string

Fields that should be shown on the hosted paypage

Payment information fields do not need to be defined here because they are always shown.

Comma delimited list of field names.

Fields allowed:

  • comments
  • ordernum
  • custref

Additionally merchant custom fields can be included in this list.

Shown fields can be used to allow customers to enter additional information. Such as an order number. It can also be used to display information to the customer. If a field is not marked as editable.

fields_editable
string

Fields that should be editable on the hosted paypage

Payment information fields do not need to be defined here because they are always shown.

Comma delimited list of field names. Only applied to fields that are shown. amount must be included here if the amount should be editable.

If the amount is fixed, it cannot be edited. Otherwise, if amount is not editiable it must be passed into the page upon request.

fields_required
string

Fields that should be requried on the hosted paypage

Payment information fields do not need to be defined here because they are always required.

Comma delimited list of field names. If a field is not listed as shown or editable, the field and value must be passed to the page when it is requested. Either as query arguments or POST arguments.

fields_returned
string

Fields that should be returned as part of the redirect back to the merchant after page processing

Comma delimited list of field names.

This is response fields that Monetra will return from purchase or pre-authorization requests. Only some response fields can be returned.

Response fields that can be returned:

  • code
  • msoft_code
  • phard_code
  • auth
  • issuer_decline
  • timestamp
  • ttid

Some input parameters can be returned.

Request fields that can be returend:

  • amount
  • cardholdername
  • street
  • zip
  • email
  • comments
  • ordernum
  • custref

Additionally merchant custom fields as defined on the profile can be returned as part of the response if they were provided as part of the request.

These fields and their value will be returned as query arguments with the GET request to the merchant's web site. Note that these fields will be visible to the customer in the redirect URL. Also, note the customer could refresh the page causing multiple GET requests to be submitted. This should be used for informational purposes and not as a way to determine if a payment was made.

fee_type
string
Enum: "none" "percent" "amount"

Fee type (if any) that should be assessed as part of the payment

Values:

  • none - No fee will be accessed
  • percent - Fee is a percentage
  • amount - Fee is a fixed dollar amount
fee_title
string

Description of the fee to show the customer

The text should be short can clear that a fee is being accessed. If a title is not provided a default title of "Processing fee" will be used.

This field is only used if a fee is being accessed.

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

Fee to be assessed if use of the hosted payment page charges a fee.

The fee can be up to 2 decimal digits. The type of fee, percent or fixed amount, is determined by the fee_type parameter.

Percentages are percentage values and should not be normalized to a decimal.

E.g values:

  • 1 = 1%
  • 10 = 10%
  • 2.54 = 2.54%

Fixed amounts are fixed amounts of dollars and cents.

E.g values:

  • 1 = $1
  • 10 = $10
  • 2.54 = $2.54
max_count
string

Maximum number of transactions that can be processed within a day.

This is to prevent abuse of the hosted paypage page and prevent fraudulent actives, such as carding. If this number of transactions (attempted, authorized, or declined) is exceeded, the page will not process any further requests that day.

If set to 0, then no transactions can process for the page and effectively disables its use.

The maximum should be based on the estimated number of transactions that will be processed per day.

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

Maximum amount of a single transaction that can be processed by the page

This is to prevent abuse of the hosted paypage page and prevent fraudulent actives, such as attempting to have large fees accessed by initiating fraudulent charges that will be disputed later.

If set to 0, then no transactions can process for the page and effectively disables its use.

The maximum should be based on the estimated largest transaction amount that will be processed by the page.

If a fixed page amount is configured, this should be set to the same value.

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

Maximum amount of all attempted transactions that can be processed within a day

This is the total of all the amounts of attempted transactions once added together. For example, txn a for $4, txn b for $9, txn c for $12 = a total of $25. If the maximum is set to $15 then txn c would not be accepted because it would exceed the maximum total amount.

This is to prevent abuse of the hosted paypage page and prevent fraudulent actives, such as attempting to have large fees accessed by initiating fraudulent charges that will be disputed later.

If set to 0, then no transactions can process for the page and effectively disables its use.

The maximum should be based on the estimated total amount of attempted payments. The total is based on attempted, authorized, and declined transactions.

redirect_url
string

URL to redirect the customer to after processing

This should be a URL to the merchant's web site. Any returned fields will be added to the URL as query parameters when redirecting the customer.

terms_url
string

URL to the merchant's terms and conditions

privacy_url
string

URL to the merchant's privacy policy

Responses

Request samples

Content type
application/json
{
  • "descr": "$50 donation button",
  • "trantype": "sale",
  • "allowed_cardtypes": "VISA|MC",
  • "amount": "19.92",
  • "fields_shown": "string",
  • "fields_editable": "string",
  • "fields_required": "string",
  • "fields_returned": "string",
  • "fee_type": "none",
  • "fee_title": "Processing Fee",
  • "fee_value": "19.92",
  • "max_count": "1000",
  • "max_amount": "51.48",
  • "max_total_amount": "19500.77",
  • "redirect_url": "string",
  • "terms_url": "string",
  • "privacy_url": "string"
}

Response samples

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

Get Hosted Paypage Page Detail

Get details for the specified hosted paypage page

libmonetra KVS equivalent for endpoint

  • action_admin = hosted_paypage
  • hosted_paypage = list
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 987653645678

Unique ID of a hosted paypage page

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "id": "987653645678",
  • "profile_id": "78965743785967",
  • "group_id": "36789654543",
  • "descr": "$50 donation button",
  • "trantype": "sale",
  • "allowed_cardtypes": "VISA|MC",
  • "amount": "19.92",
  • "fields_shown": "string",
  • "fields_editable": "string",
  • "fields_required": "string",
  • "fields_returned": "string",
  • "fee_type": "none",
  • "fee_title": "Processing Fee",
  • "fee_value": "19.92",
  • "max_count": "1000",
  • "max_amount": "51.48",
  • "max_total_amount": "19500.77",
  • "total_count": "string",
  • "total_amount": "string",
  • "redirect_url": "string",
  • "terms_url": "string",
  • "privacy_url": "string"
}

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_auth(apikey_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
Default: "no"
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": "5678967654",
  • "user": "user2",
  • "pwd": "sTnn56Wve79&#%q#K4GF9Z",
  • "temporary": "yes"
}

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_auth(apikey_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.

When searching allows filtering by users that share a given default profile id.

email
string <= 128 characters

email

flags
string
Enum: "UNATTENDED" "SELFVIEWONLY" "MFA" "ALLOW_UNLINKED_REFUND" "ALLOW_GROUP_APIKEYS" "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
  • ALLOW_GROUP_APIKEYS - Allow creation API keys representing groups.
  • 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 the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

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 the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

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 statistics
  • 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: "ALL" "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 the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

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
  • 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: "ALL" "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 the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

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
  • 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": "user2",
  • "pwd": "sTnn56Wve79&#%q#K4GF9Z",
  • "group_id": "36789654543",
  • "default_profile_id": "7584476584356",
  • "email": "email@email",
  • "flags": "MFA|ALLOW_UNLINKED_REFUND|RESET_PEER_PASSWD",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "ALL",
  • "trans_perms": "ALL",
  • "name": "Alan Alda",
  • "phone_mobile": "555-555-5555"
}

Response samples

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

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_auth(apikey_idapikey)
query Parameters
id
string
Example: id=5678967654

Conditional. User id of user to operate on, if not provided, user is required

Cannot be combined with:

  • user
user
string
Example: user=user2

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

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_auth(apikey_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.

When searching allows filtering by users that share a given default profile id.

email
string <= 128 characters

email

flags
string
Enum: "UNATTENDED" "SELFVIEWONLY" "MFA" "ALLOW_UNLINKED_REFUND" "ALLOW_GROUP_APIKEYS" "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
  • ALLOW_GROUP_APIKEYS - Allow creation API keys representing groups.
  • 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 the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

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 the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

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 statistics
  • 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: "ALL" "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 the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

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
  • 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: "ALL" "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 the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

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
  • 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": "5678967654",
  • "user": "user2",
  • "default_profile_id": "7584476584356",
  • "email": "email@email",
  • "flags": "MFA|ALLOW_UNLINKED_REFUND|RESET_PEER_PASSWD",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "ALL",
  • "trans_perms": "ALL",
  • "name": "Alan Alda",
  • "phone_mobile": "555-555-5555"
}

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_auth(apikey_idapikey)
query Parameters
id
string
Example: id=5678967654

Query a specific user id

Cannot be combined with:

  • user
user
string
Example: user=user2

Query a specific user by name

Cannot be combined with:

  • id
default_profile_id
string
Example: default_profile_id=7584476584356

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.

When searching allows filtering by users that share a given default profile id.

flags
object
Enum: "UNATTENDED" "SELFVIEWONLY" "MFA" "ALLOW_UNLINKED_REFUND" "ALLOW_GROUP_APIKEYS" "RESET_PEER_PASSWD"
Example: flags=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
  • ALLOW_GROUP_APIKEYS - Allow creation API keys representing groups.
  • RESET_PEER_PASSWD - The user is allowed to change the password of a peer that has less than or equal permissions
status
object
Enum: "ACTIVE" "DISABLED" "LOCKED"
Example: status=ACTIVE

Status of the user

Values:

  • ACTIVE - User is active and can process
  • DISABLED - User is disabled and cannot process
  • LOCKED - User is disabled and cannot process
group_id
string
Example: group_id=36789654543

Query starting at a specific group id, if not specified, defaults to user's group id.

maxdepth
string
Example: maxdepth=4

Maximum depth to display

Default is unlimited. Specify 1 to see only self and children.

search
string

Will perform a substring search across multiple fields

phone_mobile
string
Example: phone_mobile=555-555-5555

Mobile phone

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

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_auth(apikey_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": "5678967654",
  • "user": "user2"
}

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_auth(apikey_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": "5678967654",
  • "user": "user2"
}

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_auth(apikey_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": "4676",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "ALL",
  • "trans_perms": "ALL"
}

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_auth(apikey_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": "5678967654",
  • "group_id": "36789654543"
}

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_auth(apikey_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": "5678967654",
  • "user": "user2"
}

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": "555-555-5555",
  • "email": "email@email"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "key": "otpauth://totp/Super%20ISO:doug?secret=WZA5UAPCTESR3IR6&algorithm=SHA1&digits=6&period=30&issuer=Payment%20Server"
}

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

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "key": "676574637485697",
  • "expire_ts": "2022-05-24 15:06:13 -0400"
}

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_auth(apikey_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": "5678967654",
  • "user": "user2"
}

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.

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_auth(apikey_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": "Question 1?",
  • "question2": "Question 2?",
  • "question3": "Question 3?",
  • "answer1": "Answer 1",
  • "answer2": "Answer 2",
  • "answer3": "Answer 3"
}

Response samples

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

Edit Security Questions

Edit security questions

libmonetra KVS equivalent for endpoint

  • action_sys = security_questions
  • security_questions = edit
Authorizations:
basic_auth(apikey_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": "Question 1?",
  • "question2": "Question 2?",
  • "question3": "Question 3?",
  • "answer1": "Answer 1",
  • "answer2": "Answer 2",
  • "answer3": "Answer 3"
}

Response samples

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

List Security Questions

List security questions

libmonetra KVS equivalent for endpoint

  • action_sys = security_questions
  • security_questions = list
Authorizations:
basic_auth(apikey_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": "Question 1?",
  • "question2": "Question 2?",
  • "question3": "Question 3?",
  • "created_ts": "2022-05-24 15:06:13 -0400",
  • "upd_ts": "2022-05-24 15:06:13 -0400"
}

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 password.

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=SMS

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

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "question1": "Question 1?",
  • "question2": "Question 2?",
  • "question3": "Question 3?"
}

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": "46602473",
  • "answer1": "Answer 1",
  • "answer2": "Answer 2",
  • "answer3": "Answer 3"
}

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
Example: username=user1

The username to perform a reset operation on

method
required
object
Enum: "EMAIL" "SMS"
Example: method=SMS

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": "user1",
  • "reset_code": "46602473"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "question1": "Question 1?",
  • "question2": "Question 2?",
  • "question3": "Question 3?",
  • "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": "user1",
  • "reset_code": "46602473",
  • "answer1": "Answer 1",
  • "answer2": "Answer 2",
  • "answer3": "Answer 3",
  • "pwd": "sTnn56Wve79&#%q#K4GF9Z",
  • "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.

A group API key is primarily intended for integrations that need wide ranging automated reporting. For example, a group representing a company may want to have sales reports generated at the end of each day across all sub-groups and profiles. sub-groups could be franchise locations, for example. The group API key will allow the integration to be able to access this data. It would be inadvisable to use a user key in this situation because the key will be invalidated if the user ever leaves the company. Group API keys must be limited to the minimum permissions necessary to accomplish the integration requirements. Often this involves only some action_sys actions.

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.

API Key Detail

Get API Keys Details

libmonetra KVS equivalent for endpoint

  • action_sys = apikeys
  • apikeys = list
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
apikey_id
required
string
Example: 96785456789765

API key id

Used in conjunction with apikey_secret

query Parameters
profile_id
string
Example: profile_id=78965743785967

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": "96785456789765",
  • "type": "user",
  • "group_id": "36789654543",
  • "name": "POS Key 54-5",
  • "user_id": "977564336543",
  • "profile_id": "65433565432",
  • "flags": "EXTEND_ON_USE",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "ALL",
  • "trans_perms": "ALL",
  • "created_uid": "78654356",
  • "created_ts": "2022-05-24 15:06:13 -0400",
  • "last_used_ts": "2022-05-24 15:06:13 -0400",
  • "expire_ts": "2022-05-24 15:06:13 -0400",
  • "extend_sec": "180",
  • "descr": "Unattended POS key. Store 54 POS station 5"
}

Remove API Key

Deletes an API Key

libmonetra KVS equivalent for endpoint

  • action_sys = apikeys
  • apikeys = del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
apikey_id
required
string
Example: 96785456789765

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

Create API Key

Creates an API Key

There are three key types that can be created, user, profile, and group. A user key represents the user. A profile key represents a profile. A group key represents a group.

Allowed:

  • A user can create user keys for themselves.
  • A user can create profile keys for any profile they have access to.
  • A user can create group keys for any group they have access to if they havei the user flag ALLOW_GROUP_APIKEYS.
  • A user key can create profile keys for any profiles they have access to.

Disallowed:

  • A user cannot create user keys for other users.
  • A user key cannot create user keys.
  • A profile key cannot create either user or profile keys.
  • A group key cannot create either user keys.

Up to 100 API keys can be created per user, per profile or per group.

libmonetra KVS equivalent for endpoint

  • action_sys = apikeys
  • apikeys = add
Authorizations:
basic_auth
Request Body schema: application/json
type
required
string
Enum: "user" "profile" "group"

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 default profile id for the current user.
  • group - key represents a group
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_REFUND"

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. Extension is based on expiration lifetime. 30 days, will update once per day. 24 hrs, will update once per hour. 1 hr will update once per minute. Less than 1 hour will update every 10 s.
  • ALLOW_UNLINKED_REFUND - 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 the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

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 the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

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 statistics
  • 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: "ALL" "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 the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

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
  • 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: "ALL" "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 the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

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
  • 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": "POS Key 54-5",
  • "descr": "Unattended POS key. Store 54 POS station 5",
  • "flags": "EXTEND_ON_USE",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "ALL",
  • "trans_perms": "ALL",
  • "expire_sec": "3600",
  • "profile_id": "78965743785967"
}

Response samples

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

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: user_id=67869543676543

User identifier

group_id
string
Example: group_id=36789654543

Group identifier

name
string
Example: name=POS Key 54-5

API Key name

maxdepth
string
Example: maxdepth=4

Maximum depth to display

Default is top level only. Specify 1 to see only self and children.

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

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.

Create a Group

Creates a Group

libmonetra KVS equivalent for endpoint

  • action_sys = group_add
Authorizations:
basic_auth(apikey_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 the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

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 the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

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 statistics
  • 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: "ALL" "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 the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

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
  • 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: "ALL" "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 the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

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

Transaction results under this group will be included in push notifications for the corresponding push notification id.

ID returned from action_sys=pushnotification,pushnotification=add. Only allowed to be specified if flags contains PUSH_NOTIFICATION

custom_customer_fields
string

Comma separated list of custom fields to be stored with customers

Not allowed to be set if parent group has SHARE_TOKENS enabled.

company
string

Company name of group owner

gateway_name
string

Name of the gateway product

This is the name of the gateway product the merchant is using. This differs from the Company Name. For example, the company could be "Some Company Holdings, LLC." and they run the gateway "Super Gateway Payments". The merchant is using "Super Gateway Payments" and may not associate "Some Company Holdings, LLC." as their payment provider.

contact_email
string

Contact email for group owner

contact_phone
string

Contact phone number for group owner

contact_street
string

Contact street address for group owner

contact_city
string

Contact city component of address for group owner

contact_state
string

Contact state for group owner

contact_zip
string

Contact Zip or Postal code for group owner

contact_country
string

Contact country for group owner

support_email
string

Customer support email for group owner

support_phone
string

Customer support phone number for group owner

support_url
string

Customer support URL for group owner

website_url
string

Main company website for group

portal_url
string

URL for merchant portal access

tos_url
string

URL for group terms of service

privacy_url
string

URL for group privacy policy

from_email
string

From email to use when sending emails for the group

notice_email
string

Email address that are BCCd when merchant emails are sent. Does not include receipt or order invoice emails. Can be a comma separated list of multiple emails.

order_domain
string

Domain used for order invoices

silent_whitelabel
string
Default: "no"
Enum: "yes" "no"

Values:

  • yes - Powered by Monetra will be added to customer and emails
  • no - Powered by Monetra will not be added to customer and emails

Responses

Request samples

Content type
application/json
{
  • "name": "ISO - Maverick Systems",
  • "flags": "SHARE_TOKENS|REQUIRE_MFA",
  • "parent_group_id": "67895432456",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "ALL",
  • "trans_perms": "ALL",
  • "pushnotification_id": "56789098765",
  • "custom_customer_fields": "height,weight",
  • "company": "Company LLC.",
  • "gateway_name": "Gateway Product",
  • "contact_email": "email@email",
  • "contact_phone": "555-555-5555",
  • "contact_street": "124 6th Ln",
  • "contact_city": "Jacksonville",
  • "contact_state": "FL",
  • "contact_zip": "32789",
  • "contact_country": "USA",
  • "support_email": "support@email",
  • "support_phone": "555-555-5555",
  • "support_url": "https://url",
  • "website_url": "https://url",
  • "portal_url": "https://url",
  • "tos_url": "https://url",
  • "privacy_url": "https://url",
  • "from_email": "from@email",
  • "notice_email": "notice@email",
  • "order_domain": "https://url",
  • "silent_whitelabel": "yes"
}

Response samples

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

List Groups

List groups

The resulting report will contain these headers:

id, name, parent_group_id, group_depth, create_ts, upd_ts, flags, su_perms,
sys_perms, admin_perms, trans_perms, num_tokens, pushnotification_id,
custom_customer_fields, company, contact_name, contact_phone, contact_street,
contact_city, contact_state, contact_zip, contact_country, contact_email,
support_phone, support_url, website_url, support_email, portal_url, tos_url,
privacy_url, from_email, notice_email, order_domain, silent_whitelabel

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_auth(apikey_idapikey)
query Parameters
name
string

Query for specific group name

Cannot be combined with:

  • id
id
string
Example: id=36789654543

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=SHARE_TOKENS|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
empty_groups
object
Enum: "yes" "no"
Example: empty_groups=no

Used to locate 'dangling' groups with no subgroups and no profiles. It will, however, return groups that may contain users, but since these users couldn't access anything at all, this is expected as it is likely stale.

Values:

  • yes - Output empty groups
  • no - Do not output empty groups
ancestor_of
string
Example: ancestor_of=56789654367

Group ID to list ancestors of (including specified group id)

maxdepth
string
Example: maxdepth=4

Maximum 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
merge_recommendations
object
Enum: "yes" "no"
Example: merge_recommendations=no

List recommended groups for merging into other groups

Find groups that have exactly 1 sub group, no propagatable flags (PUSH_NOTIFICATION, SHARE_TOKENS, WHITELABEL_BRANDING), no merchant profiles, and no users. Its parent must not be the top level as this is likely intentional organization. Any groups in this list may serve no purpose and should be merged into its parent.

So taking a hierarchy like:

TOPLEVEL
|
|--PARTNER
   |-- ISO
      |-- MERCHANT 1
      |  |-- SUBGROUP1A
      |  |  |-- SUBSUBGROUP1A1
      |  |     |-- PROFILE(123)
      |  |     |-- USER(someone)
      |  |-- SUBGROUP1B
      |     |-- USER(someoneelse)
      |     |-- SUBSUBGROUP1B1
      |        |-- PROFILE(345)
      |-- MERCHANT 2
         |-- SUBGROUP2A (flags=PUSH_NOTIFICATION)
         |  |-- SUBSUBGROUP2A1
         |     |-- PROFILE(678)
         |     |-- USER(someone)
         |-- SUBGROUP2B
            |-- USER(someoneelse)
            |-- SUBSUBGROUP2B1
               |-- PROFILE(901)

SUBGROUP1A would be the only group in the list recommended as it only contains 1 subgroup, no profiles, no users, and no propagatable flags. "PARTNER" would not be listed as its parent is "TOPLEVEL" even though it meets the other conditions.

Values:

  • yes - Produce recommendation list
  • no - Do not produce recommendation list. Default behavior.
search
string

Will perform a substring search across multiple fields

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

Edit a Group

Edit a Group

libmonetra KVS equivalent for endpoint

  • action_sys = group_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 36789654543

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 the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

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 the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

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 statistics
  • 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: "ALL" "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 the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

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
  • 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: "ALL" "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 the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

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

Transaction results under this group will be included in push notifications for the corresponding push notification id.

ID returned from action_sys=pushnotification,pushnotification=add. Only allowed to be specified if flags contains PUSH_NOTIFICATION

custom_customer_fields
string

Comma separated list of custom fields to be stored with customers

Not allowed to be set if parent group has SHARE_TOKENS enabled.

company
string

Company name of group owner

gateway_name
string

Name of the gateway product

This is the name of the gateway product the merchant is using. This differs from the Company Name. For example, the company could be "Some Company Holdings, LLC." and they run the gateway "Super Gateway Payments". The merchant is using "Super Gateway Payments" and may not associate "Some Company Holdings, LLC." as their payment provider.

contact_email
string

Contact email for group owner

contact_phone
string

Contact phone number for group owner

contact_street
string

Contact street address for group owner

contact_city
string

Contact city component of address for group owner

contact_state
string

Contact state for group owner

contact_zip
string

Contact Zip or Postal code for group owner

contact_country
string

Contact country for group owner

support_email
string

Customer support email for group owner

support_phone
string

Customer support phone number for group owner

support_url
string

Customer support URL for group owner

website_url
string

Main company website for group

portal_url
string

URL for merchant portal access

tos_url
string

URL for group terms of service

privacy_url
string

URL for group privacy policy

from_email
string

From email to use when sending emails for the group

notice_email
string

Email address that are BCCd when merchant emails are sent. Does not include receipt or order invoice emails. Can be a comma separated list of multiple emails.

order_domain
string

Domain used for order invoices

silent_whitelabel
string
Default: "no"
Enum: "yes" "no"

Values:

  • yes - Powered by Monetra will be added to customer and emails
  • no - Powered by Monetra will not be added to customer and emails

Responses

Request samples

Content type
application/json
{
  • "addperm_propagate": "no",
  • "addperm_su_perms_mask": "TOKEN_EXPORT",
  • "addperm_sys_perms_mask": "SETLOGGING",
  • "addperm_admin_perms_mask": "TRAN_EXPORT|TRAN_IMPORT",
  • "addperm_trans_perms_mask": "FORCE|ALTPAYMENTINIT",
  • "name": "string",
  • "flags": "SHARE_TOKENS|REQUIRE_MFA",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "ALL",
  • "trans_perms": "ALL",
  • "pushnotification_id": "56789098765",
  • "custom_customer_fields": "height,weight",
  • "company": "Company LLC.",
  • "gateway_name": "Gateway Product",
  • "contact_email": "email@email",
  • "contact_phone": "555-555-5555",
  • "contact_street": "124 6th Ln",
  • "contact_city": "Jacksonville",
  • "contact_state": "FL",
  • "contact_zip": "32789",
  • "contact_country": "USA",
  • "support_email": "support@email",
  • "support_phone": "555-555-5555",
  • "support_url": "https://url",
  • "website_url": "https://url",
  • "portal_url": "https://url",
  • "tos_url": "https://url",
  • "privacy_url": "https://url",
  • "from_email": "from@email",
  • "notice_email": "notice@email",
  • "order_domain": "https://url",
  • "silent_whitelabel": "yes"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 36789654543

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": "36789654543",
  • "name": "ISO - Maverick Systems",
  • "parent_group_id": "67895432456",
  • "flags": "SHARE_TOKENS|REQUIRE_MFA",
  • "create_ts": "2022-05-24 15:06:13 -0400",
  • "upd_ts": "2022-05-24 15:06:13 -0400",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "ALL",
  • "trans_perms": "ALL",
  • "pushnotification_id": "56789098765",
  • "custom_customer_fields": "height,weight",
  • "company": "Company LLC.",
  • "gateway_name": "Gateway Product",
  • "contact_email": "email@email",
  • "contact_phone": "555-555-5555",
  • "contact_street": "124 6th Ln",
  • "contact_city": "Jacksonville",
  • "contact_state": "FL",
  • "contact_zip": "32789",
  • "contact_country": "USA",
  • "support_email": "support@email",
  • "support_phone": "555-555-5555",
  • "support_url": "https://url",
  • "website_url": "https://url",
  • "portal_url": "https://url",
  • "tos_url": "https://url",
  • "privacy_url": "https://url",
  • "from_email": "from@email",
  • "notice_email": "notice@email",
  • "order_domain": "https://url",
  • "silent_whitelabel": "yes"
}

Remove a Group

Delete a Group

libmonetra KVS equivalent for endpoint

  • action_sys = group_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 36789654543

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

Merge Groups

Merge the source group into the specified group. Can only merge into a parent or sibling.

libmonetra KVS equivalent for endpoint

  • action_sys = group_merge
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 36789654543

Group id

source_group_id
required
string
Example: 67895432456

Source group to merge groups, users, and profiles from.

Responses

Request samples 

curl -X PATCH 'https://testbox.monetra.com/api/v2/boarding/group/123/merge/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"
}

Move a Group

Move a Group from one parent to another

libmonetra KVS equivalent for endpoint

  • action_sys = group_move
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 36789654543

Group id

parent_group_id
required
string
Example: 67895432456

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" : [
        {
            "username": "123456789:pos",
            "profile_id": "492747293925853",
            "profile_name": "myname",
            "action_trans": "sale",
            "code": "AUTH",
            "ttid": "912314155123456",
            "ts": "1567172149",
            "tranflags": "HASAVS|DATAKEYED|NSF|PARTIALAUTH",
            "txnstatus": "CAPTURED|ONLINE|SENSITIVEDATA",
            "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.

Create a Push Notification Endpoint

Creates a push notification endpoint

libmonetra KVS equivalent for endpoint

  • action_su = pushnotification
  • pushnotification = add
Authorizations:
basic_auth(apikey_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 authentication 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": "ISO - Maverick Systems",
  • "url": "https://url",
  • "authtype": "NONE",
  • "eventflags": "AUTH|VOID|SETTLE|CREDIT|DEBIT",
  • "authname": "Partner - BB Books",
  • "authdata": "..."
}

Response samples

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

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_auth(apikey_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": "..."
}

Edit a Push Notification Endpoint

Edits a push notification endpoint

libmonetra KVS equivalent for endpoint

  • action_su = pushnotification
  • pushnotification = edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56789098765

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 authentication 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": "James Dean",
  • "url": "string",
  • "authtype": "NONE",
  • "eventflags": "AUTH|VOID|SETTLE|CREDIT|DEBIT",
  • "authname": "Partner - BB Books",
  • "authdata": "..."
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56789098765

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": "56789098765",
  • "display_name": "ISO - Maverick Systems",
  • "url": "https://url",
  • "eventflags": "AUTH|VOID|SETTLE|CREDIT|DEBIT",
  • "authtype": "NONE"
}

Remove a Push Notification Endpoint

Removes a push notification endpoint

libmonetra KVS equivalent for endpoint

  • action_su = pushnotification
  • pushnotification = del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56789098765

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 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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56789098765

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_auth(apikey_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.

Create a Profile

Creates a Profile

libmonetra KVS equivalent for endpoint

  • action_sys = profile_add
Authorizations:
basic_auth(apikey_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" "RECEIVE_RECEIPTS_HOSTEDPAGE" "RECURRING_SKIPMISSED" "ORDERS_REQ_LEVEL3" "RATEQUAL_NONTAX" "ALLOW_INVOICE_SMS" "ALLOW_INVOICING" "DISABLE_MSR_ENTRY" "CARDDENYLIST_CHECK" "CARDDENYLIST_DECLINE" "SETTLE_EMAIL_DETAILS" "AUTO_PINLESS_DEBIT" "3DS_DISABLE_CHALLENGES" "3DS_AUTO_DECLINE" "VERIFY_ACH"

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.
  • RECEIVE_RECEIPTS_HOSTEDPAGE - Merchant should receive merchant receipt copies by email for approved payments made through the hosted payment page. 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
  • SETTLE_EMAIL_DETAILS - Include report with transaction details for each settled batch with automatic settlement emails
  • AUTO_PINLESS_DEBIT - Automatically mark debit transactions as PIN less for CNP if determined to be debit and can route over a pinless network. Pinless debit is only allowed for a specific set of MCC codes. Check with the merchant processor to determine if this can be enabled. Otherwise the merchant could be fined for using pinless debit when not allowed for their MCC.
  • 3DS_DISABLE_CHALLENGES - Disable 3DS challenges with external 3DS provider
  • 3DS_AUTO_DECLINE - Automatically decline any sale, preauth, or verifyonly transaction without 3DS data. This applies regardless of an external 3DS provider being specified.
  • VERIFY_ACH - Verify ACH details. Any ACH transaction not explicitly permitted by the ACH verification provider will be declined, including if it is inaccessible or unable to provide a decision.
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" "F" "H" "AF" "G" "RS"

Industry transactions will take place as

Values:

  • R - Retail
  • E - eCommerce
  • M - Mail Order / Telephone Order
  • F - 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

logo
string

Base64 encoded image of the merchant's logo

logo_type
string
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
Default: "EN"
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*(\.\d{0,2})?

Maximum amount allowed to be requested by a customer for cashback

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

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.

3ds_provider
string

Name of external 3DS provider to use (e.g. paay)

External providers require a direct relationship. If in doubt, do not set this.

3ds_provider_merchid
string

Merchant/account identifier assigned by external 3DS provider

External providers require a direct relationship. If in doubt, do not set this.

Responses

Request samples

Content type
application/json
{
  • "group_id": "36789654543",
  • "profile_name": "Pizza Palace",
  • "name": "Pizza Palace",
  • "notify_email": "email@email",
  • "flags": "EMVSUPRESSSIG|EMVPIN_STANDIN_ALLOWED|EMVODA_NONE_STANDIN_ALLOWED|DEBIT_STANDIN_ALLOWED|RECURRING_SKIPMISSED|ALLOW_INVOICE_SMS|ALLOW_INVOICING",
  • "custom_trans_fields": "alpha,omega",
  • "req_trans_fields": "ordernum",
  • "req_order_fields": "ordernum",
  • "vanity_url_prefix": "pizza_palace",
  • "indcode": "R",
  • "fraudautodeny": "DENY_NOAUTO",
  • "emv_termcaps": "NOSIG|ONLINEPIN|PINBYPASSCREDIT|PINBYPASSUSDEBIT",
  • "emv_testmode": "no",
  • "emv_contact_nocvm_limit": "100.00",
  • "emv_ctls_nocvm_limit": "9999.99",
  • "countrycode": "840",
  • "currencycode": "840",
  • "logo": "...",
  • "logo_type": "string",
  • "external_id": "string",
  • "descr": "BB Books store 4",
  • "addr1": "152 Main St",
  • "addr2": "Jacksonville FL",
  • "addr3": "32034",
  • "phone": "555-555-5555",
  • "email": "email@email",
  • "url": "https://url",
  • "tz": "America/New_York",
  • "lang": "EN",
  • "cashback": "5|10|20",
  • "cashbackmax": "50.00",
  • "cashback_purchmin": "25.00",
  • "tippercent": "15|20|25|O",
  • "msr_nosig_limit": "200.00",
  • "enc_provider": "bluefin",
  • "l3_commoditycode": "R676D2452X",
  • "l3_productcode": "GHF7653",
  • "l3_description": "Fork",
  • "tax_rate_autopop": "NT",
  • "txn_export_key": "...",
  • "3ds_provider": "paay",
  • "3ds_provider_merchid": "ABC-123"
}

Response samples

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

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,
3ds_provider, 3ds_provider_merchid

libmonetra KVS equivalent for endpoint

  • action_sys = profile_list
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
group_id
string
Example: group_id=36789654543

Group identifier

profile_name
string
Example: profile_name=Pizza Palace

Name for profile

Internal name within the system

Not required to be unique

flags
object
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" "RECEIVE_RECEIPTS_HOSTEDPAGE" "RECURRING_SKIPMISSED" "ORDERS_REQ_LEVEL3" "RATEQUAL_NONTAX" "ALLOW_INVOICE_SMS" "ALLOW_INVOICING" "DISABLE_MSR_ENTRY" "CARDDENYLIST_CHECK" "CARDDENYLIST_DECLINE" "SETTLE_EMAIL_DETAILS" "AUTO_PINLESS_DEBIT" "3DS_DISABLE_CHALLENGES" "3DS_AUTO_DECLINE" "VERIFY_ACH"
Example: flags=EMVSUPRESSSIG|EMVPIN_STANDIN_ALLOWED|EMVODA_NONE_STANDIN_ALLOWED|DEBIT_STANDIN_ALLOWED|RECURRING_SKIPMISSED|ALLOW_INVOICE_SMS|ALLOW_INVOICING

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.
  • RECEIVE_RECEIPTS_HOSTEDPAGE - Merchant should receive merchant receipt copies by email for approved payments made through the hosted payment page. 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
  • SETTLE_EMAIL_DETAILS - Include report with transaction details for each settled batch with automatic settlement emails
  • AUTO_PINLESS_DEBIT - Automatically mark debit transactions as PIN less for CNP if determined to be debit and can route over a pinless network. Pinless debit is only allowed for a specific set of MCC codes. Check with the merchant processor to determine if this can be enabled. Otherwise the merchant could be fined for using pinless debit when not allowed for their MCC.
  • 3DS_DISABLE_CHALLENGES - Disable 3DS challenges with external 3DS provider
  • 3DS_AUTO_DECLINE - Automatically decline any sale, preauth, or verifyonly transaction without 3DS data. This applies regardless of an external 3DS provider being specified.
  • VERIFY_ACH - Verify ACH details. Any ACH transaction not explicitly permitted by the ACH verification provider will be declined, including if it is inaccessible or unable to provide a decision.
status
object
Enum: "ACTIVE" "DISABLED"
Example: status=ACTIVE

Status of the profile

Values:

  • ACTIVE - Profile is active and can process
  • DISABLED - Profile is disabled and cannot process
maxdepth
string
Example: maxdepth=4

Maximum depth to display

Default is unlimited. Specify 1 to see only self and children.

search
string

Will perform a substring search across multiple fields

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

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 78965743785967

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

Edit a Profile

Edits a Profile

libmonetra KVS equivalent for endpoint

  • action_sys = profile_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 78965743785967

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" "RECEIVE_RECEIPTS_HOSTEDPAGE" "RECURRING_SKIPMISSED" "ORDERS_REQ_LEVEL3" "RATEQUAL_NONTAX" "ALLOW_INVOICE_SMS" "ALLOW_INVOICING" "DISABLE_MSR_ENTRY" "CARDDENYLIST_CHECK" "CARDDENYLIST_DECLINE" "SETTLE_EMAIL_DETAILS" "AUTO_PINLESS_DEBIT" "3DS_DISABLE_CHALLENGES" "3DS_AUTO_DECLINE" "VERIFY_ACH"

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.
  • RECEIVE_RECEIPTS_HOSTEDPAGE - Merchant should receive merchant receipt copies by email for approved payments made through the hosted payment page. 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
  • SETTLE_EMAIL_DETAILS - Include report with transaction details for each settled batch with automatic settlement emails
  • AUTO_PINLESS_DEBIT - Automatically mark debit transactions as PIN less for CNP if determined to be debit and can route over a pinless network. Pinless debit is only allowed for a specific set of MCC codes. Check with the merchant processor to determine if this can be enabled. Otherwise the merchant could be fined for using pinless debit when not allowed for their MCC.
  • 3DS_DISABLE_CHALLENGES - Disable 3DS challenges with external 3DS provider
  • 3DS_AUTO_DECLINE - Automatically decline any sale, preauth, or verifyonly transaction without 3DS data. This applies regardless of an external 3DS provider being specified.
  • VERIFY_ACH - Verify ACH details. Any ACH transaction not explicitly permitted by the ACH verification provider will be declined, including if it is inaccessible or unable to provide a decision.
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" "F" "H" "AF" "G" "RS"

Industry transactions will take place as

Values:

  • R - Retail
  • E - eCommerce
  • M - Mail Order / Telephone Order
  • F - 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

logo
string

Base64 encoded image of the merchant's logo

logo_type
string
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
Default: "EN"
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*(\.\d{0,2})?

Maximum amount allowed to be requested by a customer for cashback

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

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.

3ds_provider
string

Name of external 3DS provider to use (e.g. paay)

External providers require a direct relationship. If in doubt, do not set this.

3ds_provider_merchid
string

Merchant/account identifier assigned by external 3DS provider

External providers require a direct relationship. If in doubt, do not set this.

Responses

Request samples

Content type
application/json
{
  • "name": "Pizza Palace",
  • "profile_name": "Pizza Palace",
  • "notify_email": "email@email",
  • "flags": "EMVSUPRESSSIG|EMVPIN_STANDIN_ALLOWED|EMVODA_NONE_STANDIN_ALLOWED|DEBIT_STANDIN_ALLOWED|RECURRING_SKIPMISSED|ALLOW_INVOICE_SMS|ALLOW_INVOICING",
  • "custom_trans_fields": "alpha,omega",
  • "req_trans_fields": "ordernum",
  • "req_order_fields": "ordernum",
  • "vanity_url_prefix": "pizza_palace",
  • "indcode": "R",
  • "fraudautodeny": "DENY_NOAUTO",
  • "emv_termcaps": "NOSIG|ONLINEPIN|PINBYPASSCREDIT|PINBYPASSUSDEBIT",
  • "emv_testmode": "no",
  • "emv_contact_nocvm_limit": "100.00",
  • "emv_ctls_nocvm_limit": "9999.99",
  • "countrycode": "840",
  • "currencycode": "840",
  • "logo": "...",
  • "logo_type": "string",
  • "external_id": "string",
  • "descr": "BB Books store 4",
  • "addr1": "152 Main St",
  • "addr2": "Jacksonville FL",
  • "addr3": "32034",
  • "phone": "555-555-5555",
  • "email": "email@email",
  • "url": "https://url",
  • "tz": "America/New_York",
  • "lang": "EN",
  • "cashback": "5|10|20",
  • "cashbackmax": "50.00",
  • "cashback_purchmin": "25.00",
  • "tippercent": "15|20|25|O",
  • "msr_nosig_limit": "200.00",
  • "enc_provider": "bluefin",
  • "l3_commoditycode": "R676D2452X",
  • "l3_productcode": "GHF7653",
  • "l3_description": "Fork",
  • "tax_rate_autopop": "NT",
  • "txn_export_key": "...",
  • "3ds_provider": "paay",
  • "3ds_provider_merchid": "ABC-123"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 78965743785967

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": "78965743785967",
  • "profile_name": "Pizza Palace",
  • "name": "Pizza Palace",
  • "group_id": "36789654543",
  • "group_depth": "99",
  • "flags": "SHARE_TOKENS|REQUIRE_MFA",
  • "status": "ACTIVE",
  • "indcode": "R",
  • "create_ts": "2022-05-24 15:06:13 -0400",
  • "upd_ts": "2022-05-24 15:06:13 -0400",
  • "notify_email": "email@email",
  • "custom_trans_fields": "alpha,omega",
  • "req_trans_fields": "ordernum",
  • "custom_order_fields": "special_instructions",
  • "req_order_fields": "ordernum",
  • "vanity_url_prefix": "pizza_palace",
  • "tokengroup_id": "654356543",
  • "tokengroup_name": "Pizza Palace Vault",
  • "pushnotification_id": "56789098765",
  • "whitelabelgroup_id": "647435678765",
  • "fraudautodeny": "DENY_NOAUTO",
  • "emv_termcaps": "NOSIG|ONLINEPIN|PINBYPASSCREDIT|PINBYPASSUSDEBIT",
  • "emv_testmode": "no",
  • "emv_contact_nocvm_limit": "100.00",
  • "emv_ctls_nocvm_limit": "9999.99",
  • "countrycode": "840",
  • "currencycode": "840",
  • "descr": "BB Books store 4",
  • "addr1": "152 Main St",
  • "addr2": "Jacksonville FL",
  • "addr3": "32034",
  • "phone": "555-555-5555",
  • "email": "email@email",
  • "external_id": "string",
  • "url": "https://url",
  • "tz": "America/New_York",
  • "lang": "EN",
  • "cashback": "5|10|20",
  • "cashbackmax": "50.00",
  • "cashback_purchmin": "25.00",
  • "tippercent": "15|20|25|O",
  • "msr_nosig_limit": "200.00",
  • "enc_provider": "bluefin",
  • "l3_commoditycode": "R676D2452X",
  • "l3_description": "Fork",
  • "l3_productcode": "GHF7653",
  • "tax_rate_autopop": "NT"
}

Remove a Profile

Delete a Profile

libmonetra KVS equivalent for endpoint

  • action_sys = profile_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 78965743785967

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

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 78965743785967

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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 - Retrieve merchant logo image
  • no - Do not retrieve 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": "Pizza Palace",
  • "addr1": "152 Main St",
  • "addr2": "Jacksonville FL",
  • "addr3": "32034",
  • "phone": "555-555-5555",
  • "email": "email@email",
  • "url": "https://url",
  • "countrycode": "840",
  • "currencycode": "840",
  • "indcode": "R",
  • "lang": "EN",
  • "cashback": "5|10|20",
  • "cashback_purchmin": "25.00",
  • "cashbackmax": "50.00",
  • "tippercent": "15|20|25|O",
  • "l3_description": "Fork",
  • "l3_commoditycode": "R676D2452X",
  • "l3_productcode": "GHF7653",
  • "tax_rate": "1.14",
  • "custom_fields": "alpha,omega",
  • "req_fields": "ordernum,zip",
  • "flags": "EMVSUPRESSSIG|EMVPIN_STANDIN_ALLOWED|EMVODA_NONE_STANDIN_ALLOWED|DEBIT_STANDIN_ALLOWED|RECURRING_SKIPMISSED|ALLOW_INVOICE_SMS|ALLOW_INVOICING",
  • "logo": "...",
  • "logo_type": "PNG"
}

List Profile Merchant IDs

List profile Merchant IDs

The resulting report will contain these headers:

id, profile_name, route_id, proc, mode, cardtypes, merchid, termid, divnum, authuser

libmonetra KVS equivalent for endpoint

  • action_sys = profile_list_mids
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
id
string
profile_name
string
Example: profile_name=Pizza Palace

Name for profile

Internal name within the system

Not required to be unique

group_id
string
Example: group_id=36789654543

Group identifier

maxdepth
string
Example: maxdepth=4

Maximum 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/boarding/profile_mids' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

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

Move a Profile

Move a Profile from one group to another

libmonetra KVS equivalent for endpoint

  • action_sys = profile_move
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 78965743785967

Merchant profile identifier

Request Body schema: application/json
group_id
required
string\d+

Group identifier

Responses

Request samples

Content type
application/json
{
  • "group_id": "36789654543"
}

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.

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_auth(apikey_idapikey)
path Parameters
profile_id
required
string
Example: 78965743785967

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*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "proc": "loopback",
  • "mode": "BOTH",
  • "cardtypes": "VISA|MC",
  • "route_id": "0",
  • "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": "0"
}

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_auth(apikey_idapikey)
path Parameters
profile_id
required
string
Example: 78965743785967

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

Edit a Route

Edits a Route

libmonetra KVS equivalent for endpoint

  • action_sys = route_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
profile_id
required
string
Example: 78965743785967

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
Example: 0

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*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "proc": "loopback",
  • "mode": "BOTH",
  • "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"
}

Remove a Route

Deletes a Route

libmonetra KVS equivalent for endpoint

  • action_sys = route_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
profile_id
required
string
Example: 78965743785967

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
Example: 0

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_auth(apikey_idapikey)
path Parameters
profile_id
required
string
Example: 78965743785967

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
Example: 0

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

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_auth(apikey_idapikey)
query Parameters
proc
string
Example: proc=loopback

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, multidiffer, displayname, desc

Example for "loopback" processor emulator:

{
    "report": [
        {
            "name": "MERCHID",
            "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": "13",
            "len_max": "13",
            "field_type": "VAR_TYPE_ANY",
            "submitteronly": "No",
            "multidiffer": "No",
            "displayname": "Merchant (Retailer) ID",
            "desc": "Unique merchant location number assigned by Moneris"
        },
        {
            "name": "TERMID",
            "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": "8",
            "len_max": "8",
            "field_type": "VAR_TYPE_ANY",
            "submitteronly": "No",
            "multidiffer": "Yes",
            "displayname": "Terminal ID",
            "desc": "Identifies the originations device for a POS transaction"
        },
        {
            "name": "LANGUAGE_FR",
            "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",
            "multidiffer": "No",
            "displayname": "Merchant Language French",
            "desc": "The POS should use French for messages presented to the clerk from the processor"
        },
        {
            "name": "CERTOVERRIDE",
            "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",
            "multidiffer": "No",
            "displayname": "Cert Override Mode",
            "desc": "In cert override mode some initialization parameters sent by Moneris will be ignored"
        }
    ]
}

libmonetra KVS equivalent for endpoint

  • action_sys = route_fields
  • route_fields = procfields
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
proc
required
string
Example: loopback

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.

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_auth(apikey_idapikey)
path Parameters
bbacctid
required
string
Example: 56789765678

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": "Elavon account",
  • "email": "email@email",
  • "proc": "loopback"
}

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_auth(apikey_idapikey)
path Parameters
bbacctid
required
string
Example: 56789765678

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

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_auth(apikey_idapikey)
path Parameters
bbacctid
required
string
Example: 56789765678

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": "Elavon account",
  • "email": "email@email"
}

Response samples

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

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_auth(apikey_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": "loopback",
  • "descr": "Elavon account",
  • "email": "email@email"
}

Response samples

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

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_auth(apikey_idapikey)
query Parameters
bbacctid
string
Example: bbacctid=56789765678

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

Big Batch Merchants

Big batch merchant management

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_auth(apikey_idapikey)
path Parameters
bbmerchid
required
string
Example: 9876545678934

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": "XSD8D42",
  • "proc": "loopback",
  • "emv_entrymodes": "VISA_CONTACT|SVISA_CONTACTLESS|MC_CONTACT",
  • "emv_termcaps": "NOSIG|ONLINEPIN|PINBYPASSCREDIT|PINBYPASSUSDEBIT",
  • "cardtypes": "VISA|MC",
  • "bbacctid": "56789765678",
  • "descr": "Elavon account",
  • "property1": "string",
  • "property2": "string"
}

Delete a Big Batch Merchant

Delete a Big Batch Merchant

libmonetra KVS equivalent for endpoint

  • action_su = bigbatch_manage
  • bigbatch_manage = delmerch
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
bbmerchid
required
string
Example: 9876545678934

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

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_auth(apikey_idapikey)
path Parameters
bbmerchid
required
string
Example: 9876545678934

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": "56789765678",
  • "proc": "loopback",
  • "descr": "Elavon account",
  • "cardtypes": "VISA|MC",
  • "emv_entrymodes": "VISA_CONTACT|SVISA_CONTACTLESS|MC_CONTACT",
  • "emv_termcaps": "NOSIG|ONLINEPIN|PINBYPASSCREDIT|PINBYPASSUSDEBIT",
  • "resetauthtoken": "yes"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
bbacctid
required
string
Example: 56789765678

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": "loopback",
  • "descr": "Elavon account",
  • "cardtypes": "VISA|MC",
  • "emv_entrymodes": "VISA_CONTACT|SVISA_CONTACTLESS|MC_CONTACT",
  • "emv_termcaps": "NOSIG|ONLINEPIN|PINBYPASSCREDIT|PINBYPASSUSDEBIT"
}

Response samples

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

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_auth(apikey_idapikey)
path Parameters
bbacctid
required
string
Example: 56789765678

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

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_auth(apikey_idapikey)
path Parameters
bbbatchid
required
string
Example: 49345764242

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_auth(apikey_idapikey)
path Parameters
bbacctid
required
string
Example: 56789765678

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_auth(apikey_idapikey)
query Parameters
bbacctid
string
Example: bbacctid=56789765678

ID of big batch aggregation account

bbmerchid
string
Example: bbmerchid=9876545678934

ID of big batch merchant

bbbatchid
string
Example: bbbatchid=49345764242

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_auth(apikey_idapikey)
path Parameters
bbmerchid
required
string
Example: 9876545678934

ID of big batch merchant

query Parameters
state
object
Enum: "OPEN" "CLOSED" "PENDING" "ATTEMPTED" "SETTLED" "FORCESETTLED"
Example: state=OPEN|PEINDING

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_auth(apikey_idapikey)
path Parameters
bbbatchid
required
string
Example: 49345764242

Batch number for a batch in a big batch aggregation

query Parameters
state
object
Enum: "OPEN" "CLOSED" "PENDING" "ATTEMPTED" "SETTLED" "FORCESETTLED"
Example: state=OPEN|PEINDING

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_auth(apikey_idapikey)
path Parameters
bbacctid
required
string
Example: 56789765678

ID of big batch aggregation account

bbmerchid
required
string
Example: 9876545678934

ID of big batch merchant

bbbatchid
required
string
Example: 49345764242

Batch number for a batch in a big batch aggregation

batch
required
string
Example: 47

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_auth(apikey_idapikey)
path Parameters
bbbatchid
required
string
Example: 49345764242

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",
  • "draft_locator_id": "24FDBDD0902"
}

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_auth(apikey_idapikey)
path Parameters
bbbatchid
required
string
Example: 49345764242

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

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "draft_locator_id": "24FDBDD0902"
}

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
Example: 20008BC878

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 20008BC878

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": "KIF Si Sqrt"
}

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
Example: 20008BC878

BDK id

Request Body schema: application/json
rsapublickey
required
string

RSA public key

Responses

Request samples

Content type
application/json
{
  • "rsapublickey": "..."
}

Response samples

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

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": "LOCKTOPROFILE|AUTODISABLE|TRACKEVENTS",
  • "descr": "KIF Si Sqrt"
}

Response samples

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

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_auth(apikey_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": "..."
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 2000C2105A00034

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": "14C"
}

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
Example: 20008BC878

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": "GGSgs5645GJ",
  • "flags": "KSIDFMT2"
}

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.

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_auth(apikey_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": "5436754356",
  • "serial_num": "HGIE475GH205HG",
  • "type": "quarterly_inspection",
  • "notes": "This is a note",
  • "approval_user": "James West"
}

Response samples

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

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: id=5436754356

Device id

serial_num
string
Example: serial_num=HGIE475GH205HG

Device serial number

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

type
object
Enum: "PROVISION" "ACTIVATED" "DIS_ACTIVITY" "DIS_COMPROMISE" "DIS_OTHER" "ENABLED" "INSPECTION" "NOTES" "SOFTWARECHANGE" "DECOMMISSION"
Example: type=ACTIVATED|NOTES|DECOMMISSION

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

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 5436754356

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 5436754356

Device id

Request Body schema: application/json
descr
required
string <= 128 characters

description

Responses

Request samples

Content type
application/json
{
  • "descr": "description of some kind"
}

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_auth(apikey_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": "5436754356",
  • "serial_num": "HGIE475GH205HG",
  • "reason": "possible_compromise",
  • "notes": "This is a note",
  • "approval_user": "James West"
}

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_auth(apikey_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": "5436754356",
  • "serial_num": "HGIE475GH205HG",
  • "notes": "This is a note",
  • "approval_user": "James West"
}

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Limit search to the specified profile id

id
string
Example: id=20008BC878

P2PE key id

serial_num
string
Example: serial_num=HGIE475GH205HG

Device serial number

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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
Example: id=20008BC878

P2PE key id

serial_num
string
Example: serial_num=HGIE475GH205HG

Device serial number

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

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_auth(apikey_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": "78965743785967",
  • "notes": "Device provisioned",
  • "serial_num": "HGIE475GH205HG",
  • "approval_user": "James West"
}

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.

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_auth(apikey_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": "78965743785967"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "20008BC878",
  • "key": "..."
}

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Limit search to the specified profile id

id
string
Example: id=20008BC878

Standin key id

serial_num
string
Example: serial_num=HGIE475GH205HG

Device serial number

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

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 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_auth(apikey_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": "78965743785967"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "20008BC878",
  • "key": "..."
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 1567654325

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_auth(apikey_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_auth(apikey_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
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

id
string
Example: id=1567654325

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_su = info
  • info = licinfo
Authorizations:
basic_auth(apikey_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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Limit search to the specified profile id

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

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_auth(apikey_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_auth(apikey_idapikey)
path Parameters
device_id
required
string
Example: 65432456

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_auth(apikey_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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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

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_auth(apikey_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": "78965743785967",
  • "limit": "45"
}

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_auth(apikey_idapikey)
query Parameters
bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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.

This is typically used to dereference the ALL when getting a user's permissions. Necessary when generating API keys which cannot take ALL and must have a full list of permissions.

A user will still need permissions to use allowed actions.

libmonetra KVS equivalent for endpoint

  • action_sys = info
  • info = trantypes
Authorizations:
basic_auth(apikey_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_su = info
  • info = maintenance
Authorizations:
basic_auth(apikey_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_auth(apikey_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_su = info
  • info = versions
Authorizations:
basic_auth(apikey_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_auth(apikey_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_auth(apikey_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_auth(apikey_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_auth(apikey_idapikey)
path Parameters
bufferid
required
string
Example: 665436765467

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_auth(apikey_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|CONF|WARN|INFO|TRAN|TRAN_DETAIL|CONN|PROC|PROC_DETAIL|ERROR|CRIT"
}

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_auth(apikey_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|CONF|WARN|INFO|TRAN|TRAN_DETAIL|CONN|PROC|PROC_DETAIL|ERROR|CRIT",
  • "buffer_size": "5242880",
  • "filter_user": "user_you"
}

Response samples

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

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_auth(apikey_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": "07:40|*"
}

Response samples

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

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_auth(apikey_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": "07:40|*",
  • "keep_days": "90"
}

Response samples

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

Create Automated Big Batch Settlement

Automatic big batch settlement

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = add
  • type = bigbatchsettle
Authorizations:
basic_auth(apikey_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": "56789765678",
  • "sched": "07:40|*"
}

Response samples

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

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_auth(apikey_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": "07:40|*",
  • "keep_days": "90"
}

Response samples

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

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_auth(apikey_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": "07:40|*",
  • "keep_days": "90"
}

Response samples

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

Create Automated Deleted Expired Tokens

Purge tokens with expired cards

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = add
  • type = purgeexpired
Authorizations:
basic_auth(apikey_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": "07:40|*",
  • "keep_months": "12"
}

Response samples

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

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_auth(apikey_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": "07:40|*",
  • "keep_days": "90"
}

Response samples

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

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_auth(apikey_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": "07:40|*",
  • "keep_days": "90"
}

Response samples

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

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_auth(apikey_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": "07:40|*",
  • "keep_days": "90"
}

Response samples

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

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_auth(apikey_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": "07:40|*",
  • "keep_days": "90"
}

Response samples

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

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_auth(apikey_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": "07:40|*",
  • "keep_days": "90"
}

Response samples

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

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_auth(apikey_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": "07:40|*",
  • "keep_days": "90"
}

Response samples

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

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_auth(apikey_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": "07:40|*",
  • "keep_days": "90"
}

Response samples

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

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_auth(apikey_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": "78965743785967",
  • "sched": "07:40|*"
}

Response samples

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

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_auth(apikey_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": "07:40|*",
  • "keep_days": "90"
}

Response samples

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

Delete a Scheduled Task

Delete a scheduled task

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

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": "07:40|*"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

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": "07:40|*",
  • "keep_days": "90"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

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": "07:40|*"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

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": "07:40|*",
  • "keep_days": "90"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

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": "07:40|*",
  • "keep_days": "90"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

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": "07:40|*",
  • "keep_months": "12"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

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": "07:40|*",
  • "keep_days": "90"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

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": "07:40|*",
  • "keep_days": "90"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

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": "07:40|*",
  • "keep_days": "90"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

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": "07:40|*",
  • "keep_days": "90"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

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": "07:40|*",
  • "keep_days": "90"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

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": "07:40|*",
  • "keep_days": "90"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

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": "07:40|*",
  • "keep_days": "90"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

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": "78965743785967",
  • "sched": "07:40|*"
}

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

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": "07:40|*",
  • "keep_days": "90"
}

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_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

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_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

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:

group_id, group_name, is_token_group, update_count

libmonetra KVS equivalent for endpoint

  • action_sys = profile_stats
  • profile_stats = accountupdater
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
bdate
required
string
Example: bdate=-6 months

Start of date range

edate
required
string
Example: edate=now

End of date range

group_id
string
Example: group_id=36789654543

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 Auth Statistics

Get statistics for auths

The data reported is summarized on a per profile per bucket type basis. There is no means to grab summarization at a group level, it is left as an exercise to the integrator to perform the necessary math if such a report is needed. Profiles without stats for the requested period will not be listed. If a profile doesn't have stats for the requested stat type for the period, it will not be listed.

The resulting report will contain these headers:

id, profile_name, group_id, type, count

When using JSON ouput, the output will be a hierarchical view of various statistics containing each parent group with minimal data.

Example:

{
  "id": "1",
  "name": "Monetra TopLevel",
  "groups": [
    {
      "id": "111111111111",
      "name": "merchant1",
      "profiles": [
        {
           "id": "444444444444",
           "profile_name": "merchant1 profile",
           "stats": {
             "AUTH_VISA": "5",
             "AUTH_MC": "903"
           }
        }
      ]
    },
    {
      "id": "111111111112",
      "name": "some group",
      "groups": [
        {
          "id": "11111111113",
          "name": "blah merchant",
          "profiles": [
            {
              "id": "222222222222",
              "profile_name": "blah merchant profile",
              "stats": {
                "AUTH_VISA": "34634",
                "AUTH_DISC": "1234"
              }
            }
          ]
        }
      ]
    }
  ]
}

libmonetra KVS equivalent for endpoint

  • action_sys = profile_stats
  • profile_stats = auth
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
bdate
required
string
Example: bdate=-6 months

Start of date range

edate
required
string
Example: edate=now

End of date range

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
group_id
string
Example: group_id=36789654543

Group identifier

id
string

Profile ID to request statistics for

types
required
object
Enum: "AUTH_VISA" "AUTH_MC" "AUTH_AMEX" "AUTH_DISC" "AUTH_JCB" "AUTH_CUP" "AUTH_DEBIT" "AUTH_VISADEBIT_VIA_CREDIT" "AUTH_MCDEBIT_VIA_CREDIT" "AUTH_ACH" "AUTH_CHECK" "ACH_VERIFY" "ACH_REJECT" "ACH_REJECT_AMOUNT"
Example: types=AUTH_VISA,AUTH_MC,AUTH_AMEX,AUTH_DISC,AUTH_VISADEBIT_VIA_CREDIT,AUTH_MCDEBIT_VIA_CREDIT

Comma Delimited List of Statistic Types to request

Values:

  • AUTH_VISA - Visa Authorizations
  • AUTH_MC - Mastercard Authorizations
  • AUTH_AMEX - American Express Authorizations
  • AUTH_DISC - Discover Authorizations
  • AUTH_JCB - JCB Authorizations
  • AUTH_CUP - China Union Pay Authorizations
  • AUTH_DEBIT - Debit Authorizations
  • AUTH_VISADEBIT_VIA_CREDIT - Debit run as Visa Credit -- not included in AUTH_VISA or AUTH_DEBIT
  • AUTH_MCDEBIT_VIA_CREDIT - Debit run as Mastercard Credit -- not included in AUTH_MC or AUTH_DEBIT
  • AUTH_ACH - ACH Authorizations -- likely 0
  • AUTH_CHECK - CHECK Authorizations
  • ACH_VERIFY - ACH verification service
  • ACH_REJECT - ACH rejections
  • ACH_REJECT_AMOUNT - ACH rejection sum (in cents)

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/stats/auth?bdate=epoch&edate=now&types=AUTH_VISA,AUTH_MC&json=no' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

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

Get Detailed Profile Statistics

Get detail profile statistics for settled transactions

This is an expensive query to get fine grained summarized details about settled transactions on a per-profile basis.

The resulting report will contain these headers:

id, profile_name, group_id,
VISA_auth_cnt,  VISA_auth_amt,  VISA_refund_cnt,  VISA_refund_amt,
MC_auth_cnt,    MC_auth_amt,    MC_refund_cnt,    MC_refund_amt,
DISC_auth_cnt,  DISC_auth_amt,  DISC_refund_cnt,  DISC_refund_amt,
AMEX_auth_cnt,  AMEX_auth_amt,  AMEX_refund_cnt,  AMEX_refund_amt,
JCB_auth_cnt,   JCB_auth_amt,   JCB_refund_cnt,   JCB_refund_amt,
CUP_auth_cnt,   CUP_auth_amt,   CUP_refund_cnt,   CUP_refund_amt,
DEBIT_auth_cnt, DEBIT_auth_amt, DEBIT_refund_cnt, DEBIT_refund_amt,
VISADEBIT_VIA_CREDIT_auth_cnt, VISADEBIT_VIA_CREDIT_auth_amt, VISADEBIT_VIA_CREDIT_refund_cnt, VISADEBIT_VIA_CREDIT_refund_amt,
MCDEBIT_VIA_CREDIT_auth_cnt,   MCDEBIT_VIA_CREDIT_auth_amt,   MCDEBIT_VIA_CREDIT_refund_cnt,   MCDEBIT_VIA_CREDIT_refund_amt,
EBT_auth_cnt,   EBT_auth_amt,   EBT_refund_cnt,   EBT_refund_amt,
GIFT_auth_cnt,  GIFT_auth_amt,  GIFT_refund_cnt,  GIFT_refund_amt,
ACH_auth_cnt,   ACH_auth_amt,   ACH_refund_cnt,   ACH_refund_amt,
CHECK_auth_cnt, CHECK_auth_amt, CHECK_refund_cnt, CHECK_refund_amt

When using JSON ouput, the output will be a hierarchical view of various statistics containing each parent group with minimal data.

Example:

{
  "id": "1",
  "name": "Monetra TopLevel",
  "groups": [
    {
      "id": "111111111111",
      "name": "merchant1",
      "profiles": [
        {
           "id": "444444444444",
           "profile_name": "merchant1 profile",
           "stats": {
             "VISA_auth_cnt": "5",
             "VISA_auth_amt": "903.43"
           }
        }
      ]
    },
    {
      "id": "111111111112",
      "name": "some group",
      "groups": [
        {
          "id": "11111111113",
          "name": "blah merchant",
          "profiles": [
            {
              "id": "222222222222",
              "profile_name": "blah merchant profile",
              "stats": {
                "MC_auth_cnt": "1",
                "MC_auth_amt": "12.34"
              }
            }
          ]
        }
      ]
    }
  ]
}

libmonetra KVS equivalent for endpoint

  • action_sys = profile_stats
  • profile_stats = detail
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
bdate
required
string
Example: bdate=-6 months

Start of date range

edate
required
string
Example: edate=now

End of date range

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
group_id
string
Example: group_id=36789654543

Group identifier

id
string

Profile ID to request statistics for

Responses

Request samples 

curl -X GET 'https://testbox.monetra.com/api/v2/system/stats/detail?bdate=epoch&edate=now&json=no' --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_auth(apikey_idapikey)
query Parameters
bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

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 a profile

libmonetra KVS equivalent for endpoint

  • action_sys = profile_stats
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
profile_id
required
string
Example: 78965743785967

Profile ID for statistics

query Parameters
bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

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

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/11245252' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "totaltransnum": "5",
  • "totaltransamount": "139.88",
  • "totalauthnum": "4",
  • "totalauthamount": "152.20",
  • "totalreturnnum": "1",
  • "totalreturnamount": "12.32"
}

List Profile Statistics

Get statistics for profiles

The resulting report will contain these headers:

profile_id, status, profile_name, group_id, create_ts, name, totaltransNum,
totaltransAmount, totalAuthNum, totalAuthAmount, totalReturnNum,
totalReturnAmount

When using JSON ouput, the output will be a hierarchical view of various statistics containing each parent group with minimal data.

Example:

{
  "id": "1",
  "name": "Monetra TopLevel",
  "groups": [
    {
      "id": "111111111111",
      "name": "merchant1",
      "profiles": [
        {
           "id": "444444444444",
           "status": "ACTIVE",
           "profile_name": "123456789",
           "name": "Gadgets",
           "create_ts": "2023-07-18 13:00:43 -0400",
           "stats": {
             "totalAuthNum": "5",
             "totalAuthAmount": "903.43",
             "totalReturnNum": "0",
             "totalReturnAmount": "0.00"
           }
        }
      ]
    },
    {
      "id": "111111111112",
      "name": "some group",
      "groups": [
        {
          "id": "11111111113",
          "name": "blah merchant",
          "profiles": [
            {
              "id": "222222222222",
              "status": "ACTIVE",
              "profile_name": "987654321",
              "name": "My store",
              "create_ts": "2023-07-06 18:28:44 -0400",
              "stats": {
                "totalAuthNum": "1",
                "totalAuthAmount": "12.34",
                "totalReturnNum": "0",
                "totalReturnAmount": "0.00"
              }
            }
          ]
        }
      ]
    }
  ]
}

libmonetra KVS equivalent for endpoint

  • action_sys = profile_stats
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
bdate
required
string
Example: bdate=-6 months

Start of date range

edate
required
string
Example: edate=now

End of date range

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
group_id
string
Example: group_id=36789654543

Group identifier

profile_id
string
Example: profile_id=78965743785967

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.

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

Only include totals

Values:

  • yes - Only include totals
  • no - Include details
show_zero_amounts
object
Enum: "yes" "no" "only"
Example: show_zero_amounts=yes

Whether or not to show profiles with zero totals

Values:

  • yes - Show both zero and non zero totals
  • no - Show only non-zero totals
  • only - Show only profiles with zero totals
create_ts_max
string

Only show profiles created before this date

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

Output results only for active profiles

Values:

  • yes - Output only active profiles
  • no - Output both active and disabled profiles

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_auth(apikey_idapikey)
query Parameters
file
required
string
Example: file=/tmp/export.bin

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
Example: stages=0-5

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=no

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

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_auth(apikey_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": "/tmp/export.bin",
  • "key": "DE67875FEAB4543C"
}

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_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 96748596765467

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_auth(apikey_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": "96748596765467"
}