logo
Documentation Powered by ReDoc

TranSafe - BETA (2.0.0)

Download OpenAPI specification:Download

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

Overview

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

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

Parameter Groups

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

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

Response Codes

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

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

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

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 TranSafe. It can be determined if a decline is from TranSafe if msoft_code is anything other than SUCCESS.

phard_code

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

Reports

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

  • code
  • verbiage

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

libMonetra

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

Time Formats

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

  • formatted time
  • Unix timestamp

Formatted

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

Fixed

Fixed formats are very similar to written dates and times.

Formats:

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

Offset

Offsets take this format:

+ or -
  magnitude
  space
  modifier

Modifiers:

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

Example

+1 day
-5 years

Special keywords

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

Unix Timestamp

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

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

Test Server

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

Server: https://test.transafe.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 TranSafe username and password for the account setup to run transactions is used with the Basic authentication method.

basic_auth

Security Scheme Type HTTP
HTTP Authorization Scheme basic

apikey_id

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

apikey

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

dual_control

Security Scheme Type HTTP
HTTP Authorization Scheme basic

API Key Authentication

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

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

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

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

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

  • auth_apikey_id
  • auth_apikey_secret

Programming language examples

Python

import urllib.request
import base64

URL = 'https://test.transafe.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://test.transafe.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://test.transafe.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://test.transafe.com/api/v2/report/failed'
USER = '@TEST_USERNAME_M9@'
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://test.transafe.com/api/v2/report/failed";
        var username = "@TEST_USERNAME_M9@";
        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://test.transafe.com/api/v2/report/failed";
$username = "@TEST_USERNAME_M9@";
$password = "publ1ct3st";
$opts = array(
  "http"=>array(
    "method"=>"GET",
    "header" => "Authorization: Basic " . base64_encode("$username:$password")
  ),
);
$context = stream_context_create($opts);
$file = file_get_contents($url, false, $context);
echo $file;
?>

Dual Authentication

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

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

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

The users must be different.

MFA Code

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

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

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

Transactions

Transaction operations

Reverse Transaction

Removes a previously authorized transaction in real time

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

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

libmonetra KVS equivalent for endpoint

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

Transaction identifier

query Parameters
profile_id
string

Merchant profile identifier

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

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

amount
string
Example: amount=19.92

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

Responses

Request samples 

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

Response samples

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

Adjust Transaction

Modifies transaction data

This allows adding or modifying transaction parameters after authorization.

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

This action can also edit fields that affect interchange rates (e.g tax, rate, and bdate/edate). If an interchange parameter was not known at time of authorization but is required for settlement the transaction can be modified to add this data. Also, if the parameter was sent during authorization but was not the final value, it can be updated with the final value. For example, adding a tip after the fact to a transaction if it was not sent during authorization. Or changing the tip amount after authorization.

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

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

libmonetra KVS equivalent for endpoint

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

Transaction identifier

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

Merchant profile identifier

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

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

object

Monetary parameters

object

Lodging parameters

object

Order detail parameters

object

Shipping detail parameters

object

Merchant lane parameters

property name*
string

Responses

Request samples

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

Response samples

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

Balance

Balance inquiry

Applies to:

  • Credit
  • Debit
  • Gift

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

object (_vault_account_account_data)

Account information parameters

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

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

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

ENCRYPTION

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

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

object (_transaction_balance_verification)

Verification parameters

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

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

Defaults to no if not present.

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

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

Values:

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

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

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

Requires:

  • tokenize

Values:

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

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "Y",
  • "card_signature_debit": "Y",
  • "card_token_card": "Y",
  • "rcpt_host_ts": "string",
  • "rcpt_entry_mode": "G",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "Y",
  • "rcpt_resp_code": "string",
  • "rcpt_issuer_resp_code": "string",
  • "rcpt_emv_aid": "string",
  • "rcpt_emv_name": "string",
  • "rcpt_emv_tvr": "string",
  • "rcpt_emv_tsi": "string",
  • "rcpt_emv_actype": "AAC",
  • "rcpt_emv_ac": "string",
  • "rcpt_emv_form_factor": "string",
  • "rcpt_custom": "string",
  • "rcpt_emv_iad": "string",
  • "rcpt_emv_card_decline": "string",
  • "printdata": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "balance": "string",
  • "timestamp": "string",
  • "token": "string"
}

Capture

Add an uncaptured sale to a batch

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

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

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

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

libmonetra KVS equivalent for endpoint

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

Transaction identifier

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

Merchant profile identifier

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

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

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

Processing priority.

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

Values:

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

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

rcpt
string

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

Response samples

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

Duplicate a Pre-Authorize

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

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

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

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

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

libmonetra KVS equivalent for endpoint

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

Identifier for transaction to duplicate

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

Merchant profile identifier

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

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

object

Verification parameters

object

Shipping detail parameters

object

E-commerce parameters

object

Healthcare parameters

object

Lodging parameters

object

Merchant descriptor parameters

object

Merchant lane parameters

required
object

Monetary parameters

object

Order detail parameters

object

PIN data parameters

object

Processing options

object

Recurring group

nsf
string
Enum: "yes" "no"

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

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

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

Values:

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

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

Defaults to no if not present.

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

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

Values:

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

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

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

Requires:

  • tokenize

Values:

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

Check the card deny list before going online for authorization

If on the list, decline with msoft_code=CARDDENYLIST.

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

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

Values:

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

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

Values:

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

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

Response samples

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

Duplicate a Purchase

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

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

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

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

libmonetra KVS equivalent for endpoint

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

Identifier for transaction to duplicate

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

Merchant profile identifier

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

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

object

Verification parameters

object

Shipping detail parameters

object

E-commerce parameters

object

Healthcare parameters

object

Lodging parameters

object

Merchant descriptor parameters

object

Merchant lane parameters

required
object

Monetary parameters

object

Order detail parameters

object

PIN data parameters

object

Processing options

object

Recurring group

nsf
string
Enum: "yes" "no"

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

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

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

Values:

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

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

Defaults to no if not present.

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

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

Values:

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

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

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

Requires:

  • tokenize

Values:

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

Check the card deny list before going online for authorization

If on the list, decline with msoft_code=CARDDENYLIST.

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

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

Values:

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

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

Values:

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

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

Response samples

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

Get Card Type

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

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

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

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

object (_vault_account_account_data)

Account information parameters

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

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

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

ENCRYPTION

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

Due to the difference in encrypted reader output and some formats being proprietary limited information about the encrypted account fields are provided. If it is necessary to directly send encrypted reader data to TranSafe 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, TranSafe will attempt to return an existing token for the account.

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

Requires:

  • tokenize

Values:

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

Responses

Request samples

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

Response samples

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

Incremental

Operation used to increase amount for an existing authorization

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

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

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

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

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

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

libmonetra KVS equivalent for endpoint

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

Identifier for transaction to increase amount

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

Merchant profile identifier

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

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

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

New total amount, not amount being added

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

Amount of tax that applies to the order

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

nsf
string
Enum: "yes" "no"

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

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

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

Values:

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

Lodging parameters

object

Merchant descriptor parameters

object

Merchant lane parameters

rcpt
string

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

Response samples

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

Pre-Authorization Completion

Finalize a Pre-Authorization

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

libmonetra KVS equivalent for endpoint

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

Transaction identifier

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

Merchant profile identifier

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

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

object

Shipping detail parameters

zip
string <= 32 characters

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

object

Lodging parameters

object

Merchant lane parameters

object

Monetary parameters

object

Order detail parameters

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

Processing priority.

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

Values:

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

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

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

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

Defaults to no if not present.

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

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

Values:

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

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

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

Requires:

  • tokenize

Values:

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

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

Response samples

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

Pre-Authorize

Places a hold on funds without capturing for settlement

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

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

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

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

object

Account information parameters

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

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

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

ENCRYPTION

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

Due to the difference in encrypted reader output and some formats being proprietary limited information about the encrypted account fields are provided. If it is necessary to directly send encrypted reader data to TranSafe 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, TranSafe will attempt to return an existing token for the account.

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

Requires:

  • tokenize

Values:

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

Check the card deny list before going online for authorization

If on the list, decline with msoft_code=CARDDENYLIST.

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

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

Values:

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

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

Values:

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

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

Response samples

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

Purchase

Debits available funds from cardholder's account.

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

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

object

Account information parameters

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

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

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

ENCRYPTION

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

Due to the difference in encrypted reader output and some formats being proprietary limited information about the encrypted account fields are provided. If it is necessary to directly send encrypted reader data to TranSafe 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, TranSafe will attempt to return an existing token for the account.

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

Requires:

  • tokenize

Values:

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

Check the card deny list before going online for authorization

If on the list, decline with msoft_code=CARDDENYLIST.

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

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

Values:

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

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

Values:

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

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

Response samples

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

Refund Existing Transaction

Refunds a prior purchase

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

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

libmonetra KVS equivalent for endpoint

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

Identifier for transaction to refund

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

Merchant profile identifier

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

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

object

Merchant descriptor parameters

object

Merchant lane parameters

object

Monetary parameters

object

Order detail parameters

object

PIN data parameters

object

Recurring group

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

Processing priority.

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

Values:

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

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

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

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

Defaults to no if not present.

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

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

Values:

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

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

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

Requires:

  • tokenize

Values:

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

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

Response samples

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

Unlinked Refund

Unlinked Refund

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

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

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

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

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

object

Account information parameters

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

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

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

ENCRYPTION

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

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

object

Merchant descriptor parameters

object

Merchant lane parameters

object

Monetary parameters

object

Order detail parameters

object

PIN data parameters

object

Recurring group

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

Processing priority.

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

Values:

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

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

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

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

Defaults to no if not present.

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

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

Values:

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

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

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

Requires:

  • tokenize

Values:

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

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Identifier for transaction to refund

property name*
string

Responses

Request samples

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

Response samples

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

Verify Card

Verifies avs and cv data

The two main uses for this operation are to:

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

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

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

object

Account information parameters

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

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

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

ENCRYPTION

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

Due to the difference in encrypted reader output and some formats being proprietary limited information about the encrypted account fields are provided. If it is necessary to directly send encrypted reader data to TranSafe 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, TranSafe will attempt to return an existing token for the account.

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

Requires:

  • tokenize

Values:

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

Check the card deny list before going online for authorization

If on the list, decline with msoft_code=CARDDENYLIST.

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

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

Values:

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

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

Values:

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "Y",
  • "card_signature_debit": "Y",
  • "card_token_card": "Y",
  • "rcpt_host_ts": "string",
  • "rcpt_entry_mode": "G",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "Y",
  • "rcpt_resp_code": "string",
  • "rcpt_issuer_resp_code": "string",
  • "rcpt_emv_aid": "string",
  • "rcpt_emv_name": "string",
  • "rcpt_emv_tvr": "string",
  • "rcpt_emv_tsi": "string",
  • "rcpt_emv_actype": "AAC",
  • "rcpt_emv_ac": "string",
  • "rcpt_emv_form_factor": "string",
  • "rcpt_custom": "string",
  • "rcpt_emv_iad": "string",
  • "rcpt_emv_card_decline": "string",
  • "printdata": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "timestamp": "string",
  • "token": "string",
  • "carddenylist_id": "string"
}

Void Transaction

Removes a previously authorized transaction

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

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

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

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

libmonetra KVS equivalent for endpoint

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

Transaction identifier

query Parameters
profile_id
string

Merchant profile identifier

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

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

Responses

Request samples 

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

Response samples

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

Gift

Gift specific operations

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

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

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

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

Gift Activate

Activate a Gift card

See description for the gift card issue operation for details.

Processors supporting activate

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

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

object (_vault_account_account_data)

Account information parameters

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

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

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

ENCRYPTION

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

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

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

Customer PIN number

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

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

For Gift, this is typically the plain text PIN.

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

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

Card Verification value.

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

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

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

object (_transaction_activate_merchant_descriptors)

Merchant descriptor parameters

object (_transaction_activate_lane)

Merchant lane parameters

object (_transaction_activate_order)

Order detail parameters

object (_transaction_activate_processing_options)

Processing options

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

Amount of money, including decimal. E.g 1.00

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

nsf
string
Enum: "yes" "no"

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

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

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

Values:

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

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

Response samples

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

Gift Cash Out

Remove all funds from a gift card

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

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

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

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

object (_vault_account_account_data)

Account information parameters

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

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

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

ENCRYPTION

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

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

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

Customer PIN number

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

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

For Gift, this is typically the plain text PIN.

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

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

Card Verification value.

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

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

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

object (_transaction_activate_merchant_descriptors)

Merchant descriptor parameters

object (_transaction_activate_lane)

Merchant lane parameters

object (_transaction_activate_order)

Order detail parameters

object (_transaction_activate_processing_options)

Processing options

rcpt
string

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

Response samples

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

Gift Issue

Issue a Gift card

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

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

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

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

Processors supporting issue

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

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

object (_vault_account_account_data)

Account information parameters

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

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

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

ENCRYPTION

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

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

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

Customer PIN number

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

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

For Gift, this is typically the plain text PIN.

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

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

Card Verification value.

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

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

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

object (_transaction_activate_merchant_descriptors)

Merchant descriptor parameters

object (_transaction_activate_lane)

Merchant lane parameters

object (_transaction_activate_order)

Order detail parameters

object (_transaction_activate_processing_options)

Processing options

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

Amount of money, including decimal. E.g 1.00

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

nsf
string
Enum: "yes" "no"

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

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

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

Values:

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

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

Response samples

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

Gift Merchandise Refund

Refunds merchandise to a gift card

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

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

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

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

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

object

Account information parameters

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

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

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

ENCRYPTION

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

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

object

Merchant descriptor parameters

object

Merchant lane parameters

object

Monetary parameters

object

Order detail parameters

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

Processing priority.

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

Values:

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

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

rcpt
string

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

Response samples

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

Gift Merchandise Refund Existing Transaction

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

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

libmonetra KVS equivalent for endpoint

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

Identifier for the gift card transaction to refund merchandise

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

Merchant profile identifier

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

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

object

Merchant descriptor parameters

object

Merchant lane parameters

object

Monetary parameters

object

Order detail parameters

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

Processing priority.

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

Values:

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

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

rcpt
string

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

Response samples

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

EBT

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

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

Cash accounts are typically unrestricted.

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

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

EBT Cash Balance

Get the balance on a Cash account

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

object

Account information parameters

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

These are the minimum fields required for each entry method.

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

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

ENCRYPTION

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

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

required
object

PIN data parameters

rcpt
string

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

Response samples

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

EBT Cash Purchase

Debit funds from a Cash account

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

object

Account information parameters

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

These are the minimum fields required for each entry method.

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

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

ENCRYPTION

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

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

object

Merchant descriptor parameters

object

Merchant lane parameters

object

Order detail parameters

required
object

PIN data parameters

object

Processing options

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

Amount of money, including decimal. E.g 1.00

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

nsf
string
Enum: "yes" "no"

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

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

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

Values:

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

Check the card deny list before going online for authorization

If on the list, decline with msoft_code=CARDDENYLIST.

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

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

Values:

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

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

Values:

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

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

Response samples

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

EBT Food Balance

Get the balance on a Food account

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

object

Account information parameters

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

These are the minimum fields required for each entry method.

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

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

ENCRYPTION

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

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

required
object

PIN data parameters

rcpt
string

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

Response samples

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

EBT Food Purchase

Debit funds from a Food account

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

object

Account information parameters

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

These are the minimum fields required for each entry method.

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

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

ENCRYPTION

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

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

object

Merchant descriptor parameters

object

Merchant lane parameters

object

Order detail parameters

required
object

PIN data parameters

object

Processing options

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

Amount of money, including decimal. E.g 1.00

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

nsf
string
Enum: "yes" "no"

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

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

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

Values:

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

Check the card deny list before going online for authorization

If on the list, decline with msoft_code=CARDDENYLIST.

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

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

Values:

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

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

Values:

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

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

Response samples

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

EBT Food Refund

Refund to a EBT Food account

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

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

object

Account information parameters

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

These are the minimum fields required for each entry method.

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

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

ENCRYPTION

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

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

object

Merchant descriptor parameters

object

Merchant lane parameters

object

Order detail parameters

required
object

PIN data parameters

object

Processing options

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

Amount of money, including decimal. E.g 1.00

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

nsf
string
Enum: "yes" "no"

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

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

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

Values:

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

Check the card deny list before going online for authorization

If on the list, decline with msoft_code=CARDDENYLIST.

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

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

Values:

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

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

Values:

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

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

Response samples

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

Transaction Details

Transaction detail operations

Get All Payment Details For an Order

Get all order payment transaction details

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

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

libmonetra KVS equivalent for endpoint

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

Unique ID of an order

Cannot be combined with:

  • ttid
query Parameters
profile_id
string

Merchant profile identifier

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

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

ttid
string

Transaction identifier

Cannot be combined with:

  • order_id
payment_id
string

Unique ID of a payment for an order

Requires:

  • order_id

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "Y",
  • "card_signature_debit": "Y",
  • "card_token_card": "Y",
  • "auth": "string",
  • "batch": "string",
  • "issuer_decline": "Y",
  • "item": "string",
  • "stan": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "abaroute": "string",
  • "checknum": "string",
  • "accounttype": "BUSINESS",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "cof_transid": "string",
  • "cof_authamount": "string",
  • "installment_num": "string",
  • "installment_total": "string",
  • "recurring": "recurring",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "shipcountry": "string",
  • "shipzip": "string",
  • "zip": "32606",
  • "action": "string",
  • "orig_code": "string",
  • "orig_msoft_code": "string",
  • "orig_phard_code": "string",
  • "orig_reqamount": "string",
  • "orig_verbiage": "string",
  • "merch_name": "string",
  • "merch_addr1": "string",
  • "merch_addr2": "string",
  • "merch_addr3": "string",
  • "merch_phone": "string",
  • "merch_email": "string",
  • "merch_url": "string",
  • "merch_proc": "string",
  • "custref": "55",
  • "ordernum": "A13DDES345",
  • "amount": "19.92",
  • "cashbackamount": "20.00",
  • "currency": "string",
  • "examount": "0.33",
  • "surchargeamount": "1.25",
  • "tax": "1.29",
  • "discountamount": "100.00",
  • "dutyamount": "5.07",
  • "freightamount": "225.82",
  • "bdate": "string",
  • "edate": "string",
  • "excharges": "REST",
  • "rate": "12.00",
  • "roomnum": "string",
  • "descmerch": "string",
  • "descloc": "string",
  • "clerkid": "string",
  • "stationid": "7",
  • "laneid": "4",
  • "comments": "string",
  • "divisionnum": "PAYROLL",
  • "expdate": "0129",
  • "healthcare": "yes",
  • "reversible": "yes",
  • "reversal_reason": "CLERKVOID",
  • "offline_decline": "string",
  • "tranflags": "HASAVS",
  • "txnstatus": "DECLINED",
  • "last_modified_ts": "string",
  • "order_id": "string",
  • "payment_id": "string",
  • "order_cash_discount": "string",
  • "order_cash_price": "string",
  • "order_noncash_price": "string",
  • "order_tip": "string",
  • "order_total": "string",
  • "order_tax": "string",
  • "order_discount": "string",
  • "detail_order_notes": "string",
  • "trans": "string",
  • "line_items": "string",
  • "ttid": "string",
  • "property1": "string",
  • "property2": "string"
}

Get Transaction Details

Gets fine-grained detail about a transaction

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

libmonetra KVS equivalent for endpoint

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

Transaction identifier

query Parameters
profile_id
string

Merchant profile identifier

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

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

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "Y",
  • "card_signature_debit": "Y",
  • "card_token_card": "Y",
  • "auth": "string",
  • "batch": "string",
  • "issuer_decline": "Y",
  • "item": "string",
  • "stan": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "abaroute": "string",
  • "checknum": "string",
  • "accounttype": "BUSINESS",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "cof_transid": "string",
  • "cof_authamount": "string",
  • "installment_num": "string",
  • "installment_total": "string",
  • "recurring": "recurring",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "shipcountry": "string",
  • "shipzip": "string",
  • "zip": "32606",
  • "action": "string",
  • "orig_code": "string",
  • "orig_msoft_code": "string",
  • "orig_phard_code": "string",
  • "orig_reqamount": "string",
  • "orig_verbiage": "string",
  • "merch_name": "string",
  • "merch_addr1": "string",
  • "merch_addr2": "string",
  • "merch_addr3": "string",
  • "merch_phone": "string",
  • "merch_email": "string",
  • "merch_url": "string",
  • "merch_proc": "string",
  • "custref": "55",
  • "ordernum": "A13DDES345",
  • "amount": "19.92",
  • "cashbackamount": "20.00",
  • "currency": "string",
  • "examount": "0.33",
  • "surchargeamount": "1.25",
  • "tax": "1.29",
  • "discountamount": "100.00",
  • "dutyamount": "5.07",
  • "freightamount": "225.82",
  • "bdate": "string",
  • "edate": "string",
  • "excharges": "REST",
  • "rate": "12.00",
  • "roomnum": "string",
  • "descmerch": "string",
  • "descloc": "string",
  • "clerkid": "string",
  • "stationid": "7",
  • "laneid": "4",
  • "comments": "string",
  • "divisionnum": "PAYROLL",
  • "expdate": "0129",
  • "healthcare": "yes",
  • "reversible": "yes",
  • "reversal_reason": "CLERKVOID",
  • "offline_decline": "string",
  • "tranflags": "HASAVS",
  • "txnstatus": "DECLINED",
  • "last_modified_ts": "string",
  • "order_id": "string",
  • "payment_id": "string",
  • "order_cash_discount": "string",
  • "order_cash_price": "string",
  • "order_noncash_price": "string",
  • "order_tip": "string",
  • "order_total": "string",
  • "order_tax": "string",
  • "order_discount": "string",
  • "detail_order_notes": "string",
  • "trans": "string",
  • "line_items": "string",
  • "ttid": "string",
  • "property1": "string",
  • "property2": "string"
}

Get Transaction Details For Order Payment

Gets fine-grained detail about an order payment

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

libmonetra KVS equivalent for endpoint

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

Unique ID of an order

payment_id
required
string

Unique ID of a payment for an order

query Parameters
profile_id
string

Merchant profile identifier

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

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

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "card_currency": "string",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "string",
  • "card_country_code": "string",
  • "card_debit_network": "string",
  • "card_ebt_state": "string",
  • "card_fsa": "Y",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "string",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "Y",
  • "card_signature_debit": "Y",
  • "card_token_card": "Y",
  • "auth": "string",
  • "batch": "string",
  • "issuer_decline": "Y",
  • "item": "string",
  • "stan": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "abaroute": "string",
  • "checknum": "string",
  • "accounttype": "BUSINESS",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "cof_transid": "string",
  • "cof_authamount": "string",
  • "installment_num": "string",
  • "installment_total": "string",
  • "recurring": "recurring",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "shipcountry": "string",
  • "shipzip": "string",
  • "zip": "32606",
  • "action": "string",
  • "orig_code": "string",
  • "orig_msoft_code": "string",
  • "orig_phard_code": "string",
  • "orig_reqamount": "string",
  • "orig_verbiage": "string",
  • "merch_name": "string",
  • "merch_addr1": "string",
  • "merch_addr2": "string",
  • "merch_addr3": "string",
  • "merch_phone": "string",
  • "merch_email": "string",
  • "merch_url": "string",
  • "merch_proc": "string",
  • "custref": "55",
  • "ordernum": "A13DDES345",
  • "amount": "19.92",
  • "cashbackamount": "20.00",
  • "currency": "string",
  • "examount": "0.33",
  • "surchargeamount": "1.25",
  • "tax": "1.29",
  • "discountamount": "100.00",
  • "dutyamount": "5.07",
  • "freightamount": "225.82",
  • "bdate": "string",
  • "edate": "string",
  • "excharges": "REST",
  • "rate": "12.00",
  • "roomnum": "string",
  • "descmerch": "string",
  • "descloc": "string",
  • "clerkid": "string",
  • "stationid": "7",
  • "laneid": "4",
  • "comments": "string",
  • "divisionnum": "PAYROLL",
  • "expdate": "0129",
  • "healthcare": "yes",
  • "reversible": "yes",
  • "reversal_reason": "CLERKVOID",
  • "offline_decline": "string",
  • "tranflags": "HASAVS",
  • "txnstatus": "DECLINED",
  • "last_modified_ts": "string",
  • "order_id": "string",
  • "payment_id": "string",
  • "order_cash_discount": "string",
  • "order_cash_price": "string",
  • "order_noncash_price": "string",
  • "order_tip": "string",
  • "order_total": "string",
  • "order_tax": "string",
  • "order_discount": "string",
  • "detail_order_notes": "string",
  • "trans": "string",
  • "line_items": "string",
  • "ttid": "string",
  • "property1": "string",
  • "property2": "string"
}

Transaction Receipts

Receipts can be generated for transactions, payments, and orders

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

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

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

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

Email

Email of receipts will contain a formatted receipt.

SMS

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

Pre-formatted

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

Email Transaction Receipt

Email a receipt for a transaction to the customer

libmonetra KVS equivalent for endpoint

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

Transaction identifier

query Parameters
profile_id
string

Merchant profile identifier

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

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

email
required
string

Email to send customer receipt copy to

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

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

Values:

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

Responses

Request samples 

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

Response samples

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

Email Transaction Receipt For Order Payment

Email a receipt for an order payment to a customer

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

libmonetra KVS equivalent for endpoint

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

Unique ID of an order

payment_id
required
string

Unique ID of a payment for an order

query Parameters
profile_id
string

Merchant profile identifier

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

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

email
required
string

Email to send customer receipt copy to

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

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

Values:

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

Values:

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

Responses

Request samples 

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

Response samples

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

Email an Invoice to Customer

Email a link to view the invoice to a customer

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

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

libmonetra KVS equivalent for endpoint

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

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

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

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

email
required
string

Email to send customer receipt copy to

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

Responses

Request samples 

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

Response samples

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

Get Transaction Receipt

Get Pre-formatted receipt for a transaction

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

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

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

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

libmonetra KVS equivalent for endpoint

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

Transaction identifier

query Parameters
profile_id
string

Merchant profile identifier

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

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

rcpt
string
Example: rcpt=yes

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Cannot be combined with:

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

Values:

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

Values:

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

Responses

Request samples 

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

Response samples

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

Get Transaction Receipt For Order Payment

Get Pre-formatted receipt for an order payment

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

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

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

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

libmonetra KVS equivalent for endpoint

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

Unique ID of an order

payment_id
required
string

Unique ID of a payment for an order

query Parameters
profile_id
string

Merchant profile identifier

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

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

rcpt
string
Example: rcpt=yes

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Values:

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

Values:

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

Responses

Request samples 

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

Response samples

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

SMS an Invoice to Customer

SMS a link to view the invoice to a customer

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

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

libmonetra KVS equivalent for endpoint

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

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

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

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

sms
required
string

Send SMS for order invoices

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

Requires:

  • order_id

Cannot be combined with:

  • ttid
  • payment_id

Responses

Request samples 

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

Response samples

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

Transaction Reports

Transaction Report operations

List Declined Transactions

Lists all failed transactions for the requested profile

The resulting report will contain these headers:

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

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

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

acct
string

Account number for auditing

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

amount
string
Example: amount=19.92

Amount of money, including decimal. E.g 1.00

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

bdate
string

Start of date range

edate
string

End of date range

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder

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

Cardtypes

Pipe (|) separated.

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

Flag values (pipe separated):

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

Identifier for the clerk running the transaction

comments
string

User-defined comments related to the transaction

ordernum
string
Example: ordernum=A13DDES345

Order number

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

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

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

stationid
string
Example: stationid=7

Identifier for the physical station running the transaction

type
string
Example: type=sale

Type of action that was taken.

Can be a pipe (|) separated list of actions

last_modified_bdate
string

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

last_modified_edate
string

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

Responses

Request samples 

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

Response samples

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

List Settled Transactions

Lists all settled transactions for the requested profile

The resulting report will contain these headers:

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

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

acct
string

Account number for auditing

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

amount
string
Example: amount=19.92

Amount of money, including decimal. E.g 1.00

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

batch
string

The batch number associated with the transaction

bdate
string

Start of date range

edate
string

End of date range

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder

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

Cardtypes

Pipe (|) separated.

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

Flag values (pipe separated):

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

Identifier for the clerk running the transaction

comments
string

User-defined comments related to the transaction

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

Indicates the level of payment card

Values:

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

Order number

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

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

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

stationid
string
Example: stationid=7

Identifier for the physical station running the transaction

ttid
string

Transaction identifier

token
string

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

type
string
Example: type=sale

Type of action that was taken.

Can be a pipe (|) separated list of actions

last_modified_bdate
string

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

last_modified_edate
string

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

user
string

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

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

Include interchange response data

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

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

Values:

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

Whether or not the report should include voids

Values:

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

Whether or not the report should include reversible transactions

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

Values:

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

Responses

Request samples 

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

Response samples

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

List Transactions

Lists all transactions for the requested profile

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

The resulting report will contain these headers:

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

libmonetra KVS equivalent for endpoint

  • action_admin = report_tran
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

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

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

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

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

Flag values (pipe separated):

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

Account number for auditing

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

amount
string
Example: amount=19.92

Amount of money, including decimal. E.g 1.00

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

batch
string

The batch number associated with the transaction

bdate
string

Start of date range

edate
string

End of date range

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder

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

Cardtypes

Pipe (|) separated.

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

Flag values (pipe separated):

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

Identifier for the clerk running the transaction

comments
string

User-defined comments related to the transaction

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

Indicates the level of payment card

Values:

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

Order number

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

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

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

stationid
string
Example: stationid=7

Identifier for the physical station running the transaction

ttid
string

Transaction identifier

token
string

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

type
string
Example: type=sale

Type of action that was taken.

Can be a pipe (|) separated list of actions

last_modified_bdate
string

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

last_modified_edate
string

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

user
string

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

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

Include interchange response data

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

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

Values:

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

Responses

Request samples 

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

Response samples

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

List Unsettled Transactions

Lists all unsettled transactions for the requested profile

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

The resulting report will contain these headers:

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

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

acct
string

Account number for auditing

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

amount
string
Example: amount=19.92

Amount of money, including decimal. E.g 1.00

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

batch
string

The batch number associated with the transaction

bdate
string

Start of date range

edate
string

End of date range

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder

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

Cardtypes

Pipe (|) separated.

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

Flag values (pipe separated):

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

Identifier for the clerk running the transaction

comments
string

User-defined comments related to the transaction

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

Indicates the level of payment card

Values:

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

Order number

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

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

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

stationid
string
Example: stationid=7

Identifier for the physical station running the transaction

ttid
string

Transaction identifier

token
string

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

type
string
Example: type=sale

Type of action that was taken.

Can be a pipe (|) separated list of actions

last_modified_bdate
string

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

last_modified_edate
string

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

user
string

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

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

Include interchange response data

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

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

Values:

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

Responses

Request samples 

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

Response samples

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

Chart Data

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

The chats provide buckets based on time segments over a given time period. Each bucket will have the number of the charted data in order to generate graphs.

Card Type Chart Data

Totals for card types used to generate charts

The resulting report will contain these headers:

cardtype count

libmonetra KVS equivalent for endpoint

  • action_admin = report_chartdata
  • chartdata = cardtype
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

bdate
required
string

Start of date range

edate
required
string

End of date range

grouping
required
object
Enum: "hour" "day"
Example: grouping=day

Group chart data within a time period

Grouping allows fine or course grained details about the data requested.

Values:

  • hour - Report is an hourly breakdown
  • day - report is a daily breakdown

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/report/chartdata/carddtype?bdate=-2%20days&edate=now' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Order Chart Data

Totals for orders used to generate charts

The resulting report will contain these headers:

ts_begin, ts_end, sale_count, sale_amount, return_count, return_amount

libmonetra KVS equivalent for endpoint

  • action_admin = report_chartdata
  • chartdata = orders
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

bdate
required
string

Start of date range

edate
required
string

End of date range

grouping
required
object
Enum: "hour" "day"
Example: grouping=day

Group chart data within a time period

Grouping allows fine or course grained details about the data requested.

Values:

  • hour - Report is an hourly breakdown
  • day - report is a daily breakdown

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/report/chartdata/orders?bdate=-2%20days&edate=now' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Transaction Chart Data

Totals for transactions used to generate charts

The resulting report will contain these headers:

ts_begin, ts_end, sale_count, sale_amount, return_count, return_amount, failed_count

libmonetra KVS equivalent for endpoint

  • action_admin = report_chartdata
  • chartdata = transactions
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

bdate
required
string

Start of date range

edate
required
string

End of date range

grouping
required
object
Enum: "hour" "day"
Example: grouping=day

Group chart data within a time period

Grouping allows fine or course grained details about the data requested.

Values:

  • hour - Report is an hourly breakdown
  • day - report is a daily breakdown

Responses

Request samples 

curl -X GET 'https://test.transafe.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 TranSafe order system. As long as the line items in the order contain all required information for Level 3 line items. This includes items from TranSafe's inventory system or custom order line items. This only applies when a transaction is associated with an order before settlement.

A transaction can be associated in two ways:

  • Manually, using the order payment system
  • Automatically, by sending order_id with the purchase or pre-authorization

Line item pre-populate

Profiles can be configured with pre-populated, default, Level 3 line items. The relevant information is configured on the profile. The default values will be used to create a single line item added to the transaction. This is intended for merchants that routinely sell a single item and is a convince to simplify this common type of integration.

If manual line items are added either manually or via an order, they will be used instead of the pre-populate default values. If the transaction contains more than the default item, or additional items, the integration must send the line items that are actually part of the transaction.

List Line Items

Retrieves a list of Level 3 line items associated with an unsettled transaction

The resulting report will contain these headers:

l3id, ttid, commoditycode, description, productcode, qty, unit, unitprice,
discountamount, discountrate, amount

libmonetra KVS equivalent for endpoint

  • action_admin = level3
  • level3 = list
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/level3/926660343286234' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Line Item

Adds Level 3 line item to an unsettled transaction

libmonetra KVS equivalent for endpoint

  • action_admin = level3
  • level3 = add
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

commoditycode
required
string[0-9a-zA-Z]{8,12}

Contains an international description code of the individual good or service being supplied

The acquiring bank or processor should provide the merchant an updated listing of currently defined codes. Please note that this is different from the 4-character summary commodity code. Codes can be found online at http://www.unspsc.org

The code itself will not be validated; only the format is validated.

description
required
string[0-9a-zA-Z ]{1,26}

Merchant-defined description of the item or service being sold

This is a free-form field.

productcode
required
string[0-9a-zA-Z ]{1,12}

Merchant-defined code for the item being purchased, such as a UPC #, SKU #, or Item #

qty
required
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

unit
required
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

unitprice
required
string

Item price per Unit

Must not reflect any duty, freight, discount, or tax. This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum amount is 0.00005. Maximum amount is 9999999.99.

discountamount
string

Discount amount per line item

The total discount amount applied against the line item total. This field allows up to 2 decimal places of precision. The sum of all line item discounts must be less than or equal to the transaction's discount amount. If a discount was applied to this line item, this field must be populated.

Minimum amount is 0.00. Maximum amount is 9999999.99.

discountrate
string

Discount rate per line item

The discount rate applied against the line item. This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded. This field appears to be optional. It is not valid to specify this if discount amount is not specified or is 0.

Minimum rate is 0.00. Maximum rate is 99.99.

amount
required
string

Line item total amount

This is the line item amount after all taxes and discounts have been applied (but not inclusive of duty or freight). This amount must be greater than or equal to (unitprice * qty) - discountamount. This amount has 2 decimal places of precision.

Minimum amount is 0.01. Maximum amount is 9999999.99.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "commoditycode": "string",
  • "description": "string",
  • "productcode": "string",
  • "qty": "string",
  • "unit": "string",
  • "unitprice": "string",
  • "discountamount": "string",
  • "discountrate": "string",
  • "amount": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "l3id": "string"
}

Delete Line Item

Deletes Level 3 line item from an unsettled transaction

libmonetra KVS equivalent for endpoint

  • action_admin = level3
  • level3 = del
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

l3id
required
string

ID associated with the Level 3 line item

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/level3/926660343286234/19266603985142159' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Line Item Details

Gets the specified line item for the transaction

libmonetra KVS equivalent for endpoint

  • action_admin = level3
  • level3 = list
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

l3id
required
string

ID associated with the Level 3 line item

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/level3/926660343286234/19266603985142159' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "l3id": "string",
  • "ttid": "string",
  • "commoditycode": "string",
  • "description": "string",
  • "productcode": "string",
  • "qty": "string",
  • "unit": "string",
  • "unitprice": "string",
  • "discountamount": "string",
  • "discountrate": "string",
  • "amount": "string"
}

Batch

Basic and advanced batch management operations.

Basic operations manual settlement and reports.

It is recommended to use automatic settlement instead of manual settlement. As it simplifies the settlement process and removed points of error. No one can forget to settle or forgets to retry settlement if it fails.

One case where manual settlement is necessary is if the profile is changing processing routes. Often transactions authorized by one processor can only be settled with that processor. In this case outstanding batches must be settled before the route change takes place.

More advanced operations are should be used with care and typically only after consultation, and confirmation with the processor.

Clear a Batch

Marks the batch as settled within TranSafe 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 TranSafe did not receive the response.

This must only be used after the processing institution has confirmed they've received the batch and they've instructed not sending it again.

WARNING: This function should be used with extreme caution as clearing a batch which the processing institution has not received will prevent funding of those transactions in the batch. It is imperative confirmation by the processor of funding will take place before using this action.

libmonetra KVS equivalent for endpoint

  • action_admin = batch_clear
Authorizations:
basic_authapikey_idapikey
path Parameters
batch
required
string

The batch number associated with the transaction

route_id
required
string

Processing route

More than one route ID may be associated with a profile. This can happen when split-routing is in use. The specific ID for the route being operated on must be specified in requests that accept route_id.

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Close a Batch

Close the currently open batch without sending it to the processor

This will force TranSafe to start adding transactions to a new batch.

The closed batch will remain in an unsettled state and will not be sent to the processor. To settle a batch, which will send it to the processor to request funds, see "Settle Batch". This is different than clearing a batch.

Only one batch per settlement route can be open at a time. This request enables a Merchant to close a batch so as to prevent additional transactions from being added to it while preventing the batch from being sent online to the processor.

There is often no need to manually close a batch. Batches will be closed and opened per processor requirements and after settlement.

libmonetra KVS equivalent for endpoint

  • action_admin = batch_close
Authorizations:
basic_authapikey_idapikey
path Parameters
batch
required
string

The batch number associated with the transaction

route_id
required
string

Processing route

More than one route ID may be associated with a profile. This can happen when split-routing is in use. The specific ID for the route being operated on must be specified in requests that accept route_id.

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Settled Batch Totals

Gets an abbreviated 'batch totals' summary for each 'Settled' batch, within a given date range.

The resulting report will contain these headers:

batch, route_id, timestamp, totaltransNum, totaltransAmount, totalAuthNum,
totalAuthAmount, totalReturnNum, totalReturnAmount, totaltransExamount,
totalAuthExamount, totalReturnExamount, NumVisaAuth, AmntVisaAuth,
NumVisaReturn, AmntVisaReturn, NumVisaDSAuth, AmntVisaDSAuth, NumVisaDSReturn,
AmntVisaDSReturn, NumMCAuth, AmntMCAuth, NumMCReturn, AmntMCReturn,
NumDiscAuth, AmntDiscAuth, NumDiscReturn, AmntDiscReturn, NumCUPAuth,
AmntCUPAuth, NumCUPReturn, AmntCUPReturn, NumAmexAuth, AmntAmexAuth,
NumAmexReturn, AmntAmexReturn, NumDinersAuth, AmntDinersAuth, NumDinersReturn,
AmntDinersReturn, NumCBAuth, AmntCBAuth, NumCBReturn, AmntCBReturn, NumJCBAuth,
AmntJCBAuth, NumJCBReturn, AmntJCBReturn, NumGIFTAuth, AmntGIFTAuth,
NumGIFTReturn, AmntGIFTReturn, NumOtherAuth, AmntOtherAuth, NumOtherReturn,
AmntOtherReturn, NumDebitAuth, AmntDebitAuth, NumDebitReturn, AmntDebitReturn,
NumEBTAuth, AmntEBTAuth, NumEBTReturn, AmntEBTReturn, NumCheckAuth,
AmntCheckAuth, NumACHAuth, AmntACHAuth, NumACHReturn, AmntACHReturn,
NumUnknownAuth, AmntUnknownAuth, NumUnknownReturn, AmntUnknownReturn

libmonetra KVS equivalent for endpoint

  • action_admin = report_totals
  • report_totals = settled
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

batch
string

The batch number associated with the transaction

bdate
string

Start of date range

edate
string

End of date range

reversible
object
Enum: "yes" "no"
Example: reversible=yes

Whether or not the report should include reversible transactions

If not present, show both reversible and non-reversible transactions

Values:

  • yes - Include reversible transactions
  • no - Do not include reversible transactions

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/batch/totals/settled?bdate=-5%20days&edate=now' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Get Unsettled Batch Totals

Gets an abbreviated 'batch totals' summary for each 'Unsettled' batch.

The resulting report will contain these headers:

batch, route_id, status, totaltransNum, totaltransAmount, totalAuthNum,
totalAuthAmount, totalReturnNum, totalReturnAmount, totaltransExamount,
totalAuthExamount, totalReturnExamount, NumVisaAuth, AmntVisaAuth,
NumVisaReturn, AmntVisaReturn, NumVisaDSAuth, AmntVisaDSAuth, NumVisaDSReturn,
AmntVisaDSReturn, NumMCAuth, AmntMCAuth, NumMCReturn, AmntMCReturn,
NumDiscAuth, AmntDiscAuth, NumDiscReturn, AmntDiscReturn, NumCUPAuth,
AmntCUPAuth, NumCUPReturn, AmntCUPReturn, NumAmexAuth, AmntAmexAuth,
NumAmexReturn, AmntAmexReturn, NumDinersAuth, AmntDinersAuth, NumDinersReturn,
AmntDinersReturn, NumCBAuth, AmntCBAuth, NumCBReturn, AmntCBReturn, NumJCBAuth,
AmntJCBAuth, NumJCBReturn, AmntJCBReturn, NumGIFTAuth, AmntGIFTAuth,
NumGIFTReturn, AmntGIFTReturn, NumOtherAuth, AmntOtherAuth, NumOtherReturn,
AmntOtherReturn, NumDebitAuth, AmntDebitAuth, NumDebitReturn, AmntDebitReturn,
NumEBTAuth, AmntEBTAuth, NumEBTReturn, AmntEBTReturn, NumCheckAuth,
AmntCheckAuth, NumACHAuth, AmntACHAuth, NumACHReturn, AmntACHReturn,
NumUnknownAuth, AmntUnknownAuth, NumUnknownReturn, AmntUnknownReturn

libmonetra KVS equivalent for endpoint

  • action_admin = report_totals
  • report_totals = unsettled
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

batch
string

The batch number associated with the transaction

bdate
string

Start of date range

edate
string

End of date range

Responses

Request samples 

curl -X GET 'https://test.transafe.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. TranSafe will retain data on a settled batch until that batch number is used again, at which point it will be overwritten.

libmonetra KVS equivalent for endpoint

  • action_admin = batch_set
  • batch_set = renumber
Authorizations:
basic_authapikey_idapikey
path Parameters
batch
required
string

The batch number associated with the transaction

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

newbatch
required
string
route_id
string\d+

Processing route

More than one route ID may be associated with a profile. This can happen when split-routing is in use. The specific ID for the route being operated on must be specified in requests that accept route_id.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "newbatch": "string",
  • "route_id": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Resequence Open Batch Numbers

Set open batch numbering to the given value

This will have two effects on the batch number: it will change the open batch's number to the provided value, and it will set the batch counter to that same value. When the batch is then closed/settled, the batch number will be incremented for the new batch. For example, an open batch is numbered "10". When that batch is settled, the next batch will be numbered "11". If instead batch "10" has its number set to "50" using this action, then the next batch will be numbered "51". To only change a batch's number without affecting the numbering of any other batch, see "Renumber Single Batch".

This action is relevant when batch numbers conflict, such as can happen when a merchant is attempting to fix a settlement issue with a processor.

Some notes to keep in mind when modifying a batch number:

Processors keep batch numbers for 7 days to check for duplicates. Batch numbers within that window should not be reused. It is probably wise to not reuse batch numbers within a 90-day window, so as to stay within the card brand's chargeback window to avoid an actual chargeback. TranSafe will retain data on a settled batch until that batch number is used again, at which point it will be overwritten.

libmonetra KVS equivalent for endpoint

  • action_admin = batch_set
  • batch_set = batchnum
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

batch
required
string\d+

The batch number associated with the transaction

route_id
string\d+

Processing route

More than one route ID may be associated with a profile. This can happen when split-routing is in use. The specific ID for the route being operated on must be specified in requests that accept route_id.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "batch": "string",
  • "route_id": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Settle Batch

Submits transactions for funding

To determine which route IDs are in use for the profile, the 'Unsettled Batch Totals' report can be used to determine which routes need to be settled.

This operation can be scheduled to run automatically using the scheduler. It is recommended to use the scheduler to automatically settle all closed and open batches instead of issuing this action manually.

libmonetra KVS equivalent for endpoint

  • action_trans = settle
Authorizations:
basic_authapikey_idapikey
path Parameters
batch
required
string

The batch number associated with the transaction

route_id
required
string

Processing route

More than one route ID may be associated with a profile. This can happen when split-routing is in use. The specific ID for the route being operated on must be specified in requests that accept route_id.

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Unsettle Batch

Marks a batch in TranSafe 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 TranSafe. It is important that this action only be taken with confirmation from the processor that this should happen.

This will not unsettle with the processor. Any batches accepted by the processor will be funded regardless if they are rescinded via this action.

Warning: Rescinding and then settling again will most likely cause double charging of customers. It is imperative to confirm with the processor a batch marked as settled will not be funded unless rescinded and settled.

libmonetra KVS equivalent for endpoint

  • action_admin = batch_rescind
Authorizations:
basic_authapikey_idapikey
path Parameters
batch
required
string

The batch number associated with the transaction

route_id
required
string

Processing route

More than one route ID may be associated with a profile. This can happen when split-routing is in use. The specific ID for the route being operated on must be specified in requests that accept route_id.

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Image

Image operations

Delete Check

Delete a check image

libmonetra KVS equivalent for endpoint

  • action_admin = image_del
  • image_type = check
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X DELETE 'https://test.transafe.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"
}

Delete Signature

Delete a signature image

libmonetra KVS equivalent for endpoint

  • action_admin = image_del
  • image_type = signature
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/image/19538953454/signature' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Store Signature

Stores a signature.

Typically used for receipts

libmonetra KVS equivalent for endpoint

  • action_admin = image_add
  • image_type = signature
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

image
required
string[a-zA-Z0-9+/\n]+={0,2}[\n]*

Base64-encoded image data. Supports TIFF, PNG and PBM formats.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "image": "ABC="
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Images

Gets images for the specified transaction.

See List Images for report output

libmonetra KVS equivalent for endpoint

  • action_admin = image_get
Authorizations:
basic_authapikey_idapikey
path Parameters
ttid
required
string

Transaction identifier

query Parameters
image_format
object
Enum: "TIFF" "PNG" "PBM"
Example: image_format=TIFF

Image format

Values:

  • TIFF - TIFF Image
  • PNG - PNG Image
  • PBM - PBM Image

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/image/4783758439245' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

List Images

Lists stored images

The resulting report will contain these headers:

ttid, ts, status, ptrannum, batch, image_type, image

libmonetra KVS equivalent for endpoint

  • action_admin = image_get
Authorizations:
basic_authapikey_idapikey
query Parameters
batch
string

The batch number associated with the transaction

status
object
Enum: "unsettled" "settled"
Example: status=unsettled

Transaction status

Values:

  • unsettled - Unsettled
  • settled - Settled
bdate
string

Start of date range

edate
string

End of date range

image_format
object
Enum: "TIFF" "PNG" "PBM"
Example: image_format=TIFF

Image format

Values:

  • TIFF - TIFF Image
  • PNG - PNG Image
  • PBM - PBM Image

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/image?bdate=-5%20months&edate=now' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Account Vault

The account vault allows for security storing customer accounts. Both cards and ACH information.

When storing an account it is recommended to tokenize the as part of a transaction instead of manually creating an entry. If no charge is taking place at the time, it is recommended to use the verification transaction to at least verify the card is valid.

Stored accounts can be referenced when processing transactions to charge the card. They can also be attached to a schedule for an installment or recurring payment. Additionally, they can be attached to a customer.

When working with customers in the customer system, a default_token can be associated with the customer for using the customer to process payments. Additionally a stored account can have a customer_id set to associate the account to a customer. A customer can have multiple stored accounts associated with them.

It is recommend that a zip code be added to the stored account to ensure proper interchange rates.

Remove Account

Permanently removes a stored account from the vault

libmonetra KVS equivalent for endpoint

  • action_admin = token_del
Authorizations:
basic_authapikey_idapikey
path Parameters
token
required
string

Referent to the account data that's been stored

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/vault/account/1719266678671633432' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Account Details

Gets details for the specified stored account

libmonetra KVS equivalent for endpoint

  • action_admin = token_list
Authorizations:
basic_authapikey_idapikey
path Parameters
token
required
string

Referent to the account data that's been stored

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/vault/account/1001709895560774683' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "token": "string",
  • "tokengroup_id": "string",
  • "create_profile_id": "string",
  • "create_ts": "string",
  • "update_ts": "string",
  • "type": "NORMAL",
  • "flags": "PROC_TOKEN",
  • "cardtype": "VISA",
  • "abaroute": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "expdate": "0129",
  • "cardholdername": "John Doe",
  • "descr": "string",
  • "clientref": "string",
  • "customer_id": "string",
  • "street": "91st St",
  • "zip": "32606",
  • "descmerch": "string",
  • "descloc": "string"
}

Edit Account

Edits a stored account

libmonetra KVS equivalent for endpoint

  • action_admin = token_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
token
required
string

Referent to the account data that's been stored

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

active
string
Enum: "yes" "no"

Token active status

Values:

  • yes - The token is active
  • no - The token is not active
object (_vault_account__token__account_data)

Account information parameters

There are multiple ways to collect the customer's account information. These are the minimum fields required for each entry method.

  • Chip card
    • icc
  • Swipe
    • trackdata
  • Keyed
    • account
    • expdate
  • Bank account
    • account
    • abaroute
    • accounttype
    • cardholdername
  • Ticket
    • cardshieldticket
  • Token
    • token

Additional modifiers are also present which can provide information about how the data was received. For example, Cards and phones can be tapped in which case the rfid modifier needs to be sent as yes to indicate the data was accepted by this entry method. Keyed can be marked as one of the cardpresent acceptance types to specify the circumstances of the keyed entry.

ENCRYPTION

Many of these can be sent encrypted when using an encrypting reader with a supported encryption method. The e_* fields are used with encrypted account data and either are sent in addition to or in place of the listed fields. Typically, integrators do not directly work with encrypting readers and instead use UniTerm for device integration.

Due to the difference in encrypted reader output and some formats being proprietary limited information about the encrypted account fields are provided. If it is necessary to directly send encrypted reader data to TranSafe please contact support who can work with you and the device manufacturer on how to format the data for the relevant fields to a given device.

street
string

Street address for AVS.

Typically, only numbers need to be passed in this field, as letters and other characters are ignored by the processor

zip
string <= 32 characters

Zip code for AVS verification. All Card Not Present transactions require this to avoid being 'downgraded'

clientref
string\d+

Reference number associated with the customer

matching_token
string
Enum: "yes" "no"

When enabled, the token vault will be searched for tokens matching this account. If found, the token will be updated instead of a new token being added.

Values:

  • yes - Try to match an existing token with this account
  • no - Do not try to match an existing token with this account
customer_id
string[0-9]+

Customer identifier, numeric only

cof_transid
string

Transaction ID from initial transaction

cof_authamount
string

Authorized amount from initial transaction

descr
string <= 128 characters

Description of the account

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "active": "yes",
  • "account_data": {
    },
  • "street": "1st St",
  • "zip": "32606",
  • "clientref": "string",
  • "matching_token": "yes",
  • "customer_id": "string",
  • "cof_transid": "string",
  • "cof_authamount": "string",
  • "descr": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Export Accounts

Export stored account tokens

Stored accounts are exported per group and are only exported encrypted. A PGP public key must be provided in order to encrypt the report data.

Stored account tokens can only be exported by users within the top most group. Users within a sub group cannot export stored accounts.

The resulting PGP encrypted data will contain a report which will contain these headers:

token, create_ts, update_ts, flags, status, cardtype, abaroute, account,
expdate, cardholdername, descr, clientref, customer_id, street, zip, descmerch,
descloc

libmonetra KVS equivalent for endpoint

  • action_su = token_export
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
pgp_pubkey
required
string

PGP public key

group_id
required
string\d+

Group identifier

Responses

Request samples

Content type
application/json
{
  • "pgp_pubkey": "string",
  • "group_id": "string"
}

Response samples

Content type
application/json
{
  • "datablock": "string"
}

Get Stored Account Count

Get count of stored accounts for the user's group

libmonetra KVS equivalent for endpoint

  • action_admin = token_list
  • token_list = count
Authorizations:
basic_authapikey_idapikey

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/vault/account/count' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "count": "string"
}

List Accounts

Lists stored account details

The resulting report will contain these headers:

token, tokengroup_id, create_profile_id, create_ts, update_ts, type, flags,
status, cardtype, abaroute, account, expdate, cardholdername, descr, clientref,
customer_id, au_ts, au_status, street, zip, descmerch, descloc

libmonetra KVS equivalent for endpoint

  • action_admin = token_list
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

active
object
Enum: "yes" "no"
Example: active=yes

Token active status

Values:

  • yes - The token is active
  • no - The token is not active
clientref
string

Reference number associated with the customer

id
string

Customer identifier

expdate_end
string

Maximum expiration date a card can have. Limit all expiration dates to before this time.

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder.

Will be read from account data (EMV, Track 1, etc.) but is not guaranteed to be present. Some presentation methods, such as keyed, do not have any way to capture the name as part of the account data.

Further, Visa explicitly does not allow the cardholder name to be transmitted as part of a contactless read. Typically, a contactless read will result in a cardholder name of "/".

If the name is known by another means, it can be entered in this parameter to override what was read (or not read) from the card.

cardtypes
object
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "BML" "GIFT" "VISADEBIT" "MCDEBIT" "OTHERDEBIT" "EBT" "CHECK" "INTERAC" "CUP" "PAYPALEC" "ACH"
Example: cardtypes=VISA|MC

Cardtypes

Pipe (|) separated.

Cardtype support is dependant on the processor. Not all processor support all cardtypes.

Flag values (pipe separated):

  • VISA - Visa credit
  • MC - Mastercard credit
  • AMEX - American Express credit
  • DISC - Discover credit
  • DINERS - Diners credit
  • JCB - JCB credit. Formerly Japan Credit Bureau
  • BML - Bill me later
  • GIFT - Private label Gift. Not cards backed by a credit card brand such as Visa, Mastercard, etc.
  • VISADEBIT - Visa debit
  • MCDEBIT - Mastercard debit
  • OTHERDEBIT - Debit not Visa or Mastercard
  • EBT - Electronic Benefits Transfer
  • CHECK - Paper checks
  • INTERAC - Interac (Canadian debit)
  • CUP - China Union Pay credit
  • PAYPALEC - PayPal Express Checkout token
  • ACH - Bank transfer
account
string

Last 4 digits of account number

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/vault/account?active=no&cardtypes=VISA%7CMC' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Store Account

Stores an account

Allows for manually tokenizing a payment method and storing it in the token vault. The token can be used for later transaction processing.

Note: Tokenization can happen at time of authorization or verification by using the tokenize=yes parameter as part of the transaction.

libmonetra KVS equivalent for endpoint

  • action_admin = token_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object (_vault_account_account_data)

Account information parameters

There are multiple ways to collect the customer's account information. These are the minimum fields required for each entry method.

  • Chip card
    • icc
  • Swipe
    • trackdata
  • Keyed
    • account
    • expdate
  • Bank account
    • account
    • abaroute
    • accounttype
    • cardholdername
  • Ticket
    • cardshieldticket
  • Token
    • token

Additional modifiers are also present which can provide information about how the data was received. For example, Cards and phones can be tapped in which case the rfid modifier needs to be sent as yes to indicate the data was accepted by this entry method. Keyed can be marked as one of the cardpresent acceptance types to specify the circumstances of the keyed entry.

ENCRYPTION

Many of these can be sent encrypted when using an encrypting reader with a supported encryption method. The e_* fields are used with encrypted account data and either are sent in addition to or in place of the listed fields. Typically, integrators do not directly work with encrypting readers and instead use UniTerm for device integration.

Due to the difference in encrypted reader output and some formats being proprietary limited information about the encrypted account fields are provided. If it is necessary to directly send encrypted reader data to TranSafe please contact support who can work with you and the device manufacturer on how to format the data for the relevant fields to a given device.

carddenylist_id
string\d+

ID in the card deny list

street
string

Street address for AVS.

Typically, only numbers need to be passed in this field, as letters and other characters are ignored by the processor

zip
string <= 32 characters

Zip code for AVS verification. All Card Not Present transactions require this to avoid being 'downgraded'

clientref
string\d+

Reference number associated with the customer

matching_token
string
Enum: "yes" "no"

When enabled, the token vault will be searched for tokens matching this account. If found, the token will be updated instead of a new token being added.

Values:

  • yes - Try to match an existing token with this account
  • no - Do not try to match an existing token with this account
customer_id
string[0-9]+

Customer identifier, numeric only

cof_transid
string

Transaction ID from initial transaction

cof_authamount
string

Authorized amount from initial transaction

descr
string <= 128 characters

Description of the account

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "carddenylist_id": "string",
  • "street": "1st St",
  • "zip": "32606",
  • "clientref": "string",
  • "matching_token": "yes",
  • "customer_id": "string",
  • "cof_transid": "string",
  • "cof_authamount": "string",
  • "descr": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "token": "string"
}

Scheduled Payments

Scheduled payments allow using a stored account to be charged on a configured period. Both recurring and installment payments are supported.

Scheduled payments are a schedule and instructions on how much, how often, and what to charge. They are linked to a stored account stored in TranSafe. The stored account a schedule is using for the charge can be changed to a different account. This allows updating schedules without disrupting them.

List Installment Payments

Lists installment payment details

The resulting report will contain these headers:

id, token, create_ts, update_ts, type, flags, status, cardtype, account,
cardholdername, bdate, edate, frequency, installment_total, amount, last_run,
last_run_success, last_run_ttid, next_run, installment_num, total_paid, notes

Additional columns may be present if profile custom fields are in use.

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = list
  • type = installment
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

clientref
string

Reference number associated with the customer

customer_id
string

Customer identifier, numeric only

expdate_end
string

Maximum expiration date a card can have. Limit all expiration dates to before this time.

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder.

Will be read from account data (EMV, Track 1, etc.) but is not guaranteed to be present. Some presentation methods, such as keyed, do not have any way to capture the name as part of the account data.

Further, Visa explicitly does not allow the cardholder name to be transmitted as part of a contactless read. Typically, a contactless read will result in a cardholder name of "/".

If the name is known by another means, it can be entered in this parameter to override what was read (or not read) from the card.

cardtypes
object
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "BML" "GIFT" "VISADEBIT" "MCDEBIT" "OTHERDEBIT" "EBT" "CHECK" "INTERAC" "CUP" "PAYPALEC" "ACH"
Example: cardtypes=VISA|MC

Cardtypes

Pipe (|) separated.

Cardtype support is dependant on the processor. Not all processor support all cardtypes.

Flag values (pipe separated):

  • VISA - Visa credit
  • MC - Mastercard credit
  • AMEX - American Express credit
  • DISC - Discover credit
  • DINERS - Diners credit
  • JCB - JCB credit. Formerly Japan Credit Bureau
  • BML - Bill me later
  • GIFT - Private label Gift. Not cards backed by a credit card brand such as Visa, Mastercard, etc.
  • VISADEBIT - Visa debit
  • MCDEBIT - Mastercard debit
  • OTHERDEBIT - Debit not Visa or Mastercard
  • EBT - Electronic Benefits Transfer
  • CHECK - Paper checks
  • INTERAC - Interac (Canadian debit)
  • CUP - China Union Pay credit
  • PAYPALEC - PayPal Express Checkout token
  • ACH - Bank transfer
account
string

Last 4 digits of account number

status
object
Enum: "ACTIVE" "DISABLED" "ERROR" "DONE" "PENDING"
Example: status=ACTIVE

Status of scheduled payment

Values:

  • ACTIVE - Payment will process at the next scheduled time
  • DISABLED - Payment will not process at the next scheduled time. Payment can be re-activated to continue processing. If the RECURRING_SKIPMISSED flag is not set a catchup for all missed payments will take place.
  • ERROR - Payment will not process at the next scheduled time. Payment has failed in a way that corrective action must be taken. For example, account closed.
  • DONE - Payment will not process at the next scheduled time. Payment sequence has been completed based on configured schedule.
  • PENDING - Payment is enabled but has not processed any payments

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/vault/payment/installment?active=yes' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Installment Payment

Adds an installment payment

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = add
  • type = installment
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

customer_id
string[0-9]+

Customer identifier, numeric only

token
required
string\d+

Reference to the stored account that's being charged for the scheduled payment

clientref
string\d+

Reference number associated with the customer

cof_transid
string

Transaction ID from initial transaction

cof_authamount
string

Authorized amount from initial transaction

descr
string <= 128 characters

Description of the payment

bdate
string

Start of date range

installment_total
required
string\d+

Total number of installment payments to make

frequency
required
string
Enum: "daily" "weekly" "biweekly" "monthly" "bimonthly" "quarterly" "semiannually" "annually"

Frequency of payment

Values:

  • daily - Takes place every day
  • weekly - Takes place every week on the given day of week. Ex. Every Wednesday
  • biweekly - Takes place every two weeks on the given day. Ex. Every other Friday
  • monthly - Takes place every month on the given day of the month. If the day is after the last day of the month (e.g. 31st when the month only has 30 days), the last day of the month will be used for that month
  • bimonthly - Takes place every two months on the given day of the month
  • quarterly - Takes place every three months on the given day of the month
  • semiannually - Takes place every six months
  • annually - Takes place once a year
amount
required
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "customer_id": "string",
  • "token": "string",
  • "clientref": "string",
  • "cof_transid": "string",
  • "cof_authamount": "string",
  • "descr": "string",
  • "bdate": "string",
  • "installment_total": "string",
  • "frequency": "daily",
  • "amount": "19.92",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

List Recurring Payments

Lists recurring payment details

The resulting report will contain these headers:

id, token, create_ts, update_ts, type, flags, status, cardtype, account,
cardholdername, bdate, edate, frequency, installment_total, amount, last_run,
last_run_success, last_run_ttid, next_run, installment_num, total_paid, notes

Additional columns may be present if profile custom fields are in use.

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = list
  • type = recurring
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

clientref
string

Reference number associated with the customer

customer_id
string

Customer identifier, numeric only

expdate_end
string

Maximum expiration date a card can have. Limit all expiration dates to before this time.

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder.

Will be read from account data (EMV, Track 1, etc.) but is not guaranteed to be present. Some presentation methods, such as keyed, do not have any way to capture the name as part of the account data.

Further, Visa explicitly does not allow the cardholder name to be transmitted as part of a contactless read. Typically, a contactless read will result in a cardholder name of "/".

If the name is known by another means, it can be entered in this parameter to override what was read (or not read) from the card.

cardtypes
object
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "BML" "GIFT" "VISADEBIT" "MCDEBIT" "OTHERDEBIT" "EBT" "CHECK" "INTERAC" "CUP" "PAYPALEC" "ACH"
Example: cardtypes=VISA|MC

Cardtypes

Pipe (|) separated.

Cardtype support is dependant on the processor. Not all processor support all cardtypes.

Flag values (pipe separated):

  • VISA - Visa credit
  • MC - Mastercard credit
  • AMEX - American Express credit
  • DISC - Discover credit
  • DINERS - Diners credit
  • JCB - JCB credit. Formerly Japan Credit Bureau
  • BML - Bill me later
  • GIFT - Private label Gift. Not cards backed by a credit card brand such as Visa, Mastercard, etc.
  • VISADEBIT - Visa debit
  • MCDEBIT - Mastercard debit
  • OTHERDEBIT - Debit not Visa or Mastercard
  • EBT - Electronic Benefits Transfer
  • CHECK - Paper checks
  • INTERAC - Interac (Canadian debit)
  • CUP - China Union Pay credit
  • PAYPALEC - PayPal Express Checkout token
  • ACH - Bank transfer
account
string

Last 4 digits of account number

status
object
Enum: "ACTIVE" "DISABLED" "ERROR" "DONE" "PENDING"
Example: status=ACTIVE

Status of scheduled payment

Values:

  • ACTIVE - Payment will process at the next scheduled time
  • DISABLED - Payment will not process at the next scheduled time. Payment can be re-activated to continue processing. If the RECURRING_SKIPMISSED flag is not set a catchup for all missed payments will take place.
  • ERROR - Payment will not process at the next scheduled time. Payment has failed in a way that corrective action must be taken. For example, account closed.
  • DONE - Payment will not process at the next scheduled time. Payment sequence has been completed based on configured schedule.
  • PENDING - Payment is enabled but has not processed any payments

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/vault/payment/recurring?clientref=55' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Recurring Payment

Adds a recurring payment

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = add
  • type = recurring
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

token
required
string\d+

Reference to the stored account that's being charged for the scheduled payment

clientref
string\d+

Reference number associated with the customer

cof_transid
string

Transaction ID from initial transaction

cof_authamount
string

Authorized amount from initial transaction

descr
string <= 128 characters

Description of of the payment

bdate
string

Start of date range

edate
string

End of date range

frequency
required
string
Enum: "daily" "weekly" "biweekly" "monthly" "bimonthly" "quarterly" "semiannually" "annually"

Frequency of payment

Values:

  • daily - Takes place every day
  • weekly - Takes place every week on the given day of week. Ex. Every Wednesday
  • biweekly - Takes place every two weeks on the given day. Ex. Every other Friday
  • monthly - Takes place every month on the given day of the month. If the day is after the last day of the month (e.g. 31st when the month only has 30 days), the last day of the month will be used for that month
  • bimonthly - Takes place every two months on the given day of the month
  • quarterly - Takes place every three months on the given day of the month
  • semiannually - Takes place every six months
  • annually - Takes place once a year
amount
required
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "token": "string",
  • "clientref": "string",
  • "cof_transid": "string",
  • "cof_authamount": "string",
  • "descr": "string",
  • "bdate": "string",
  • "edate": "string",
  • "frequency": "daily",
  • "amount": "19.92",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Get Installment Payment Details

Gets details for the specified installment payment

Additional columns may be present if profile custom fields are in use.

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = list
  • type = installment
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Schedule ID

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/vault/payment/installment/1719266657160421715' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "token": "string",
  • "create_ts": "string",
  • "update_ts": "string",
  • "type": "NORMAL",
  • "flags": "PROC_TOKEN",
  • "status": "ACTIVE",
  • "cardtype": "VISA",
  • "account": "XXXXXXXXXXXX1234",
  • "cardholdername": "John Doe",
  • "bdate": "string",
  • "edate": "string",
  • "installment_total": "string",
  • "amount": "19.92",
  • "last_run": "string",
  • "last_run_success": "string",
  • "last_run_ttid": "string",
  • "next_run": "string",
  • "installment_num": "string",
  • "total_paid": "string",
  • "notes": "string",
  • "property1": "string",
  • "property2": "string"
}

Edit Installment Payment

Edits a stored installment payment

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = edit
  • type = installment
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Schedule ID

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

active
string
Enum: "yes" "no"

Token active status

Values:

  • yes - The token is active
  • no - The token is not active
customer_id
string[0-9]+

Customer identifier, numeric only

token
string\d+

Referent to the account data that's been stored

clientref
string\d+

Reference number associated with the customer

cof_transid
string

Transaction ID from initial transaction

cof_authamount
string

Authorized amount from initial transaction

descr
string <= 128 characters

Description of the payment

bdate
string

Start of date range

installment_total
string\d+

Total number of installment payments to make

frequency
string
Enum: "daily" "weekly" "biweekly" "monthly" "bimonthly" "quarterly" "semiannually" "annually"

Frequency of payment

Values:

  • daily - Takes place every day
  • weekly - Takes place every week on the given day of week. Ex. Every Wednesday
  • biweekly - Takes place every two weeks on the given day. Ex. Every other Friday
  • monthly - Takes place every month on the given day of the month. If the day is after the last day of the month (e.g. 31st when the month only has 30 days), the last day of the month will be used for that month
  • bimonthly - Takes place every two months on the given day of the month
  • quarterly - Takes place every three months on the given day of the month
  • semiannually - Takes place every six months
  • annually - Takes place once a year
amount
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "active": "yes",
  • "customer_id": "string",
  • "token": "string",
  • "clientref": "string",
  • "cof_transid": "string",
  • "cof_authamount": "string",
  • "descr": "string",
  • "bdate": "string",
  • "installment_total": "string",
  • "frequency": "daily",
  • "amount": "19.92",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Recurring Payment Detail

Gets details for the specified recurring payment

Additional columns may be present if profile custom fields are in use.

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = list
  • type = recurring
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Schedule ID

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/vault/payment/recurring/' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "token": "string",
  • "create_ts": "string",
  • "update_ts": "string",
  • "type": "NORMAL",
  • "flags": "PROC_TOKEN",
  • "status": "ACTIVE",
  • "cardtype": "VISA",
  • "account": "XXXXXXXXXXXX1234",
  • "cardholdername": "John Doe",
  • "bdate": "string",
  • "edate": "string",
  • "frequency": "daily",
  • "amount": "19.92",
  • "last_run": "string",
  • "last_run_success": "string",
  • "last_run_ttid": "string",
  • "next_run": "string",
  • "total_paid": "string",
  • "notes": "string",
  • "property1": "string",
  • "property2": "string"
}

Edit Recurring Payment

Edits a stored recurring payment

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = edit
  • type = recurring
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Schedule ID

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

active
string
Enum: "yes" "no"

Token active status

Values:

  • yes - The token is active
  • no - The token is not active
token
string\d+

Reference to the stored account that's being charged for the scheduled payment

clientref
string\d+

Reference number associated with the customer

cof_transid
string

Transaction ID from initial transaction

cof_authamount
string

Authorized amount from initial transaction

descr
string <= 128 characters

Description of of the payment

bdate
string

Start of date range

edate
string

End of date range

frequency
string
Enum: "daily" "weekly" "biweekly" "monthly" "bimonthly" "quarterly" "semiannually" "annually"

Frequency of payment

Values:

  • daily - Takes place every day
  • weekly - Takes place every week on the given day of week. Ex. Every Wednesday
  • biweekly - Takes place every two weeks on the given day. Ex. Every other Friday
  • monthly - Takes place every month on the given day of the month. If the day is after the last day of the month (e.g. 31st when the month only has 30 days), the last day of the month will be used for that month
  • bimonthly - Takes place every two months on the given day of the month
  • quarterly - Takes place every three months on the given day of the month
  • semiannually - Takes place every six months
  • annually - Takes place once a year
amount
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "active": "yes",
  • "token": "string",
  • "clientref": "string",
  • "cof_transid": "string",
  • "cof_authamount": "string",
  • "descr": "string",
  • "bdate": "string",
  • "edate": "string",
  • "frequency": "daily",
  • "amount": "19.92",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

List Payment History

Lists transactions that have been run by the recurring billing system

This includes both recurring and installment payments but does not include transactions run using stored accounts.

The resulting report will contain these headers:

user, ttid, msoft_code, phard_code, type, proc, entrymode, txnstatus,
tranflags, capture, reversible, card, pclevel, cardlevel, abaroute, account,
expdate, checknum, timestamp, last_modified_ts, accounttype, reasoncode,
amount, reqamount, orig_authamount, authamount, examount, tax, cashback,
authnum, stan, batch, item, code, verbiage, cardholdername, avs, cv, clerkid,
stationid, comments, divisionnum, promoid, descmerch, descloc, ptrannum,
ordernum, custref, discountamount, freightamount, dutyamount, shipzip,
shipcountry, l3num, bdate, edate, roomnum, excharges, rate, customer_id, token,
order_id, surchargeamount, accounting_id

libmonetra KVS equivalent for endpoint

  • action_admin = report_tran
  • token = yes
  • txnstatus = CAPTURED|UNCAPTURED|COMPLETE|DECLINED
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

bdate
string

Start of date range

edate
string

End of date range

token
string

Referent to the account data that's been stored

customer_id
string

Customer identifier, numeric only

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/vault/payment/history?bdate=-1%20year&edate=now' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Remove Stored Payment

Permanently removes a stored payment from the vault

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Schedule ID

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/vault/payment/1719266657160421715' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Card Deny List

The card deny list is an internal, merchant maintained, list of cards or ACH accounts the merchant is choosing not to accept.

Accounts can be added to the list two different ways:

  • Manually
  • Atomically when a transaction is online declined.
    • This will happen if the CARDDENYLIST_DECLINE profile flag is set
    • A transaction includes the carddenylist_decline flag set to yes

Accounts can be checked if they are on the card deny list two different ways:

  • Manually
  • Automatically when a transaction is attempted
    • This will happen if the CARDDENYLIST_CHECK profile flag is set
    • A transaction includes the carddenylist_check flag set to yes

List Deny List

Lists accounts on the card deny list

The resulting report will contain these headers:

id, last4, expdate, cardtype, added, last_seen,
expire, cardholdername, reason_code

libmonetra KVS equivalent for endpoint

  • action_admin = carddenylist
  • carddenylist = list
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

expdate_bdate
string

Used to filter report by card expiration date range. Expiration is when the card expires, the expdate parameter sent with account. This is the beginning date of the expiration date range to match.

expdate_edate
string

Used to filter report by card expiration date range. Expiration is when the card expires, the expdate parameter sent with account. This is the ending date of the expiration date range to match.

added_bdate
string

Used to filter report by added date range. This is the beginning date of the added date rate to match.

added_edate
string

Used to filter report by added date range. This is the ending date of the added date range to match.

last_seen_bdate
string

Used to filter report by last seen date range. This is the beginning date of the last seen date range to match.

last_seen_edate
string

Used to filter report by last seen date range. This is the ending date of the last seen date range to match.

expire_bdate
string

Used to filter report by expire date range

Expiration is when the entry in the list will be removed.

Coresponds expire parameter sent with an add operation. This is the beginning of the expire range to match."

expire_edate
string

Used to filter report by expire date range

Expiration is when the entry in the list should be removed.

Coresponds expire parameter sent with an add operation. This is the endinf of the expire range to match."

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/cardlist/deny' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add a card to the deny list

Add a card to the deny list

libmonetra KVS equivalent for endpoint

  • action_admin = carddenylist
  • carddenylist = add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object (_vault_account_account_data)

Account information parameters

There are multiple ways to collect the customer's account information. These are the minimum fields required for each entry method.

  • Chip card
    • icc
  • Swipe
    • trackdata
  • Keyed
    • account
    • expdate
  • Bank account
    • account
    • abaroute
    • accounttype
    • cardholdername
  • Ticket
    • cardshieldticket
  • Token
    • token

Additional modifiers are also present which can provide information about how the data was received. For example, Cards and phones can be tapped in which case the rfid modifier needs to be sent as yes to indicate the data was accepted by this entry method. Keyed can be marked as one of the cardpresent acceptance types to specify the circumstances of the keyed entry.

ENCRYPTION

Many of these can be sent encrypted when using an encrypting reader with a supported encryption method. The e_* fields are used with encrypted account data and either are sent in addition to or in place of the listed fields. Typically, integrators do not directly work with encrypting readers and instead use UniTerm for device integration.

Due to the difference in encrypted reader output and some formats being proprietary limited information about the encrypted account fields are provided. If it is necessary to directly send encrypted reader data to TranSafe please contact support who can work with you and the device manufacturer on how to format the data for the relevant fields to a given device.

reason_code
string
Default: "DECLINE"
Enum: "DECLINE" "TESTCARD" "CHARGEBACK"

Reason an account was added to the deny list

Values:

  • DECLINE - Due to decline
  • TESTCARD - Identified as a test card
  • CHARGEBACK - Due to receiving a chargeback
expire
string

How long to keep a card on file before being automatically removed

Standard date format accepted by the payment server. Can be a specific date to expire on or a relative data (E.g "+10 days").

Default is 180 days if not specified. Smallest amount of time allowed is 1 day. Anything shorter will be rounded up to 1 day.

The deny list is automatically cleaned up on a regular basis. Anything added to the list will have an expiration associated with it for how long it should be on the list. This expiration is different than the card's expiration date associated with the account number. This is how long the entry will remain in the list. It can be set to a very long time such as 50+ years.

Card expiration date is not used for removal for several reasons.

  1. Test cards do not have a "real" expiration date and should not necessarily be removed when the account expdate is reached.
  2. When cards are close to expiring the issuer will send new cards with an updated expdate but the same account number. A merchant may still want to deny these cards and a separate removal expiration is intended to handle this situation.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    },
  • "reason_code": "DECLINE",
  • "expire": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "carddenylist_id": "string"
}

Check if card is on deny list

Check if account is on the card deny list

Will return details about the card if it is on the list.

No fields returned indicates it is not on the list. Use the presence of the id response key to determine if a record was found.

libmonetra KVS equivalent for endpoint

  • action_admin = carddenylist
  • carddenylist = list
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object (_vault_account_account_data)

Account information parameters

There are multiple ways to collect the customer's account information. These are the minimum fields required for each entry method.

  • Chip card
    • icc
  • Swipe
    • trackdata
  • Keyed
    • account
    • expdate
  • Bank account
    • account
    • abaroute
    • accounttype
    • cardholdername
  • Ticket
    • cardshieldticket
  • Token
    • token

Additional modifiers are also present which can provide information about how the data was received. For example, Cards and phones can be tapped in which case the rfid modifier needs to be sent as yes to indicate the data was accepted by this entry method. Keyed can be marked as one of the cardpresent acceptance types to specify the circumstances of the keyed entry.

ENCRYPTION

Many of these can be sent encrypted when using an encrypting reader with a supported encryption method. The e_* fields are used with encrypted account data and either are sent in addition to or in place of the listed fields. Typically, integrators do not directly work with encrypting readers and instead use UniTerm for device integration.

Due to the difference in encrypted reader output and some formats being proprietary limited information about the encrypted account fields are provided. If it is necessary to directly send encrypted reader data to TranSafe please contact support who can work with you and the device manufacturer on how to format the data for the relevant fields to a given device.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "account_data": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "last4": "string",
  • "expdate": "0129",
  • "cardtype": "VISA",
  • "added": "string",
  • "last_seen": "string",
  • "expire": "string",
  • "cardholdername": "John Doe",
  • "reason_code": "DECLINE"
}

Remove a card from the deny list

Remove a card from the deny list

libmonetra KVS equivalent for endpoint

  • action_admin = carddenylist
  • carddenylist = remove
Authorizations:
basic_authapikey_idapikey
path Parameters
carddenylist_id
required
string

ID in the card deny list

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/cardlist/deny/134543245543' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Card Details

Account detail for a card on the card deny list

libmonetra KVS equivalent for endpoint

  • action_admin = carddenylist
  • carddenylist = list
Authorizations:
basic_authapikey_idapikey
path Parameters
carddenylist_id
required
string

ID in the card deny list

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/cardlist/deny/143432' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "last4": "string",
  • "expdate": "0129",
  • "cardtype": "VISA",
  • "added": "string",
  • "last_seen": "string",
  • "expire": "string",
  • "cardholdername": "John Doe",
  • "reason_code": "DECLINE"
}

Customer

The Customer database is a limited Client Management System (CMS) with a focus on payments. It is not a full replacement for a dedicated CMS but is intended for smaller merchants that only need payment handling functionality of a CMS.

This system allows creating customer, managing metadata about the customer. For example, addresses, stored cards, and scheduled payments. Customer can optionally be utilized by TranSafe's order system. This is to aid in creating and notification of invoices.

Larger business with an existing CMS are expected to use the TranSafe customer database for helping manage customer payments. The external CMS would include the ID for the customer created in TranSafe's system. The external CMS then be able to use the TranSafe system to manage payment information and initiate transactions.

List Customers

Lists customers

The billing and shipping address information provided by the report are the customer's default addresses. They may not be present if no addresses were set as defaults.

The resulting report will contain these headers:

id, tokengroup_id, create_profile_id, ts_created, ts_modified, flags,
display_name, name_company, name_prefix, name_first, name_middle, name_last,
name_suffix, phone_work, phone_home, phone_mobile, phone_fax, email, website,
business_id, accounting_id, notes, default_billing_id, default_shipping_id,
default_token, billing_display_name, billing_address1, billing_address2,
billing_city, billing_state, billing_country, billing_postal_code,
billing_delivery_notes, shipping_display_name, shipping_address1,
shipping_address2, shipping_city, shipping_state, shipping_country,
shipping_postal_code, shipping_delivery_notes

Additional columns may be present if profile custom fields are in use.

libmonetra KVS equivalent for endpoint

  • action_admin = customer_list
  • customer_list = customer
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/customer' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Customer

Adds a customer to the customer database for the merchant or token group

libmonetra KVS equivalent for endpoint

  • action_admin = customer_add
  • customer_add = customer
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

display_name
required
string <= 128 characters

Display name

name_company
string <= 128 characters

Company name

name_prefix
string <= 32 characters

Name prefix, Mr. Mrs. Ms. Dr...

Free-form field

name_first
string <= 32 characters

First name

name_middle
string <= 32 characters

Middle name

name_last
string <= 32 characters

Last name

name_suffix
string <= 32 characters

Name suffix, Jr. Sr. III...

Free-form field

phone_work
string <= 32 characters [-+0-9() .]*

Work phone

phone_home
string <= 32 characters [-+0-9() .]*

Home phone

phone_mobile
string <= 32 characters [-+0-9() .]*

Mobile phone

phone_fax
string <= 32 characters [-+0-9() .]*

Fax number

email
string <= 128 characters

email

website
string <= 128 characters

Website

business_id
string <= 32 characters

Business ID - FEIN

accounting_id
string <= 128 characters

ID used in external accounting system for customer

notes
string <= 1024 characters

General free-form information

flags
string
Enum: "TAXEXEMPT" "EMAIL_RECEIPT_RECURRING"

flags controlling behavior

Values:

  • TAXEXEMPT - Customer is non-taxable
  • EMAIL_RECEIPT_RECURRING - Send receipt email for recurring transactions. The following conditions must be met for customers to receive recurring receipt emails. + This flag must be enabled. + Customer must have an email on file. + The merchant profile must have a name configured. + The merchant profile must have a public reply email configured.
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "display_name": "string",
  • "name_company": "string",
  • "name_prefix": "string",
  • "name_first": "string",
  • "name_middle": "string",
  • "name_last": "string",
  • "name_suffix": "string",
  • "phone_work": "string",
  • "phone_home": "string",
  • "phone_mobile": "string",
  • "phone_fax": "string",
  • "email": "string",
  • "website": "string",
  • "business_id": "string",
  • "accounting_id": "string",
  • "notes": "string",
  • "flags": "TAXEXEMPT",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Delete Customer

Deletes a customer

WARNING: This will purge tokens associated with the customer! If tokens need to be retained, remove them from the customer before deleting.

libmonetra KVS equivalent for endpoint

  • action_admin = customer_del
  • customer_del = customer
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Customer identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/customer/19266575665036873' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Customer Details

Details for a specific customer

libmonetra KVS equivalent for endpoint

  • action_admin = customer_list
  • customer_list = customer
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Customer identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/customer/19266575665036873' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "tokengroup_id": "string",
  • "create_profile_id": "string",
  • "ts_created": "string",
  • "ts_modified": "string",
  • "flags": "TAXEXEMPT",
  • "display_name": "string",
  • "name_company": "string",
  • "name_prefix": "string",
  • "name_first": "string",
  • "name_middle": "string",
  • "name_last": "string",
  • "name_suffix": "string",
  • "phone_work": "string",
  • "phone_home": "string",
  • "phone_mobile": "string",
  • "phone_fax": "string",
  • "email": "string",
  • "website": "string",
  • "business_id": "string",
  • "accounting_id": "string",
  • "notes": "string",
  • "default_billing_id": "string",
  • "default_shipping_id": "string",
  • "default_token": "string",
  • "billing_display_name": "string",
  • "billing_address1": "string",
  • "billing_address2": "string",
  • "billing_city": "string",
  • "billing_state": "string",
  • "billing_country": "string",
  • "billing_postal_code": "string",
  • "billing_delivery_notes": "string",
  • "shipping_display_name": "string",
  • "shipping_address1": "string",
  • "shipping_address2": "string",
  • "shipping_city": "string",
  • "shipping_state": "string",
  • "shipping_country": "string",
  • "shipping_postal_code": "string",
  • "shipping_delivery_notes": "string",
  • "property1": "string",
  • "property2": "string"
}

Edit Customer

Edits an existing customer

libmonetra KVS equivalent for endpoint

  • action_admin = customer_edit
  • customer_edit = customer
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Customer identifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

display_name
string <= 128 characters

Display name

name_company
string <= 128 characters

Company name

name_prefix
string <= 32 characters

Name prefix, Mr. Mrs. Ms. Dr...

Free-form field

name_first
string <= 32 characters

First name

name_middle
string <= 32 characters

Middle name

name_last
string <= 32 characters

Last name

name_suffix
string <= 32 characters

Name suffix, Jr. Sr. III...

Free-form field

phone_work
string <= 32 characters [-+0-9() .]*

Work phone

phone_home
string <= 32 characters [-+0-9() .]*

Home phone

phone_mobile
string <= 32 characters [-+0-9() .]*

Mobile phone

phone_fax
string <= 32 characters [-+0-9() .]*

Fax number

email
string <= 128 characters

email

website
string <= 128 characters

Website

business_id
string <= 32 characters

Business ID - FEIN

accounting_id
string <= 128 characters

ID used in external accounting system for customer

notes
string <= 1024 characters

General free-form information

flags
string
Enum: "TAXEXEMPT" "EMAIL_RECEIPT_RECURRING"

flags controlling behavior

Values:

  • TAXEXEMPT - Customer is non-taxable
  • EMAIL_RECEIPT_RECURRING - Send receipt email for recurring transactions. The following conditions must be met for customers to receive recurring receipt emails. + This flag must be enabled. + Customer must have an email on file. + The merchant profile must have a name configured. + The merchant profile must have a public reply email configured.
default_token
string[0-9]*

Default token/payment to use

default_billing_id
string[0-9]+

Default ID of billing address in use from customer_addresses

0 means no default

default_shipping_id
string[0-9]+

Default ID of shipping address in use from customer_addresses

0 means no default

property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "display_name": "string",
  • "name_company": "string",
  • "name_prefix": "string",
  • "name_first": "string",
  • "name_middle": "string",
  • "name_last": "string",
  • "name_suffix": "string",
  • "phone_work": "string",
  • "phone_home": "string",
  • "phone_mobile": "string",
  • "phone_fax": "string",
  • "email": "string",
  • "website": "string",
  • "business_id": "string",
  • "accounting_id": "string",
  • "notes": "string",
  • "flags": "TAXEXEMPT",
  • "default_token": "string",
  • "default_billing_id": "string",
  • "default_shipping_id": "string",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

List Customer's Tokens

Lists all stored accounts associated with this customer

The resulting report will contain these headers:

token, tokengroup_id, create_profile_id, create_ts, update_ts, type, flags,
cardtype, abaroute, account, expdate, cardholdername, descr, clientref,
customer_id, street, zip, descmerch, descloc

libmonetra KVS equivalent for endpoint

  • action_admin = token_list
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Customer identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/customer/19266575665036873/tokens' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Customer Address

Customer address operations

List Customer Addresses

Lists a customer's addresses

The resulting report will contain these headers:

id, customer_id, display_name, address1, address2, city, state, country,
postal_code, delivery_notes

Additional fields may be present if profile custom fields are in use.

libmonetra KVS equivalent for endpoint

  • action_admin = customer_list
  • customer_list = customer_address
Authorizations:
basic_authapikey_idapikey
path Parameters
customer_id
required
string

Customer identifier, numeric only

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/customer/19266575665036873/address' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Customer Address

Adds an address to a customer

libmonetra KVS equivalent for endpoint

  • action_admin = customer_add
  • customer_add = customer_address
Authorizations:
basic_authapikey_idapikey
path Parameters
customer_id
required
string

Customer identifier, numeric only

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

display_name
string <= 128 characters

Display name

address1
required
string <= 128 characters

Address line 1

address2
string <= 128 characters

Address line 2

city
string <= 128 characters

City

state
string <= 128 characters

State

country
string <= 3 characters [a-zA-Z]{0,3}

Country

ISO 3166-1 alpha-3 country code

postal_code
string

Postal code

delivery_notes
string <= 1024 characters

Delivery notes

default_billing
string
Default: "no"
Enum: "yes" "no"

Specifies whether or not this is the default billing address

Values:

  • yes - Set this address as the customer's default billing address
  • no - This is not the default billing address
default_shipping
string
Default: "no"
Enum: "yes" "no"

Specifies whether or not this is the default shipping address

Values:

  • yes - Set this address as the customer's default shipping address
  • no - This is not the default shipping address
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "display_name": "string",
  • "address1": "string",
  • "address2": "string",
  • "city": "string",
  • "state": "string",
  • "country": "str",
  • "postal_code": "string",
  • "delivery_notes": "string",
  • "default_billing": "yes",
  • "default_shipping": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Delete Customer Address

Deletes a customer's address

libmonetra KVS equivalent for endpoint

  • action_admin = customer_del
  • customer_del = customer_address
Authorizations:
basic_authapikey_idapikey
path Parameters
customer_id
required
string

Customer identifier, numeric only

id
required
string

Customer address identifier

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/customer/19266575665036873/address/19266578682904270' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Customer Address Details

Details for a specific customer address

Additional fields may be present if profile custom fields are in use.

libmonetra KVS equivalent for endpoint

  • action_admin = customer_list
  • customer_list = customer_address
Authorizations:
basic_authapikey_idapikey
path Parameters
customer_id
required
string

Customer identifier, numeric only

id
required
string

Customer address identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/customer/19266575665036873/address/19266578682904270' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "customer_id": "string",
  • "display_name": "string",
  • "address1": "string",
  • "address2": "string",
  • "city": "string",
  • "state": "string",
  • "country": "string",
  • "postal_code": "string",
  • "delivery_notes": "string",
  • "property1": "string",
  • "property2": "string"
}

Edit Customer Address

Edits an existing customer's address

libmonetra KVS equivalent for endpoint

  • action_admin = customer_edit
  • customer_edit = customer_address
Authorizations:
basic_authapikey_idapikey
path Parameters
customer_id
required
string

Customer identifier, numeric only

id
required
string

Customer address identifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

display_name
string <= 128 characters

Display name

address1
string <= 128 characters

Address line 1

address2
string <= 128 characters

Address line 2

city
string <= 128 characters

City

state
string <= 128 characters

State

country
string <= 3 characters [a-zA-Z]{0,3}

Country

ISO 3166-1 alpha-3 country code

postal_code
string

Postal code

delivery_notes
string <= 1024 characters

Delivery notes

default_billing
string
Default: "no"
Enum: "yes" "no"

Specifies whether or not this is the default billing address

Values:

  • yes - Set this address as the customer's default billing address
  • no - This is not the default billing address
default_shipping
string
Default: "no"
Enum: "yes" "no"

Specifies whether or not this is the default shipping address

Values:

  • yes - Set this address as the customer's default shipping address
  • no - This is not the default shipping address
property name*
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "display_name": "string",
  • "address1": "string",
  • "address2": "string",
  • "city": "string",
  • "state": "string",
  • "country": "str",
  • "postal_code": "string",
  • "delivery_notes": "string",
  • "default_billing": "yes",
  • "default_shipping": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Inventory Bulk

Inventory bulk operations

Bulk Inventory Operation

Allows for grouping multiple inventory operations into a single operation

The bulk operation is "atomic" and if any steps fail everything will fail.

Bulk operations take any of the actions for the category as KVS pairs.

Actions to be performed are structured as a JSON-array of objects, with the key/value pairs matching the field definitions, plus a prodmanage key with value set to the appropriate action being taken. Reference the libMonetra KVS for the appropriate values. This JSON object is passed in to the bulk key on the request.

Back references can be used for ids and timestamps in the format of: :id[{idx}] or :timestamp_ms[{idx}] Where the {idx} is the array index of the response for a member being referenced.

The result of a bulk operation will also return a bulk key in the response with JSON output containing: result, id, timestamp_ms, error if appropriate.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = bulk
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

bulk
required
string

Bulk data encoded as JSON

If the bulk JSON data is being sent in a protocol which itself is JSON data (ReST submitting JSON) the data within this key must be escaped as a string.

This also applies to JSON response data. If the protocol is JSON the data will be escaped as a string and will need to be decoded.

E.g. when using a JSON protocol for transport

JSON Data
[ { "action": "sub_action_1", "key1": "val1", "key2": "val2" }, { "action": "sub_action_2", "key1": "val1", "key2": "val2" }, { "action": "sub_action_3", "key1": "val1", "key2": "val2" } ]

Encoded for JSON transport protocol
{
    "key": "val",
    "bulk": "[{\"action\":\"sub_action_1\",\"key1\":\"val1\",\"key2\":\"val2\"},{\"action\":\"sub_action_2\",\"key1\":\"val1\",\"key2\":\"val2\"},{\"action\":\"sub_action_3\",\"key1\":\"val1\",\"key2\":\"val2\"}]"
}

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "bulk": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "bulk": "string"
}

Inventory Categories

All inventory discounts and products are grouped into categories. Before anything can be added to the system categories must be created to hold them.

Categories allow for logical grouping of similar types of items and make it easier to find items. Specifically in a POS setting where the items will be displayed for a clerk to select.

Example categories for a restaurant

  • Drinks
  • Sandwiches
  • Deserts
  • Discounts

List Categories

List inventory categories

The resulting report will contain these headers:

id, name, timestamp_ms, description, sortorder, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = category
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string

Name of the category

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/category' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Category

Add an inventory category

Products, and discounts are added to categories. The category allows for grouping similar products and discounts that apply specifically to those products.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = category_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
required
string <= 32 characters

Name of the category

description
string <= 128 characters

Description of the category

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "name": "string",
  • "description": "string",
  • "sortorder": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string",
  • "timestamp_ms": "string"
}

Delete Category

Delete an inventory category

The category must be empty.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = category_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the category

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/inventory/category/20120539065950458?timestamp_ms=1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get Category Detail

Gets details for the specified category

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = category
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the category

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/category/1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "timestamp_ms": "string",
  • "description": "string",
  • "sortorder": "string",
  • "is_deleted": "yes"
}

Edit Category

Edit an inventory category

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = category_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the category

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the category

description
string <= 128 characters

Description of the category

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "name": "string",
  • "description": "string",
  • "sortorder": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "timestamp_ms": "string"
}

Inventory Discounts

Multiple types of discounts are supported and can be applied in different ways.

Specifically discounts can be:

  • Fixed
  • Percentage

They can apply to:

  • Items
  • The entire order
  • Both items and the entire order
  • A cash discount

Cash discounts

A cash discount can be added to an order to reduce the total to account for the discount offered when paying with cash. This should be a percentage discount.

Except in special cases, per brand processing rules the amount shown to customer must be the total when paying with a credit card. There are special cases for certain MCC designations that can show the credit card processing as a separate additional fee.

However, the vast majority of merchants do not qualify these special cases and instead need to show the credit card price and that paying with cash will result in a discount.

This is purely how the price is presented to the customer. Whether notifying there is an additional credit card fee or a discount when paying with cash the customer is paying the difference for the convince of using a credit card.

The discount is offered when paying with cash due to the merchant not incurring some credit card processing fees when accepting cash. However, the merchant is not required to offer a cash discount. They can charge the same price for credit card and cash. Or they can offer a discount less than the credit card processing fee would cost them.

This discount does not have to be specifically for credit card processing fees either. The merchant is free to cash discount for any reason. The requirement that the total is the credit card total. A second cash total can still be presented to the customer.

If a merchant is not accepting cash the total needs to be inclusive all credit card fees. Except in special cases. If a merchant is unsure if they qualify for any special cases, they most likely don't.

List Discounts

List inventory category discounts

The resulting report will contain these headers:

id, name, timestamp_ms, category_id, amount, type, usecase, description,
sortorder, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = discount
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string

Name of the discount

category_id
string

Unique ID of the product category

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/discount' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Discount

Add a discount to an inventory category

Discounts can be applied to products, orders or both. They can be percentage based or a fixed amount.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = discount_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

category_id
required
string\d+

Unique ID of the product category

name
required
string <= 32 characters

Name of the discount

description
string <= 128 characters

Description of the discount

type
required
string
Default: "percentage"
Enum: "percentage" "fixed"

How the discount amount is applied

Values:

  • percentage - Amount is applied as a percentage
  • fixed - Discount is applied as a fixed amount
usecase
required
string
Enum: "item" "order" "both" "cashdiscount"

What the discount applies to in the order

Values:

  • item - The discount is applied to a specific item in the order
  • order - The discount is applied to the total order amount
  • both - The discount can be applied to either a specific item or the total order amount
  • cashdiscount - The discount applies exclusivly to full cash payments
amount
required
string\d*(\.\d{0,5})?

Amount (up to 5 decimal places)

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "category_id": "string",
  • "name": "string",
  • "description": "string",
  • "type": "percentage",
  • "usecase": "item",
  • "amount": "string",
  • "sortorder": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string",
  • "timestamp_ms": "string"
}

Delete Discount

Delete an inventory category discount

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = discount_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the discount

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/inventory/discount/26863859502458458?timestamp_ms=1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get Discount Detail

Gets details for the specified discount

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = discount
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the discount

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/discount/1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "timestamp_ms": "string",
  • "category_id": "string",
  • "amount": "string",
  • "type": "percentage",
  • "usecase": "item",
  • "description": "string",
  • "sortorder": "string",
  • "is_deleted": "yes"
}

Edit Discount

Edit an inventory category discount

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = discount_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the discount

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the discount

description
string <= 128 characters

Description of the discount

type
string
Default: "percentage"
Enum: "percentage" "fixed"

How the discount amount is applied

Values:

  • percentage - Amount is applied as a percentage
  • fixed - Discount is applied as a fixed amount
usecase
string
Enum: "item" "order" "both" "cashdiscount"

What the discount applies to in the order

Values:

  • item - The discount is applied to a specific item in the order
  • order - The discount is applied to the total order amount
  • both - The discount can be applied to either a specific item or the total order amount
  • cashdiscount - The discount applies exclusivly to full cash payments
amount
string\d*(\.\d{0,5})?

Amount (up to 5 decimal places)

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "name": "string",
  • "description": "string",
  • "type": "percentage",
  • "usecase": "item",
  • "amount": "string",
  • "sortorder": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "timestamp_ms": "string"
}

Inventory Products

Products are high level metadata about items being sold by the merchant.

Products must have at least one SKU added to them in order to be sold. Due to the potential for product variations having different barcodes but still being considered the same product, SKUs are necessary.

Price is not set on the products but instead on SKUs.

Multiple tax rates can be set on a product in order to account for products that are untaxed vs taxed. Multiple tax rates can be applied.

List Products

List inventory products

The resulting report will contain these headers:

id, name, timestamp_ms, category_id, taxrates, modifiersets,
fractional_qty, description, commoditycode, unit, req_modifiersets, sortorder,
image_type, image_data, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = product
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string

Name of the product

category_id
string

Unique ID of the product category

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

fetch_images
object
Enum: "yes" "no"
Example: fetch_images=yes

Include base64-encoded image data

Values:

  • yes - Return image data
  • no - Do not return image data

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/product' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Product

Add an inventory product

Products represent base items. All products will have SKUs which are the actual item's. All products are part of a category.

For example

  • Category = Classic Literature
    • Product = A Tale of Two Cities
      • SKU = Hard cover
      • SKU = Paperback
      • SKU = Audio

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = product_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
required
string <= 32 characters

Name of the product

category_id
required
string\d+

Unique ID of the product category

description
string <= 128 characters

Description of the product

taxrates
string

comma separated list of taxrate ids (up to 4)

modifiersets
string

comma separated list of modifierset ids (up to 8)

req_modifiersets
string

comma separated list of required modifierset ids (must exist in modifiersets)

commoditycode
string[0-9a-zA-Z]{8,12}

Contains an international description code of the individual good or service being supplied

The acquiring bank or processor should provide the merchant an updated listing of currently defined codes. Please note that this is different from the 4-character summary commodity code. Codes can be found online at http://www.unspsc.org

The code itself will not be validated; only the format is validated.

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

sortorder
string\d+

UI sort order (display purposes only)

image_data
string[a-zA-Z0-9+/\n]+={0,2}[\n]*

Base64-encoded image data. Supports JPG and PNG formats. 300x300, 256KB max size.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "name": "string",
  • "category_id": "string",
  • "description": "string",
  • "taxrates": "string",
  • "modifiersets": "string",
  • "req_modifiersets": "string",
  • "commoditycode": "string",
  • "unit": "string",
  • "sortorder": "string",
  • "image_data": "ABC="
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string",
  • "timestamp_ms": "string"
}

Delete Product

Delete an inventory product

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = product_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the product

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/inventory/product/27589475894035458?timestamp_ms=1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get Product Detail

Gets details for the specified product

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = product
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the product

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

fetch_images
object
Enum: "yes" "no"
Example: fetch_images=yes

Include base64-encoded image data

Values:

  • yes - Return image data
  • no - Do not return image data

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/product/1758939453334' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "timestamp_ms": "string",
  • "category_id": "string",
  • "taxrates": "string",
  • "modifiersets": "string",
  • "fractional_qty": "yes",
  • "description": "string",
  • "commoditycode": "string",
  • "unit": "string",
  • "req_modifiersets": "string",
  • "sortorder": "string",
  • "image_type": "PNG",
  • "image_data": "ABC=",
  • "is_deleted": "yes"
}

Edit Product

Edit an inventory product

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = product_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the product

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the product

category_id
string\d+

Unique ID of the product category

description
string <= 128 characters

Description of the product

taxrates
string

comma separated list of taxrate ids (up to 4)

modifiersets
string

comma separated list of modifierset ids (up to 8)

req_modifiersets
string

comma separated list of required modifierset ids (must exist in modifiersets)

commoditycode
string[0-9a-zA-Z]{8,12}

Contains an international description code of the individual good or service being supplied

The acquiring bank or processor should provide the merchant an updated listing of currently defined codes. Please note that this is different from the 4-character summary commodity code. Codes can be found online at http://www.unspsc.org

The code itself will not be validated; only the format is validated.

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

sortorder
string\d+

UI sort order (display purposes only)

image_data
string[a-zA-Z0-9+/\n]+={0,2}[\n]*

Base64-encoded image data. Supports JPG and PNG formats. 300x300, 256KB max size.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "name": "string",
  • "category_id": "string",
  • "description": "string",
  • "taxrates": "string",
  • "modifiersets": "string",
  • "req_modifiersets": "string",
  • "commoditycode": "string",
  • "unit": "string",
  • "sortorder": "string",
  • "image_data": "ABC="
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "timestamp_ms": "string"
}

Inventory SKUs

SKUs are the actual item being sold and are contained within a product.

Product variations can be manufacturing variations of the same product. For example a refreshed version of a product with the same name and functionality.

Another possibility is a product with multiple variations. For example, a vacuum cleaner. Model is XYZ but there are three SKUs that different based on accessory bundles offered as part of the SKU. While it is one product it has multiple SKUs. This is typically manufacturer bundles where each SKU has a different accompanying UPC code.

In both examples the price may differ between the SKUs. This is why price is set on the SKU and not on the product.

List SKUs

List inventory product SKUs

The resulting report will contain these headers:

id, name, timestamp_ms, product_id, inventory, price, in_stock,
inventory_timestamp_ms, barcode, description, sortorder, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = sku
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string

Name of the SKU

product_id
string

Unique ID of the product

in_stock
object
Enum: "yes" "no"
Example: in_stock=yes

Whether the in stock status should be evaulated as a condition

Values:

  • yes - Only return in-stock skus
  • no - Only return out-of-stock skus
timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/sku' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add SKU

Add an inventory product SKU

A SKU is a specific version of a product. For example, if the product is a book, there could be hardcover and paperback SKUs.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = sku_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

product_id
required
string\d+

Unique ID of the product

name
required
string <= 32 characters

Name of the SKU

price
required
string\d*(\.\d{0,5})?

Price (up to 5 decimal places)

inventory
string
Default: "unlimited"
Enum: "unlimited" "tracked" "outofstock"

Type of item stocking

Values:

  • unlimited - The item quantity is not tracked
  • tracked - The item quantity is tracked and there is a finite number available at a given time
  • outofstock - The item is not currently in stock
barcode
string <= 32 characters

Decoded Barcode. E.g. 2d barcode decoded to the UPC number

description
string <= 128 characters

Description of the SKU

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "product_id": "string",
  • "name": "string",
  • "price": "string",
  • "inventory": "unlimited",
  • "barcode": "string",
  • "description": "string",
  • "sortorder": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string",
  • "timestamp_ms": "string"
}

Delete SKU

Delete an inventory product SKU

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = sku_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the SKU

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/inventory/sku/13748493859345458?timestamp_ms=57849320845' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get SKU Detail

Gets details for the specified SKU

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = sku
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the SKU

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/sku/1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "timestamp_ms": "string",
  • "product_id": "string",
  • "inventory": "unlimited",
  • "price": "string",
  • "in_stock": "yes",
  • "inventory_timestamp_ms": "string",
  • "barcode": "string",
  • "description": "string",
  • "sortorder": "string",
  • "is_deleted": "yes"
}

Edit SKU

Edit an inventory product SKU

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = sku_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the SKU

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the SKU

price
string\d*(\.\d{0,5})?

Price (up to 5 decimal places)

inventory
string
Default: "unlimited"
Enum: "unlimited" "tracked" "outofstock"

Type of item stocking

Values:

  • unlimited - The item quantity is not tracked
  • tracked - The item quantity is tracked and there is a finite number available at a given time
  • outofstock - The item is not currently in stock
barcode
string <= 32 characters

Decoded Barcode. E.g. 2d barcode decoded to the UPC number

description
string <= 128 characters

Description of the SKU

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "name": "string",
  • "price": "string",
  • "inventory": "unlimited",
  • "barcode": "string",
  • "description": "string",
  • "sortorder": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "timestamp_ms": "string"
}

Set SKU Quantity

Set the quantity for SKU

Tracking for the number of items in stock

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = inventory_set
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the SKU

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

cnt
required
string\d+

Exact count of inventory in stock

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "cnt": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "timestamp_ms": "string"
}

Inventory Modifier Sets

Modifier sets are similar to categories. In that they are a logical grouping of modifiers.

Modifier sets are attached to products in order to allow modifying products.

In the SKU section an example of a vacuum cleaner with multiple accessory bundle variations was used. In that case the SKUs were due to manufacturer bundles with different UPC codes.

Building on that example, a product might have a single SKU for the item because the manufacturer only produces one item. Instead the merchant has their on add on bundles they sell with the item. A modifier set can be used with a modifier for each add on.

List Modifier Sets

List inventory modifier sets

The resulting report will contain these headers:

id, name, timestamp_ms, description, multiselect, maxselect, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = modifierset
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string

Name of the modifier set

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/modifierset' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Modifier Set

Add an inventory modifier set

A grouping of like modifiers. For example, pizza toppings. Where each topping is a modifier within the set.

Modifier sets are applied to products. It can be applied to multiple products. For example, a pizza topping modifier set could apply to product pizza and product calzone (which is like a pizza but harder to eat and they're dumb). Both can and often use the same topping modifiers.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifierset_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
required
string <= 32 characters

Name of the modifier set

description
string <= 128 characters

Description of the modifier set

multiselect
string
Default: "no"
Enum: "yes" "no"

Whether or not multiple selection is allowed

Values:

  • yes - Multiple selection is allowed
  • no - Multiple selection is NOT allowed
maxselect
string\d+

How many items may be selected at once (only if multiselect, default=unlimited)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "name": "string",
  • "description": "string",
  • "multiselect": "yes",
  • "maxselect": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string",
  • "timestamp_ms": "string"
}

Delete Modifier Set

Delete an inventory modifier set

The modifier set must be empty.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifierset_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the modifier set

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/inventory/modifierset/84578903855643344?timestamp_ms=1895849024551' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get Modifier Set Detail

Gets details for the specified modifier set

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = modifierset
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the modifier set

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/modifierset/1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "timestamp_ms": "string",
  • "description": "string",
  • "multiselect": "yes",
  • "maxselect": "string",
  • "is_deleted": "yes"
}

Edit Modifier Set

Edit an inventory modifier set

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifierset_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the modifier set

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the modifier set

description
string <= 128 characters

Description of the modifier set

multiselect
string
Default: "no"
Enum: "yes" "no"

Whether or not multiple selection is allowed

Values:

  • yes - Multiple selection is allowed
  • no - Multiple selection is NOT allowed
maxselect
string\d+

How many items may be selected at once (only if multiselect, default=unlimited)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "name": "string",
  • "description": "string",
  • "multiselect": "yes",
  • "maxselect": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "timestamp_ms": "string"
}

Inventory Modifiers

Modifiers are ways a product can be altered. They belong to modifier sets to better group the modifiers. A common term for a modifier is an add on.

Modifiers can have their own price that can increase the total price of a product. They are not required to have a price and will not increase the product price if added.

An example is a pizza where a topping modifier set is created and within the set is a modifier representing each topping and it's additional price per topping.

List Modifiers

List inventory modifiers

The resulting report will contain these headers:

id, name, timestamp_ms, modifierset_id, price, description, unit, sortorder,
is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = modifier
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string

Name of the modifier

modifierset_id
string

Unique ID of the modifier set

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/modifier' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Modifier

Add an inventory modifier to a modifier set

Modifiers augment a product and are typically add ons. This is different than a SKU.

For example, a pizza topping would be a modifier. Pepperoni, mushroom, or bacon. Multiple modifiers can be applied to an order.

All modifiers are part of a modifier set in order to provide logical groupings for modifiers.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifier_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

modifierset_id
required
string\d+

Unique ID of the modifier set

name
required
string <= 32 characters

Name of the modifier

description
string <= 128 characters

Description of the modifier

price
string\d*(\.\d{0,5})?

Price (up to 5 decimal places)

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "modifierset_id": "string",
  • "name": "string",
  • "description": "string",
  • "price": "string",
  • "unit": "string",
  • "sortorder": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string",
  • "timestamp_ms": "string"
}

Delete Modifier

Delete an inventory modifier

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifier_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the modifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/inventory/modifier/82859028592849248?timestamp_ms=1895849024551' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get Modifier Detail

Gets details for the specified modifier

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = modifier
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the modifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/modifier/1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "timestamp_ms": "string",
  • "modifierset_id": "string",
  • "price": "string",
  • "description": "string",
  • "unit": "string",
  • "sortorder": "string",
  • "is_deleted": "yes"
}

Edit Modifier

Edit an inventory modifier

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifier_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the modifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the modifier

description
string <= 128 characters

Description of the modifier

price
string\d*(\.\d{0,5})?

Price (up to 5 decimal places)

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "name": "string",
  • "description": "string",
  • "price": "string",
  • "unit": "string",
  • "sortorder": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "timestamp_ms": "string"
}

Inventory Tax Rates

Tax rates are the amount of tax that is charged to an item. This is used for automatic calculation of tax when the inventory system is used in conjunction with the order system.

Multiple tax rates may be necessary and multiple can be applied to products. There may be a state and county tax that are tracked and remitted separately. Two tax rates would be created and both added to a product. When the inventory is used with the order system, this allows generating tax rate reports to aid with remittance to the relevant governments.

List Tax Rates

List inventory tax rates

The resulting report will contain these headers:

id, name, timestamp_ms, percentage, default, roundmethod, sortorder, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = taxrate
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string

Name of the tax rate

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/taxrate' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add Tax Rate

Add an inventory tax rate

Allows creating a tax rate that can be applied to products. Multiple tax rates could be necessary for reporting purposes.

For example, separate rates for state, county, and city. Multiple tax rates can be applied to products.

Having several tax rates my be necessary if products are taxed differently based on their type. For example, some places have digital and physical goods rates.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = taxrate_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
required
string <= 32 characters

Name of the tax rate

percentage
required
string\d*(\.\d{0,5})?

Percentage of tax rate (up to 5 decimal places)

default
string
Default: "no"
Enum: "yes" "no"

Whether this should be applied by default to new products (UI)

Values:

  • yes - Apply by default to new products
  • no - Do not apply by default to new products
roundmethod
string
Enum: "normal" "bankers"

Method used for rounding

Values:

  • normal - Round to the nearest whole number
  • bankers - Round to the nearest even whole number
sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "name": "string",
  • "percentage": "string",
  • "default": "yes",
  • "roundmethod": "normal",
  • "sortorder": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string",
  • "timestamp_ms": "string"
}

Delete Tax Rate

Delete an inventory tax rate

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = taxrate_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the tax rate

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/inventory/taxrate/14859438593544438?timestamp_ms=1859386643324' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get Tax Rate Detail

Gets details for the specified tax rate

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = taxrate
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the tax rate

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/taxrate/1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "timestamp_ms": "string",
  • "percentage": "string",
  • "default": "yes",
  • "roundmethod": "normal",
  • "sortorder": "string",
  • "is_deleted": "yes"
}

Edit Tax Rate

Edit an inventory tax rate

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = taxrate_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of the tax rate

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the tax rate

percentage
string\d*(\.\d{0,5})?

Percentage of tax rate (up to 5 decimal places)

default
string
Default: "no"
Enum: "yes" "no"

Whether this should be applied by default to new products (UI)

Values:

  • yes - Apply by default to new products
  • no - Do not apply by default to new products
roundmethod
string
Enum: "normal" "bankers"

Method used for rounding

Values:

  • normal - Round to the nearest whole number
  • bankers - Round to the nearest even whole number
sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "name": "string",
  • "percentage": "string",
  • "default": "yes",
  • "roundmethod": "normal",
  • "sortorder": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "timestamp_ms": "string"
}

Orders

The order system allows creating orders

The profile flag ALLOW_INVOICING must be set.

Order types

There are three types of 'orders':

  • Order - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • Quick - Single or no line item orders. Typically used for single amount payments
  • Invoice - Billing invoice for later payment

The line items can be based on inventory items from the inventory system or a custom (one off) line item. Customers who have an external product system and only need the invoice for billing will often use a single custom line item for the order amount. You can attach the external system generated PDF so the customer will be able to view it from the link they get sent to pay. This is useful in the external invoice generation scenario where TranSafe 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 TranSafe for viewing. Since it's the same link for open orders to allow payment and closed orders for viewing receipts, sending is contained in one place ("Receipts").

Invoices will be automatically email to the customer when closed. This requires a customer from the customer system to be associated with the order and that customer must have an email on file. Further, if the profile has the RECEIVE_RECEIPTS_INVOICE flag set, an email will be sent to the notify_email.

timestamp_ms

The timestamp_ms parameter is used to ensure changes do not create conflicts. The value for timestamp_ms is either returned by an operation and is then used in the next. Or it can be retrieved by getting an order details or when listing orders.

Cancel an Order or Invoice

Cancel an order in the OPEN or PENDING states

The order is not removed from the system. Must be used instead of order delete if there have been payments attempted against it.

It is recommended to delete orders if possible as it doesn't leave stale records.

NOTE: must cancel all applied payments before canceling an order or invoice.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = order_cancel
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order identifier, numeric only

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

cancel_reason
required
string
Enum: "CANCEL" "RETURN" "SATISFACTION"

Reason for order cancellation

Values:

  • CANCEL - Generic cancel
  • RETURN - All items in the order were returned
  • SATISFACTION - Customer was not satisfied
timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "cancel_reason": "CANCEL",
  • "timestamp_ms": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

List Orders

List orders

The resulting report will contain these headers:

id, timestamp_ms, user, id_base62, type, flags, status, cancel_reason,
merch_status, customer_id, customer_display_name, ordernum, ponumber,
allowed_cardtypes, securitytoken, timestamp_create, timestamp_close,
timestamp_sent, timestamp_viewed, invoice_date, invoice_due, taxrates,
taxamounts, total_amount, total_tax, total_discount, total_paid, total_tip,
total_amount_cash, total_amount_noncash, notes, total_tax_override, ship_name,
ship_address1, ship_address2, ship_city, ship_state, ship_zip, ship_country,
ship_notes, invoice_filename, invoice_data, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = orders
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

customer_id
string

Comma separated list of customer identifiers

ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to TranSafe, an order number should be sent on all transactions.

Normally, an order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

type
object
Enum: "ORDER" "QUICK" "INVOICE"
Example: type=ORDER,QUICK

Comma separated list of order types

Flag values (comma separated):

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
object
Enum: "PENDING" "OPEN" "PARTIALPAID" "COMPLETE" "CANCEL" "FORCECLOSED"
Example: status=OPEN,PARTIALPAID

Comma separated list of order status

Flag values (comma separated):

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
  • PARTIALPAID - Order has been partially paid
  • COMPLETE - Order is complete
  • CANCEL - Order has been canceled
  • FORCECLOSED - Order was force closed
timestamp_create_bdate
string

Start of order created date range as a timestamp

timestamp_create_edate
string

End of order created date range as a timestamp

timestamp_close_bdate
string

Start of order closed date range as a timestamp

timestamp_close_edate
string

End of order closed date range as a timestamp

fetch_invoices
object
Enum: "yes" "no"
Example: fetch_invoices=yes

Include base64-encoded invoice data

Applies to invoices with external (PDF) invoice documents.

Values:

  • yes - Return invoice data
  • no - Do not return invoice data
timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Create an Order or Invoice

Create an order or invoice

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = order_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

type
required
string
Enum: "ORDER" "QUICK" "INVOICE"

Type of order

Values:

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
required
string
Enum: "PENDING" "OPEN"

Status of the order

Values:

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
flags
string
Value: "NOTIP"

Type of order

Flag values (pipe separated):

  • NOTIP - Do not attempt to perform tip prompting when collecting payment
merch_status
string
Enum: "PENDING" "COMPLETE" "PREPARING" "BACKORDERED"

Merchant status of the order

Values:

  • PENDING - Order is pending
  • COMPLETE - Order is complete
  • PREPARING - Order is being prepared
  • BACKORDERED - Order is delayed while waiting for back ordered items
customer_id
string[0-9]+

Customer identifier, numeric only

Required when type = Invoice

ordernum
string <= 128 characters

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to TranSafe, an order number should be sent on all transactions.

Normally, an order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

ponumber
string <= 32 characters

Unique identifier of the order

Typically used with Invoices

allowed_cardtypes
string
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "CUP" "GIFT" "ACH"

Card types allowed to be used for payment

Pipe-separated (|) list of cardtypes accepted for payment. Merchant must be configured to accept the provided cardtypes. Defaults to allow all if not provided.

This is typically used in conjunction with accepting payment online using the TranSafe Invoice Payment Web Page for online order or invoice payment.

Flag values (pipe separated):

  • VISA - Visa
  • MC - Mastercard
  • AMEX - American Express
  • DISC - Discover
  • DINERS - Diners
  • JCB - Japan Credit Bureau
  • CUP - China Union Pay
  • GIFT - Generic gift card
  • ACH - Electronic funds transfer, e.g. CCD,PPD
invoice_date
string

Date the order was created

Current date if not provided

invoice_due
string

Date the order is due

Current date if not provided

notes
string <= 1024 characters

General free-form information

Will be shown to customers!

total_tax_override
string0?\.\d{2}

Tax override amount, only used if all line items have no tax rates

ship_name
string <= 32 characters

Shipping name of recipient

"To" field on shipping label.

ship_address1
string <= 32 characters

Shipping street address of recipient

Line 1

ship_address2
string <= 32 characters

Shipping street address of recipient

Line 2

ship_city
string <= 32 characters

Shipping city of recipient

ship_state
string <= 32 characters

Shipping state / provence of recipient

ship_zip
string <= 32 characters

Shipping zip / postal Code of recipient

Used for tax zones

ship_country
string <= 32 characters

Shipping country of recipient

ship_notes
string <= 128 characters

Shipping delivery instructions

invoice_filename
string <= 32 characters

Filename of externally attached invoice PDF

Requires:

  • invoice_data
invoice_data
string[a-zA-Z0-9+/\n]+={0,2}[\n]*

PDF base64 encoded invoice PDF

Used for externally generated invoice billing

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "type": "ORDER",
  • "status": "PENDING",
  • "flags": "NOTIP",
  • "merch_status": "PENDING",
  • "customer_id": "string",
  • "ordernum": "A13DDES345",
  • "ponumber": "string",
  • "allowed_cardtypes": "VISA",
  • "invoice_date": "string",
  • "invoice_due": "string",
  • "notes": "string",
  • "total_tax_override": "string",
  • "ship_name": "string",
  • "ship_address1": "string",
  • "ship_address2": "string",
  • "ship_city": "string",
  • "ship_state": "string",
  • "ship_zip": "string",
  • "ship_country": "string",
  • "ship_notes": "string",
  • "invoice_filename": "string",
  • "invoice_data": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string",
  • "timestamp_ms": "string"
}

Delete an Order or Invoice

Completely remove an order or invoice from the system

Cannot be used if an order has had payments applied. If payments have been applied the order must be canceled.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = order_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order identifier, numeric only

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/order/1456543256' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get Order Detail

Gets details for the specified order

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = orders
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order identifier, numeric only

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

fetch_invoices
object
Enum: "yes" "no"
Example: fetch_invoices=yes

Include base64-encoded invoice data

Applies to invoices with external (PDF) invoice documents.

Values:

  • yes - Return invoice data
  • no - Do not return invoice data
timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/789567654256' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp_ms": "string",
  • "user": "string",
  • "id_base62": "string",
  • "type": "ORDER",
  • "flags": "NOTIP",
  • "status": "PENDING",
  • "cancel_reason": "CANCEL",
  • "merch_status": "PENDING",
  • "customer_id": "string",
  • "customer_display_name": "string",
  • "ordernum": "A13DDES345",
  • "ponumber": "string",
  • "allowed_cardtypes": "VISA",
  • "securitytoken": "string",
  • "timestamp_create": "string",
  • "timestamp_close": "string",
  • "timestamp_sent": "string",
  • "timestamp_viewed": "string",
  • "invoice_date": "string",
  • "invoice_due": "string",
  • "taxrates": "string",
  • "taxamounts": "string",
  • "total_amount": "string",
  • "total_tax": "string",
  • "total_discount": "string",
  • "total_paid": "string",
  • "total_tip": "string",
  • "total_amount_cash": "string",
  • "total_amount_noncash": "string",
  • "notes": "string",
  • "total_tax_override": "string",
  • "ship_name": "string",
  • "ship_address1": "string",
  • "ship_address2": "string",
  • "ship_city": "string",
  • "ship_state": "string",
  • "ship_zip": "string",
  • "ship_country": "string",
  • "ship_notes": "string",
  • "invoice_filename": "string",
  • "invoice_data": "string",
  • "is_deleted": "yes"
}

Edit an Order or Invoice

Edit and order or invoice

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = order_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order identifier, numeric only

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

type
string
Enum: "ORDER" "QUICK" "INVOICE"

Type of order

Values:

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
string
Enum: "PENDING" "OPEN"

Status of the order

Values:

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
flags
string
Value: "NOTIP"

Type of order

Flag values (pipe separated):

  • NOTIP - Do not attempt to perform tip prompting when collecting payment
merch_status
string
Enum: "PENDING" "COMPLETE" "PREPARING" "BACKORDERED"

Merchant status of the order

Values:

  • PENDING - Order is pending
  • COMPLETE - Order is complete
  • PREPARING - Order is being prepared
  • BACKORDERED - Order is delayed while waiting for back ordered items
customer_id
string[0-9]+

Customer identifier, numeric only

ordernum
string <= 128 characters

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to TranSafe, an order number should be sent on all transactions.

Normally, an order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

ponumber
string <= 32 characters

Unique identifier of the order

Typically used with Invoices

allowed_cardtypes
string
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "CUP" "GIFT" "ACH"

Card types allowed to be used for payment

Pipe-separated (|) list of cardtypes accepted for payment. Merchant must be configured to accept the provided cardtypes. Defaults to allow all if not provided.

This is typically used in conjunction with accepting payment online using the TranSafe Invoice Payment Web Page for online order or invoice payment.

Flag values (pipe separated):

  • VISA - Visa
  • MC - Mastercard
  • AMEX - American Express
  • DISC - Discover
  • DINERS - Diners
  • JCB - Japan Credit Bureau
  • CUP - China Union Pay
  • GIFT - Generic gift card
  • ACH - Electronic funds transfer, e.g. CCD,PPD
invoice_date
string

Date the order was created

Current date if not provided

invoice_due
string

Date the order is due

Current date if not provided

notes
string <= 1024 characters

General free-form information

Will be shown to customers!

total_tax_override
string0?\.\d{2}

Tax override amount, only used if all line items have no tax rates

ship_name
string <= 32 characters

Shipping name of recipient

"To" field on shipping label.

ship_address1
string <= 32 characters

Shipping street address of recipient

Line 1

ship_address2
string <= 32 characters

Shipping street address of recipient

Line 2

ship_city
string <= 32 characters

Shipping city of recipient

ship_state
string <= 32 characters

Shipping state / provence of recipient

ship_zip
string <= 32 characters

Shipping zip / postal Code of recipient

Used for tax zones

ship_country
string <= 32 characters

Shipping country of recipient

ship_notes
string <= 128 characters

Shipping delivery instructions

invoice_filename
string <= 32 characters

Filename of externally attached invoice PDF

Requires:

  • invoice_data
invoice_data
string[a-zA-Z0-9+/\n]+={0,2}[\n]*

PDF base64 encoded invoice PDF

Used for externally generated invoice billing

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "type": "ORDER",
  • "status": "PENDING",
  • "flags": "NOTIP",
  • "merch_status": "PENDING",
  • "customer_id": "string",
  • "ordernum": "A13DDES345",
  • "ponumber": "string",
  • "allowed_cardtypes": "VISA",
  • "invoice_date": "string",
  • "invoice_due": "string",
  • "notes": "string",
  • "total_tax_override": "string",
  • "ship_name": "string",
  • "ship_address1": "string",
  • "ship_address2": "string",
  • "ship_city": "string",
  • "ship_state": "string",
  • "ship_zip": "string",
  • "ship_country": "string",
  • "ship_notes": "string",
  • "invoice_filename": "string",
  • "invoice_data": "string",
  • "timestamp_ms": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "timestamp_ms": "string"
}

Order Bulk

Order bulk operations

Bulk Order Operation

Allows for grouping multiple order operations into a single operation

The bulk operation is "atomic" and if any steps fail everything will fail.

Bulk operations take any of the actions for the category as KVS pairs.

Actions to be performed are structured as a JSON-array of objects, with the key/value pairs matching the field definitions, plus a ordermanage key with value set to the appropriate action being taken. Reference the libMonetra KVS for the appropriate values. This JSON object is passed in to the bulk key on the request.

Back references can be used for ids and timestamps in the format of: :id[{idx}] or :timestamp_ms[{idx}] Where the {idx} is the array index of the response for a member being referenced.

The result of a bulk operation will also return a bulk key in the response with JSON output containing: result, id, timestamp_ms, error if appropriate.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = bulk
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

bulk
required
string

Bulk data encoded as JSON

If the bulk JSON data is being sent in a protocol which itself is JSON data (ReST submitting JSON) the data within this key must be escaped as a string.

This also applies to JSON response data. If the protocol is JSON the data will be escaped as a string and will need to be decoded.

E.g. when using a JSON protocol for transport

JSON Data
[ { "action": "sub_action_1", "key1": "val1", "key2": "val2" }, { "action": "sub_action_2", "key1": "val1", "key2": "val2" }, { "action": "sub_action_3", "key1": "val1", "key2": "val2" } ]

Encoded for JSON transport protocol
{
    "key": "val",
    "bulk": "[{\"action\":\"sub_action_1\",\"key1\":\"val1\",\"key2\":\"val2\"},{\"action\":\"sub_action_2\",\"key1\":\"val1\",\"key2\":\"val2\"},{\"action\":\"sub_action_3\",\"key1\":\"val1\",\"key2\":\"val2\"}]"
}

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "bulk": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "bulk": "string"
}

Order Discounts

Order discount management. This is for managing discounts applied to the entire order. Discounts can be added to an order using a custom discount or by referencing a discount from the inventory system. An inventory system discount must be of a type that can be applied to orders.

When operating on a discount, such as edit or delete, the id of the discount within the order is referenced. Not the discount id within the inventory system if the inventory system was used.

Add a Custom Fixed Discount

Add a custom fixed discount to the order

For adding discounts that are not in the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_add
  • ref_id = 0
  • type = DISCOUNT_FIXED
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

amount
required
string\d*(\.\d{0,5})?

Amount of money, including up to 5 decimal places. E.g 1.00 or 2.399

This is the amount of 1 unit.

taxrates
string

comma separated list of taxrate ids (up to 4)

name
required
string <= 32 characters

Name of the discount

productcode
string[0-9a-zA-Z ]{1,12}

Merchant-defined code for the item being purchased, such as a UPC #, SKU #, or Item #

commoditycode
string[0-9a-zA-Z]{8,12}

Contains an international description code of the individual good or service being supplied

The acquiring bank or processor should provide the merchant an updated listing of currently defined codes. Please note that this is different from the 4-character summary commodity code. Codes can be found online at http://www.unspsc.org

The code itself will not be validated; only the format is validated.

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "amount": "4.779",
  • "taxrates": "string",
  • "name": "string",
  • "productcode": "string",
  • "commoditycode": "string",
  • "unit": "string",
  • "notes": "string",
  • "group_name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Add a Custom Percent Discount

Add a custom percent discount to the order

For adding discounts that are not in the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_add
  • ref_id = 0
  • type = DISCOUNT_PERCENT
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

amount
required
string\d*(\.\d{0,5})?

Amount of money, including up to 5 decimal places. E.g 1.00 or 2.399

This is the amount of 1 unit.

taxrates
string

comma separated list of taxrate ids (up to 4)

name
required
string <= 32 characters

Name of the discount

productcode
string[0-9a-zA-Z ]{1,12}

Merchant-defined code for the item being purchased, such as a UPC #, SKU #, or Item #

commoditycode
string[0-9a-zA-Z]{8,12}

Contains an international description code of the individual good or service being supplied

The acquiring bank or processor should provide the merchant an updated listing of currently defined codes. Please note that this is different from the 4-character summary commodity code. Codes can be found online at http://www.unspsc.org

The code itself will not be validated; only the format is validated.

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "amount": "4.779",
  • "taxrates": "string",
  • "name": "string",
  • "productcode": "string",
  • "commoditycode": "string",
  • "unit": "string",
  • "notes": "string",
  • "group_name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Add a Fixed Discount

Add a fixed amount discount to the order

The discount references a discount from the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_add
  • type = DISCOUNT_FIXED
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ref_id
required
string[0-9]+

Unique ID of the discount

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ref_id": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "notes": "string",
  • "group_name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Add a Percent Discount

Add a percentage discount to the order

The discount references a discount from the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_add
  • type = DISCOUNT_PERCENT
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ref_id
required
string[0-9]+

Unique ID of the discount

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ref_id": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "notes": "string",
  • "group_name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Remove a Discount

Remove a discount form an order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order discount identifier

order_id
required
string

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/order/20245528771333405/discount/5894387586' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Edit a Discount

Edit a discount for an order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order discount identifier

order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

ringorder
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "notes": "string",
  • "group_name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Order Items

Order item management. This is for managing items added to an order. Items can be added to an order using a custom item or by referencing a SKU from the inventory system.

When operating on a item, such as edit or delete, the id of the item within the order is referenced. Not the SKU id within the inventory system if the inventory system was used.

Add a Custom Item

Add a custom line item to the order

For adding line items that are not SKUs in the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_add
  • ref_id = 0
  • type = ADDON
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

amount
required
string\d*(\.\d{0,5})?

Amount of money, including up to 5 decimal places. E.g 1.00 or 2.399

This is the amount of 1 unit.

taxrates
string

comma separated list of taxrate ids (up to 4)

name
required
string <= 32 characters

Name of the line item

productcode
string[0-9a-zA-Z ]{1,12}

Merchant-defined code for the item being purchased, such as a UPC #, SKU #, or Item #

commoditycode
string[0-9a-zA-Z]{8,12}

Contains an international description code of the individual good or service being supplied

The acquiring bank or processor should provide the merchant an updated listing of currently defined codes. Please note that this is different from the 4-character summary commodity code. Codes can be found online at http://www.unspsc.org

The code itself will not be validated; only the format is validated.

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "amount": "4.779",
  • "taxrates": "string",
  • "name": "string",
  • "productcode": "string",
  • "commoditycode": "string",
  • "unit": "string",
  • "notes": "string",
  • "group_name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

List Items

List order items

Gets Items for the specified Order.

The resulting report will contain these headers:

id, timestamp_ms, order_id, type, ringorder, ref_id, qty, amount,
total_modifiers, total_mod_disc, total_ord_disc, taxrates, name,
productcode, commoditycode, unit, notes, group_name, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = items
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

customer_id
string

Comma separated list of customer identifiers

ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to TranSafe, an order number should be sent on all transactions.

Normally, an order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

type
object
Enum: "ORDER" "QUICK" "INVOICE"
Example: type=ORDER,QUICK

Comma separated list of order types

Flag values (comma separated):

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
object
Enum: "PENDING" "OPEN" "PARTIALPAID" "COMPLETE" "CANCEL" "FORCECLOSED"
Example: status=OPEN,PARTIALPAID

Comma separated list of order status

Flag values (comma separated):

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
  • PARTIALPAID - Order has been partially paid
  • COMPLETE - Order is complete
  • CANCEL - Order has been canceled
  • FORCECLOSED - Order was force closed
timestamp_create_bdate
string

Start of order created date range as a timestamp

timestamp_create_edate
string

End of order created date range as a timestamp

timestamp_close_bdate
string

Start of order closed date range as a timestamp

timestamp_close_edate
string

End of order closed date range as a timestamp

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/7589432567654/item' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add an Item

Add a line item to the order

The line item references a SKU from the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_add
  • type = ADDON
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ref_id
required
string[0-9]+

Unique ID of the inventory SKU

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ref_id": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "notes": "string",
  • "group_name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Remove an Item

Remove a line item form an order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/order/item/675894315' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get Item Detail

Gets details for the specified Item in an order

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = items
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to TranSafe, an order number should be sent on all transactions.

Normally, an order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/item/8594387568950432' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp_ms": "string",
  • "type": "ADDON",
  • "ringorder": "string",
  • "ref_id": "string",
  • "qty": "string",
  • "amount": "19.92",
  • "total_modifiers": "string",
  • "total_mod_disc": "string",
  • "total_ord_disc": "string",
  • "taxrates": "string",
  • "name": "string",
  • "productcode": "string",
  • "commoditycode": "string",
  • "unit": "string",
  • "notes": "string",
  • "group_name": "string",
  • "is_deleted": "yes"
}

Edit an Item

Edit a line item for an order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

ringorder
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "notes": "string",
  • "group_name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Order Item Discounts

Order item discount management. This is for managing item discounts added to an item in an order. Item discounts can be added to an order using a custom item discount or by referencing discount from the inventory system. An inventory system discount must be of a type that can be applied to items.

When referencing an item to apply a discount, the item must be added to the order first. The item id within the order, not the inventory SKU id, is referenced when adding the discount.

When operating on a item discount, such as edit or delete, the id of the item discount within the order is referenced. Not the discount id within the inventory system if the inventory system was used.

Add a Custom Item Fixed Discount

Add a custom fixed discount to a line item

For adding discounts that are not in the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_add
  • ref_id = 0
  • type = DISCOUNT_FIXED
Authorizations:
basic_authapikey_idapikey
path Parameters
item_id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

amount
required
string\d*(\.\d{0,5})?

Amount of money, including up to 5 decimal places. E.g 1.00 or 2.399

This is the amount of 1 unit.

name
required
string <= 32 characters

Name of line item discount

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "amount": "4.779",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Add a Custom Item Percent Discount

Add a custom percent discount to a line item

For adding discounts that are not in the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_add
  • ref_id = 0
  • type = DISCOUNT_PERCENT
Authorizations:
basic_authapikey_idapikey
path Parameters
item_id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

amount
required
string\d*(\.\d{0,5})?

Amount of money, including up to 5 decimal places. E.g 1.00 or 2.399

This is the amount of 1 unit.

name
required
string <= 32 characters

Name of line item discount

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "amount": "4.779",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Add an Item Fixed Discount

Add a fixed discount to a line item

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_add
  • type = DISCOUNT_FIXED
Authorizations:
basic_authapikey_idapikey
path Parameters
item_id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ref_id
required
string\d+

Unique ID of the inventory discount

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ref_id": "string",
  • "ringorder": "string",
  • "qty": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Add an Item Percent Discount

Add a percent discount to a line item

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_add
  • type = DISCOUNT_PERCENT
Authorizations:
basic_authapikey_idapikey
path Parameters
item_id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ref_id
required
string\d+

Unique ID of the inventory discount

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ref_id": "string",
  • "ringorder": "string",
  • "qty": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Remove an Item Discount

Remove a discount from a line item in the order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order item discount identifier

order_id
required
string

Unique ID of an order

item_id
required
string

Order item identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/order/item/discount/76789625' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Edit an Item Discount

Edit a line item discount

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order item discount identifier

order_id
required
string

Unique ID of an order

item_id
required
string

Order item identifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

ringorder
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "ringorder": "string",
  • "qty": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Order Item Modifiers

Order item modifier management. This is for managing item modifiers added to an item in an order. Item modifier can be added to an order using a custom item modifier or by referencing modifiers from the inventory system.

When referencing an item to apply a modifier, the item must be added to the order first. The item id within the order, not the inventory SKU id, is referenced when adding the modifier.

When operating on a item modifier, such as edit or delete, the id of the item modifier within the order is referenced. Not the modifier id within the inventory system if the inventory system was used.

Add a Custom Item Modifier

Add a custom modifier to a line item

For adding modifiers that are not in the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_add
  • ref_id = 0
  • type = ADDON
Authorizations:
basic_authapikey_idapikey
path Parameters
item_id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

amount
required
string\d*(\.\d{0,5})?

Amount of money, including up to 5 decimal places. E.g 1.00 or 2.399

This is the amount of 1 unit.

name
required
string <= 32 characters

Name of line item modifier

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ringorder": "string",
  • "qty": "string",
  • "amount": "4.779",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

List Order Item Modifiers

List order item modifiers

The resulting report will contain these headers:

id, timestamp_ms, item_id, order_id, type, ringorder, ref_id, qty, amount, name, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = modifiers
Authorizations:
basic_authapikey_idapikey
path Parameters
item_id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

customer_id
string

Comma separated list of customer identifiers

ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to TranSafe, an order number should be sent on all transactions.

Normally, an order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

type
object
Enum: "ORDER" "QUICK" "INVOICE"
Example: type=ORDER,QUICK

Comma separated list of order types

Flag values (comma separated):

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
object
Enum: "PENDING" "OPEN" "PARTIALPAID" "COMPLETE" "CANCEL" "FORCECLOSED"
Example: status=OPEN,PARTIALPAID

Comma separated list of order status

Flag values (comma separated):

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
  • PARTIALPAID - Order has been partially paid
  • COMPLETE - Order is complete
  • CANCEL - Order has been canceled
  • FORCECLOSED - Order was force closed
timestamp_create_bdate
string

Start of order created date range as a timestamp

timestamp_create_edate
string

End of order created date range as a timestamp

timestamp_close_bdate
string

Start of order closed date range as a timestamp

timestamp_close_edate
string

End of order closed date range as a timestamp

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/item/7584933567654/modifier' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add an Item Modifier

Add an item modifier to a line item

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_add
  • type = ADDON
Authorizations:
basic_authapikey_idapikey
path Parameters
item_id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ref_id
required
string\d+

Unique ID of the inventory modifier

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ref_id": "string",
  • "ringorder": "string",
  • "qty": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Remove an Item Modifier

Remove a modifier from a line item in the order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_del
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order item modifier identifier

order_id
required
string

Unique ID of an order

item_id
required
string

Order item identifier

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/order/item/modifier/785903676' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get Item Modifier Detail

Gets details for the specified modifier

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = modifiers
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order item modifier identifier

item_id
required
string

Order item identifier

order_id
required
string

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/modifier/75849356543' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp_ms": "string",
  • "item_id": "string",
  • "order_id": "string",
  • "type": "ADDON",
  • "ringorder": "string",
  • "ref_id": "string",
  • "qty": "string",
  • "amount": "19.92",
  • "name": "string",
  • "is_deleted": "yes"
}

Edit an Item Modifier

Edit a line item modifier

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_edit
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Order item modifier identifier

order_id
required
string

Unique ID of an order

item_id
required
string

Order item identifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

ringorder
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "timestamp_ms": "string",
  • "ringorder": "string",
  • "qty": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Order Payments

Allows associating payments to an order. As well as manging the payments applied to orders. Payments can be previous transactions made through TranSafe or external payments (cash and check) that are being recorded for reporting purposes.

Add a Cash Payment

Add a cash payment to the order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = payment_add
  • tendertype = CASH
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

amount
required
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

tip
required
string\d+(\.\d{0,2})?

Tip amount

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "amount": "19.92",
  • "tip": "0.33"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Add a Check Payment

Add a check payment to the order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = payment_add
  • tendertype = CHECK
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

amount
required
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

tip
required
string\d+(\.\d{0,2})?

Tip amount

checknum
required
string\d+

Check number

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "amount": "19.92",
  • "tip": "0.33",
  • "checknum": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

List Payments

List order payments

Gets the Payments for the specified order.

The resulting report will contain these headers:

id, timestamp_ms, user, order_id, tendertype, amount, tip, status, ttid,
timestamp, cardtype, last4, cardholdername, checknum, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = payments
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

customer_id
string

Comma separated list of customer identifiers

ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to TranSafe, an order number should be sent on all transactions.

Normally, an order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

type
object
Enum: "ORDER" "QUICK" "INVOICE"
Example: type=ORDER,QUICK

Comma separated list of order types

Flag values (comma separated):

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
object
Enum: "PENDING" "OPEN" "PARTIALPAID" "COMPLETE" "CANCEL" "FORCECLOSED"
Example: status=OPEN,PARTIALPAID

Comma separated list of order status

Flag values (comma separated):

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
  • PARTIALPAID - Order has been partially paid
  • COMPLETE - Order is complete
  • CANCEL - Order has been canceled
  • FORCECLOSED - Order was force closed
timestamp_create_bdate
string

Start of order created date range as a timestamp

timestamp_create_edate
string

End of order created date range as a timestamp

timestamp_close_bdate
string

Start of order closed date range as a timestamp

timestamp_close_edate
string

End of order closed date range as a timestamp

timestamp_ms
string

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/5784392456/payment' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Add a Payment

Add a payment to the order

References an existing transaction.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = payment_add
  • tendertype = TXN
Authorizations:
basic_authapikey_idapikey
path Parameters
order_id
required
string

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ttid
required
string

Transaction identifier

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "ttid": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN",
  • "id": "string"
}

Cancel a Payment

Cancels a cash or check payment associated with the order

A transaction that was applied to the order using a ttid cannot be canceled directly. It must be reversed which will automatically mark it as canceled in the order.

External payments, such as cash and check, that were made outside of TranSafe are removed from the order using this operation. It is the responsibility of the merchant to take any further action that is necessary when canceling a payment. For example, providing cash to the customer if a cash payment was accepted.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = payment_cancel
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of a payment for an order

order_id
required
string

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/order/20245528771333405/payment/758493245430' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "NOTRUN"
}

Get Payment Detail

Gets details for the specified payment

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = payments
Authorizations:
basic_authapikey_idapikey
path Parameters
id
required
string

Unique ID of a payment for an order

order_id
required
string

Unique ID of an order

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/payment/758493245430' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp_ms": "string",
  • "user": "string",
  • "order_id": "string",
  • "tendertype": "TXN",
  • "amount": "19.92",
  • "tip": "0.33",
  • "status": "PENDING",
  • "ttid": "string",
  • "timestamp": "string",
  • "cardtype": "VISA",
  • "last4": "string",
  • "cardholdername": "John Doe",
  • "checknum": "string",
  • "is_deleted": "yes"
}

Order Reports

Order reports allow reporting of not only orders but other systems that are utilized by orders. These reports offer insight into the use of orders to allow merchant to tailor their offerings, or meet other obligations (tip, and tax remittance).

Reports are about usage within orders. For example, the customer report allows determining how many, how often, and how much specific customers are spending.

Or the SKU activity report allows determining which SKUs are most or least popular.

Aging

Aging report for unpaid invoices grouped by customer

The resulting report will contain these headers:

customer_id, customer_display_name, current, 1-30, 31-60, 61-90,
91-120, 120+

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = aging
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string

Customer identifier

type
object
Enum: "ORDER" "QUICK" "INVOICE"
Example: type=ORDER,QUICK

Comma separated list of order types

Flag values (comma separated):

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/report/aging' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Customers

Customer summary

The resulting report will contain these headers:

customer_id, customer_display_name, count, total_amount

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = customersummary
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string

Customer identifier

order_id
string

Unique ID of an order

bdate
string

Start of date range

edate
string

End of date range

limit
string

Maximum number of rows to return

has_count
object
Enum: "yes" "no"
Example: has_count=yes

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/report/modifier?customer=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Item Discounts

Item discount summary

The resulting report will contain these headers:

discount_id, discount_name, usecase, category_id, category_name, count

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = itemdiscountsummary
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string

Order discount identifier

order_id
string

Unique ID of an order

bdate
string

Start of date range

edate
string

End of date range

limit
string

Maximum number of rows to return

has_count
object
Enum: "yes" "no"
Example: has_count=yes

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/report/discount/item?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Item Modifier Activity

Item Modifier activity

The resulting report will contain these headers:

modifier_id, modifier_name, modifierset_id, modifierset_name,
count

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = modifiersummary
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string

Order item modifier identifier

order_id
string

Unique ID of an order

bdate
string

Start of date range

edate
string

End of date range

limit
string

Maximum number of rows to return

has_count
object
Enum: "yes" "no"
Example: has_count=yes

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/report/modifier?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Order Discounts

Order discount summary

The resulting report will contain these headers:

discount_id, discount_name, usecase, category_id, category_name, count

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = orderdiscountsummary
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string

Order discount identifier

order_id
string

Unique ID of an order

bdate
string

Start of date range

edate
string

End of date range

limit
string

Maximum number of rows to return

has_count
object
Enum: "yes" "no"
Example: has_count=yes

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/report/discount/order?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Payments

Payment report grouped by user

The resulting report will contain these headers:

user, sale_amount, refund_amount

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = payments
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

order_in
string
tendertype
object
Enum: "TXN" "CASH" "CHECK"
Example: tendertype=TXN

Type of payment tender

Values:

  • TXN - TranSafe transaction
  • CASH - Cash
  • CHECK - Check
bdate
string

Start of date range

edate
string

End of date range

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/report/payment?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Product Activity

Product activity

The resulting report will contain these headers:

product_id, product_name, category_id, category_name, count

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = productsummary
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string

Unique ID of the product

order_id
string

Unique ID of an order

bdate
string

Start of date range

edate
string

End of date range

limit
string

Maximum number of rows to return

has_count
object
Enum: "yes" "no"
Example: has_count=yes

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/report/product?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

SKU Activity

SKU activity

The resulting report will contain these headers:

sku_id, sku_name, product_id, product_name, category_id,
category_name, count

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = skusummary
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string

Unique ID of the SKU

order_id
string

Unique ID of an order

bdate
string

Start of date range

edate
string

End of date range

limit
string

Maximum number of rows to return

has_count
object
Enum: "yes" "no"
Example: has_count=yes

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/report/sku?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Tax History

Tax history report

The resulting report will contain these headers:

taxrate_id, taxrate_name, order_id, timestamp, amount

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = taxhistory
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string

Unique ID of the tax rate

order_id
string

Unique ID of an order

bdate
string

Start of date range

edate
string

End of date range

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/report/tax/history?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Tax Summary

Tax summary report

The resulting report will contain these headers:

taxrate_id, taxrate_name, amount

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = taxsummary
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string

Unique ID of the tax rate

order_id
string

Unique ID of an order

bdate
string

Start of date range

edate
string

End of date range

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/report/tax?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Tips

Tip report grouped by user

The resulting report will contain these headers:

user, sale_tip, refund_tip

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = tip
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

order_in
string
tendertype
object
Enum: "TXN" "CASH" "CHECK"
Example: tendertype=TXN

Type of payment tender

Values:

  • TXN - TranSafe transaction
  • CASH - Cash
  • CHECK - Check
bdate
string

Start of date range

edate
string

End of date range

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/report/tip?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

User

User management

Accessing profiles

Users within the group will be able to access and process the profiles within the group they are in. Users can have a default profile set so they do not need to specify a profile with every transaction.

Additionally users can be locked to only allow processing with a specific profile. This allows a clerk to only process transactions for their work location while allowing someone like a floating manager to process at whichever store they happen to be at.

Change User Password

Change User Password

User's are able to change their own password provided they have the necessary permissions.

If changing another user's password, this can fail under the following conditions:

  • User whose password is being changed has greater permissions than the authenticated user
  • The RESET_PEER_PASSWD flag is not set

libmonetra KVS equivalent for endpoint

  • action_sys = user_passwd
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
id
string\d+

Conditional. User id of user to operate on, if not provided, user is required

Cannot be combined with:

  • user
user
string <= 128 characters

Conditional. Username of user to operate on, if not provided, id is required

Cannot be combined with:

  • id
pwd
string <= 256 characters

New password to set for user being edited

temporary
string
Enum: "yes" "no"

Whether the user's password is a temporary password

By default if changing another user's password, the password is temporary, meaning the user must change it immediately upon initial login. This may be set to no to make the password permanent, however this is only allowed if the user's password being modified is an UNATTENDED user. When changing a user's own password, it is always permanent and this flag is ignored.

Values:

  • yes - Password is temporary and required to be changed on first login
  • no - Password is not temporary and does not need to be changed on first login

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "user": "string",
  • "pwd": "string",
  • "temporary": "yes"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Delete User

Delete a user

Deleting a user can fail for the following conditions:

  • Cannot delete self
  • Cannot delete someone with greater perms than themselves

libmonetra KVS equivalent for endpoint

  • action_sys = user_del
Authorizations:
basic_authapikey_idapikey
query Parameters
id
string

Conditional. User id of user to operate on, if not provided, user is required

Cannot be combined with:

  • user
user
string

Conditional. Username of user to operate on, if not provided, id is required

Cannot be combined with:

  • id

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/user' \
  --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=' \
  -d '
    {
      "user": "james"
    }' \
  -H 'Content-Type: application/json; charset=utf-8'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

List Users

List users

The resulting report will contain these headers:

id, username, group_id, group_depth, status, flags, create_ts, upd_ts,
lastlogin_ts, pwchange_ts, login_fail_cnt, lock_ts, su_perms, sys_perms,
admin_perms, trans_perms, default_profile_id, name, mobilephone

status can be one of:

  • ACTIVE - good standing
  • DISABLED - administratively disabled
  • LOCKED - locked due to login failures

libmonetra KVS equivalent for endpoint

  • action_sys = user_list
Authorizations:
basic_authapikey_idapikey
query Parameters
id
string

Query a specific user id

Cannot be combined with:

  • user
user
string

Query a specific user by name

Cannot be combined with:

  • id
group_id
string

Query starting at a specific group id, if not specified, defaults to user's group id.

maxdepth
string

Maximum group depth to display

Default is unlimited. Specify 1 to see only self and children.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/user?user=james' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "report": {
    }
}

Edit User

Edits a user

If id is specified user can also be specified in order to change the username.

If editing self, cannot edit perms, or flags. Can edit other fields though.

libmonetra KVS equivalent for endpoint

  • action_sys = user_edit
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
id
string\d+

Conditional. User id of user to operate on, if not provided, user is required

Cannot be combined with:

  • user
user
string <= 128 characters

Conditional. Username of user to operate on, if not provided, id is required

Cannot be combined with:

  • id
default_profile_id
string\d+

Profile id of the default profile the user is assigned to use

So they can run transactions without specifying a profile.

If not specified, will auto-link to the profile at the same group level, if there is only one. If there are none or more than 1, will remain unlinked.

email
string <= 128 characters

email

flags
string
Enum: "UNATTENDED" "SELFVIEWONLY" "MFA" "ALLOW_UNLINKED_REFUND" "RESET_PEER_PASSWD"

Flag values (pipe separated):

  • UNATTENDED - Meant for system/application/integration accounts
  • SELFVIEWONLY - Cannot see anything about other users such as the users themselves nor any transactions other users have performed
  • MFA - The user is enabled for multifactor authentication. Cannot be enabled or disabled on a user unless the current user has the flag set, unless the group mandates MFA on users (in which case that takes precedence and cannot be disabled). Unattended users cannot have MFA enabled.
  • ALLOW_UNLINKED_REFUND - Allow refunds via key or card entry rather than requiring them be linked to a prior transaction. If this flag is not set, even when linked to a prior transaction it will ensure that the prior transaction is a SALE and the total amounts of the refunds for all linked never exceed the original total
  • RESET_PEER_PASSWD - The user is allowed to change the password of a peer that has less than or equal permissions
su_perms
string
Enum: "ALL" "IMPORTEXPORT" "MAINTENANCE" "P2PE_BDK_GENERATE" "P2PE_BDK_DEACTIVATE" "P2PE_BDK_LIST" "P2PE_BDK_EDIT" "P2PE_BDK_EXPORT" "P2PE_BDK_PRINT" "P2PE_BDK_KCV" "P2PE_DEVICE_PROVISION" "P2PE_DEVICE_DEACTIVATE" "P2PE_DEVICE_LIST" "P2PE_DEVICE_EDIT" "E2EE_KEY_GENERATE" "E2EE_KEY_EDIT" "E2EE_KEY_LIST" "E2EE_KEY_DEACTIVATE" "BIGBATCH_MANAGE" "BIGBATCH" "BIGBATCH_SETTLE" "PRODUCT_LICENSE" "PUSHNOTIFICATION" "TOKEN_EXPORT"

System restricted access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • IMPORTEXPORT - Allow importing and exporting database data
  • MAINTENANCE - Enable maintains mode to prevent transaction processing. Primarily used in conjunction with IMPORTEXPORT permission
  • P2PE_BDK_GENERATE - Generate a Base Derivation Key for P2PE device encryption
  • P2PE_BDK_DEACTIVATE - Deactivate a P2PE Base Derivation Key
  • P2PE_BDK_LIST - List P2PE Base Derivation Key
  • P2PE_BDK_EDIT - Edit a P2PE Base Derivation Key
  • P2PE_BDK_EXPORT - Export a P2PE Base Derivation Key for sharing with a Key Injection Facility
  • P2PE_BDK_PRINT - Print encrypted P2PE Base Derivation Key on a compatible printer. Only applies when keys are managed by an HSM
  • P2PE_BDK_KCV - P2PE Base Derivation Key Check Value
  • P2PE_DEVICE_PROVISION - Provision a device in TranSafe that uses P2PE. Provisioning is required for Validated P2PE, non validated P2PW TranSafe 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 TranSafe
  • 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 TranSafe
  • PUSHNOTIFICATION - Manage push notification endpoints
  • TOKEN_EXPORT - Store account export
sys_perms
string
Enum: "ALL" "V8_COMPLEX_EMULATION" "GETPERMS" "GROUP_ADD" "GROUP_EDIT" "GROUP_MOVE" "GROUP_DEL" "GROUP_LIST" "USER_ADD" "USER_EDIT" "USER_MOVE" "USER_DEL" "USER_LIST" "USER_ENABLE" "USER_DISABLE" "USER_PASSWD" "USER_UNLOCK" "PROFILE_ADD" "PROFILE_EDIT" "PROFILE_MOVE" "PROFILE_DEL" "PROFILE_LIST" "PROFILE_STATS" "PROFILE_ENABLE" "PROFILE_DISABLE" "ROUTE_ADD" "ROUTE_EDIT" "ROUTE_DEL" "ROUTE_LIST" "ROUTE_FIELDS" "CRON" "INFO" "SETLOGGING" "REGISTER_CLIENT" "SKYLINK_MANAGE" "APIKEYS" "MFA_GENERATE" "MFA_RESET" "SECURITY_QUESTIONS"

System access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • V8_COMPLEX_EMULATION - Allow TranSafe v8 protocol emulation. Allows equivalent v8 protocol actions to be used
  • GETPERMS - Get user permissions
  • GROUP_ADD - Create a group
  • GROUP_EDIT - Edit a group
  • GROUP_MOVE - Move a group to a different group
  • GROUP_DEL - Delete a group
  • GROUP_LIST - List groups
  • USER_ADD - Create a user
  • USER_EDIT - Edit a user
  • USER_MOVE - Move a user to a different group
  • USER_DEL - Delete a user
  • USER_LIST - List users
  • USER_ENABLE - Enable a user
  • USER_DISABLE - Disable a user
  • USER_PASSWD - Change a user's password. Includes self
  • USER_UNLOCK - Unlock a user
  • PROFILE_ADD - Add a profile
  • PROFILE_EDIT - Edit a profile
  • PROFILE_MOVE - Move a profile to a different group
  • PROFILE_DEL - Delete a profile
  • PROFILE_LIST - List profiles
  • PROFILE_STATS - Profile statics
  • PROFILE_ENABLE - Enable a profile
  • PROFILE_DISABLE - Disable a profile
  • ROUTE_ADD - Add a route
  • ROUTE_EDIT - Edit a route
  • ROUTE_DEL - Delete a route
  • ROUTE_LIST - List routes
  • ROUTE_FIELDS - Get processor specific fields for use with adding or editing a route
  • CRON - System task scheduler operations
  • INFO - TranSafe information
  • SETLOGGING - Start / Stop an in memory logging buffer
  • REGISTER_CLIENT - Registers use of a product with TranSafe
  • SKYLINK_MANAGE - Manage SkyLink product licences
  • APIKEYS - API key management
  • MFA_GENERATE - Enable or change MFA method
  • MFA_RESET - Reset MFA so it needs to be generated
  • SECURITY_QUESTIONS - User security questions
admin_perms
string
Enum: "REPORT_TRAN" "REPORT_TOTALS" "REPORT_CHARTDATA" "REPORT_QUEUE" "BATCH_CLEAR" "BATCH_SET" "BATCH_RESCIND" "BATCH_CLOSE" "TRAN_EDIT" "TRAN_NULLIFY" "TRAN_DETAIL" "TRAN_RECEIPT" "TRAN_IMPORT" "TRAN_EXPORT" "MERCH_INFO" "IMAGE_ADD" "IMAGE_DEL" "IMAGE_GET" "TOKEN_ADD" "TOKEN_EDIT" "TOKEN_DEL" "TOKEN_SCHEDULE" "TOKEN_LIST" "CUSTOMER_ADD" "CUSTOMER_EDIT" "CUSTOMER_DEL" "CUSTOMER_LIST" "TICKETREQUEST" "LEVEL3" "TRAN_EXPORT" "TRAN_IMPORT" "PRODMANAGE" "PRODLIST" "ORDERMANAGE" "ORDERLIST" "ORDERREPORT" "CARDDENYLIST" "P2PE" "STANDINKEY_GENERATE"

Administrative access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • REPORT_TRAN - Transaction and batch detail reports
  • REPORT_TOTALS - Transaction and batch total reports
  • REPORT_CHARTDATA - Card data breakdown for report views
  • REPORT_QUEUE - List queued transactions pending authorization
  • BATCH_CLEAR - Mark batch as settled without funding
  • BATCH_SET - Change batch number
  • BATCH_RESCIND - Unsettle a batch (can double charge customers)
  • BATCH_CLOSE - Close a batch so new transactions are not added but do not settle
  • TRAN_EDIT - Edit a transaction
  • TRAN_NULLIFY - Delete a previously-authorized transaction without any attempt to go online and remove an authorization hold. Similar to a void.
  • TRAN_DETAIL - Transaction details
  • TRAN_RECEIPT - Transaction receipts. Generating and sending receipts, and invoices
  • TRAN_IMPORT - Import transaction data from a different TranSafe into this instance of TranSafe
  • TRAN_EXPORT - Emport transaction data from TranSafe into a different instance of TranSafe
  • 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 TranSafe
  • TRAN_IMPORT - Import transaction data into TranSafe
  • PRODMANAGE - Manage products (sku, amount, etc) in the inventory system
  • PRODLIST - List product details in the inventory system
  • ORDERMANAGE - Manage orders and invoices
  • ORDERLIST - List orders and invoices
  • ORDERREPORT - Reports for orders and invoices
  • CARDDENYLIST - Manage the card deny list
  • P2PE - P2PE device management
  • STANDINKEY_GENERATE - Generate an encryption key used for encrypting account data as part of stand-in authorization
trans_perms
string
Enum: "VERIFYONLY" "SALE" "PREAUTH" "REVERSAL" "INCREMENTAL" "PREAUTHCOMPLETE" "FORCE" "CAPTURE" "VOID" "ADJUST" "REFUND" "ACTIVATE" "BALANCEINQ" "CASHOUT" "TOREVERSAL" "MERCHRETURN" "ISSUE" "TIP" "EBTFSSALE" "EBTFSRETURN" "EBTFSVOUCHER" "EBTFSBALANCE" "EBTCBSALE" "EBTCBCASH" "EBTCBBALANCE" "CHECKVERIFY" "CHECKCONVONLY" "CHECKCONVVRFY" "CHECKCONVGUAR" "CHECKCONVOVER" "CHECKIMAGEUPLOAD" "SETTLE" "SETTLERFR" "TERMLOAD" "INTERACMAC" "EMVCOMPLETE" "ALTPAYMENTINIT" "CARDTYPE"

Transaction access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • VERIFYONLY - Card verification
  • SALE - Purchase
  • PREAUTH - Authorization only (preauth)
  • REVERSAL - Reverse a transaction
  • INCREMENTAL - Incremental
  • PREAUTHCOMPLETE - Complete an authorization only (preauth) transaction
  • FORCE - Force purchase without online authorization
  • CAPTURE - Capture an un-captured transaction
  • VOID - Void a trasnaction
  • ADJUST - Adjust a transaction
  • REFUND - Refund
  • ACTIVATE - Activate a private label gift card
  • BALANCEINQ - Request account balance
  • CASHOUT - Remove all funds from a gift card in order to provide the customer with cash for the value
  • TOREVERSAL - Timeout reversal
  • MERCHRETURN - Merchandise return. Used by gift cards
  • ISSUE - Issue a gift card
  • TIP - Add a tip to a gift card
  • EBTFSSALE - Electronic Benefits Transfer food purchase
  • EBTFSRETURN - Electronic Benefits Transfer food refund
  • EBTFSVOUCHER - Electronic Benefits Transfer food voucher (paper food stamps) purchase
  • EBTFSBALANCE - Electronic Benefits Transfer food balance
  • EBTCBSALE - Electronic Benefits Transfer cash purchase
  • EBTCBCASH - Electronic Benefits Transfer cash withdrawal
  • EBTCBBALANCE - Electronic Benefits Transfer cash balance
  • CHECKVERIFY - Check verification only (without conversion)
  • CHECKCONVONLY - Check conversion only (without verification)
  • CHECKCONVVRFY - Check verification and conversion
  • CHECKCONVGUAR - Check conversation guarantee
  • CHECKCONVOVER - Convert a check with override
  • CHECKIMAGEUPLOAD - Upload check image
  • SETTLE - Settle
  • SETTLERFR - Request Settlement Status (limited processor support)
  • TERMLOAD - Terminal loading data
  • INTERACMAC - Interac MACing parameters
  • EMVCOMPLETE - EMV completion transaction
  • ALTPAYMENTINIT - Init an alternative payment method
  • CARDTYPE - Determine cardtype of presented account
name
string <= 128 characters

User's real name

phone_mobile
string <= 32 characters [-+0-9() .]*

Mobile phone

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "user": "string",
  • "default_profile_id": "string",
  • "email": "string",
  • "flags": "UNATTENDED",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "REPORT_TRAN",
  • "trans_perms": "VERIFYONLY",
  • "name": "string",
  • "phone_mobile": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Create User

Creates a user

Fail if there are explicitly specified perms and perms are greater than allowed.

libmonetra KVS equivalent for endpoint

  • action_sys = user_add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
user
required
string <= 128 characters

User name of user to add

pwd
required
string <= 256 characters

Password to set for user being added

group_id
string\d+

Group user should be added to. If not specified, defaults to the same group as the current user

default_profile_id
string\d+

Profile id of the default profile the user is assigned to use

So they can run transactions without specifying a profile.

If not specified, will auto-link to the profile at the same group level, if there is only one. If there are none or more than 1, will remain unlinked.

email
string <= 128 characters

email

flags
string
Enum: "UNATTENDED" "SELFVIEWONLY" "MFA" "ALLOW_UNLINKED_REFUND" "RESET_PEER_PASSWD"

Flag values (pipe separated):

  • UNATTENDED - Meant for system/application/integration accounts
  • SELFVIEWONLY - Cannot see anything about other users such as the users themselves nor any transactions other users have performed
  • MFA - The user is enabled for multifactor authentication. Cannot be enabled or disabled on a user unless the current user has the flag set, unless the group mandates MFA on users (in which case that takes precedence and cannot be disabled). Unattended users cannot have MFA enabled.
  • ALLOW_UNLINKED_REFUND - Allow refunds via key or card entry rather than requiring them be linked to a prior transaction. If this flag is not set, even when linked to a prior transaction it will ensure that the prior transaction is a SALE and the total amounts of the refunds for all linked never exceed the original total
  • RESET_PEER_PASSWD - The user is allowed to change the password of a peer that has less than or equal permissions
su_perms
string
Enum: "ALL" "IMPORTEXPORT" "MAINTENANCE" "P2PE_BDK_GENERATE" "P2PE_BDK_DEACTIVATE" "P2PE_BDK_LIST" "P2PE_BDK_EDIT" "P2PE_BDK_EXPORT" "P2PE_BDK_PRINT" "P2PE_BDK_KCV" "P2PE_DEVICE_PROVISION" "P2PE_DEVICE_DEACTIVATE" "P2PE_DEVICE_LIST" "P2PE_DEVICE_EDIT" "E2EE_KEY_GENERATE" "E2EE_KEY_EDIT" "E2EE_KEY_LIST" "E2EE_KEY_DEACTIVATE" "BIGBATCH_MANAGE" "BIGBATCH" "BIGBATCH_SETTLE" "PRODUCT_LICENSE" "PUSHNOTIFICATION" "TOKEN_EXPORT"

System restricted access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • IMPORTEXPORT - Allow importing and exporting database data
  • MAINTENANCE - Enable maintains mode to prevent transaction processing. Primarily used in conjunction with IMPORTEXPORT permission
  • P2PE_BDK_GENERATE - Generate a Base Derivation Key for P2PE device encryption
  • P2PE_BDK_DEACTIVATE - Deactivate a P2PE Base Derivation Key
  • P2PE_BDK_LIST - List P2PE Base Derivation Key
  • P2PE_BDK_EDIT - Edit a P2PE Base Derivation Key
  • P2PE_BDK_EXPORT - Export a P2PE Base Derivation Key for sharing with a Key Injection Facility
  • P2PE_BDK_PRINT - Print encrypted P2PE Base Derivation Key on a compatible printer. Only applies when keys are managed by an HSM
  • P2PE_BDK_KCV - P2PE Base Derivation Key Check Value
  • P2PE_DEVICE_PROVISION - Provision a device in TranSafe that uses P2PE. Provisioning is required for Validated P2PE, non validated P2PW TranSafe 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 TranSafe
  • 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 TranSafe
  • PUSHNOTIFICATION - Manage push notification endpoints
  • TOKEN_EXPORT - Store account export
sys_perms
string
Enum: "ALL" "V8_COMPLEX_EMULATION" "GETPERMS" "GROUP_ADD" "GROUP_EDIT" "GROUP_MOVE" "GROUP_DEL" "GROUP_LIST" "USER_ADD" "USER_EDIT" "USER_MOVE" "USER_DEL" "USER_LIST" "USER_ENABLE" "USER_DISABLE" "USER_PASSWD" "USER_UNLOCK" "PROFILE_ADD" "PROFILE_EDIT" "PROFILE_MOVE" "PROFILE_DEL" "PROFILE_LIST" "PROFILE_STATS" "PROFILE_ENABLE" "PROFILE_DISABLE" "ROUTE_ADD" "ROUTE_EDIT" "ROUTE_DEL" "ROUTE_LIST" "ROUTE_FIELDS" "CRON" "INFO" "SETLOGGING" "REGISTER_CLIENT" "SKYLINK_MANAGE" "APIKEYS" "MFA_GENERATE" "MFA_RESET" "SECURITY_QUESTIONS"

System access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • V8_COMPLEX_EMULATION - Allow TranSafe v8 protocol emulation. Allows equivalent v8 protocol actions to be used
  • GETPERMS - Get user permissions
  • GROUP_ADD - Create a group
  • GROUP_EDIT - Edit a group
  • GROUP_MOVE - Move a group to a different group
  • GROUP_DEL - Delete a group
  • GROUP_LIST - List groups
  • USER_ADD - Create a user
  • USER_EDIT - Edit a user
  • USER_MOVE - Move a user to a different group
  • USER_DEL - Delete a user
  • USER_LIST - List users
  • USER_ENABLE - Enable a user
  • USER_DISABLE - Disable a user
  • USER_PASSWD - Change a user's password. Includes self
  • USER_UNLOCK - Unlock a user
  • PROFILE_ADD - Add a profile
  • PROFILE_EDIT - Edit a profile
  • PROFILE_MOVE - Move a profile to a different group
  • PROFILE_DEL - Delete a profile
  • PROFILE_LIST - List profiles
  • PROFILE_STATS - Profile statics
  • PROFILE_ENABLE - Enable a profile
  • PROFILE_DISABLE - Disable a profile
  • ROUTE_ADD - Add a route
  • ROUTE_EDIT - Edit a route
  • ROUTE_DEL - Delete a route
  • ROUTE_LIST - List routes
  • ROUTE_FIELDS - Get processor specific fields for use with adding or editing a route
  • CRON - System task scheduler operations
  • INFO - TranSafe information
  • SETLOGGING - Start / Stop an in memory logging buffer
  • REGISTER_CLIENT - Registers use of a product with TranSafe
  • SKYLINK_MANAGE - Manage SkyLink product licences
  • APIKEYS - API key management
  • MFA_GENERATE - Enable or change MFA method
  • MFA_RESET - Reset MFA so it needs to be generated
  • SECURITY_QUESTIONS - User security questions
admin_perms
string
Enum: "REPORT_TRAN" "REPORT_TOTALS" "REPORT_CHARTDATA" "REPORT_QUEUE" "BATCH_CLEAR" "BATCH_SET" "BATCH_RESCIND" "BATCH_CLOSE" "TRAN_EDIT" "TRAN_NULLIFY" "TRAN_DETAIL" "TRAN_RECEIPT" "TRAN_IMPORT" "TRAN_EXPORT" "MERCH_INFO" "IMAGE_ADD" "IMAGE_DEL" "IMAGE_GET" "TOKEN_ADD" "TOKEN_EDIT" "TOKEN_DEL" "TOKEN_SCHEDULE" "TOKEN_LIST" "CUSTOMER_ADD" "CUSTOMER_EDIT" "CUSTOMER_DEL" "CUSTOMER_LIST" "TICKETREQUEST" "LEVEL3" "TRAN_EXPORT" "TRAN_IMPORT" "PRODMANAGE" "PRODLIST" "ORDERMANAGE" "ORDERLIST" "ORDERREPORT" "CARDDENYLIST" "P2PE" "STANDINKEY_GENERATE"

Administrative access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • REPORT_TRAN - Transaction and batch detail reports
  • REPORT_TOTALS - Transaction and batch total reports
  • REPORT_CHARTDATA - Card data breakdown for report views
  • REPORT_QUEUE - List queued transactions pending authorization
  • BATCH_CLEAR - Mark batch as settled without funding
  • BATCH_SET - Change batch number
  • BATCH_RESCIND - Unsettle a batch (can double charge customers)
  • BATCH_CLOSE - Close a batch so new transactions are not added but do not settle
  • TRAN_EDIT - Edit a transaction
  • TRAN_NULLIFY - Delete a previously-authorized transaction without any attempt to go online and remove an authorization hold. Similar to a void.
  • TRAN_DETAIL - Transaction details
  • TRAN_RECEIPT - Transaction receipts. Generating and sending receipts, and invoices
  • TRAN_IMPORT - Import transaction data from a different TranSafe into this instance of TranSafe
  • TRAN_EXPORT - Emport transaction data from TranSafe into a different instance of TranSafe
  • 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 TranSafe
  • TRAN_IMPORT - Import transaction data into TranSafe
  • PRODMANAGE - Manage products (sku, amount, etc) in the inventory system
  • PRODLIST - List product details in the inventory system
  • ORDERMANAGE - Manage orders and invoices
  • ORDERLIST - List orders and invoices
  • ORDERREPORT - Reports for orders and invoices
  • CARDDENYLIST - Manage the card deny list
  • P2PE - P2PE device management
  • STANDINKEY_GENERATE - Generate an encryption key used for encrypting account data as part of stand-in authorization
trans_perms
string
Enum: "VERIFYONLY" "SALE" "PREAUTH" "REVERSAL" "INCREMENTAL" "PREAUTHCOMPLETE" "FORCE" "CAPTURE" "VOID" "ADJUST" "REFUND" "ACTIVATE" "BALANCEINQ" "CASHOUT" "TOREVERSAL" "MERCHRETURN" "ISSUE" "TIP" "EBTFSSALE" "EBTFSRETURN" "EBTFSVOUCHER" "EBTFSBALANCE" "EBTCBSALE" "EBTCBCASH" "EBTCBBALANCE" "CHECKVERIFY" "CHECKCONVONLY" "CHECKCONVVRFY" "CHECKCONVGUAR" "CHECKCONVOVER" "CHECKIMAGEUPLOAD" "SETTLE" "SETTLERFR" "TERMLOAD" "INTERACMAC" "EMVCOMPLETE" "ALTPAYMENTINIT" "CARDTYPE"

Transaction access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • VERIFYONLY - Card verification
  • SALE - Purchase
  • PREAUTH - Authorization only (preauth)
  • REVERSAL - Reverse a transaction
  • INCREMENTAL - Incremental
  • PREAUTHCOMPLETE - Complete an authorization only (preauth) transaction
  • FORCE - Force purchase without online authorization
  • CAPTURE - Capture an un-captured transaction
  • VOID - Void a trasnaction
  • ADJUST - Adjust a transaction
  • REFUND - Refund
  • ACTIVATE - Activate a private label gift card
  • BALANCEINQ - Request account balance
  • CASHOUT - Remove all funds from a gift card in order to provide the customer with cash for the value
  • TOREVERSAL - Timeout reversal
  • MERCHRETURN - Merchandise return. Used by gift cards
  • ISSUE - Issue a gift card
  • TIP - Add a tip to a gift card
  • EBTFSSALE - Electronic Benefits Transfer food purchase
  • EBTFSRETURN - Electronic Benefits Transfer food refund
  • EBTFSVOUCHER - Electronic Benefits Transfer food voucher (paper food stamps) purchase
  • EBTFSBALANCE - Electronic Benefits Transfer food balance
  • EBTCBSALE - Electronic Benefits Transfer cash purchase
  • EBTCBCASH - Electronic Benefits Transfer cash withdrawal
  • EBTCBBALANCE - Electronic Benefits Transfer cash balance
  • CHECKVERIFY - Check verification only (without conversion)
  • CHECKCONVONLY - Check conversion only (without verification)
  • CHECKCONVVRFY - Check verification and conversion
  • CHECKCONVGUAR - Check conversation guarantee
  • CHECKCONVOVER - Convert a check with override
  • CHECKIMAGEUPLOAD - Upload check image
  • SETTLE - Settle
  • SETTLERFR - Request Settlement Status (limited processor support)
  • TERMLOAD - Terminal loading data
  • INTERACMAC - Interac MACing parameters
  • EMVCOMPLETE - EMV completion transaction
  • ALTPAYMENTINIT - Init an alternative payment method
  • CARDTYPE - Determine cardtype of presented account
name
string <= 128 characters

User's real name

phone_mobile
string <= 32 characters [-+0-9() .]*

Mobile phone

Responses

Request samples

Content type
application/json
{
  • "user": "string",
  • "pwd": "string",
  • "group_id": "string",
  • "default_profile_id": "string",
  • "email": "string",
  • "flags": "UNATTENDED",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "REPORT_TRAN",
  • "trans_perms": "VERIFYONLY",
  • "name": "string",
  • "phone_mobile": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "string"
}

Disable User

Disable User that is enabled

Will return failure if user is disabled or locked.

Admistratively disables a user. The user cannot be used until enabled. This will not expire and the user must be manually enabled.

libmonetra KVS equivalent for endpoint

  • action_sys = user_disable
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
id
string\d+

Conditional. User id of user to operate on, if not provided, user is required

Cannot be combined with:

  • user
user
string <= 128 characters

Conditional. Username of user to operate on, if not provided, id is required

Cannot be combined with:

  • id

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "user": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Enable User

Enable User that was disabled

Will return failure if user is not currently disabled.

Admistratively enable a user. The user must have been previously disabled. Locked user's are not considered disabled and should be unlocked using the unlock action.

libmonetra KVS equivalent for endpoint

  • action_sys = user_enable
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
id
string\d+

Conditional. User id of user to operate on, if not provided, user is required

Cannot be combined with:

  • user
user
string <= 128 characters

Conditional. Username of user to operate on, if not provided, id is required

Cannot be combined with:

  • id

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "user": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Permissions

Gets the user's permissions

This is the permissions for the authenticating user. In order to get permissions for a specific user, use the "List Users" report filtering on the user in question.

This action should be used for password / API key verification if needing to verify before further processing take place.

libmonetra KVS equivalent for endpoint

  • action_sys = getperms
Authorizations:
basic_authapikey_idapikey

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/user/permissions' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "pass_expire_secs": "string",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "REPORT_TRAN",
  • "trans_perms": "VERIFYONLY"
}

Unlock User

Unlock a locked user

Will return failure if user not locked.

Users are automatically locked after too many login failures. Locking is temporary and will expire automatically after a set amount of time. The unlock action unlocks the user without having to wait for the lock time period to elapse.

libmonetra KVS equivalent for endpoint

  • action_sys = user_unlock
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
id
string\d+

Conditional. User id of user to operate on, if not provided, user is required

Cannot be combined with:

  • user
user
string <= 128 characters

Conditional. Username of user to operate on, if not provided, id is required

Cannot be combined with:

  • id

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "user": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

MFA

User multi factor authentication management

Multi Factor Authentication (MFA) is supported using a variety of methods. See "Generating" for more information about each method. Also see the "MFA Code" section under the main "Authentication" information.

MFA can be enabled for any user at any time. Groups can mandate that all users within the group and in any subgroup must enable MFA.

This section is for managing MFA not generating an MFA code. MFA code generation is an out of band process.

Generate Multi Factor Authentication

Generate (or replace) the existing Multi Factor Authentication mechanism

This requires the full username and password, an APIKey cannot be used to call this function. If MFA is already set up on the account, the existing MFA code must also be provided.

phone_mobile or email can be provided if the corresponding type is chosen to explictly set where the code should be sent. It is not required if the user account already has these configured.

When an action is attempted that requires MFA but an MFA code is not provided an msoft_code=ACCT_MFA_REQUIRED will be returned. If sms or email codes methods were chosen, an sms or email will automatically be trigered to send the MFA code to the user.

If the user does not already have the MFA user flag, it will be automatically added to the account.

libmonetra KVS equivalent for endpoint

  • action_sys = mfa_generate
  • mfa_generate = totp
Authorizations:
basic_auth
Request Body schema: application/json
type
required
string
Enum: "TOTP_APP" "TOTP_SMS" "TOTP_EMAIL"

Values:

  • TOTP_APP - Using external application, such as Google Authenticator, Authy, or Last Pass Authenticator
  • TOTP_SMS - Send TOTP-based text messages with 6 digit code to phone_mobile configured on user account
  • TOTP_EMAIL - TOTP-based email messages with 6 digit code to email configured on user account
phone_mobile
string <= 32 characters [-+0-9() .]*

Mobile phone

email
string <= 128 characters

email

Responses

Request samples

Content type
application/json
{
  • "type": "TOTP_APP",
  • "phone_mobile": "string",
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "key": "string"
}

Generate Multi Factor Authentication Cookie

MFA timed bypass with authentication cookie

It is desirable for many web interfaces to not constantly prompt for MFA, but instead let a user choose that they are on a private trusted device and to store a cookie on the system for a duration that can be used in place of MFA.

A real MFA code is required to request a cookie that will be valid for the desired duration, specified in seconds. The maximum duration allowed to be specified is 30 days (2592000s), minimum is 15 minutes (900s), though periods less than 24hrs may be a questionable use.

The cookie will need to be presented instead of the MFA code, and will be passed in the same API field of mfa_code, just as the TOTP code normally is.

This is NOT an API key, it still requires the valid username and password to be specified when using it. This is purely an MFA code.

A single user account may have up to 5 generated cookies that are valid at any time, if a new one is requested and the limit is exceeded, it will replace the old one. (multiples are allowed to allow logins from multiple devices or browsers).

The cookie should be stored in a browser cookie for web UIs (perhaps encrypted, but implementation dependent)

Generally, upon logging into a web system, an integrator should generate a temporary auto-extending api key. The cookie can be used for this purpose.

If the cookie is expired, the user will only get the msoft_code=ACCT_MFA_INVALID response and it will be treated as an error so a validity period should also be tracked by the cookie so as to not cause authentication failures that could lead to blacklisting.

libmonetra KVS equivalent for endpoint

  • action_sys = mfa_generate
  • mfa_generate = cookie
Authorizations:
basic_auth
Request Body schema: application/json
expire_s
required
string\d+

Number of seconds this cookie is requested to be valid for

The valid range is 15 minutes to 30 days (900s - 2592000s). Generally an expiration period will be 24hrs or more.

Responses

Request samples

Content type
application/json
{
  • "expire_s": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "key": "string",
  • "expire_ts": "string"
}

Reset Multi Factor Authentication

Reset Multi Factor Authentication so it needs to be generated

MFA will remain enabled requiring the user to generate an MFA key.

user or id must be provided to reset the MFA for the specified user. MFA self reset is not allowed. Self reset requres the user to utilize the 3-step self reset process.

Subsequent operations will return the msoft_code=MFA_GENERATE indicating MFA needs to be generated.

libmonetra KVS equivalent for endpoint

  • action_sys = mfa_reset
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
id
string\d+

Conditional. User id of user to operate on, if not provided, user will be used if it was provided

Cannot be combined with:

  • user
user
string <= 128 characters

Conditional. Username of user to operate on, if not provided, id will be used if it was provided

Cannot be combined with:

  • id

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "user": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Self Reset

User self password and MFA reset management. Users are able to initiate a reset request for their password and MFA tokens when they've forgotten one or the other.

In order to do this, they must have security questions on file and know the answers. They also must have a phone number for SMS or an email on file because part of the process involves sending them a verification code.

The reset processes are multi-step with, as indicated, out of band verification of the user.

List Security Questions

List security questions

libmonetra KVS equivalent for endpoint

  • action_sys = security_questions
  • security_questions = list
Authorizations:
basic_authapikey_idapikey

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/user/security_questions' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "question1": "string",
  • "question2": "string",
  • "question3": "string",
  • "created_ts": "string",
  • "upd_ts": "string"
}

Edit Security Questions

Edit security questions

libmonetra KVS equivalent for endpoint

  • action_sys = security_questions
  • security_questions = edit
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
question1
string [ 3 .. 128 ] characters .{3,128}

Security question

question2
string [ 3 .. 128 ] characters .{3,128}

Security question

question3
string [ 3 .. 128 ] characters .{3,128}

Security question

answer1
string

Security answer

answer2
string

Security answer

answer3
string

Security answer

Responses

Request samples

Content type
application/json
{
  • "question1": "string",
  • "question2": "string",
  • "question3": "string",
  • "answer1": "string",
  • "answer2": "string",
  • "answer3": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Create Security Questions

Create user's security questions

  • Operates only on the logged-in user
  • User must be a normal attended user
  • Unattended users are not allowed
  • Questions may not be duplicates nor contain the username
  • Answers may not be duplicates nor contain the username or password, and must be at least 3 alpha-numeric characters (excluding whitespace and punctuation)

libmonetra KVS equivalent for endpoint

  • action_sys = security_questions
  • security_questions = add
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
question1
required
string [ 3 .. 128 ] characters .{3,128}

Security question

question2
required
string [ 3 .. 128 ] characters .{3,128}

Security question

question3
required
string [ 3 .. 128 ] characters .{3,128}

Security question

answer1
required
string

Security answer

answer2
required
string

Security answer

answer3
required
string

Security answer

Responses

Request samples

Content type
application/json
{
  • "question1": "string",
  • "question2": "string",
  • "question3": "string",
  • "answer1": "string",
  • "answer2": "string",
  • "answer3": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Self MFA Reset - Step 1: Code

User self-reset of multi factor authentication

This is a multi-step process consisting of several steps.

  1. code
  2. security_questions
  3. reset

This relies on a one-time use verification code to initiate the reset attempt which will be emailed or sent via SMS to the user. This code is then entered into a follow-up request to retrieve the user's security questions. The final follow-up will pass the same verification code and all 3 security question answers.

The reset operation may be initiated at most 3 times in a 24hr period. The emailed or sms code may only be used once for each step of the reset operation.

The user is required to authenticate using their username and mfa.

If the user does not have security questions configured this action will fail with an error. Also, the user must have an email or phone number capable of receiving sms messages on file (based on the method chosen for receiving the security code).

libmonetra KVS equivalent for endpoint

  • action_sys = auth_reset
  • auth_reset = mfa
  • phase = code
Authorizations:
basic_auth
query Parameters
method
required
object
Enum: "EMAIL" "SMS"
Example: method=EMAIL

Values:

  • EMAIL - Send reset code by email
  • SMS - send reset code by sms

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/user/self/reset/mfa/code?reset_method=email' --basic -u 'test_retail:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Self MFA Reset - Step 2: Security Questions

Retrieve security questions for a user for self password reset

libmonetra KVS equivalent for endpoint

  • action_sys = auth_reset
  • auth_reset = mfa
  • phase = security_questions
Authorizations:
basic_auth
Request Body schema: application/json
reset_code
required
string

Self reset authentication code sent to the user via email or sms

Responses

Request samples

Content type
application/json
{
  • "reset_code": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "question1": "string",
  • "question2": "string",
  • "question3": "string"
}

Self MFA Reset - Step 3: Reset

Request the finalization of the self MFA reset operation

libmonetra KVS equivalent for endpoint

  • action_sys = auth_reset
  • auth_reset = mfa
  • phase = reset
Authorizations:
basic_auth
Request Body schema: application/json
reset_code
required
string

Self reset authentication code sent to the user via email or sms

answer1
required
string

Security answer

answer2
required
string

Security answer

answer3
required
string

Security answer

Responses

Request samples

Content type
application/json
{
  • "reset_code": "string",
  • "answer1": "string",
  • "answer2": "string",
  • "answer3": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Self Password Reset - Step 1: Code

User self-reset of password

This is a multi-step process consisting of several steps.

  1. code
  2. security_questions
  3. reset

This relies on a one-time use verification code to initiate the reset attempt which will be emailed or sent via SMS to the user. This code is then entered into a follow-up request to retrieve the user's security questions and an indicator stating if the user has MFA enabled and configured. The final follow-up will pass the same verification code, all 3 security question answers, and possibly the mfa_code if the account has MFA enabled.

The reset operation may be initiated at most 3 times in a 24hr period. The emailed or sms code may only be used once for each step of the reset operation.

Password resets require the username of the user requesting the reset. The user's password is not used for authentication in any of the three steps. For ReST neither API Key or Basic authentication is used. Instead the authentication parameters are passed in the request itself per the requirements of each step.

If the user does not have security questions configured this action will fail silently without error. Also, the user must have an email or phone number capable of receiving sms messages on file (based on the method chosen for receiving the security code).

libmonetra KVS equivalent for endpoint

  • action_sys = auth_reset
  • auth_reset = password
  • phase = code
Authorizations:
None
query Parameters
username
required
string

The username to perform a reset operation on

method
required
object
Enum: "EMAIL" "SMS"
Example: method=EMAIL

Values:

  • EMAIL - Send reset code by email
  • SMS - send reset code by sms

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/user/self/reset/password/code?username=user1&reset_method=email'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Self Password Reset - Step 2: Security Questions

Retrieve security questions for a user for self password reset

libmonetra KVS equivalent for endpoint

  • action_sys = auth_reset
  • auth_reset = password
  • phase = security_questions
Authorizations:
None
Request Body schema: application/json
username
required
string

The username to perform a reset operation on

reset_code
required
string

Self reset authentication code sent to the user via email or sms

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "reset_code": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "question1": "string",
  • "question2": "string",
  • "question3": "string",
  • "mfa_enabled": "yes"
}

Self Password Reset - Step 3: Reset

Request the finalization of the self password reset operation

libmonetra KVS equivalent for endpoint

  • action_sys = auth_reset
  • auth_reset = password
  • phase = reset
Authorizations:
None
Request Body schema: application/json
username
required
string

The username to perform a reset operation on

reset_code
required
string

Self reset authentication code sent to the user via email or sms

answer1
required
string

Security answer

answer2
required
string

Security answer

answer3
required
string

Security answer

pwd
required
string <= 256 characters

Password

mfa_code
required
string

If mfa_enabled was true, then the current mfa code (either from APP, EMAIL or SMS). Cannot be an MFA cookie

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "reset_code": "string",
  • "answer1": "string",
  • "answer2": "string",
  • "answer3": "string",
  • "pwd": "string",
  • "mfa_code": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

API Keys

API keys are used to provide an alternative authentication method for users and Point of Sale (POS) systems. This will allow a user to disassociate their username and password from authentication.

API keys are composed of two parts. A public key id and a private key secret. The key secret must be protected.

API keys can also be created specifically for profiles and are intended for use by POS systems that use external user management. A profile API key has functionality only allowing payment transactions. Other operations are restricted.

Profile API keys allow a POS or other system to not be linked to a user for processing transactions. That way if the user is disabled or removed the system will continue to operate.

Whereas a user API key can be created with any permissions already afforded to the user. It is possible to create user API keys with further lower permissions than the user currently has.

API keys can be configured for limited duration, after which the specific key will no longer function. There is also an EXTEND_ON_USE flag which can extend the life of the key on use.

Some intended uses for API keys:

iFrame

The iFrame currently uses HMAC authentication to verify the request is being generated by a valid user. A profile API key can be generated and used instead of a username and password for authentication.

POS

A POS system with external user management can be configured to use a profile API key to unlink the system from a specific user. The POS will be able to process transactions without having an "unattended" user that needs a password stored somewhere.

Web Interface and Mobile Apps

One way a web interface or mobile app could operate is by having the user login with their username and password, then request an API key representing the user. The integration would not store the username and password. Instead it would store the API key and further operations would be performed using the API key. An expiration combined with the EXTEND_ON_USE flag is recommended for this scenario.

Remove API Key

Deletes an API Key

libmonetra KVS equivalent for endpoint

  • action_sys = apikeys
  • apikeys = del
Authorizations:
basic_authapikey_idapikey
path Parameters
apikey_id
required
string

API key id

Used in conjunction with apikey_secret

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/apikey/U123' --basic -u 'test_retail:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

API Key Detail

Get API Keys Details

libmonetra KVS equivalent for endpoint

  • action_sys = apikeys
  • apikeys = list
Authorizations:
basic_authapikey_idapikey
path Parameters
apikey_id
required
string

API key id

Used in conjunction with apikey_secret

query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/apikey/U123' --basic -u 'test_retail:publ1ct3st'

Response samples

Content type
application/json
{
  • "apikey_id": "string",
  • "type": "user",
  • "group_id": "string",
  • "name": "string",
  • "user_id": "string",
  • "profile_id": "string",
  • "flags": "EXTEND_ON_USE",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "REPORT_TRAN",
  • "trans_perms": "VERIFYONLY",
  • "created_uid": "string",
  • "created_ts": "string",
  • "last_used_ts": "string",
  • "expire_ts": "string",
  • "extend_sec": "string",
  • "descr": "string"
}

List API Keys

List API Keys

The resulting report will contain these headers:

apikey_id, type, group_id, name, user_id, profile_id, flags, su_perms, sys_perms,
admin_perms, trans_perms, created_uid, created_ts, last_used_ts, expire_ts,
extend_sec, descr

libmonetra KVS equivalent for endpoint

  • action_sys = apikeys
  • apikeys = list
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

user_id
string

User identifier

group_id
string

Group identifier

name
string

API Key name

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/apikey' --basic -u 'test_retail:publ1ct3st'

Response samples

Content type
application/json
{
  • "report": {
    }
}

Create API Key

Creates an API Key

Up to 100 API keys can be created per user and per profile

libmonetra KVS equivalent for endpoint

  • action_sys = apikeys
  • apikeys = add
Authorizations:
basic_auth
Request Body schema: application/json
type
required
string
Enum: "user" "profile"

Type of API Key

Values:

  • user - Key represents a user. Uses the current user that is authenticated
  • profile - key represents a profile. Uses the profile_id specified, or if none, the defaultprofile id for the current user.
name
required
string <= 256 characters

API Key name

descr
string <= 128 characters

Description of the key and its intended use

flags
string
Enum: "EXTEND_ON_USE" "ALLOW_UNLINKED_REFUNDS"

flags controlling behavior

Values:

  • EXTEND_ON_USE - On use of the key, it's expiration will be extended. Expiration of the key will become now plus the value of expire_sec provided during key creation.
  • ALLOW_UNLINKED_REFUNDS - Allow the API key to perform unlinked refunds. Necessary when generating a Profile API Key if a profile key is intended to issue unlinked refunds. The user creating the key is required to have the ALLOW_UNLINKED_REFUND user flag set in order to enable this API key flag.
su_perms
string
Enum: "ALL" "IMPORTEXPORT" "MAINTENANCE" "P2PE_BDK_GENERATE" "P2PE_BDK_DEACTIVATE" "P2PE_BDK_LIST" "P2PE_BDK_EDIT" "P2PE_BDK_EXPORT" "P2PE_BDK_PRINT" "P2PE_BDK_KCV" "P2PE_DEVICE_PROVISION" "P2PE_DEVICE_DEACTIVATE" "P2PE_DEVICE_LIST" "P2PE_DEVICE_EDIT" "E2EE_KEY_GENERATE" "E2EE_KEY_EDIT" "E2EE_KEY_LIST" "E2EE_KEY_DEACTIVATE" "BIGBATCH_MANAGE" "BIGBATCH" "BIGBATCH_SETTLE" "PRODUCT_LICENSE" "PUSHNOTIFICATION" "TOKEN_EXPORT"

System restricted access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • IMPORTEXPORT - Allow importing and exporting database data
  • MAINTENANCE - Enable maintains mode to prevent transaction processing. Primarily used in conjunction with IMPORTEXPORT permission
  • P2PE_BDK_GENERATE - Generate a Base Derivation Key for P2PE device encryption
  • P2PE_BDK_DEACTIVATE - Deactivate a P2PE Base Derivation Key
  • P2PE_BDK_LIST - List P2PE Base Derivation Key
  • P2PE_BDK_EDIT - Edit a P2PE Base Derivation Key
  • P2PE_BDK_EXPORT - Export a P2PE Base Derivation Key for sharing with a Key Injection Facility
  • P2PE_BDK_PRINT - Print encrypted P2PE Base Derivation Key on a compatible printer. Only applies when keys are managed by an HSM
  • P2PE_BDK_KCV - P2PE Base Derivation Key Check Value
  • P2PE_DEVICE_PROVISION - Provision a device in TranSafe that uses P2PE. Provisioning is required for Validated P2PE, non validated P2PW TranSafe 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 TranSafe
  • 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 TranSafe
  • PUSHNOTIFICATION - Manage push notification endpoints
  • TOKEN_EXPORT - Store account export
sys_perms
string
Enum: "ALL" "V8_COMPLEX_EMULATION" "GETPERMS" "GROUP_ADD" "GROUP_EDIT" "GROUP_MOVE" "GROUP_DEL" "GROUP_LIST" "USER_ADD" "USER_EDIT" "USER_MOVE" "USER_DEL" "USER_LIST" "USER_ENABLE" "USER_DISABLE" "USER_PASSWD" "USER_UNLOCK" "PROFILE_ADD" "PROFILE_EDIT" "PROFILE_MOVE" "PROFILE_DEL" "PROFILE_LIST" "PROFILE_STATS" "PROFILE_ENABLE" "PROFILE_DISABLE" "ROUTE_ADD" "ROUTE_EDIT" "ROUTE_DEL" "ROUTE_LIST" "ROUTE_FIELDS" "CRON" "INFO" "SETLOGGING" "REGISTER_CLIENT" "SKYLINK_MANAGE" "APIKEYS" "MFA_GENERATE" "MFA_RESET" "SECURITY_QUESTIONS"

System access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • V8_COMPLEX_EMULATION - Allow TranSafe v8 protocol emulation. Allows equivalent v8 protocol actions to be used
  • GETPERMS - Get user permissions
  • GROUP_ADD - Create a group
  • GROUP_EDIT - Edit a group
  • GROUP_MOVE - Move a group to a different group
  • GROUP_DEL - Delete a group
  • GROUP_LIST - List groups
  • USER_ADD - Create a user
  • USER_EDIT - Edit a user
  • USER_MOVE - Move a user to a different group
  • USER_DEL - Delete a user
  • USER_LIST - List users
  • USER_ENABLE - Enable a user
  • USER_DISABLE - Disable a user
  • USER_PASSWD - Change a user's password. Includes self
  • USER_UNLOCK - Unlock a user
  • PROFILE_ADD - Add a profile
  • PROFILE_EDIT - Edit a profile
  • PROFILE_MOVE - Move a profile to a different group
  • PROFILE_DEL - Delete a profile
  • PROFILE_LIST - List profiles
  • PROFILE_STATS - Profile statics
  • PROFILE_ENABLE - Enable a profile
  • PROFILE_DISABLE - Disable a profile
  • ROUTE_ADD - Add a route
  • ROUTE_EDIT - Edit a route
  • ROUTE_DEL - Delete a route
  • ROUTE_LIST - List routes
  • ROUTE_FIELDS - Get processor specific fields for use with adding or editing a route
  • CRON - System task scheduler operations
  • INFO - TranSafe information
  • SETLOGGING - Start / Stop an in memory logging buffer
  • REGISTER_CLIENT - Registers use of a product with TranSafe
  • SKYLINK_MANAGE - Manage SkyLink product licences
  • APIKEYS - API key management
  • MFA_GENERATE - Enable or change MFA method
  • MFA_RESET - Reset MFA so it needs to be generated
  • SECURITY_QUESTIONS - User security questions
admin_perms
string
Enum: "REPORT_TRAN" "REPORT_TOTALS" "REPORT_CHARTDATA" "REPORT_QUEUE" "BATCH_CLEAR" "BATCH_SET" "BATCH_RESCIND" "BATCH_CLOSE" "TRAN_EDIT" "TRAN_NULLIFY" "TRAN_DETAIL" "TRAN_RECEIPT" "TRAN_IMPORT" "TRAN_EXPORT" "MERCH_INFO" "IMAGE_ADD" "IMAGE_DEL" "IMAGE_GET" "TOKEN_ADD" "TOKEN_EDIT" "TOKEN_DEL" "TOKEN_SCHEDULE" "TOKEN_LIST" "CUSTOMER_ADD" "CUSTOMER_EDIT" "CUSTOMER_DEL" "CUSTOMER_LIST" "TICKETREQUEST" "LEVEL3" "TRAN_EXPORT" "TRAN_IMPORT" "PRODMANAGE" "PRODLIST" "ORDERMANAGE" "ORDERLIST" "ORDERREPORT" "CARDDENYLIST" "P2PE" "STANDINKEY_GENERATE"

Administrative access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • REPORT_TRAN - Transaction and batch detail reports
  • REPORT_TOTALS - Transaction and batch total reports
  • REPORT_CHARTDATA - Card data breakdown for report views
  • REPORT_QUEUE - List queued transactions pending authorization
  • BATCH_CLEAR - Mark batch as settled without funding
  • BATCH_SET - Change batch number
  • BATCH_RESCIND - Unsettle a batch (can double charge customers)
  • BATCH_CLOSE - Close a batch so new transactions are not added but do not settle
  • TRAN_EDIT - Edit a transaction
  • TRAN_NULLIFY - Delete a previously-authorized transaction without any attempt to go online and remove an authorization hold. Similar to a void.
  • TRAN_DETAIL - Transaction details
  • TRAN_RECEIPT - Transaction receipts. Generating and sending receipts, and invoices
  • TRAN_IMPORT - Import transaction data from a different TranSafe into this instance of TranSafe
  • TRAN_EXPORT - Emport transaction data from TranSafe into a different instance of TranSafe
  • 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 TranSafe
  • TRAN_IMPORT - Import transaction data into TranSafe
  • PRODMANAGE - Manage products (sku, amount, etc) in the inventory system
  • PRODLIST - List product details in the inventory system
  • ORDERMANAGE - Manage orders and invoices
  • ORDERLIST - List orders and invoices
  • ORDERREPORT - Reports for orders and invoices
  • CARDDENYLIST - Manage the card deny list
  • P2PE - P2PE device management
  • STANDINKEY_GENERATE - Generate an encryption key used for encrypting account data as part of stand-in authorization
trans_perms
string
Enum: "VERIFYONLY" "SALE" "PREAUTH" "REVERSAL" "INCREMENTAL" "PREAUTHCOMPLETE" "FORCE" "CAPTURE" "VOID" "ADJUST" "REFUND" "ACTIVATE" "BALANCEINQ" "CASHOUT" "TOREVERSAL" "MERCHRETURN" "ISSUE" "TIP" "EBTFSSALE" "EBTFSRETURN" "EBTFSVOUCHER" "EBTFSBALANCE" "EBTCBSALE" "EBTCBCASH" "EBTCBBALANCE" "CHECKVERIFY" "CHECKCONVONLY" "CHECKCONVVRFY" "CHECKCONVGUAR" "CHECKCONVOVER" "CHECKIMAGEUPLOAD" "SETTLE" "SETTLERFR" "TERMLOAD" "INTERACMAC" "EMVCOMPLETE" "ALTPAYMENTINIT" "CARDTYPE"

Transaction access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as current user combined with the mask of the perms on the group. Cannot exceed perms of current user or owning group.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • VERIFYONLY - Card verification
  • SALE - Purchase
  • PREAUTH - Authorization only (preauth)
  • REVERSAL - Reverse a transaction
  • INCREMENTAL - Incremental
  • PREAUTHCOMPLETE - Complete an authorization only (preauth) transaction
  • FORCE - Force purchase without online authorization
  • CAPTURE - Capture an un-captured transaction
  • VOID - Void a trasnaction
  • ADJUST - Adjust a transaction
  • REFUND - Refund
  • ACTIVATE - Activate a private label gift card
  • BALANCEINQ - Request account balance
  • CASHOUT - Remove all funds from a gift card in order to provide the customer with cash for the value
  • TOREVERSAL - Timeout reversal
  • MERCHRETURN - Merchandise return. Used by gift cards
  • ISSUE - Issue a gift card
  • TIP - Add a tip to a gift card
  • EBTFSSALE - Electronic Benefits Transfer food purchase
  • EBTFSRETURN - Electronic Benefits Transfer food refund
  • EBTFSVOUCHER - Electronic Benefits Transfer food voucher (paper food stamps) purchase
  • EBTFSBALANCE - Electronic Benefits Transfer food balance
  • EBTCBSALE - Electronic Benefits Transfer cash purchase
  • EBTCBCASH - Electronic Benefits Transfer cash withdrawal
  • EBTCBBALANCE - Electronic Benefits Transfer cash balance
  • CHECKVERIFY - Check verification only (without conversion)
  • CHECKCONVONLY - Check conversion only (without verification)
  • CHECKCONVVRFY - Check verification and conversion
  • CHECKCONVGUAR - Check conversation guarantee
  • CHECKCONVOVER - Convert a check with override
  • CHECKIMAGEUPLOAD - Upload check image
  • SETTLE - Settle
  • SETTLERFR - Request Settlement Status (limited processor support)
  • TERMLOAD - Terminal loading data
  • INTERACMAC - Interac MACing parameters
  • EMVCOMPLETE - EMV completion transaction
  • ALTPAYMENTINIT - Init an alternative payment method
  • CARDTYPE - Determine cardtype of presented account
expire_sec
required
string\d+|infinite

How long the API key should be valid.

Can be a numeric whole number of seconds or they key word infinite to indicate the key should never expire. Once a key has expired, it can no longer be used.

Minimum allowed value is 30 indicating the key will only be valid for 30 seconds.

Will be used as the extend time when combined with the extend_on_use flag.

profile_id
string\d+

Profile ID the key should represent instead of the user.

Can only be present when type=profile and is not valid when type=user

Responses

Request samples

Content type
application/json
{
  • "type": "user",
  • "name": "string",
  • "descr": "string",
  • "flags": "EXTEND_ON_USE",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "REPORT_TRAN",
  • "trans_perms": "VERIFYONLY",
  • "expire_sec": "3600",
  • "profile_id": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "apikey_id": "string",
  • "apikey_secret": "string"
}

Deactivate SkyLink Device

Deactivates a SkyLink device

When deactivated the license seat used by that device will be immediately available for use by another installation.

libmonetra KVS equivalent for endpoint

  • action_sys = skylink_manage
  • skylink_manage = deactivate
Authorizations:
basic_authapikey_idapikey
path Parameters
device_id
required
string

ID of registered SkyLink device

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/system/licensing/skylink/12543' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get SkyLink Device List

Gets a list devices registered for SkyLink

The resulting report will contain these headers:

device_id, active, deactivated_ts, last_used_user, last_used_ts, version, name,
manuf, model, os, osver, deactivation_cnt

libmonetra KVS equivalent for endpoint

  • action_sys = skylink_manage
  • skylink_manage = list
Authorizations:
basic_authapikey_idapikey
query Parameters
show_deactivated
object
Enum: "yes" "no"
Example: show_deactivated=yes

Show deactivated devices

Values:

  • yes - Include deactived devices
  • no - Do not include deactived devices

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/system/licensing/skylink' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Get SkyLink Limit

Get the current number SkyLink instances used with a profile

libmonetra KVS equivalent for endpoint

  • action_sys = skylink_manage
  • skylink_manage = getlimit
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/system/licensing/skylink/limit' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "limit": "string"
}

Set SkyLink Limit

Set the maximum number of SkyLink instances that can be used with a profile

libmonetra KVS equivalent for endpoint

  • action_sys = skylink_manage
  • skylink_manage = setlimit
Authorizations:
basic_authapikey_idapikey
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

limit
required
string\d+

Maximum number of SkyLink devices

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "limit": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get SkyLink Max Limit During Time Period

Gets the highest limit set across a period of time

Will show results for all profiles visible to the caller

The resulting report will contain these headers:

profile_id, limit

libmonetra KVS equivalent for endpoint

  • action_sys = skylink_manage
  • skylink_manage = limitmax
Authorizations:
basic_authapikey_idapikey
query Parameters
bdate
string

Start of date range

edate
string

End of date range

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/system/licensing/skylink/limit/max' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": {
    }
}

Get SkyLink Set Limit History

Get history of limit changes for SkyLink

Applies to a single profile.

The resulting report will contain these headers:

ts, is_current, limit, request_user

libmonetra KVS equivalent for endpoint

  • action_sys = skylink_manage
  • skylink_manage = limithistory
Authorizations:
basic_authapikey_idapikey
query Parameters
profile_id
string

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

show_deactivated
object
Enum: "yes" "no"
Example: show_deactivated=yes

Show deactivated devices

Values:

  • yes - Include deactived devices
  • no - Do not include deactived devices

Responses

Request samples 

curl -X GET 'https://test.transafe.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": {
    }
}