logo
API docs by Redocly

TranSafe (1.3.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

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, a HTTP 200 repsonse code will be returned for all transactions. The response parameters code, msoft_code, and phard_code are used to determine the transaction outcome.

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

Only HTTP Basic authentication is currently supported.

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

Basic Authentication

HTTP Basic Authentication involves sending the Authorization HTTP header with the type Basic and the base64 encoded username:password.

E.g.

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

If the authorization data is not present the response code 401 and WWW-Authenticate header is returned in the response indicating the authentication that must be used.

WWW-Authenticate: Basic realm="Payment Server Resource"

Colon escaping

Basic auth does not allow colons (':') to be present in usernames. However, most usernames for the system will include a colon. To deal with this, all colons must be replaced with a pipe ('|').

If a username contains a pipe, please contact support.

user:sub -> user|sub

For example, take the username test_retail:public and a password of publ1ct3st. Therefore, the username must be transformed to test_retail|public, resulting in basic authentication data to be encoded of test_retail|public:publ1ct3st. The resulting Authentication header data would be Authorization: Basic dGVzdF9yZXRhaWx8cHVibGljOnB1YmwxY3Qzc3Q=

Programming language examples

We do not recommend using most programming language's build 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/v1/report/failed'
USER = 'test_retail|public'
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/v1/report/failed";
        var username = "test_retail|public";
        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());
                }
            }
        }
    }
}

Using the language API credential management increase the transaction processing time. Using the language API 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.

PHP
<?php
$url = "https://test.transafe.com/api/v1/report/failed";
$username = "test_retail|public";
$password = "publ1ct3st";
$opts = array(
  "http"=>array(
    "method"=>"GET",
    "header" => "Authorization: Basic " . base64_encode("$username:$password")
  ),
);
$context = stream_context_create($opts);
$file = file_get_contents($url, false, $context);
echo $file;
?>

Transaction

Transaction operations

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 = reversal
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 18446744073709551615

Transaction identifier

The transaction identifier should be treated as a string value and can be alpha, numeric, and some special characters. It should be considered in the same category as a UUID. Math or conversion should not be performed on the value and it should be stored as a string blob of characters.

query Parameters
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/v1/transaction/926573735405091' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Get Transaction Details

Gets fine-grained detail about a transaction

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

The most common use for this operation is re-printing receipts. All data needed for receipts is returned as part of this request. Sending the rcpt parameter will allow for formatted receipt data to also be returned.

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = trandetail
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 18446744073709551615

Transaction identifier

The transaction identifier should be treated as a string value and can be alpha, numeric, and some special characters. It should be considered in the same category as a UUID. Math or conversion should not be performed on the value and it should be stored as a string blob of characters.

Cannot be combined with:

  • order_id
query Parameters
rcpt
string
Example: rcpt=yes

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Email to send customer receipt copy to

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

rcpt_sms
string
Example: rcpt_sms=555-555-5555

Send SMS for order invoices

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

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

Values:

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

Values:

  • yes - Email merchant receipt to the merchant
  • no - Do not email merchant receipt to the merchant
order_id
string
Example: order_id=58445676543

Unique ID of an order

Cannot be combined with:

  • ttid
payment_id
string
Example: payment_id=987653645678

Unique ID of a payment for an order

Requires:

  • order_id

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/transaction/926572778835889' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "account": "XXXXXXXXXXXX1234",
  • "abaroute": "267084131",
  • "checknum": "45678",
  • "accounttype": "PERSONAL|CHECKING",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "cof_transid": "930734056218579",
  • "cof_authamount": "19.22",
  • "installment_num": "17",
  • "installment_total": "149",
  • "recurring": "recurring",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "shipcountry": "840",
  • "shipzip": "32789",
  • "zip": "32606",
  • "action": "SALE",
  • "orig_code": "AUTH",
  • "orig_msoft_code": "INT_SUCCESS",
  • "orig_phard_code": "SUCCESS",
  • "orig_reqamount": "155.34",
  • "orig_verbiage": "Transaction approved",
  • "merch_name": "Pizza Palace",
  • "merch_addr1": "777 77th Ct",
  • "merch_addr2": "Jacksonville FL",
  • "merch_addr3": "32789",
  • "merch_phone": "555-555-5555",
  • "merch_email": "merchant@email",
  • "merch_url": "https://url",
  • "merch_proc": "loopback",
  • "custref": "55",
  • "ordernum": "A13DDES345",
  • "ptrannum": "1987",
  • "amount": "19.92",
  • "cashbackamount": "20.00",
  • "currency": "124",
  • "examount": "0.33",
  • "surchargeamount": "1.25",
  • "tax": "1.29",
  • "discountamount": "100.00",
  • "dutyamount": "5.07",
  • "freightamount": "225.82",
  • "convenience_fee": "1.23",
  • "supplemental_fee": "1.23",
  • "bdate": "-6 months",
  • "edate": "now",
  • "excharges": "GIFT|MINI",
  • "rate": "12.00",
  • "roomnum": "5143",
  • "descmerch": "Pizza Palace LLC",
  • "descloc": "Store CA 543",
  • "clerkid": "Doe-1553",
  • "stationid": "7",
  • "laneid": "4",
  • "comments": "Extra beef",
  • "divisionnum": "PAYROLL",
  • "expdate": "0129",
  • "healthcare": "no",
  • "reversible": "yes",
  • "reversal_reason": "CLERKVOID",
  • "offline_decline": "...",
  • "tranflags": "CAPTURED|ONLINE|SENSITIVEDATA",
  • "txnstatus": "COMPLETE|ONLINE|SENSITIVEDATA",
  • "last_modified_ts": "1653422816",
  • "order_id": "58445676543",
  • "payment_id": "987653645678",
  • "order_cash_discount": "12.37",
  • "order_cash_price": "142.97",
  • "order_noncash_price": "155.34",
  • "order_tip": "0.50",
  • "order_total": "155.34",
  • "order_tax": "2.44",
  • "order_discount": "5.22",
  • "detail_order_notes": "Extra pickles",
  • "trans": "...",
  • "line_items": "...",
  • "ttid": "18446744073709551615",
  • "property1": "string",
  • "property2": "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 is not known or finalized, it can be added or updated.

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

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

libmonetra KVS equivalent for endpoint

  • action = adjust
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 18446744073709551615

Transaction identifier

The transaction identifier should be treated as a string value and can be alpha, numeric, and some special characters. It should be considered in the same category as a UUID. Math or conversion should not be performed on the value and it should be stored as a string blob of characters.

Request Body schema: application/json
object (Adjust_Transaction_v8_params_money)

Monetary parameters

object (Adjust_Transaction_v8_params_lodging)

Lodging parameters

object (Adjust_Transaction_v8_params_order)

Order detail parameters

object (Adjust_Transaction_v8_params_shipping)

Shipping detail parameters

object (Adjust_Transaction_v8_params_lane)

Merchant lane parameters

property name*
additional property
string

Responses

Request samples

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

Balance

Balance inquiry

Applies to:

  • Credit
  • Debit
  • Gift

libmonetra KVS equivalent for endpoint

  • action = balanceinq
Authorizations:
basic_auth
Request Body schema: application/json
object (Store_Account_v8_params_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 (Balance_v8_params_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

Responses

Request samples

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

Response samples

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

Capture

Add an uncaptured sale to a batch

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

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

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

Using capture=no outside of MCC's where it's required will not cause processing errors. However, the amount should not be changed in this situation. If 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 = capture
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 18446744073709551615

Transaction identifier

The transaction identifier should be treated as a string value and can be alpha, numeric, and some special characters. It should be considered in the same category as a UUID. Math or conversion should not be performed on the value and it should be stored as a string blob of characters.

Request Body schema: application/json
priority
string
Default: "normal"
Enum: "low" "normal" "high"

Processing priority.

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

Values:

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

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

rcpt
string

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

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 = cardtype
Authorizations:
basic_auth
Request Body schema: application/json
object (Store_Account_v8_params_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
{
  • "account_data": {
    },
  • "tokenize": "no",
  • "matching_token": "yes"
}

Response samples

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

Get All Payment Details

Get all order payment transaction details

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = trandetail
Authorizations:
basic_auth
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

Cannot be combined with:

  • ttid
query Parameters
ttid
string
Example: ttid=18446744073709551615

Transaction identifier

The transaction identifier should be treated as a string value and can be alpha, numeric, and some special characters. It should be considered in the same category as a UUID. Math or conversion should not be performed on the value and it should be stored as a string blob of characters.

Cannot be combined with:

  • order_id
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.
rcpt_email
string
Example: rcpt_email=email@email

Email to send customer receipt copy to

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

rcpt_sms
string
Example: rcpt_sms=555-555-5555

Send SMS for order invoices

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

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

Values:

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

Values:

  • yes - Email merchant receipt to the merchant
  • no - Do not email merchant receipt to the merchant
payment_id
string
Example: payment_id=987653645678

Unique ID of a payment for an order

Requires:

  • order_id

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/transaction/order/17485767483/payment' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "account": "XXXXXXXXXXXX1234",
  • "abaroute": "267084131",
  • "checknum": "45678",
  • "accounttype": "PERSONAL|CHECKING",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "cof_transid": "930734056218579",
  • "cof_authamount": "19.22",
  • "installment_num": "17",
  • "installment_total": "149",
  • "recurring": "recurring",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "shipcountry": "840",
  • "shipzip": "32789",
  • "zip": "32606",
  • "action": "SALE",
  • "orig_code": "AUTH",
  • "orig_msoft_code": "INT_SUCCESS",
  • "orig_phard_code": "SUCCESS",
  • "orig_reqamount": "155.34",
  • "orig_verbiage": "Transaction approved",
  • "merch_name": "Pizza Palace",
  • "merch_addr1": "777 77th Ct",
  • "merch_addr2": "Jacksonville FL",
  • "merch_addr3": "32789",
  • "merch_phone": "555-555-5555",
  • "merch_email": "merchant@email",
  • "merch_url": "https://url",
  • "merch_proc": "loopback",
  • "custref": "55",
  • "ordernum": "A13DDES345",
  • "ptrannum": "1987",
  • "amount": "19.92",
  • "cashbackamount": "20.00",
  • "currency": "124",
  • "examount": "0.33",
  • "surchargeamount": "1.25",
  • "tax": "1.29",
  • "discountamount": "100.00",
  • "dutyamount": "5.07",
  • "freightamount": "225.82",
  • "convenience_fee": "1.23",
  • "supplemental_fee": "1.23",
  • "bdate": "-6 months",
  • "edate": "now",
  • "excharges": "GIFT|MINI",
  • "rate": "12.00",
  • "roomnum": "5143",
  • "descmerch": "Pizza Palace LLC",
  • "descloc": "Store CA 543",
  • "clerkid": "Doe-1553",
  • "stationid": "7",
  • "laneid": "4",
  • "comments": "Extra beef",
  • "divisionnum": "PAYROLL",
  • "expdate": "0129",
  • "healthcare": "no",
  • "reversible": "yes",
  • "reversal_reason": "CLERKVOID",
  • "offline_decline": "...",
  • "tranflags": "CAPTURED|ONLINE|SENSITIVEDATA",
  • "txnstatus": "COMPLETE|ONLINE|SENSITIVEDATA",
  • "last_modified_ts": "1653422816",
  • "order_id": "58445676543",
  • "payment_id": "987653645678",
  • "order_cash_discount": "12.37",
  • "order_cash_price": "142.97",
  • "order_noncash_price": "155.34",
  • "order_tip": "0.50",
  • "order_total": "155.34",
  • "order_tax": "2.44",
  • "order_discount": "5.22",
  • "detail_order_notes": "Extra pickles",
  • "trans": "...",
  • "line_items": "...",
  • "ttid": "18446744073709551615",
  • "property1": "string",
  • "property2": "string"
}

Get Payment Details

Get transaction details for a payment made to an order

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = trandetail
Authorizations:
basic_auth
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

Cannot be combined with:

  • ttid
payment_id
required
string
Example: 987653645678

Unique ID of a payment for an order

Requires:

  • order_id
query Parameters
ttid
string
Example: ttid=18446744073709551615

Transaction identifier

The transaction identifier should be treated as a string value and can be alpha, numeric, and some special characters. It should be considered in the same category as a UUID. Math or conversion should not be performed on the value and it should be stored as a string blob of characters.

Cannot be combined with:

  • order_id
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.
rcpt_email
string
Example: rcpt_email=email@email

Email to send customer receipt copy to

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

rcpt_sms
string
Example: rcpt_sms=555-555-5555

Send SMS for order invoices

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

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

Values:

  • yes - Requesting duplicate receipt copy
  • no - Requesting original receipt copy
rcpt_merch_copy
object
Enum: "yes" "no"
Example: rcpt_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/v1/transaction/order/17485767483/payment/7849345732' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "account": "XXXXXXXXXXXX1234",
  • "abaroute": "267084131",
  • "checknum": "45678",
  • "accounttype": "PERSONAL|CHECKING",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "cof_transid": "930734056218579",
  • "cof_authamount": "19.22",
  • "installment_num": "17",
  • "installment_total": "149",
  • "recurring": "recurring",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "shipcountry": "840",
  • "shipzip": "32789",
  • "zip": "32606",
  • "action": "SALE",
  • "orig_code": "AUTH",
  • "orig_msoft_code": "INT_SUCCESS",
  • "orig_phard_code": "SUCCESS",
  • "orig_reqamount": "155.34",
  • "orig_verbiage": "Transaction approved",
  • "merch_name": "Pizza Palace",
  • "merch_addr1": "777 77th Ct",
  • "merch_addr2": "Jacksonville FL",
  • "merch_addr3": "32789",
  • "merch_phone": "555-555-5555",
  • "merch_email": "merchant@email",
  • "merch_url": "https://url",
  • "merch_proc": "loopback",
  • "custref": "55",
  • "ordernum": "A13DDES345",
  • "ptrannum": "1987",
  • "amount": "19.92",
  • "cashbackamount": "20.00",
  • "currency": "124",
  • "examount": "0.33",
  • "surchargeamount": "1.25",
  • "tax": "1.29",
  • "discountamount": "100.00",
  • "dutyamount": "5.07",
  • "freightamount": "225.82",
  • "convenience_fee": "1.23",
  • "supplemental_fee": "1.23",
  • "bdate": "-6 months",
  • "edate": "now",
  • "excharges": "GIFT|MINI",
  • "rate": "12.00",
  • "roomnum": "5143",
  • "descmerch": "Pizza Palace LLC",
  • "descloc": "Store CA 543",
  • "clerkid": "Doe-1553",
  • "stationid": "7",
  • "laneid": "4",
  • "comments": "Extra beef",
  • "divisionnum": "PAYROLL",
  • "expdate": "0129",
  • "healthcare": "no",
  • "reversible": "yes",
  • "reversal_reason": "CLERKVOID",
  • "offline_decline": "...",
  • "tranflags": "CAPTURED|ONLINE|SENSITIVEDATA",
  • "txnstatus": "COMPLETE|ONLINE|SENSITIVEDATA",
  • "last_modified_ts": "1653422816",
  • "order_id": "58445676543",
  • "payment_id": "987653645678",
  • "order_cash_discount": "12.37",
  • "order_cash_price": "142.97",
  • "order_noncash_price": "155.34",
  • "order_tip": "0.50",
  • "order_total": "155.34",
  • "order_tax": "2.44",
  • "order_discount": "5.22",
  • "detail_order_notes": "Extra pickles",
  • "trans": "...",
  • "line_items": "...",
  • "ttid": "18446744073709551615",
  • "property1": "string",
  • "property2": "string"
}

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 = activate
Authorizations:
basic_auth
Request Body schema: application/json
object (Store_Account_v8_params_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 (Gift_Activate_v8_params_merchant_descriptors)

Merchant descriptor parameters

object (Adjust_Transaction_v8_params_lane)

Merchant lane parameters

object (Adjust_Transaction_v8_params_order)

Order detail parameters

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

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 = cashout
Authorizations:
basic_auth
Request Body schema: application/json
object (Store_Account_v8_params_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 (Gift_Activate_v8_params_merchant_descriptors)

Merchant descriptor parameters

object (Adjust_Transaction_v8_params_lane)

Merchant lane parameters

object (Adjust_Transaction_v8_params_order)

Order detail parameters

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

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 = issue
Authorizations:
basic_auth
Request Body schema: application/json
object (Store_Account_v8_params_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 (Gift_Activate_v8_params_merchant_descriptors)

Merchant descriptor parameters

object (Adjust_Transaction_v8_params_lane)

Merchant lane parameters

object (Adjust_Transaction_v8_params_order)

Order detail parameters

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

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 cards should be 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 = merchreturn
Authorizations:
basic_auth
Request Body schema: application/json
object (Store_Account_v8_params_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 (Gift_Activate_v8_params_merchant_descriptors)

Merchant descriptor parameters

object (Adjust_Transaction_v8_params_lane)

Merchant lane parameters

object (Adjust_Transaction_v8_params_money)

Monetary parameters

object (Adjust_Transaction_v8_params_order)

Order detail parameters

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

Processing priority.

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

Values:

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

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

rcpt
string

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Identifier for the gift card transaction to refund merchandise

property name*
additional property
string

Responses

Request samples

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

Response samples

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

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 = merchreturn
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 18446744073709551615

Identifier for the gift card transaction to refund merchandise

Request Body schema: application/json
object (Store_Account_v8_params_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 (Gift_Activate_v8_params_merchant_descriptors)

Merchant descriptor parameters

object (Adjust_Transaction_v8_params_lane)

Merchant lane parameters

object (Adjust_Transaction_v8_params_money)

Monetary parameters

object (Adjust_Transaction_v8_params_order)

Order detail parameters

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

Processing priority.

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

Values:

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

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

rcpt
string

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Responses

Request samples

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

Incremental

Operation used to increase amount for an existing authorization

Primarily used by lodging. However, some processors and card brands support this operation on other industries. Neither processors nor card brands uniformly support incremental authorizations across non-lodging industry. The merchant needs to verify with the processor how they can use incremental if they are non-lodging industry. It is recommended that incremental only be used with lodging due to non-uniform support.

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 = incremental
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 18446744073709551615

Identifier for transaction to increase amount

Request Body schema: application/json
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 (Adjust_Transaction_v8_params_lodging)

Lodging parameters

object (Gift_Activate_v8_params_merchant_descriptors)

Merchant descriptor parameters

object (Adjust_Transaction_v8_params_lane)

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

Responses

Request samples

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

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 = preauthcomplete
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 18446744073709551615

Transaction identifier

The transaction identifier should be treated as a string value and can be alpha, numeric, and some special characters. It should be considered in the same category as a UUID. Math or conversion should not be performed on the value and it should be stored as a string blob of characters.

Request Body schema: application/json
object (Adjust_Transaction_v8_params_shipping)

Shipping detail parameters

zip
string <= 32 characters

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

object (Adjust_Transaction_v8_params_lodging)

Lodging parameters

object (Adjust_Transaction_v8_params_lane)

Merchant lane parameters

object (Adjust_Transaction_v8_params_money)

Monetary parameters

object (Adjust_Transaction_v8_params_order)

Order detail parameters

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

Processing priority.

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

Values:

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

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

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

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

Defaults to no if not present.

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

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

Values:

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

When paired with tokenize, 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*
additional property
string

Responses

Request samples

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

Pre-Authorize

Places a hold on funds without capturing for settlement

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

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

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

libmonetra KVS equivalent for endpoint

  • action = preauth
Authorizations:
basic_auth
Request Body schema: application/json
object (Store_Account_v8_params_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 (Balance_v8_params_verification)

Verification parameters

object (Adjust_Transaction_v8_params_shipping)

Shipping detail parameters

object (Pre_Authorize_v8_params_ecomm)

E-commerce parameters

object (Pre_Authorize_v8_params_health)

Healthcare parameters

object (Adjust_Transaction_v8_params_lodging)

Lodging parameters

object (Gift_Activate_v8_params_merchant_descriptors)

Merchant descriptor parameters

object (Adjust_Transaction_v8_params_lane)

Merchant lane parameters

required
object (Pre_Authorize_v8_params_money)

Monetary parameters

object (Adjust_Transaction_v8_params_order)

Order detail parameters

object (Pre_Authorize_v8_params_pin_data)

PIN data parameters

object (Gift_Activate_v8_params_processing_options)

Processing options

object (Pre_Authorize_v8_params_recurring_data)

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.
ttid
string [ 1 .. 38 ] characters [a-zA-Z0-9+ _-{}]{1,38}

Identifier for transaction to duplicate

property name*
additional property
string

Responses

Request samples

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

Response samples

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

Duplicate Pre-Authorization

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.

libmonetra KVS equivalent for endpoint

  • action = preauth
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 18446744073709551615

Identifier for transaction to duplicate

Request Body schema: application/json
object (Store_Account_v8_params_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 (Balance_v8_params_verification)

Verification parameters

object (Adjust_Transaction_v8_params_shipping)

Shipping detail parameters

object (Pre_Authorize_v8_params_ecomm)

E-commerce parameters

object (Pre_Authorize_v8_params_health)

Healthcare parameters

object (Adjust_Transaction_v8_params_lodging)

Lodging parameters

object (Gift_Activate_v8_params_merchant_descriptors)

Merchant descriptor parameters

object (Adjust_Transaction_v8_params_lane)

Merchant lane parameters

required
object (Pre_Authorize_v8_params_money)

Monetary parameters

object (Adjust_Transaction_v8_params_order)

Order detail parameters

object (Pre_Authorize_v8_params_pin_data)

PIN data parameters

object (Gift_Activate_v8_params_processing_options)

Processing options

object (Pre_Authorize_v8_params_recurring_data)

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

Responses

Request samples

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

Response samples

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

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 = sale
Authorizations:
basic_auth
Request Body schema: application/json
object (Store_Account_v8_params_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 (Balance_v8_params_verification)

Verification parameters

object (Adjust_Transaction_v8_params_shipping)

Shipping detail parameters

object (Pre_Authorize_v8_params_ecomm)

E-commerce parameters

object (Pre_Authorize_v8_params_health)

Healthcare parameters

object (Adjust_Transaction_v8_params_lodging)

Lodging parameters

object (Gift_Activate_v8_params_merchant_descriptors)

Merchant descriptor parameters

object (Adjust_Transaction_v8_params_lane)

Merchant lane parameters

required
object (Pre_Authorize_v8_params_money)

Monetary parameters

object (Adjust_Transaction_v8_params_order)

Order detail parameters

object (Pre_Authorize_v8_params_pin_data)

PIN data parameters

object (Gift_Activate_v8_params_processing_options)

Processing options

object (Pre_Authorize_v8_params_recurring_data)

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.
ttid
string [ 1 .. 38 ] characters [a-zA-Z0-9+ _-{}]{1,38}

Identifier for transaction to duplicate

property name*
additional property
string

Responses

Request samples

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

Response samples

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

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

libmonetra KVS equivalent for endpoint

  • action = sale
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 18446744073709551615

Identifier for transaction to duplicate

Request Body schema: application/json
object (Store_Account_v8_params_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 (Balance_v8_params_verification)

Verification parameters

object (Adjust_Transaction_v8_params_shipping)

Shipping detail parameters

object (Pre_Authorize_v8_params_ecomm)

E-commerce parameters

object (Pre_Authorize_v8_params_health)

Healthcare parameters

object (Adjust_Transaction_v8_params_lodging)

Lodging parameters

object (Gift_Activate_v8_params_merchant_descriptors)

Merchant descriptor parameters

object (Adjust_Transaction_v8_params_lane)

Merchant lane parameters

required
object (Pre_Authorize_v8_params_money)

Monetary parameters

object (Adjust_Transaction_v8_params_order)

Order detail parameters

object (Pre_Authorize_v8_params_pin_data)

PIN data parameters

object (Gift_Activate_v8_params_processing_options)

Processing options

object (Pre_Authorize_v8_params_recurring_data)

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

Responses

Request samples

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

Response samples

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

Refund

Refunds a prior purchase

Also used to load funds onto a gift card.

For credit and gift cards, 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 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 = return
Authorizations:
basic_auth
Request Body schema: application/json
object (Store_Account_v8_params_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 (Gift_Activate_v8_params_merchant_descriptors)

Merchant descriptor parameters

object (Adjust_Transaction_v8_params_lane)

Merchant lane parameters

object (Adjust_Transaction_v8_params_money)

Monetary parameters

object (Adjust_Transaction_v8_params_order)

Order detail parameters

object (Pre_Authorize_v8_params_pin_data)

PIN data parameters

object (Pre_Authorize_v8_params_recurring_data)

Recurring group

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

Processing priority.

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

Values:

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

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

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

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

Defaults to no if not present.

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

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

Values:

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

When paired with tokenize, 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 [ 1 .. 38 ] characters [a-zA-Z0-9+ _-{}]{1,38}

Identifier for transaction to refund

property name*
additional property
string

Responses

Request samples

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

Response samples

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

Refund Existing Transaction

Issue a refund 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 = return
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 18446744073709551615

Identifier for transaction to refund

Request Body schema: application/json
object (Store_Account_v8_params_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 (Gift_Activate_v8_params_merchant_descriptors)

Merchant descriptor parameters

object (Adjust_Transaction_v8_params_lane)

Merchant lane parameters

object (Adjust_Transaction_v8_params_money)

Monetary parameters

object (Adjust_Transaction_v8_params_order)

Order detail parameters

object (Pre_Authorize_v8_params_pin_data)

PIN data parameters

object (Pre_Authorize_v8_params_recurring_data)

Recurring group

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

Processing priority.

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

Values:

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

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

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

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

Defaults to no if not present.

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

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

Values:

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

When paired with tokenize, 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*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "account_data": {
    },
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "money": {
    },
  • "order": {
    },
  • "pin_data": {
    },
  • "recurring_data": {
    },
  • "priority": "normal",
  • "timeout": "30",
  • "tokenize": "no",
  • "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",
  • "draft_locator_id": "24FDBDD0902",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "rcpt_host_ts": "052422143743",
  • "rcpt_entry_mode": "C",
  • "rcpt_acct_type": "chequing",
  • "rcpt_emv_cvm": "none",
  • "rcpt_emv_pinbypass": "N",
  • "rcpt_resp_code": "A00",
  • "rcpt_issuer_resp_code": "00",
  • "rcpt_emv_aid": "A0000000031010",
  • "rcpt_emv_name": "Visa Credit",
  • "rcpt_emv_tvr": "8080008000",
  • "rcpt_emv_tsi": "6800",
  • "rcpt_emv_actype": "ARQC",
  • "rcpt_emv_ac": "D737017E33C78692",
  • "rcpt_emv_form_factor": "05",
  • "rcpt_custom": "Rec Num:002000089,Transid:940152939191917,VCode:1234",
  • "rcpt_emv_iad": "06010A03A02000",
  • "rcpt_emv_card_decline": "...",
  • "printdata": "APPRoVED",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "authamount": "6.50",
  • "balance": "12.00",
  • "account": "XXXXXXXXXXXX1234",
  • "cof_authamount": "19.22",
  • "cof_transid": "930734056218579",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "token": "6789656783904467894",
  • "ttid": "18446744073709551615"
}

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 = avsonly
Authorizations:
basic_auth
Request Body schema: application/json
object (Store_Account_v8_params_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 (Balance_v8_params_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
carddenylist_check
string
Enum: "yes" "no"

Check the card deny list before going online for authorization

If on the list, decline with msoft_code=CARDDENYLIST.

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

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

Values:

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

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

Values:

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

Responses

Request samples

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

Response samples

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

Void Transaction

Removes a previously authorized transaction

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

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

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

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

libmonetra KVS equivalent for endpoint

  • action = void
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 18446744073709551615

Transaction identifier

The transaction identifier should be treated as a string value and can be alpha, numeric, and some special characters. It should be considered in the same category as a UUID. Math or conversion should not be performed on the value and it should be stored as a string blob of characters.

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/transaction/926573735405091/void' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Transaction Reports

Transaction Report operations

Clear Failed Transactions

Removes transactions from the failed history

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = cfh
Authorizations:
basic_auth
query Parameters
bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/report/failed' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

List Failed Transactions

Lists all failed transactions for the requested user (merchant) account

The resulting report will contain these headers:

ttid, msoft_code, phard_code, type, proc, entrymode, txnstatus,
tranflags, card, abaroute, account, expdate, checknum, timestamp,
accounttype, code, verbiage, reasoncode, amount, batch,
cardholdername, avs, cv, clerkid, stationid, comments,
divisionnum, promoid, descmerch, ptrannum, ordernum, custref, user

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = gft
Authorizations:
basic_auth
query Parameters
acct
string
Example: acct=5454

Account number for auditing

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

amount
string
Example: amount=19.92

Amount of money, including decimal. E.g 1.00

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

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder

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

Cardtypes

Pipe (|) separated.

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

Flag values (pipe separated):

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

Identifier for the clerk running the transaction

comments
string
Example: comments=Extra beef

User-defined comments related to the transaction

ptrannum
string
Example: ptrannum=1987

Numeric-only transaction number. If ordernum is present, it will supersede and be preferred over ptrannum

stationid
string
Example: stationid=7

Identifier for the physical station running the transaction

type
string
Example: type=sale

Type of action that was taken.

Can be a pipe (|) separated list of actions

last_modified_bdate
string
Example: last_modified_bdate=-9 days

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

last_modified_edate
string
Example: last_modified_edate=-4 days

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

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/report/failed' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Clear Settled Transactions

Removes transactions from the settled history

The transactions will no longer be returned by the settled report. These transactions are entirely purged from the system. Transactions that have been purged cannot be duplicated by ttid.

This should be done periodically based on business needs. Typically, 180 days should be kept at any given time to handle chargebacks and returns. If business needs dictate a longer time (e.g. a longer return policy), that should be taken into account when specifying the transactions to remove.

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = cth
Authorizations:
basic_auth
query Parameters
batch
string
Example: batch=47

The batch number associated with the transaction

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/report/settled ' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

List Settled Transactions

Lists all settled transactions for the requested user (merchant) account

The resulting report will contain these headers:

ttid, msoft_code, phard_code, type,proc, entrymode, txnstatus,
tranflags, reversible, card, pclevel, cardlevel, abaroute,
account, expdate, checknum, timestamp, last_modified_ts,
accounttype, reasoncode, amount, reqamount, orig_authamount,
authamount, examount, tax, cashback, authnum, stan, batnum, item,
cardholdername, avs, cv, clerkid, stationid, comments,
divisionnum, promoid, descmerch, ptrannum, ordernum, custref,
discountamount, freightamount, dutyamount, shipzip, shipcountry,
l3num, user

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = gl
Authorizations:
basic_auth
query Parameters
acct
string
Example: acct=5454

Account number for auditing

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

amount
string
Example: amount=19.92

Amount of money, including decimal. E.g 1.00

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

batch
string
Example: batch=47

The batch number associated with the transaction

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

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

Whether or not the report should include captured transactions

If not present, show both captured and uncaptured transactions.

Values:

  • yes - Only show captured transactions
  • no - Do not show captured transactions
cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder

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

Cardtypes

Pipe (|) separated.

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

Flag values (pipe separated):

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

Identifier for the clerk running the transaction

comments
string
Example: comments=Extra beef

User-defined comments related to the transaction

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

Indicates the level of payment card

Values:

  • 0 - Consumer card
  • 1 - Business card
  • 2 - Corporate or purchase card
ptrannum
string
Example: ptrannum=1987

Numeric-only transaction number. If ordernum is present, it will supersede and be preferred over ptrannum

stationid
string
Example: stationid=7

Identifier for the physical station running the transaction

ttid
string
Example: ttid=18446744073709551615

Transaction identifier

The transaction identifier should be treated as a string value and can be alpha, numeric, and some special characters. It should be considered in the same category as a UUID. Math or conversion should not be performed on the value and it should be stored as a string blob of characters.

type
string
Example: type=sale

Type of action that was taken.

Can be a pipe (|) separated list of actions

last_modified_bdate
string
Example: last_modified_bdate=-9 days

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

last_modified_edate
string
Example: last_modified_edate=-4 days

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

user
string
Example: user=user19

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

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/v1/report/settled' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

List Unsettled Transactions

Lists all unsettled transactions for the requested user (merchant) account

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, card, pclevel, cardlevel, abaroute,
account, expdate, checknum, timestamp, last_modified_ts,
accounttype, amount, reqamount, orig_authamount, authamount,
examount, tax, cashback, authnum, stan, batch, item,
cardholdername, avs, cv, clerkid, stationid, comments, divisionnum,
promoid, descmerch, ptrannum, ordernum, custref, discountamount,
freightamount, dutyamount, shipzip, shipcountry, l3num

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = gut
Authorizations:
basic_auth
query Parameters
acct
string
Example: acct=5454

Account number for auditing

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

amount
string
Example: amount=19.92

Amount of money, including decimal. E.g 1.00

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

batch
string
Example: batch=47

The batch number associated with the transaction

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

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

Whether or not the report should include captured transactions

If not present, show both captured and uncaptured transactions.

Values:

  • yes - Only show captured transactions
  • no - Do not show captured transactions
cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder

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

Cardtypes

Pipe (|) separated.

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

Flag values (pipe separated):

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

Identifier for the clerk running the transaction

comments
string
Example: comments=Extra beef

User-defined comments related to the transaction

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

Indicates the level of payment card

Values:

  • 0 - Consumer card
  • 1 - Business card
  • 2 - Corporate or purchase card
ptrannum
string
Example: ptrannum=1987

Numeric-only transaction number. If ordernum is present, it will supersede and be preferred over ptrannum

stationid
string
Example: stationid=7

Identifier for the physical station running the transaction

ttid
string
Example: ttid=18446744073709551615

Transaction identifier

The transaction identifier should be treated as a string value and can be alpha, numeric, and some special characters. It should be considered in the same category as a UUID. Math or conversion should not be performed on the value and it should be stored as a string blob of characters.

type
string
Example: type=sale

Type of action that was taken.

Can be a pipe (|) separated list of actions

last_modified_bdate
string
Example: last_modified_bdate=-9 days

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

last_modified_edate
string
Example: last_modified_edate=-4 days

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

user
string
Example: user=user19

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

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/report/unsettled' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Level 3

Level 3 operations

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
  • admin = l3list
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 18446744073709551615

Transaction identifier

The transaction identifier should be treated as a string value and can be alpha, numeric, and some special characters. It should be considered in the same category as a UUID. Math or conversion should not be performed on the value and it should be stored as a string blob of characters.

query Parameters
l3id
string
Example: l3id=56789673

ID associated with the Level 3 line item

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/level3/926660343286234' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Add Line Item

Adds Level 3 line item to an unsettled transaction

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = l3add
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 18446744073709551615

Transaction identifier

The transaction identifier should be treated as a string value and can be alpha, numeric, and some special characters. It should be considered in the same category as a UUID. Math or conversion should not be performed on the value and it should be stored as a string blob of characters.

Request Body schema: application/json
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
{
  • "commoditycode": "50301700",
  • "description": "Pickles",
  • "productcode": "7456",
  • "qty": "1",
  • "unit": "1",
  • "unitprice": "0.25",
  • "discountamount": "2.53",
  • "discountrate": "4.05",
  • "amount": "1.51"
}

Response samples

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

Delete Line Item

Deletes Level 3 line item from an unsettled transaction

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = l3del
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 18446744073709551615

Transaction identifier

The transaction identifier should be treated as a string value and can be alpha, numeric, and some special characters. It should be considered in the same category as a UUID. Math or conversion should not be performed on the value and it should be stored as a string blob of characters.

l3id
required
string
Example: 56789673

ID associated with the Level 3 line item

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/level3/926660343286234/19266603985142159' --basic -u 'test_retail|public:publ1ct3st'

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
  • admin = l3list
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 18446744073709551615

Transaction identifier

The transaction identifier should be treated as a string value and can be alpha, numeric, and some special characters. It should be considered in the same category as a UUID. Math or conversion should not be performed on the value and it should be stored as a string blob of characters.

l3id
required
string
Example: 56789673

ID associated with the Level 3 line item

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/level3/926660343286234/19266603985142159' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Batch

Batch operations

Force-Settle 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.

WARNING: This function should be used with extreme caution as Force Settling a batch which the processing institution has not received will prevent funding of those transactions in the batch.

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = forcesettle
Authorizations:
basic_auth
path Parameters
batch
required
string
Example: 47

The batch number associated with the transaction

sub
required
string
Example: 0

Route to settle

More than one might be present if split-routing is in use. For example, Credit could be sub 0 and Gift sub 1. Use the 'Unsettled Batch Totals' report to determine which sub routes need to be settled.

Note: Every account will have at least one route which is route 0.

Responses

Request samples 

curl -X POST 'https://test.transafe.com/api/v1/batch/123/settle/0/force' --basic -u 'test_retail|public:publ1ct3st' -d ''

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:

BatchNum, sub, status, totaltransNum, totaltransAmount, totalAuthNum,
totalAuthAmount, totalReturnNum, totalReturnAmount, 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, NumUnknownAuth, AmntUnknownAuth, NumUnknownReturn,
AmntUnknownReturn

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = pbt
Authorizations:
basic_auth
query Parameters
batch
string
Example: batch=47

The batch number associated with the transaction

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

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

Whether or not the report should include reversible transactions

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

Values:

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

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/report/settled/totals?bdate=-5%20days&edate=now' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Get Unsettled Batch Totals

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

The resulting report will contain these headers:

BatchNum, sub, status, totaltransNum, totaltransAmount, totalAuthNum,
totalAuthAmount, totalReturnNum, totalReturnAmount, 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, NumUnknownAuth, AmntUnknownAuth, NumUnknownReturn,
AmntUnknownReturn

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = bt
Authorizations:
basic_auth
query Parameters
batch
string
Example: batch=47

The batch number associated with the transaction

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/report/unsettled/totals' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Settle Batch

Submits transactions for funding

This operation can be scheduled to run automatically using the scheduler.

libmonetra KVS equivalent for endpoint

  • action = settle
Authorizations:
basic_auth
path Parameters
batch
required
string
Example: 47

The batch number associated with the transaction

sub
required
string
Example: 0

Route to settle

More than one might be present if split-routing is in use. For example, Credit could be sub 0 and Gift sub 1. Use the 'Unsettled Batch Totals' report to determine which sub routes need to be settled.

Note: Every account will have at least one route which is route 0.

Responses

Request samples 

curl -X POST 'https://test.transafe.com/api/v1/batch/123/settle/0' --basic -u 'test_retail|public:publ1ct3st' -d ''

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.

Warning: Unsettling and then settling again will most likely cause double charging of customers.

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = unsettlebatch
Authorizations:
basic_auth
path Parameters
batch
required
string
Example: 47

The batch number associated with the transaction

sub
required
string
Example: 0

Route to settle

More than one might be present if split-routing is in use. For example, Credit could be sub 0 and Gift sub 1. Use the 'Unsettled Batch Totals' report to determine which sub routes need to be settled.

Note: Every account will have at least one route which is route 0.

Responses

Request samples 

curl -X POST 'https://test.transafe.com/api/v1/batch/123/unsettle/0' --basic -u 'test_retail|public:publ1ct3st' -d ''

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
  • admin = imagedel
  • image_type = check
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 18446744073709551615

Transaction identifier

The transaction identifier should be treated as a string value and can be alpha, numeric, and some special characters. It should be considered in the same category as a UUID. Math or conversion should not be performed on the value and it should be stored as a string blob of characters.

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/image/19538953454/check' --basic -u 'test_retail|public:publ1ct3st'

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
  • admin = imagedel
  • image_type = signature
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 18446744073709551615

Transaction identifier

The transaction identifier should be treated as a string value and can be alpha, numeric, and some special characters. It should be considered in the same category as a UUID. Math or conversion should not be performed on the value and it should be stored as a string blob of characters.

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/image/19538953454/signature' --basic -u 'test_retail|public:publ1ct3st'

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
  • admin = imageadd
  • image_type = signature
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 18446744073709551615

Transaction identifier

The transaction identifier should be treated as a string value and can be alpha, numeric, and some special characters. It should be considered in the same category as a UUID. Math or conversion should not be performed on the value and it should be stored as a string blob of characters.

Request Body schema: application/json
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
{
  • "image": "..."
}

Response samples

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

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
  • admin = getimages
Authorizations:
basic_auth
query Parameters
ttid
string
Example: ttid=18446744073709551615

Transaction identifier

The transaction identifier should be treated as a string value and can be alpha, numeric, and some special characters. It should be considered in the same category as a UUID. Math or conversion should not be performed on the value and it should be stored as a string blob of characters.

batch
string
Example: batch=47

The batch number associated with the transaction

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

Transaction status

Values:

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

Start of date range

edate
string
Example: edate=now

End of date range

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

Image format

Values:

  • TIFF - TIFF Image
  • PNG - PNG Image
  • PBM - PBM Image

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/image?bdate=-5%20months&edate=now' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Get Transaction Images

Gets images for the specified transaction.

See List Images for report output

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = getimages
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 18446744073709551615

Transaction identifier

The transaction identifier should be treated as a string value and can be alpha, numeric, and some special characters. It should be considered in the same category as a UUID. Math or conversion should not be performed on the value and it should be stored as a string blob of characters.

query Parameters
batch
string
Example: batch=47

The batch number associated with the transaction

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

Transaction status

Values:

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

Start of date range

edate
string
Example: edate=now

End of date range

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

Image format

Values:

  • TIFF - TIFF Image
  • PNG - PNG Image
  • PBM - PBM Image

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/image/4783758439245' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Customer

Customer operations

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:

ts_created, ts_modified, 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_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

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringlist
  • recurringlist = customer
Authorizations:
basic_auth
query Parameters
id
string
Example: id=56789687564

Customer identifier

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/customer' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Add Customer

Adds a customer to the customer database for the merchant or token group

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringadd
  • recurringadd = customer
Authorizations:
basic_auth
Request Body schema: application/json
display_name
required
string <= 128 characters

Display name

name_company
string <= 128 characters

Company name

name_prefix
string <= 32 characters

Name prefix, Mr. Mrs. Ms. Dr...

Free-form field

name_first
string <= 32 characters

First name

name_middle
string <= 32 characters

Middle name

name_last
string <= 32 characters

Last name

name_suffix
string <= 32 characters

Name suffix, Jr. Sr. III...

Free-form field

phone_work
string <= 32 characters [-+0-9() .]*

Work phone

phone_home
string <= 32 characters [-+0-9() .]*

Home phone

phone_mobile
string <= 32 characters [-+0-9() .]*

Mobile phone

phone_fax
string <= 32 characters [-+0-9() .]*

Fax number

email
string <= 128 characters

email

website
string <= 128 characters

Website

business_id
string <= 32 characters

Business ID - FEIN

accounting_id
string <= 128 characters

ID used in external accounting system for customer

notes
string <= 1024 characters

General free-form information

flags
string
Enum: "TAXEXEMPT" "EMAIL_RECEIPT_RECURRING"

flags controlling behavior

Values:

  • TAXEXEMPT - Customer is non-taxable
  • EMAIL_RECEIPT_RECURRING - Send receipt email for recurring transactions. The following conditions must be met for customers to receive recurring receipt emails. + This flag must be enabled. + Customer must have an email on file. + The merchant profile must have a name configured. + The merchant profile must have a public reply email configured.
property name*
additional property
string

Responses

Request samples

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

Response samples

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

List Customer Addresses

Lists a customer's addresses

The resulting report will contain these headers:

display_name, address1, address2, city, state, country, postal_code,
delivery_notes

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringlist
  • recurringlist = customeraddress
Authorizations:
basic_auth
path Parameters
customer_id
required
string
Example: 56789687564

Customer identifier, numeric only

query Parameters
id
string
Example: id=67899767789

Customer address identifier

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/customer/19266575665036873/address' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Add Customer Address

Adds an address to a customer

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringadd
  • recurringadd = customeraddress
Authorizations:
basic_auth
path Parameters
customer_id
required
string
Example: 56789687564

Customer identifier, numeric only

Request Body schema: application/json
display_name
string <= 128 characters

Display name

address1
required
string <= 128 characters

Address line 1

address2
string <= 128 characters

Address line 2

city
string <= 128 characters

City

state
string <= 128 characters

State

country
string <= 3 characters [a-zA-Z]{0,3}

Country

ISO 3166-1 alpha-3 country code

postal_code
string

Postal code

delivery_notes
string <= 1024 characters

Delivery notes

default_billing
string
Default: "no"
Enum: "yes" "no"

Specifies whether or not this is the default billing address

Values:

  • yes - Set this address as the customer's default billing address
  • no - This is not the default billing address
default_shipping
string
Default: "no"
Enum: "yes" "no"

Specifies whether or not this is the default shipping address

Values:

  • yes - Set this address as the customer's default shipping address
  • no - This is not the default shipping address
property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "display_name": "James Dean",
  • "address1": "673 2nd St",
  • "address2": "STE 4",
  • "city": "Winter Haven",
  • "state": "FL",
  • "country": "USA",
  • "postal_code": "33839",
  • "delivery_notes": "Don't ring bell",
  • "default_billing": "yes",
  • "default_shipping": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

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

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
  • admin = recurringdel
  • recurringdel = customer
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 56789687564

Customer identifier

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/customer/19266575665036873' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Get Customer Details

Details for a specific customer

See customer list for response report details

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringlist
  • recurringlist = customer
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 56789687564

Customer identifier

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/customer/19266575665036873' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Edit Customer

Edits an existing customer

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringedit
  • recurringedit = customer
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 56789687564

Customer identifier

Request Body schema: application/json
display_name
string <= 128 characters

Display name

name_company
string <= 128 characters

Company name

name_prefix
string <= 32 characters

Name prefix, Mr. Mrs. Ms. Dr...

Free-form field

name_first
string <= 32 characters

First name

name_middle
string <= 32 characters

Middle name

name_last
string <= 32 characters

Last name

name_suffix
string <= 32 characters

Name suffix, Jr. Sr. III...

Free-form field

phone_work
string <= 32 characters [-+0-9() .]*

Work phone

phone_home
string <= 32 characters [-+0-9() .]*

Home phone

phone_mobile
string <= 32 characters [-+0-9() .]*

Mobile phone

phone_fax
string <= 32 characters [-+0-9() .]*

Fax number

email
string <= 128 characters

email

website
string <= 128 characters

Website

business_id
string <= 32 characters

Business ID - FEIN

accounting_id
string <= 128 characters

ID used in external accounting system for customer

notes
string <= 1024 characters

General free-form information

flags
string
Enum: "TAXEXEMPT" "EMAIL_RECEIPT_RECURRING"

flags controlling behavior

Values:

  • TAXEXEMPT - Customer is non-taxable
  • EMAIL_RECEIPT_RECURRING - Send receipt email for recurring transactions. The following conditions must be met for customers to receive recurring receipt emails. + This flag must be enabled. + Customer must have an email on file. + The merchant profile must have a name configured. + The merchant profile must have a public reply email configured.
default_token
string[0-9]*

Default token/payment to use

default_billing_id
string[0-9]+

Default ID of billing address in use from customer_addresses

0 means no default

default_shipping_id
string[0-9]+

Default ID of shipping address in use from customer_addresses

0 means no default

property name*
additional property
string

Responses

Request samples

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

Response samples

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

Delete Customer Address

Deletes a customer's address

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringdel
  • recurringdel = customeraddress
Authorizations:
basic_auth
path Parameters
customer_id
required
string
Example: 56789687564

Customer identifier, numeric only

id
required
string
Example: 67899767789

Customer address identifier

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/customer/19266575665036873/address/19266578682904270' --basic -u 'test_retail|public:publ1ct3st'

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

See customer address list for response report details

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringlist
  • recurringlist = customeraddress
Authorizations:
basic_auth
path Parameters
customer_id
required
string
Example: 56789687564

Customer identifier, numeric only

id
required
string
Example: 67899767789

Customer address identifier

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/customer/19266575665036873/address/19266578682904270' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Edit Customer Address

Edits an existing customer's address

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringedit
  • recurringedit = customeraddress
Authorizations:
basic_auth
path Parameters
customer_id
required
string
Example: 56789687564

Customer identifier, numeric only

id
required
string
Example: 67899767789

Customer address identifier

Request Body schema: application/json
display_name
string <= 128 characters

Display name

address1
string <= 128 characters

Address line 1

address2
string <= 128 characters

Address line 2

city
string <= 128 characters

City

state
string <= 128 characters

State

country
string <= 3 characters [a-zA-Z]{0,3}

Country

ISO 3166-1 alpha-3 country code

postal_code
string

Postal code

delivery_notes
string <= 1024 characters

Delivery notes

default_billing
string
Default: "no"
Enum: "yes" "no"

Specifies whether or not this is the default billing address

Values:

  • yes - Set this address as the customer's default billing address
  • no - This is not the default billing address
default_shipping
string
Default: "no"
Enum: "yes" "no"

Specifies whether or not this is the default shipping address

Values:

  • yes - Set this address as the customer's default shipping address
  • no - This is not the default shipping address
property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "display_name": "James Dean",
  • "address1": "673 2nd St",
  • "address2": "STE 4",
  • "city": "Winter Haven",
  • "state": "FL",
  • "country": "USA",
  • "postal_code": "33839",
  • "delivery_notes": "Don't ring bell",
  • "default_billing": "yes",
  • "default_shipping": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

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

List Customer's Tokens

Lists all stored accounts associated with this customer

The resulting report will contain these headers:

token, type, create_ts, update_ts, flags, active, cardtype, abaroute, account,
expdate, cardholdername, street, zip, descr, clientref, customer_id,
customer_display_name, amount, frequency, bdate, edate, installment_num,
installment_total, last_run_id, last_success_date, last_run_date,
next_run_date, next_run_amount

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringlist
Authorizations:
basic_auth
path Parameters
customer_id
required
string
Example: 56789687564

Customer identifier, numeric only

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/customer/19266575665036873/tokens' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Merchant

Merchant operations

Change Password

Changes the user's password

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = chngpwd
Authorizations:
basic_auth
Request Body schema: application/json
pwd
required
string <= 256 characters

New password

Responses

Request samples

Content type
application/json
{
  • "pwd": "sTnn56Wve79&#%q#K4GF9Z"
}

Response samples

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

Check Password

Verifies the current user's password

Response will not differentiate between an invalid user and a bad password

libmonetra KVS equivalent for endpoint

  • action = chkpwd
Authorizations:
basic_auth

Responses

Request samples 

curl -X POST 'https://test.transafe.com/api/v1/merchant/password' --basic -u 'test_retail|public:publ1ct3st' -d ''

Response samples

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

Get Merchant Configuration

Gets the merchant's configuration

The resulting report will contain these headers:

cardtype, auth_proc, settle_proc, auth_merchid, settle_merchid, auth_sub,
settle_sub, indcode, trantypes, emv, mac_required, gift_binrange, can_standin,
auth_procfeatures, settle_procfeatures

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = merchinfo
Authorizations:
basic_auth

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/merchant/configuration' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Get Merchant Information

Gets the merchant's information

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = merchinfo
  • merchinfo = termparams
Authorizations:
basic_auth

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/merchant/info' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "merch_name": "Pizza Palace",
  • "merch_addr1": "777 77th Ct",
  • "merch_addr2": "Jacksonville FL",
  • "merch_addr3": "32789",
  • "merch_phone": "555-555-5555",
  • "merch_email": "merchant@email",
  • "merch_url": "https://url",
  • "merch_proc": "loopback",
  • "countrycode": "840",
  • "currencycode": "840",
  • "property1": "string",
  • "property2": "string"
}

Get Permissions

Gets the user's permissions

The resulting report will contain these headers:

trantypes, admintypes, userflags, obscure, unattended

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = getperms
Authorizations:
basic_auth

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/merchant/permissions' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Inventory

Inventory operations

List Categories

List inventory categories

The resulting report will contain these headers:

id, timestamp_ms, is_deleted, name, description, sortorder

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodlist
  • json = false
  • prodlist = category
Authorizations:
basic_auth
query Parameters
id
string
Example: id=567896543

Unique ID of the category

name
string
Example: name=Fruit

Name of the category

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/inventory/category' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "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
  • admin = prodmanage
  • prodmanage = category_add
Authorizations:
basic_auth
Request Body schema: application/json
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
{
  • "name": "Fruit",
  • "description": "Fruits",
  • "sortorder": "7"
}

Response samples

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

Get Category Discounts

Gets discounts for the given category.

See List Stored Discounts for report output

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodlist
  • json = false
  • prodlist = discount
Authorizations:
basic_auth
path Parameters
category_id
required
string
Example: 567896543

Unique ID of the product category

query Parameters
id
string
Example: id=834678965675

Unique ID of the discount

name
string
Example: name=$5 Off

Name of the discount

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/inventory/category/1873893758493/discount' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "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
  • admin = prodmanage
  • prodmanage = discount_add
Authorizations:
basic_auth
path Parameters
category_id
required
string
Example: 567896543

Unique ID of the product category

Request Body schema: application/json
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
{
  • "name": "$5 Off",
  • "description": "$5 off promotion",
  • "type": "fixed",
  • "usecase": "order",
  • "amount": "5.00",
  • "sortorder": "7"
}

Response samples

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

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
  • admin = prodmanage
  • prodmanage = modifier_add
Authorizations:
basic_auth
path Parameters
modifierset_id
required
string
Example: 6756394857674839

Unique ID of the modifier set

Request Body schema: application/json
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
{
  • "name": "Pepperoni",
  • "description": "Pepperoni pizza topping",
  • "price": "25.00",
  • "unit": "1",
  • "sortorder": "7"
}

Response samples

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

List Modifier Sets

List inventory modifier sets

The resulting report will contain these headers:

id, name, timestamp_ms, description, multiselect, maxselect

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodlist
  • json = false
  • prodlist = modifierset
Authorizations:
basic_auth
query Parameters
id
string
Example: id=6756394857674839

Unique ID of the modifier set

name
string
Example: name=Toppings

Name of the modifier set

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/product/modifierset' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "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
  • admin = prodmanage
  • prodmanage = modifierset_add
Authorizations:
basic_auth
Request Body schema: application/json
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
{
  • "name": "Toppings",
  • "description": "Pizza toppings",
  • "multiselect": "no",
  • "maxselect": "5"
}

Response samples

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

List Products

List inventory products

The resulting report will contain these headers:

id, name, timestamp_ms, category_id, taxrates, modifiersets,
description, commoditycode, unit, req_modifiersets, sortorder,
image_type

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodlist
  • json = false
  • prodlist = product
Authorizations:
basic_auth
query Parameters
id
string
Example: id=6789646596763

Unique ID of the product

name
string
Example: name=Large pizza

Name of the product

category_id
string
Example: category_id=567896543

Unique ID of the product category

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

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

Include base64-encoded image data

Values:

  • yes - Return image data
  • no - Do not return image data

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/inventory/product' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "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
  • admin = prodmanage
  • prodmanage = product_add
Authorizations:
basic_auth
Request Body schema: application/json
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
{
  • "name": "Large pizza",
  • "category_id": "567896543",
  • "description": "A really big pizza",
  • "taxrates": "5654367654",
  • "modifiersets": "65789837657843,1456543456,14567876543",
  • "req_modifiersets": "6578943,456543",
  • "commoditycode": "50301700",
  • "unit": "1",
  • "sortorder": "7",
  • "image_data": "ABC="
}

Response samples

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

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
  • admin = prodmanage
  • prodmanage = sku_add
Authorizations:
basic_auth
path Parameters
product_id
required
string
Example: 6789646596763

Unique ID of the product

Request Body schema: application/json
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
{
  • "name": "Large hand tossed",
  • "price": "25.00",
  • "inventory": "unlimited",
  • "barcode": "015000071356",
  • "description": "Large hand tossed pizza",
  • "sortorder": "7"
}

Response samples

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

List Tax Rates

List inventory tax rates

The resulting report will contain these headers:

id, name, timestamp_ms, percentage, default, roundmethod, sortorder

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodlist
  • json = false
  • prodlist = taxrate
Authorizations:
basic_auth
query Parameters
id
string
Example: id=65748376543

Unique ID of the tax rate

name
string
Example: name=County tax

Name of the tax rate

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/inventory/taxrate' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "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
  • admin = prodmanage
  • prodmanage = taxrate_add
Authorizations:
basic_auth
Request Body schema: application/json
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
{
  • "name": "County tax",
  • "percentage": "1.254",
  • "default": "yes",
  • "roundmethod": "normal",
  • "sortorder": "7"
}

Response samples

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

Delete Category

Delete an inventory category

The category must be empty.

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodmanage
  • prodmanage = category_del
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 567896543

Unique ID of the category

query Parameters
timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/inventory/category/20120539065950458?timestamp_ms=1588258706031'

Response samples

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

Get Category Detail

Gets details for the specified category.

See List Stored Categories for report output

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodlist
  • json = false
  • prodlist = category
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 567896543

Unique ID of the category

query Parameters
name
string
Example: name=Fruit

Name of the category

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/inventory/category/1588258706031' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Edit Category

Edit an inventory category

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodmanage
  • prodmanage = category_edit
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 567896543

Unique ID of the category

Request Body schema: application/json
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
{
  • "timestamp_ms": "1653340525",
  • "name": "Fruit",
  • "description": "Fruits",
  • "sortorder": "7"
}

Response samples

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

Delete Discount

Delete an inventory category discount

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodmanage
  • prodmanage = discount_del
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 834678965675

Unique ID of the discount

query Parameters
timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/inventory/category/discount/26863859502458458?timestamp_ms=1588258706031'

Response samples

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

Get Discount Detail

Gets details for the specified discount.

See List Stored Discounts for report output

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodlist
  • json = false
  • prodlist = discount
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 834678965675

Unique ID of the discount

query Parameters
name
string
Example: name=$5 Off

Name of the discount

category_id
string
Example: category_id=567896543

Unique ID of the product category

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/inventory/category/discount/1588258706031' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Edit Discount

Edit an inventory category discount

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodmanage
  • prodmanage = discount_edit
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 834678965675

Unique ID of the discount

Request Body schema: application/json
timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

category_id
string\d+

Unique ID of the product category

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

Response samples

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

Delete Modifier

Delete an inventory modifier

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodmanage
  • prodmanage = modifier_del
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 39836566395734

Unique ID of the modifier

query Parameters
timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/inventory/modifierset/modifier/82859028592849248?timestamp_ms=1895849024551'

Response samples

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

Get Modifier Detail

Gets details for the specified modifier.

See List Stored Modifiers for report output

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodlist
  • json = false
  • prodlist = modifier
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 39836566395734

Unique ID of the modifier

query Parameters
name
string
Example: name=Pepperoni

Name of the modifier

modifierset_id
string
Example: modifierset_id=6756394857674839

Unique ID of the modifier set

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/inventory/modifier/1588258706031' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Edit Modifier

Edit an inventory modifier

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodmanage
  • prodmanage = modifier_edit
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 39836566395734

Unique ID of the modifier

Request Body schema: application/json
timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

modifierset_id
string\d+

Unique ID of the modifier set

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

Response samples

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

Delete Modifier Set

Delete an inventory modifier set

The modifier set must be empty.

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodmanage
  • prodmanage = modifierset_del
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 6756394857674839

Unique ID of the modifier set

query Parameters
timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/inventory/modifierset/84578903855643344?timestamp_ms=1895849024551'

Response samples

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

Edit Modifier Set

Edit an inventory modifier set

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodmanage
  • prodmanage = modifierset_edit
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 6756394857674839

Unique ID of the modifier set

Request Body schema: application/json
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
{
  • "timestamp_ms": "1653340525",
  • "name": "Toppings",
  • "description": "Pizza toppings",
  • "multiselect": "no",
  • "maxselect": "5"
}

Response samples

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

Delete Product

Delete an inventory product

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodmanage
  • prodmanage = product_del
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 6789646596763

Unique ID of the product

query Parameters
timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/inventory/product/27589475894035458?timestamp_ms=1588258706031'

Response samples

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

Get Product Detail

Gets details for the specified product.

See List Stored products for report output

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodlist
  • json = false
  • prodlist = product
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 6789646596763

Unique ID of the product

query Parameters
name
string
Example: name=Large pizza

Name of the product

category_id
string
Example: category_id=567896543

Unique ID of the product category

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

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

Include base64-encoded image data

Values:

  • yes - Return image data
  • no - Do not return image data

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/inventory/product/1758939453334' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Edit Product

Edit an inventory product

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodmanage
  • prodmanage = product_edit
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 6789646596763

Unique ID of the product

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

Response samples

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

Delete SKU

Delete an inventory product SKU

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodmanage
  • prodmanage = sku_del
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 5784936543

Unique ID of the SKU

query Parameters
timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/inventory/product/sku/13748493859345458?timestamp_ms=57849320845'

Response samples

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

Get SKU Detail

Gets details for the specified SKU.

See List Stored SKUs for report output

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodlist
  • json = false
  • prodlist = sku
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 5784936543

Unique ID of the SKU

query Parameters
name
string
Example: name=Large hand tossed

Name of the SKU

product_id
string
Example: product_id=6789646596763

Unique ID of the product

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

Whether the in stock status should be evaulated as a condition

Values:

  • yes - Only return in-stock skus
  • no - Only return out-of-stock skus
timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/inventory/sku/1588258706031' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Edit SKU

Edit an inventory product SKU

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodmanage
  • prodmanage = sku_edit
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 5784936543

Unique ID of the SKU

Request Body schema: application/json
timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

product_id
string\d+

Unique ID of the product

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

Response samples

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

Delete Tax Rate

Delete an inventory tax rate

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodmanage
  • prodmanage = taxrate_del
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 65748376543

Unique ID of the tax rate

query Parameters
timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/inventory/taxrate/14859438593544438?timestamp_ms=1859386643324'

Response samples

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

Get Tax Rate Detail

Gets details for the specified tax rate.

See List Stored tax rates for report output

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodlist
  • json = false
  • prodlist = taxrate
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 65748376543

Unique ID of the tax rate

query Parameters
name
string
Example: name=County tax

Name of the tax rate

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/inventory/taxrate/1588258706031' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Edit Tax Rate

Edit an inventory tax rate

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodmanage
  • prodmanage = taxrate_edit
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 65748376543

Unique ID of the tax rate

Request Body schema: application/json
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
{
  • "timestamp_ms": "1653340525",
  • "name": "County tax",
  • "percentage": "1.254",
  • "default": "yes",
  • "roundmethod": "normal",
  • "sortorder": "7"
}

Response samples

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

List Discounts

List inventory category discounts

The resulting report will contain these headers:

id, name, timestamp_ms, category_id, description, type,
usecase, amount, sortorder

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodlist
  • json = false
  • prodlist = discount
Authorizations:
basic_auth
query Parameters
id
string
Example: id=834678965675

Unique ID of the discount

name
string
Example: name=$5 Off

Name of the discount

category_id
string
Example: category_id=567896543

Unique ID of the product category

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/inventory/category/discount' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Get Modifier Set Detail

Gets details for the specified modifier set.

See List Stored Modifier Sets for report output

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodlist
  • json = false
  • prodlist = modifierset
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 6756394857674839

Unique ID of the modifier set

query Parameters
name
string
Example: name=Toppings

Name of the modifier set

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/product/modifierset/1588258706031' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

List Modifiers

List inventory modifiers

The resulting report will contain these headers:

id, name, timestamp_ms, modifierset_id, description, price,
commoditycode, unit, sortorder

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodlist
  • json = false
  • prodlist = modifier
Authorizations:
basic_auth
query Parameters
id
string
Example: id=39836566395734

Unique ID of the modifier

name
string
Example: name=Pepperoni

Name of the modifier

modifierset_id
string
Example: modifierset_id=6756394857674839

Unique ID of the modifier set

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/inventory/modifierset/modifier' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Get Modifier Set Modifiers

Gets modifiers for a given modifier set.

See List Stored Modifiers for report output

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodlist
  • json = false
  • prodlist = modifier
Authorizations:
basic_auth
path Parameters
modifierset_id
required
string
Example: 6756394857674839

Unique ID of the modifier set

query Parameters
id
string
Example: id=39836566395734

Unique ID of the modifier

name
string
Example: name=Pepperoni

Name of the modifier

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/inventory/modifierset/1588258706031/modifiers' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

List SKUs

List inventory product SKUs

The resulting report will contain these headers:

id, name, timestamp_ms, product_id, barcode, description,
price, sortorder, in_stock

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodlist
  • json = false
  • prodlist = sku
Authorizations:
basic_auth
query Parameters
id
string
Example: id=5784936543

Unique ID of the SKU

name
string
Example: name=Large hand tossed

Name of the SKU

product_id
string
Example: product_id=6789646596763

Unique ID of the product

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

Whether the in stock status should be evaulated as a condition

Values:

  • yes - Only return in-stock skus
  • no - Only return out-of-stock skus
timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/inventory/product/sku' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Get Product SKUs

Gets SKUs for a given product.

See List Stored SKUs for report output

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodlist
  • json = false
  • prodlist = sku
Authorizations:
basic_auth
path Parameters
product_id
required
string
Example: 6789646596763

Unique ID of the product

query Parameters
id
string
Example: id=5784936543

Unique ID of the SKU

name
string
Example: name=Large hand tossed

Name of the SKU

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

Whether the in stock status should be evaulated as a condition

Values:

  • yes - Only return in-stock skus
  • no - Only return out-of-stock skus
timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/inventory/product/1588258706031/skus' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Set SKU Quantity

Set the quantity for SKU

Tracking for the number of items in stock

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = prodmanage
  • prodmanage = inventory_set
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 5784936543

Unique ID of the SKU

Request Body schema: application/json
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
{
  • "timestamp_ms": "1653340525",
  • "cnt": "17"
}

Response samples

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

Order

Order operations

Add a Cash Payment

Add a cash payment to the order

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = ordermanage
  • ordermanage = payment_add
  • tendertype = CASH
Authorizations:
basic_auth
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
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
{
  • "amount": "19.92",
  • "tip": "0.33"
}

Response samples

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

Add a Check Payment

Add a check payment to the order

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = ordermanage
  • ordermanage = payment_add
  • tendertype = CHECK
Authorizations:
basic_auth
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
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
{
  • "amount": "19.92",
  • "tip": "0.33",
  • "checknum": "45678"
}

Response samples

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

Add a 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
  • admin = ordermanage
  • ordermanage = item_add
  • ref_id = 0
  • type = DISCOUNT_FIXED
Authorizations:
basic_auth
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

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

Response samples

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

Add a Custom 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
  • admin = ordermanage
  • ordermanage = item_add
  • ref_id = 0
  • type = ADDON
Authorizations:
basic_auth
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

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

Response samples

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

Add 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
  • admin = ordermanage
  • ordermanage = modifier_add
  • ref_id = 0
  • type = DISCOUNT_FIXED
Authorizations:
basic_auth
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
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
{
  • "ringorder": "2",
  • "qty": "1",
  • "amount": "199.95",
  • "name": "10% off"
}

Response samples

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

Add a Custom Item 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
  • admin = ordermanage
  • ordermanage = modifier_add
  • ref_id = 0
  • type = ADDON
Authorizations:
basic_auth
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
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
{
  • "ringorder": "2",
  • "qty": "1",
  • "amount": "199.95",
  • "name": "Extra veggies"
}

Response samples

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

Add 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
  • admin = ordermanage
  • ordermanage = modifier_add
  • ref_id = 0
  • type = DISCOUNT_PERCENT
Authorizations:
basic_auth
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
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
{
  • "ringorder": "2",
  • "qty": "1",
  • "amount": "199.95",
  • "name": "10% off"
}

Response samples

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

Add a Custom 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
  • admin = ordermanage
  • ordermanage = item_add
  • ref_id = 0
  • type = DISCOUNT_PERCENT
Authorizations:
basic_auth
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

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

Response samples

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

Add a Fixed Discount

Add a fixed amount discount to the order

The discount references a discount from the inventory system.

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = ordermanage
  • ordermanage = item_add
  • type = DISCOUNT_FIXED
Authorizations:
basic_auth
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
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
{
  • "ref_id": "765432",
  • "ringorder": "2",
  • "qty": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

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

List Payments

List order payments

Gets the Payments for the specified order.

The resulting report will contain these headers:

id, timestamp_ms, order_id, tendertype, amount, tip, status, ttid,
cardtype, last4, cardholdername, checknum, is_deleted

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = orderlist
  • json = no
  • orderlist = payments
Authorizations:
basic_auth
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
id
string
Example: id=987653645678

Unique ID of a payment for an order

customer_id
string
Example: customer_id=54345,567043,31567

Comma separated list of customer identifiers

ordernum
string
Example: ordernum=A13DDES345

Order number

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

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

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

type
object
Enum: "ORDER" "QUICK" "INVOICE"
Example: type=ORDER,QUICK

Comma separated list of order types

Flag values (comma separated):

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
object
Enum: "PENDING" "OPEN" "PARTIALPAID" "COMPLETE" "CANCEL" "FORCECLOSED"
Example: status=OPEN,PARTIALPAID

Comma separated list of order status

Flag values (comma separated):

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
  • PARTIALPAID - Order has been partially paid
  • COMPLETE - Order is complete
  • CANCEL - Order has been canceled
  • FORCECLOSED - Order was force closed
timestamp_create_bdate
string
Example: timestamp_create_bdate=1653406830

Start of order created date range as a timestamp

timestamp_create_edate
string
Example: timestamp_create_edate=1653406830

End of order created date range as a timestamp

timestamp_close_bdate
string
Example: timestamp_close_bdate=1653406830

Start of order closed date range as a timestamp

timestamp_close_edate
string
Example: timestamp_close_edate=1653406830

End of order closed date range as a timestamp

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/order/5784392456/payment' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Add a Payment

Add a payment to the order

References an existing transaction.

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = ordermanage
  • ordermanage = payment_add
  • tendertype = TXN
Authorizations:
basic_auth
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
ttid
required
string [ 1 .. 38 ] characters [a-zA-Z0-9+ _-{}]{1,38}

Transaction identifier

The transaction identifier should be treated as a string value and can be alpha, numeric, and some special characters. It should be considered in the same category as a UUID. Math or conversion should not be performed on the value and it should be stored as a string blob of characters.

Responses

Request samples

Content type
application/json
{
  • "ttid": "18446744073709551615"
}

Response samples

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

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
  • admin = ordermanage
  • ordermanage = item_add
  • type = DISCOUNT_PERCENT
Authorizations:
basic_auth
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
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
{
  • "ref_id": "765432",
  • "ringorder": "2",
  • "qty": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

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

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
  • admin = orderlist
  • json = no
  • orderlist = items
Authorizations:
basic_auth
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
id
string
Example: id=785676543

Order item identifier

customer_id
string
Example: customer_id=54345,567043,31567

Comma separated list of customer identifiers

ordernum
string
Example: ordernum=A13DDES345

Order number

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

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

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

type
object
Enum: "ORDER" "QUICK" "INVOICE"
Example: type=ORDER,QUICK

Comma separated list of order types

Flag values (comma separated):

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
object
Enum: "PENDING" "OPEN" "PARTIALPAID" "COMPLETE" "CANCEL" "FORCECLOSED"
Example: status=OPEN,PARTIALPAID

Comma separated list of order status

Flag values (comma separated):

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
  • PARTIALPAID - Order has been partially paid
  • COMPLETE - Order is complete
  • CANCEL - Order has been canceled
  • FORCECLOSED - Order was force closed
timestamp_create_bdate
string
Example: timestamp_create_bdate=1653406830

Start of order created date range as a timestamp

timestamp_create_edate
string
Example: timestamp_create_edate=1653406830

End of order created date range as a timestamp

timestamp_close_bdate
string
Example: timestamp_close_bdate=1653406830

Start of order closed date range as a timestamp

timestamp_close_edate
string
Example: timestamp_close_edate=1653406830

End of order closed date range as a timestamp

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/order/7589432567654/item' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "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
  • admin = ordermanage
  • ordermanage = item_add
  • type = ADDON
Authorizations:
basic_auth
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
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
{
  • "ref_id": "86956395206",
  • "ringorder": "2",
  • "qty": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

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

Add an Item Fixed Discount

Add a fixed discount to a line item

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = ordermanage
  • ordermanage = modifier_add
  • type = DISCOUNT_FIXED
Authorizations:
basic_auth
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
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
{
  • "ref_id": "15676543",
  • "ringorder": "2",
  • "qty": "1"
}

Response samples

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

List Order Item Modifiers

List order item modifiers

Gets modifiers for the specified item.

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
  • admin = orderlist
  • json = no
  • orderlist = modifiers
Authorizations:
basic_auth
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
id
string
Example: id=63676598

Order item modifier identifier

customer_id
string
Example: customer_id=54345,567043,31567

Comma separated list of customer identifiers

ordernum
string
Example: ordernum=A13DDES345

Order number

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

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

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

type
object
Enum: "ORDER" "QUICK" "INVOICE"
Example: type=ORDER,QUICK

Comma separated list of order types

Flag values (comma separated):

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
object
Enum: "PENDING" "OPEN" "PARTIALPAID" "COMPLETE" "CANCEL" "FORCECLOSED"
Example: status=OPEN,PARTIALPAID

Comma separated list of order status

Flag values (comma separated):

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
  • PARTIALPAID - Order has been partially paid
  • COMPLETE - Order is complete
  • CANCEL - Order has been canceled
  • FORCECLOSED - Order was force closed
timestamp_create_bdate
string
Example: timestamp_create_bdate=1653406830

Start of order created date range as a timestamp

timestamp_create_edate
string
Example: timestamp_create_edate=1653406830

End of order created date range as a timestamp

timestamp_close_bdate
string
Example: timestamp_close_bdate=1653406830

Start of order closed date range as a timestamp

timestamp_close_edate
string
Example: timestamp_close_edate=1653406830

End of order closed date range as a timestamp

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/order/item/7584933567654/modifier' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Add an Item Modifier

Add an item modifier to a line item

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = ordermanage
  • ordermanage = modifier_add
  • type = ADDON
Authorizations:
basic_auth
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
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
{
  • "ref_id": "46789525",
  • "ringorder": "2",
  • "qty": "1"
}

Response samples

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

Add an Item Percent Discount

Add a percent discount to a line item

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = ordermanage
  • ordermanage = modifier_add
  • type = DISCOUNT_PERCENT
Authorizations:
basic_auth
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
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
{
  • "ref_id": "15676543",
  • "ringorder": "2",
  • "qty": "1"
}

Response samples

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

Cancel a Payment

Cancels a cash or check payment associated with the order

A transaction that was applied to the order cannot be canceled directly. It must be reversed which will atomically mark it as canceled in the order.

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = ordermanage
  • ordermanage = payment_cancel
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 987653645678

Unique ID of a payment for an order

order_id
required
string
Example: 58445676543

Unique ID of an order

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/order/20245528771333405/payment/758493245430' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Get Payment Detail

Gets details for the specified payment.

See List Payments for report output

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = orderlist
  • json = no
  • orderlist = payments
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 987653645678

Unique ID of a payment for an order

order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
customer_id
string
Example: customer_id=54345,567043,31567

Comma separated list of customer identifiers

ordernum
string
Example: ordernum=A13DDES345

Order number

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

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

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

type
object
Enum: "ORDER" "QUICK" "INVOICE"
Example: type=ORDER,QUICK

Comma separated list of order types

Flag values (comma separated):

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
object
Enum: "PENDING" "OPEN" "PARTIALPAID" "COMPLETE" "CANCEL" "FORCECLOSED"
Example: status=OPEN,PARTIALPAID

Comma separated list of order status

Flag values (comma separated):

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
  • PARTIALPAID - Order has been partially paid
  • COMPLETE - Order is complete
  • CANCEL - Order has been canceled
  • FORCECLOSED - Order was force closed
timestamp_create_bdate
string
Example: timestamp_create_bdate=1653406830

Start of order created date range as a timestamp

timestamp_create_edate
string
Example: timestamp_create_edate=1653406830

End of order created date range as a timestamp

timestamp_close_bdate
string
Example: timestamp_close_bdate=1653406830

Start of order closed date range as a timestamp

timestamp_close_edate
string
Example: timestamp_close_edate=1653406830

End of order closed date range as a timestamp

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/order/payment/758493245430' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

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
  • admin = ordermanage
  • ordermanage = order_cancel
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 58445676543

Order identifier, numeric only

Request Body schema: application/json
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
{
  • "cancel_reason": "RETURN",
  • "timestamp_ms": "1653340525"
}

Response samples

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

List Orders

List orders

The resulting report will contain these headers:

id, timestamp_ms, 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, notes, total_tax_override,
ship_name, ship_address1, ship_address2, ship_city, ship_state,
ship_zip, ship_country, ship_notes, invoice_filename, is_deleted

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = orderlist
  • json = no
  • orderlist = orders
Authorizations:
basic_auth
query Parameters
id
string
Example: id=58445676543

Order identifier, numeric only

customer_id
string
Example: customer_id=54345,567043,31567

Comma separated list of customer identifiers

ordernum
string
Example: ordernum=A13DDES345

Order number

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

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

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

type
object
Enum: "ORDER" "QUICK" "INVOICE"
Example: type=ORDER,QUICK

Comma separated list of order types

Flag values (comma separated):

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
object
Enum: "PENDING" "OPEN" "PARTIALPAID" "COMPLETE" "CANCEL" "FORCECLOSED"
Example: status=OPEN,PARTIALPAID

Comma separated list of order status

Flag values (comma separated):

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
  • PARTIALPAID - Order has been partially paid
  • COMPLETE - Order is complete
  • CANCEL - Order has been canceled
  • FORCECLOSED - Order was force closed
timestamp_create_bdate
string
Example: timestamp_create_bdate=1653406830

Start of order created date range as a timestamp

timestamp_create_edate
string
Example: timestamp_create_edate=1653406830

End of order created date range as a timestamp

timestamp_close_bdate
string
Example: timestamp_close_bdate=1653406830

Start of order closed date range as a timestamp

timestamp_close_edate
string
Example: timestamp_close_edate=1653406830

End of order closed date range as a timestamp

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

Include base64-encoded invoice data

Applies to invoices with external (PDF) invoice documents.

Values:

  • yes - Return invoice data
  • no - Do not return invoice data
timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

rcpt_email
string
Example: rcpt_email=email@email

Email to send customer invoice or order information to

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

Will send a link to view and pay the invoice/order if open. Otherwise, will send a link to the completed order with the invoice/order and any payment receipts.

Requires a single order id to be specified.

rcpt_sms
string
Example: rcpt_sms=555-555-5555

SMS to send customer invoice or order information to

Will send a link to view and pay the invoice/order if open. Otherwise, will send a link to the completed order with the invoice/order and any payment receipts.

Can be a 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 a single order id to be specified.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/order' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Create an Order or Invoice

Create an order or invoice

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = ordermanage
  • ordermanage = order_add
Authorizations:
basic_auth
Request Body schema: application/json
type
required
string
Enum: "ORDER" "QUICK" "INVOICE"

Type of order

Values:

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
required
string
Enum: "PENDING" "OPEN"

Status of the order

Values:

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
flags
string
Value: "NOTIP"

Type of order

Flag values (pipe separated):

  • NOTIP - Do not attempt to perform tip prompting when collecting payment
merch_status
string
Enum: "PENDING" "COMPLETE" "PREPARING" "BACKORDERED"

Merchant status of the order

Values:

  • PENDING - Order is pending
  • COMPLETE - Order is complete
  • PREPARING - Order is being prepared
  • BACKORDERED - Order is delayed while waiting for back ordered items
customer_id
string[0-9]+

Customer identifier, numeric only

Required when type = Invoice

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

Order number

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

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

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

ponumber
string <= 32 characters

Unique identifier of the order

Typically used with Invoices

allowed_cardtypes
string
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "CUP" "GIFT" "ACH"

Card types allowed to be used for payment

Pipe-separated (|) list of cardtypes accepted for payment. Merchant must be configured to accept the provided cardtypes. Defaults to allow all if not provided.

This is typically used in conjunction with accepting payment online using the 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

total_tax_override
string0?\.\d{2}

Tax override amount, only used if all line items have no tax rates

ship_name
string <= 32 characters

Shipping name of recipient

"To" field on shipping label.

ship_address1
string <= 32 characters

Shipping street address of recipient

Line 1

ship_address2
string <= 32 characters

Shipping street address of recipient

Line 2

ship_city
string <= 32 characters

Shipping city of recipient

ship_state
string <= 32 characters

Shipping state / provence of recipient

ship_zip
string <= 32 characters

Shipping zip / postal Code of recipient

Used for tax zones

ship_country
string <= 32 characters

Shipping country of recipient

ship_notes
string <= 128 characters

Shipping delivery instructions

invoice_filename
string <= 32 characters

Filename of externally attached invoice PDF

Requires:

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

PDF base64 encoded invoice PDF

Used for externally generated invoice billing.

Max file size is 512 KB.

Responses

Request samples

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

Response samples

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

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
  • admin = ordermanage
  • ordermanage = order_del
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 58445676543

Order identifier, numeric only

query Parameters
timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/order/1456543256' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Get Order Detail

Gets details for the specified order.

See List Orders for report output

Can be used to send receipt email or sms

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = orderlist
  • json = no
  • orderlist = orders
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 58445676543

Order identifier, numeric only

query Parameters
customer_id
string
Example: customer_id=54345,567043,31567

Comma separated list of customer identifiers

ordernum
string
Example: ordernum=A13DDES345

Order number

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

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

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

type
object
Enum: "ORDER" "QUICK" "INVOICE"
Example: type=ORDER,QUICK

Comma separated list of order types

Flag values (comma separated):

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
object
Enum: "PENDING" "OPEN" "PARTIALPAID" "COMPLETE" "CANCEL" "FORCECLOSED"
Example: status=OPEN,PARTIALPAID

Comma separated list of order status

Flag values (comma separated):

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
  • PARTIALPAID - Order has been partially paid
  • COMPLETE - Order is complete
  • CANCEL - Order has been canceled
  • FORCECLOSED - Order was force closed
timestamp_create_bdate
string
Example: timestamp_create_bdate=1653406830

Start of order created date range as a timestamp

timestamp_create_edate
string
Example: timestamp_create_edate=1653406830

End of order created date range as a timestamp

timestamp_close_bdate
string
Example: timestamp_close_bdate=1653406830

Start of order closed date range as a timestamp

timestamp_close_edate
string
Example: timestamp_close_edate=1653406830

End of order closed date range as a timestamp

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

Include base64-encoded invoice data

Applies to invoices with external (PDF) invoice documents.

Values:

  • yes - Return invoice data
  • no - Do not return invoice data
timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

rcpt_email
string
Example: rcpt_email=email@email

Email to send customer invoice or order information to

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

Will send a link to view and pay the invoice/order if open. Otherwise, will send a link to the completed order with the invoice/order and any payment receipts.

Requires a single order id to be specified.

rcpt_sms
string
Example: rcpt_sms=555-555-5555

SMS to send customer invoice or order information to

Will send a link to view and pay the invoice/order if open. Otherwise, will send a link to the completed order with the invoice/order and any payment receipts.

Can be a 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 a single order id to be specified.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/order/789567654256' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Edit an Order or Invoice

Edit and order or invoice

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = ordermanage
  • ordermanage = order_edit
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 58445676543

Order identifier, numeric only

Request Body schema: application/json
type
string
Enum: "ORDER" "QUICK" "INVOICE"

Type of order

Values:

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
string
Enum: "PENDING" "OPEN"

Status of the order

Values:

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
flags
string
Value: "NOTIP"

Type of order

Flag values (pipe separated):

  • NOTIP - Do not attempt to perform tip prompting when collecting payment
merch_status
string
Enum: "PENDING" "COMPLETE" "PREPARING" "BACKORDERED"

Merchant status of the order

Values:

  • PENDING - Order is pending
  • COMPLETE - Order is complete
  • PREPARING - Order is being prepared
  • BACKORDERED - Order is delayed while waiting for back ordered items
customer_id
string[0-9]+

Customer identifier, numeric only

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

Order number

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

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

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

ponumber
string <= 32 characters

Unique identifier of the order

Typically used with Invoices

allowed_cardtypes
string
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "CUP" "GIFT" "ACH"

Card types allowed to be used for payment

Pipe-separated (|) list of cardtypes accepted for payment. Merchant must be configured to accept the provided cardtypes. Defaults to allow all if not provided.

This is typically used in conjunction with accepting payment online using the 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

total_tax_override
string0?\.\d{2}

Tax override amount, only used if all line items have no tax rates

ship_name
string <= 32 characters

Shipping name of recipient

"To" field on shipping label.

ship_address1
string <= 32 characters

Shipping street address of recipient

Line 1

ship_address2
string <= 32 characters

Shipping street address of recipient

Line 2

ship_city
string <= 32 characters

Shipping city of recipient

ship_state
string <= 32 characters

Shipping state / provence of recipient

ship_zip
string <= 32 characters

Shipping zip / postal Code of recipient

Used for tax zones

ship_country
string <= 32 characters

Shipping country of recipient

ship_notes
string <= 128 characters

Shipping delivery instructions

invoice_filename
string <= 32 characters

Filename of externally attached invoice PDF

Requires:

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

PDF base64 encoded invoice PDF

Used for externally generated invoice billing.

Max file size is 512 KB.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

Responses

Request samples

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

Response samples

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

Remove a Discount

Remove a discount form an order

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = ordermanage
  • ordermanage = item_del
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 67876547364567

Order discount identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/order/20245528771333405/discount/5894387586' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Edit a Discount

Edit a discount for an order

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = ordermanage
  • ordermanage = item_edit
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 67876547364567

Order discount identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
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
{
  • "timestamp_ms": "1653340525",
  • "ringorder": "2",
  • "qty": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

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

Remove an Item

Remove a line item form an order

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = ordermanage
  • ordermanage = item_del
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/order/item/675894315' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Get Item Detail

Gets details for the specified Item.

See List Items for report output

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = orderlist
  • json = no
  • orderlist = items
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
customer_id
string
Example: customer_id=54345,567043,31567

Comma separated list of customer identifiers

ordernum
string
Example: ordernum=A13DDES345

Order number

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

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

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

type
object
Enum: "ORDER" "QUICK" "INVOICE"
Example: type=ORDER,QUICK

Comma separated list of order types

Flag values (comma separated):

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
object
Enum: "PENDING" "OPEN" "PARTIALPAID" "COMPLETE" "CANCEL" "FORCECLOSED"
Example: status=OPEN,PARTIALPAID

Comma separated list of order status

Flag values (comma separated):

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
  • PARTIALPAID - Order has been partially paid
  • COMPLETE - Order is complete
  • CANCEL - Order has been canceled
  • FORCECLOSED - Order was force closed
timestamp_create_bdate
string
Example: timestamp_create_bdate=1653406830

Start of order created date range as a timestamp

timestamp_create_edate
string
Example: timestamp_create_edate=1653406830

End of order created date range as a timestamp

timestamp_close_bdate
string
Example: timestamp_close_bdate=1653406830

Start of order closed date range as a timestamp

timestamp_close_edate
string
Example: timestamp_close_edate=1653406830

End of order closed date range as a timestamp

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/order/item/8594387568950432' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Edit an Item

Edit a line item for an order

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = ordermanage
  • ordermanage = item_edit
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
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
{
  • "timestamp_ms": "1653340525",
  • "ringorder": "2",
  • "qty": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

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

Remove an Item Discount

Remove a discount from a line item in the order

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = ordermanage
  • ordermanage = modifier_del
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 24566437

Order item discount identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

item_id
required
string
Example: 785676543

Order item identifier

query Parameters
timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/order/item/discount/76789625' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Edit an Item Discount

Edit a line item discount

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = ordermanage
  • ordermanage = modifier_edit
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 24566437

Order item discount identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

item_id
required
string
Example: 785676543

Order item identifier

Request Body schema: application/json
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
{
  • "timestamp_ms": "1653340525",
  • "ringorder": "2",
  • "qty": "1"
}

Response samples

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

Remove an Item Modifier

Remove a modifier from a line item in the order

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = ordermanage
  • ordermanage = modifier_del
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 63676598

Order item modifier identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

item_id
required
string
Example: 785676543

Order item identifier

query Parameters
timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/order/item/modifier/785903676' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Get Modifier Detail

Gets details for the specified modifier.

See List Modifiers for report output

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = orderlist
  • json = no
  • orderlist = modifiers
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 63676598

Order item modifier identifier

item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
customer_id
string
Example: customer_id=54345,567043,31567

Comma separated list of customer identifiers

ordernum
string
Example: ordernum=A13DDES345

Order number

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

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

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

type
object
Enum: "ORDER" "QUICK" "INVOICE"
Example: type=ORDER,QUICK

Comma separated list of order types

Flag values (comma separated):

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
object
Enum: "PENDING" "OPEN" "PARTIALPAID" "COMPLETE" "CANCEL" "FORCECLOSED"
Example: status=OPEN,PARTIALPAID

Comma separated list of order status

Flag values (comma separated):

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
  • PARTIALPAID - Order has been partially paid
  • COMPLETE - Order is complete
  • CANCEL - Order has been canceled
  • FORCECLOSED - Order was force closed
timestamp_create_bdate
string
Example: timestamp_create_bdate=1653406830

Start of order created date range as a timestamp

timestamp_create_edate
string
Example: timestamp_create_edate=1653406830

End of order created date range as a timestamp

timestamp_close_bdate
string
Example: timestamp_close_bdate=1653406830

Start of order closed date range as a timestamp

timestamp_close_edate
string
Example: timestamp_close_edate=1653406830

End of order closed date range as a timestamp

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/order/modifier/75849356543' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Edit an Item Modifier

Edit a line item modifier

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = ordermanage
  • ordermanage = modifier_edit
Authorizations:
basic_auth
path Parameters
id
required
string
Example: 63676598

Order item modifier identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

item_id
required
string
Example: 785676543

Order item identifier

Request Body schema: application/json
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
{
  • "timestamp_ms": "1653340525",
  • "ringorder": "2",
  • "qty": "1"
}

Response samples

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

Order Reports

Order Report operations

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
  • admin = orderreport
  • orderreport = aging
Authorizations:
basic_auth
query Parameters
id
string
Example: id=56789687564

Customer identifier

type
object
Enum: "ORDER" "QUICK" "INVOICE"
Example: type=ORDER,QUICK

Comma separated list of order types

Flag values (comma separated):

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/order/report/aging' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "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
  • admin = orderreport
  • orderreport = customersummary
Authorizations:
basic_auth
query Parameters
id
string
Example: id=56789687564

Customer identifier

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

limit
string
Example: limit=4

Maximum number of rows to return

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

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/order/report/modifier?customer=-30%20days' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "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
  • admin = orderreport
  • orderreport = itemdiscountsummary
Authorizations:
basic_auth
query Parameters
id
string
Example: id=67876547364567

Order discount identifier

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

limit
string
Example: limit=4

Maximum number of rows to return

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

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/order/report/discount/item?bdate=-30%20days' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "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
  • admin = orderreport
  • orderreport = modifiersummary
Authorizations:
basic_auth
query Parameters
id
string
Example: id=63676598

Order item modifier identifier

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

limit
string
Example: limit=4

Maximum number of rows to return

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

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/order/report/modifier?bdate=-30%20days' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "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
  • admin = orderreport
  • orderreport = orderdiscountsummary
Authorizations:
basic_auth
query Parameters
id
string
Example: id=67876547364567

Order discount identifier

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

limit
string
Example: limit=4

Maximum number of rows to return

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

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/order/report/discount/order?bdate=-30%20days' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "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
  • admin = orderreport
  • orderreport = payments
Authorizations:
basic_auth
query Parameters
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
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/order/report/payment?bdate=-30%20days' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "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
  • admin = orderreport
  • orderreport = productsummary
Authorizations:
basic_auth
query Parameters
id
string
Example: id=6789646596763

Unique ID of the product

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

limit
string
Example: limit=4

Maximum number of rows to return

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

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/order/report/product?bdate=-30%20days' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "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
  • admin = orderreport
  • orderreport = skusummary
Authorizations:
basic_auth
query Parameters
id
string
Example: id=5784936543

Unique ID of the SKU

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

limit
string
Example: limit=4

Maximum number of rows to return

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

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/order/report/sku?bdate=-30%20days' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Tax History

Tax summary report

The resulting report will contain these headers:

taxrate_id, taxrate_name, order_id, timestamp, amount

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = orderreport
  • orderreport = taxhistory
Authorizations:
basic_auth
query Parameters
id
string
Example: id=65748376543

Unique ID of the tax rate

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/order/report/tax/history?bdate=-30%20days' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "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
  • admin = orderreport
  • orderreport = taxsummary
Authorizations:
basic_auth
query Parameters
id
string
Example: id=65748376543

Unique ID of the tax rate

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/order/report/tax?bdate=-30%20days' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "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
  • admin = orderreport
  • orderreport = tip
Authorizations:
basic_auth
query Parameters
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
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/order/report/tip?bdate=-30%20days' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Maintenance

Maintenance operations

Clear Sensitive Transaction Data

Removes sensitive account data from the system

Only applies to transaction history contained in settled batches and will not impact stored tokens. Transactions that have been secured are unable to be referenced by ttid for creating a duplicate transaction. The sensitive data (account) will have been cleared so the necessary information is not available for duplicate transactions.

This operation can be scheduled to run automatically using the scheduler. Also, this can be scheduled at an administrative level.

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = securetrans
Authorizations:
basic_auth
query Parameters
batch
string
Example: batch=47

The batch number associated with the transaction

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/maintenance/sensitive?bdate=-5%20years&edate=-3%20years' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Clear Un-Captured Transactions

Clears uncaptured transactions

This is intended to remove stale transactions that would not be funded if settled. To prevent accidental misuse, this request can only operate on transactions which are at least 30 days old. Typically, settlement of a transaction over 30 days old will result in a rejection of funding.

If an old transaction needs to be collected, a new charge should be issued.

Transactions that have not been captured include:

  • preauths
  • sale transactions sent with capture=no

This operation can be scheduled to run automatically using the scheduler. Also, this can be scheduled at an administrative level.

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = cut
Authorizations:
basic_auth
query Parameters
bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/maintenance/uncaptured?bdate=-1%20year&edate=-6%20months' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Scheduled Payments

Scheduled Payment operations

List Installment Payments

Lists installment payment details

The resulting report will contain these headers:

token, type, create_ts, update_ts, flags, active, cardtype,
abaroute, account, expdate, cardholdername, street, zip, descr,
clientref, customer_id, customer_display_name, amount, frequency,
bdate, edate, installment_num, installment_total, last_run_id,
last_success_date, last_run_date, next_run_date, next_run_amount,
billing_merchant

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringlist
  • type = installment
Authorizations:
basic_auth
query Parameters
token
string
Example: token=6789656783904467894

Referent to the account data that's been stored

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

Token active status

Values:

  • yes - The token is active
  • no - The token is not active
clientref
string
Example: clientref=55

Reference number associated with the customer

id
string
Example: id=56789687564

Customer identifier

expdate_end
string
Example: expdate_end=1022

Maximum expiration date a card can have. Limit all expiration dates to before this time.

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder.

Will be read from account data (EMV, Track 1, etc.) but is not guaranteed to be present. Some presentation methods, such as keyed, do not have any way to capture the name as part of the account data.

Further, Visa explicitly does not allow the cardholder name to be transmitted as part of a contactless read. Typically, a contactless read will result in a cardholder name of "/".

If the name is known by another means, it can be entered in this parameter to override what was read (or not read) from the card.

This is purely a reporting field and is not used by issuers to perform verification of the card or customer.

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

Cardtypes

Pipe (|) separated.

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

Flag values (pipe separated):

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

Last 4 digits of account number

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/vault/payment/installment?active=yes' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Add Installment Payment

Adds an installment payment

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringadd
  • type = installment
Authorizations:
basic_auth
Request Body schema: application/json
object (Store_Account_v8_params_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/allow list

street
string

Street address associated with the account

zip
string <= 32 characters

Zip code associated with the account

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

Responses

Request samples

Content type
application/json
{
  • "account_data": {
    },
  • "carddenylist_id": "67898765",
  • "street": "1st St",
  • "zip": "32606",
  • "clientref": "55",
  • "matching_token": "no",
  • "customer_id": "56789687564",
  • "cof_transid": "67898768",
  • "cof_authamount": "76.42",
  • "descr": "description of some kind",
  • "bdate": "-6 months",
  • "installment_total": "149",
  • "frequency": "monthly",
  • "amount": "19.92",
  • "property1": "string",
  • "property2": "string"
}

Response samples

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

List Recurring Payments

Lists recurring payment details

The resulting report will contain these headers:

token, type, create_ts, update_ts, flags, active, cardtype,
abaroute, account, expdate, cardholdername, street, zip, descr,
clientref, customer_id, customer_display_name, amount, frequency,
bdate, last_run_id, last_success_date, last_run_date,
next_run_date, next_run_amount, billing_merchant

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringlist
  • type = recurring
Authorizations:
basic_auth
query Parameters
token
string
Example: token=6789656783904467894

Referent to the account data that's been stored

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

Token active status

Values:

  • yes - The token is active
  • no - The token is not active
clientref
string
Example: clientref=55

Reference number associated with the customer

id
string
Example: id=56789687564

Customer identifier

expdate_end
string
Example: expdate_end=1022

Maximum expiration date a card can have. Limit all expiration dates to before this time.

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder.

Will be read from account data (EMV, Track 1, etc.) but is not guaranteed to be present. Some presentation methods, such as keyed, do not have any way to capture the name as part of the account data.

Further, Visa explicitly does not allow the cardholder name to be transmitted as part of a contactless read. Typically, a contactless read will result in a cardholder name of "/".

If the name is known by another means, it can be entered in this parameter to override what was read (or not read) from the card.

This is purely a reporting field and is not used by issuers to perform verification of the card or customer.

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

Cardtypes

Pipe (|) separated.

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

Flag values (pipe separated):

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

Last 4 digits of account number

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/vault/payment/recurring?clientref=55' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Add Recurring Payment

Adds a recurring payment

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringadd
  • type = recurring
Authorizations:
basic_auth
Request Body schema: application/json
object (Store_Account_v8_params_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/allow list

street
string

Street address associated with the account

zip
string <= 32 characters

Zip code associated with the account

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 of the payment

bdate
string

Start of date range

edate
string

End of date range

frequency
required
string
Enum: "daily" "weekly" "biweekly" "monthly" "bimonthly" "quarterly" "semiannually" "annually"

Frequency of payment

Values:

  • daily - Takes place every day
  • weekly - Takes place every week on the given day of week. Ex. Every Wednesday
  • biweekly - Takes place every two weeks on the given day. Ex. Every other Friday
  • monthly - Takes place every month on the given day of the month. If the day is after the last day of the month (e.g. 31st when the month only has 30 days), the last day of the month will be used for that month
  • bimonthly - Takes place every two months on the given day of the month
  • quarterly - Takes place every three months on the given day of the month
  • semiannually - Takes place every six months
  • annually - Takes place once a year
amount
required
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

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

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "account_data": {
    },
  • "carddenylist_id": "67898765",
  • "street": "1st St",
  • "zip": "32606",
  • "clientref": "55",
  • "matching_token": "no",
  • "customer_id": "56789687564",
  • "cof_transid": "67898768",
  • "cof_authamount": "76.42",
  • "descr": "description of some kind",
  • "bdate": "-6 months",
  • "edate": "now",
  • "frequency": "monthly",
  • "amount": "19.92",
  • "property1": "string",
  • "property2": "string"
}

Response samples

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

Delete Payment History

Purges payment history

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringpurgehist
Authorizations:
basic_auth
query Parameters
bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/vault/payment/history?bdate=-5%20years&edate=-1%20years' --basic -u 'test_retail|public:publ1ct3st'

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:

id, token, timestamp, ttid, code, phard_code, msoft_code, verbiage

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringhist
Authorizations:
basic_auth
query Parameters
bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

token
string
Example: token=6789656783904467894

Referent to the account data that's been stored

hist_id
string
Example: hist_id=5678976

Transaction ID for recurring transaction

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/vault/payment/history?bdate=-1%20year&edate=now' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Get Installment Payment Details

Gets details for the specified installment payment

See List Installment Payments for report output

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringlist
  • type = installment
Authorizations:
basic_auth
path Parameters
token
required
string
Example: 6789656783904467894

Referent to the account data that's been stored

query Parameters
active
object
Enum: "yes" "no"
Example: active=yes

Token active status

Values:

  • yes - The token is active
  • no - The token is not active
clientref
string
Example: clientref=55

Reference number associated with the customer

id
string
Example: id=56789687564

Customer identifier

expdate_end
string
Example: expdate_end=1022

Maximum expiration date a card can have. Limit all expiration dates to before this time.

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder.

Will be read from account data (EMV, Track 1, etc.) but is not guaranteed to be present. Some presentation methods, such as keyed, do not have any way to capture the name as part of the account data.

Further, Visa explicitly does not allow the cardholder name to be transmitted as part of a contactless read. Typically, a contactless read will result in a cardholder name of "/".

If the name is known by another means, it can be entered in this parameter to override what was read (or not read) from the card.

This is purely a reporting field and is not used by issuers to perform verification of the card or customer.

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

Cardtypes

Pipe (|) separated.

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

Flag values (pipe separated):

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

Last 4 digits of account number

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/vault/payment/installment/1719266657160421715' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Edit Installment Payment

Edits a stored installment payment

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringedit
  • type = installment
Authorizations:
basic_auth
path Parameters
token
required
string
Example: 6789656783904467894

Referent to the account data that's been stored

Request Body schema: application/json
active
string
Enum: "yes" "no"

Token active status

Values:

  • yes - The token is active
  • no - The token is not active
object (Edit_Account_v8_params_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 associated with the account

zip
string <= 32 characters

Zip code associated with the account

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 payment

bdate
string

Start of date range

installment_total
string\d+

Total number of installment payments to make

frequency
string
Enum: "daily" "weekly" "biweekly" "monthly" "bimonthly" "quarterly" "semiannually" "annually"

Frequency of payment

Values:

  • daily - Takes place every day
  • weekly - Takes place every week on the given day of week. Ex. Every Wednesday
  • biweekly - Takes place every two weeks on the given day. Ex. Every other Friday
  • monthly - Takes place every month on the given day of the month. If the day is after the last day of the month (e.g. 31st when the month only has 30 days), the last day of the month will be used for that month
  • bimonthly - Takes place every two months on the given day of the month
  • quarterly - Takes place every three months on the given day of the month
  • semiannually - Takes place every six months
  • annually - Takes place once a year
amount
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

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

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "active": "yes",
  • "account_data": {
    },
  • "street": "1st St",
  • "zip": "32606",
  • "clientref": "55",
  • "matching_token": "no",
  • "customer_id": "56789687564",
  • "cof_transid": "67898768",
  • "cof_authamount": "76.42",
  • "descr": "description of some kind",
  • "bdate": "-6 months",
  • "installment_total": "149",
  • "frequency": "monthly",
  • "amount": "19.92",
  • "property1": "string",
  • "property2": "string"
}

Response samples

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

Get Recurring Payment Detail

Gets details for the specified recurring payment

See List Recurring Payments for report output

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringlist
  • type = recurring
Authorizations:
basic_auth
path Parameters
token
required
string
Example: 6789656783904467894

Referent to the account data that's been stored

query Parameters
active
object
Enum: "yes" "no"
Example: active=yes

Token active status

Values:

  • yes - The token is active
  • no - The token is not active
clientref
string
Example: clientref=55

Reference number associated with the customer

id
string
Example: id=56789687564

Customer identifier

expdate_end
string
Example: expdate_end=1022

Maximum expiration date a card can have. Limit all expiration dates to before this time.

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder.

Will be read from account data (EMV, Track 1, etc.) but is not guaranteed to be present. Some presentation methods, such as keyed, do not have any way to capture the name as part of the account data.

Further, Visa explicitly does not allow the cardholder name to be transmitted as part of a contactless read. Typically, a contactless read will result in a cardholder name of "/".

If the name is known by another means, it can be entered in this parameter to override what was read (or not read) from the card.

This is purely a reporting field and is not used by issuers to perform verification of the card or customer.

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

Cardtypes

Pipe (|) separated.

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

Flag values (pipe separated):

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

Last 4 digits of account number

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/vault/payment/recurring/' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Edit Recurring Payment

Edits a stored recurring payment

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringedit
  • type = recurring
Authorizations:
basic_auth
path Parameters
token
required
string
Example: 6789656783904467894

Referent to the account data that's been stored

Request Body schema: application/json
active
string
Enum: "yes" "no"

Token active status

Values:

  • yes - The token is active
  • no - The token is not active
skipmissed
string
Default: "no"
Enum: "yes" "no"

Whether missed payments should be skipped

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

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

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

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

Values:

  • yes - Do not charge missed payments
  • no - Charge missed payments
object (Edit_Account_v8_params_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 associated with the account

zip
string <= 32 characters

Zip code associated with the account

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 of the payment

bdate
string

Start of date range

edate
string

End of date range

frequency
string
Enum: "daily" "weekly" "biweekly" "monthly" "bimonthly" "quarterly" "semiannually" "annually"

Frequency of payment

Values:

  • daily - Takes place every day
  • weekly - Takes place every week on the given day of week. Ex. Every Wednesday
  • biweekly - Takes place every two weeks on the given day. Ex. Every other Friday
  • monthly - Takes place every month on the given day of the month. If the day is after the last day of the month (e.g. 31st when the month only has 30 days), the last day of the month will be used for that month
  • bimonthly - Takes place every two months on the given day of the month
  • quarterly - Takes place every three months on the given day of the month
  • semiannually - Takes place every six months
  • annually - Takes place once a year
amount
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

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

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "active": "yes",
  • "skipmissed": "no",
  • "account_data": {
    },
  • "street": "1st St",
  • "zip": "32606",
  • "clientref": "55",
  • "matching_token": "no",
  • "customer_id": "56789687564",
  • "cof_transid": "67898768",
  • "cof_authamount": "76.42",
  • "descr": "description of some kind",
  • "bdate": "-6 months",
  • "edate": "now",
  • "frequency": "monthly",
  • "amount": "19.92",
  • "property1": "string",
  • "property2": "string"
}

Response samples

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

Remove Stored Payment

Permanently removes a stored payment from the vault

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringdel
Authorizations:
basic_auth
path Parameters
token
required
string
Example: 6789656783904467894

Referent to the account data that's been stored

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/vault/payment/1719266657160421715' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Account Vault

Stored account operations

Remove Account

Permanently removes a stored account from the vault

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringdel
Authorizations:
basic_auth
path Parameters
token
required
string
Example: 6789656783904467894

Referent to the account data that's been stored

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/vault/account/1719266678671633432' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Get Account Detail

Gets details for the specified stored account

See List Stored Accounts for report output

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringlist
  • type = store
Authorizations:
basic_auth
path Parameters
token
required
string
Example: 6789656783904467894

Referent to the account data that's been stored

query Parameters
active
object
Enum: "yes" "no"
Example: active=yes

Token active status

Values:

  • yes - The token is active
  • no - The token is not active
clientref
string
Example: clientref=55

Reference number associated with the customer

id
string
Example: id=56789687564

Customer identifier

expdate_end
string
Example: expdate_end=1022

Maximum expiration date a card can have. Limit all expiration dates to before this time.

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder.

Will be read from account data (EMV, Track 1, etc.) but is not guaranteed to be present. Some presentation methods, such as keyed, do not have any way to capture the name as part of the account data.

Further, Visa explicitly does not allow the cardholder name to be transmitted as part of a contactless read. Typically, a contactless read will result in a cardholder name of "/".

If the name is known by another means, it can be entered in this parameter to override what was read (or not read) from the card.

This is purely a reporting field and is not used by issuers to perform verification of the card or customer.

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

Cardtypes

Pipe (|) separated.

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

Flag values (pipe separated):

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

Last 4 digits of account number

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/vault/account/1001709895560774683' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Edit Account

Edits a stored account

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringedit
  • type = store
Authorizations:
basic_auth
path Parameters
token
required
string
Example: 6789656783904467894

Referent to the account data that's been stored

Request Body schema: application/json
active
string
Enum: "yes" "no"

Token active status

Values:

  • yes - The token is active
  • no - The token is not active
object (Edit_Account_v8_params_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

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "active": "yes",
  • "account_data": {
    },
  • "street": "1st St",
  • "zip": "32606",
  • "clientref": "55",
  • "matching_token": "no",
  • "customer_id": "56789687564",
  • "cof_transid": "67898768",
  • "cof_authamount": "76.42",
  • "descr": "description of some kind",
  • "property1": "string",
  • "property2": "string"
}

Response samples

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

List Accounts

Lists stored account details

The resulting report will contain these headers:

token, type, create_ts, update_ts, flags, active, cardtype,
abaroute, account, expdate, cardholdername, street, zip, descr,
clientref, customer_id, customer_display_name

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringlist
  • type = store
Authorizations:
basic_auth
query Parameters
token
string
Example: token=6789656783904467894

Referent to the account data that's been stored

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

Token active status

Values:

  • yes - The token is active
  • no - The token is not active
clientref
string
Example: clientref=55

Reference number associated with the customer

id
string
Example: id=56789687564

Customer identifier

expdate_end
string
Example: expdate_end=1022

Maximum expiration date a card can have. Limit all expiration dates to before this time.

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder.

Will be read from account data (EMV, Track 1, etc.) but is not guaranteed to be present. Some presentation methods, such as keyed, do not have any way to capture the name as part of the account data.

Further, Visa explicitly does not allow the cardholder name to be transmitted as part of a contactless read. Typically, a contactless read will result in a cardholder name of "/".

If the name is known by another means, it can be entered in this parameter to override what was read (or not read) from the card.

This is purely a reporting field and is not used by issuers to perform verification of the card or customer.

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

Cardtypes

Pipe (|) separated.

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

Flag values (pipe separated):

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

Last 4 digits of account number

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/vault/account?active=no&cardtypes=VISA%7CMC' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "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
  • admin = recurringadd
  • type = store
Authorizations:
basic_auth
Request Body schema: application/json
object (Store_Account_v8_params_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/allow 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

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "account_data": {
    },
  • "carddenylist_id": "67898765",
  • "street": "1st St",
  • "zip": "32606",
  • "clientref": "55",
  • "matching_token": "no",
  • "customer_id": "56789687564",
  • "cof_transid": "67898768",
  • "cof_authamount": "76.42",
  • "descr": "description of some kind",
  • "property1": "string",
  • "property2": "string"
}

Response samples

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

Remove Expired Accounts

Permanently removes accounts that have expired from the vault

libmonetra KVS equivalent for endpoint

  • action = admin
  • admin = recurringpurgeexpired
Authorizations:
basic_auth
query Parameters
keep_months
string
Example: keep_months=12

Represents the number of months after a card has expired that it should be kept on file

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/vault/account/expired?keep_months=24' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Card Deny List

Accounts that have been marked as should not be accepted

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
  • admin = carddenylist
  • carddenylist = list
Authorizations:
basic_auth
query Parameters
carddenylist_id
string
Example: carddenylist_id=67898765

ID in the card deny/allow list

expdate_bdate
string
Example: expdate_bdate=-5 months

Used to filter report by card expiration date range. Expiration is when the card expires, the expdate parameter sent with account. This is the beginning date of the expiration date range to match.

expdate_edate
string
Example: expdate_edate=-2 months

Used to filter report by card expiration date range. Expiration is when the card expires, the expdate parameter sent with account. This is the ending date of the expiration date range to match.

added_bdate
string
Example: added_bdate=-5 months

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

added_edate
string
Example: added_edate=-2 months

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

last_seen_bdate
string
Example: last_seen_bdate=-5 months

Used to filter report by last seen date range. This is the beginning date of the last seen date range to match.

last_seen_edate
string
Example: last_seen_edate=-2 months

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

expire_bdate
string
Example: expire_bdate=-5 months

Used to filter report by expire date range

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

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

expire_edate
string
Example: expire_edate=-2 months

Used to filter report by expire date range

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

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

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v1/cardlist/deny' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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

Add a card to the deny list

Authorizations:
basic_auth
Request Body schema: application/json
object (Store_Account_v8_params_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.

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
{
  • "account_data": {
    },
  • "expire": "+90 days"
}

Response samples

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

Check if card is on deny list

Check if account is on the card deny list

If the card is on the deny list the report will contain a single row with information about the card. No rows indicates the card is not on the 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
  • admin = carddenylist
  • carddenylist = list
Authorizations:
basic_auth
Request Body schema: application/json
account
string <= 2048 characters \d+

Account number

cardshieldticket
string\d+

Temporary token used to capture account data with the purpose of using it later in a transaction request

The ticket only lasts for five minutes, after which it is expired and cannot be used. If the ticket needs to be user for a longer duration it should be converted to a stored account.

The ticket will have been generated and returned to the merchant by TranSafe from a ticket request of some kind. The PaymentFrame is the most common method.

Typically used for e-commerce where payment data is collected before final order submission. Or when the account information is collected from secure account entry method. For example, it is a response parameter from the e-commerce PaymentFrame which allows the customer to enter their card details without sending the information to the merchant's web server.

cardholdername
string <= 128 characters

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.

This is purely a reporting field and is not used by issuers to perform verification of the card or customer.

cardpresent
string
Default: "yes"
Enum: "yes" "no" "ecomm" "mobileinapp"

Used for Retail/Restaurant accounts where the card is not present at the time of the transaction

Ignored for anything besides Retail or Restaurant accounts

Values:

  • yes - Card was present
  • no - Card was not present. Will be processed in a similar fashion to Mail Order/Telephone Order
  • ecomm - Card was not present. Will be processed in a similar fashion to E-commerce
  • mobileinapp - Account data received as mobile in-app payment
countrycode
string\d{3}
Default: "840"

ISO 3166-1 numeric country code where the account was issued

Primarily used for zip / postal code verification. Due to countries have different zip / postal codes the country code for the account can be sent and will verify the zip / postal code based on the country of issuance.

Typically, the country code does not need to be specified with a transaciton. TranSafe will determine the county code by the following.

  1. If countrycode was sent, it will be used.
  2. If card present EMV the country code is part of the EMV data.
  3. The card number will be match with the global bin file and the country code will be determined based on the card number
  4. The country code of the merchant will be used.
e_account
string[[:xdigit:]]+

Encrypted account number

Requires:

  • e_id
e_datafield
string[[:xdigit:]]+

Encrypted keyed data block.

Can contain multiple account data parameters

Requires:

  • e_datafieldfmt
  • e_id
e_datafieldfmt
string
Enum: "account" "expdate" "cv"

Format of encrypted keyed data block.

The order of elements defines the data and order of data within the e_datafield. Pipe (|) delimited list.

Requires:

  • e_datafield

Flag values (pipe separated):

  • account - Account number
  • expdate - Expiration date
  • cv - Card verification code
e_datafieldmasked
string

Masked version of the account data contained in e_datafield

Requires:

  • e_datafield
e_trackdata
string

Encrypted trackdata.

Supports both track 1 and track 2. Can also contain masked version of trackdata.

When using an encrypting reader with EMV, this may be present with icc. The track 2-equivalent data in icc will be masked with the encrypted track 2- equivalent contained here. Typically, masked trackdata will not be present here because it is contained in the icc data.

Format:

  • [ENCRYPTED TRACK2]
  • [MASKED TRACK1]|[ENCRYPTED TRACK1]
  • [MASKED TRACK2]|[ENCRYPTED TRACK2]
  • [MASKED TRACK1][MASKED TRACK2]|[ENCRYPTED TRACK1]|[ENCRYPTED TRACK2]

Requires:

  • e_id
e_id
string[[:xdigit:]]+

Encryption identifier

Identifies the encryption type and Key Serial Number (KSN) used for the encryption.

Encryption types:

  • CardShield
  • OnGuard
  • TransArmor

Format:

  • [Encryption Type]|[KSN]
  • [KSN] (implies CardShield)
expdate
string = 4 characters (0[1-9]|1[1-2])\d{2}

Expiration date of the card (MMYY format)

icc
string

Integrated Chip Card TLV data as read via EMV insert or tap

rfid
string
Default: "no"
Enum: "yes" "no" "capable"

Whether or not transaction was accepted via RFID (proximity)

Values:

  • yes - Account data was captured by contactless reader
  • no - Account data not captured by contactless reader
  • capable - The POS is capable of accepting RFID, but the transaction was not an RFID transaction
token
string\d+

Referent to the account data that's been stored

trackdata
string[[:print:]]+

Magnetic stripe data as read from a card via swipe

abaroute
string = 9 characters \d{9}

ABA routing number

Requires:

  • account
checknum
string\d+

Check number

Requires:

  • abaroute
accounttype
string
Enum: "BUSINESS" "PERSONAL" "CHECKING" "SAVINGS"

Type of account

Pipe (|) delimited list.

Default is PERSONAL|CHECKING

  • BUSINESS and PERSONAL cannot be combined.
  • CHECKING and SAVINGS cannot be combined.

Example:

  • To indicate personal checking account:
    • accounttype=PERSONAL|CHECKING

Requires:

  • abaroute
  • account

Flag values (pipe separated):

  • BUSINESS - Business account
  • PERSONAL - Personal account
  • CHECKING - Checking account
  • SAVINGS - Savings account

Responses

Request samples

Content type
application/json
{
  • "account": "5454545454545454",
  • "cardshieldticket": "567865678987",
  • "cardholdername": "John Doe",
  • "cardpresent": "yes",
  • "countrycode": "840",
  • "e_account": "DEF5325DEA5678DB6",
  • "e_datafield": "DE45AC529FDE35",
  • "e_datafieldfmt": "account|expdate",
  • "e_datafieldmasked": "5454********5454",
  • "e_trackdata": "...",
  • "e_id": "645FF245ED34CD5A",
  • "expdate": "0129",
  • "icc": "4F07A0000000031010500B564953412043524544495457134761739001010010D22122011143804400000F5A0847617390010100105F201A554154205553412F5465737420436172642030342020202020205F24032212315F280208405F2A0208405F2D02656E5F300202015F34010182021C008407A0000000031010950580800080009A031701059B0268009C01009F02060000000100009F03060000000000009F0607A00000000310109F0702FF009F0902008C9F100706010A03A020009F1101019F120B56697361204372656469749F1A0208409F1B04000000009F1E0838303338383535389F1F183131343338303434383930303030303030303030303030309F21030933379F2608D737017E33C786929F2701809F3303E0F8C89F34031F00029F3501229F360200E09F3704526F34219F3901059F4005F000F0F0019F4104000000039F530152",
  • "rfid": "no",
  • "token": "6789656783904467894",
  • "trackdata": "%B4111111111111111^TEST CARD/VI^29121015432112345678?;4111111111111111=29121015432112345678?",
  • "abaroute": "267084131",
  • "checknum": "45678",
  • "accounttype": "PERSONAL|CHECKING"
}

Response samples

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

Remove a card from the deny list

Authorizations:
basic_auth
path Parameters
carddenylist_id
required
string
Example: 67898765

ID in the card deny/allow list

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/cardlist/deny/134543245543' --basic -u 'test_retail|public:publ1ct3st'

Response samples

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