logo
API docs by Redocly

TranSafe (2.3.2)

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.

Parameters

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

Empty vs not Present

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

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

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

$0.00 Amounts

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

Extra Parameters

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

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

Examples

Payload Samples

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

cURL

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

Groups

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

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

Response Codes

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

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

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

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

code

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

msoft_code

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

phard_code

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

Reports

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

  • code
  • verbiage

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

libMonetra

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

Time Formats

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

  • formatted time
  • Unix timestamp

Formatted

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

Fixed

Fixed formats are very similar to written dates and times.

Formats:

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

Offset

Offsets take this format:

+ or -
  magnitude
  space
  modifier

Modifiers:

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

Example

+1 day
-5 years

Special keywords

  • now - current date/time
  • epoch - Unix timestamp of 0 = Jan 1, 1970 00:00:00 UTC
  • BOD - Beginning of the current day
  • EOD - End of the current day

Unix Timestamp

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

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

Test Server

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

Server: https://test.transafe.com Username: test_retail:public Password: publ1ct3st

If a private test account is needed please contact us.

Authentication

API Keys and HTTP Basic authentication are currently supported.

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

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

API Key Authentication

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

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

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

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

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

  • auth_apikey_id
  • auth_apikey_secret

Programming language examples

Python

import urllib.request
import base64

URL = 'https://test.transafe.com/api/v2/report/failed'
KEY_ID = 'X123'
KEY_SECRET = 'b64a='

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

req = urllib.request.Request(URL, headers=headers)
with urllib.request.urlopen(req) as o:
    print(o.read().decode('utf-8'))
C#
using System;
using System.IO;
using System.Net;
using System.Text;

class AuthExample
{
    static void Main(string[] args)
    {
        var url        = "https://test.transafe.com/api/v2/report/failed";
        var key_id     = "X123";
        var key_secret = "b64a=";
        // var json = 'json data to post'

        ServicePointManager.Expect100Continue = false;
        ServicePointManager.UseNagleAlgorithm = true;
        ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;

        var request = WebRequest.Create(url);
        request.Method = "GET";
        request.Headers.Add("X-API-KEY-ID", key_id);
        request.Headers.Add("X-API-KEY", key_secret);
        // # For POST
        //   request.ContentType   = "application/json";
        // # 'json' contains data to post
        //   request.ContentLength = json.Length;
        //   Stream requestStream  = request.GetRequestStream();
        //   requestStream.Write(Encoding.ASCII.GetBytes(json), 0, json.Length);
        //   requestStream.Close();

        using (var response = (HttpWebResponse)request.GetResponse()) {
            Console.WriteLine(response.StatusDescription);

            using (var dataStream = response.GetResponseStream()) {
                using (var reader = new StreamReader(dataStream)) {
                    Console.WriteLine(reader.ReadToEnd());
                }
            }
        }
    }
}
PHP
<?php
$url = "https://test.transafe.com/api/v2/report/failed";
$key_id = "X123";
$key_secret = "b64a=";
$opts = array(
  "http"=>array(
    "method"=>"GET",
    "header" => "X-API-KEY-ID:" . $key_id . "\r\n" . "X-API-KEY: " . $key_secret . "\r\n"
  ),
);
$context = stream_context_create($opts);
$file = file_get_contents($url, false, $context);
echo $file;
?>

Basic Authentication

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

E.g.

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

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

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

Colon escaping

Basic auth does not allow colons (':') to be present in usernames. However, it's valid for usernames to have been created with a colon (':'). If colons (':') are present they need to be replaced with a pipe ('|').

user:sub -> user|sub

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

Programming language examples

We do not recommend using most programming language's built-in credential management APIs. Such as .Net's HTTPPasswordMgrWithDefaultRealm with a HTTPBasicAuthHandler object. Or Python's NetworkCredential with the CredentialCache. Instead we recommend sending the authorization data directly/explicitly in the request header.

Using the language API credential management can increase the transaction processing time. Many language APIs will first send the request without authorization data. The server will respond with a 401 authorization data required response. The request will be sent a second time with the authorization data. The extra request that is known to fail adds additional and unnecessary, messaging which increases request processing time.

Python

import urllib.request
import base64

URL = 'https://test.transafe.com/api/v2/report/failed'
USER = '@TEST_USERNAME_M9@'
PASS = 'publ1ct3st'

auth_data = '%s:%s' % (USER, PASS)
auth_data = base64.b64encode(auth_data.encode()).decode('utf-8')
headers = {
    'Authorization': 'Basic %s' % auth_data
}

req = urllib.request.Request(URL, headers=headers)
with urllib.request.urlopen(req) as o:
    print(o.read().decode('utf-8'))
C#
using System;
using System.IO;
using System.Net;
using System.Text;

class AuthExample
{
    static void Main(string[] args)
    {
        var url      = "https://test.transafe.com/api/v2/report/failed";
        var username = "@TEST_USERNAME_M9@";
        var password = "publ1ct3st";
        var authData = System.Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(username + ":" + password));
        // var json = 'json data to post'

        ServicePointManager.Expect100Continue = false;
        ServicePointManager.UseNagleAlgorithm = true;
        ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;

        var request = WebRequest.Create(url);
        request.Method = "GET";
        request.Headers.Add("Authorization", "Basic " + authData);
        // # For POST
        //   request.ContentType   = "application/json";
        // # 'json' contains data to post
        //   request.ContentLength = json.Length;
        //   Stream requestStream  = request.GetRequestStream();
        //   requestStream.Write(Encoding.ASCII.GetBytes(json), 0, json.Length);
        //   requestStream.Close();

        using (var response = (HttpWebResponse)request.GetResponse()) {
            Console.WriteLine(response.StatusDescription);

            using (var dataStream = response.GetResponseStream()) {
                using (var reader = new StreamReader(dataStream)) {
                    Console.WriteLine(reader.ReadToEnd());
                }
            }
        }
    }
}
PHP
<?php
$url = "https://test.transafe.com/api/v2/report/failed";
$username = "@TEST_USERNAME_M9@";
$password = "publ1ct3st";
$opts = array(
  "http"=>array(
    "method"=>"GET",
    "header" => "Authorization: Basic " . base64_encode("$username:$password")
  ),
);
$context = stream_context_create($opts);
$file = file_get_contents($url, false, $context);
echo $file;
?>

Dual Authentication

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

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

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

The users must be different.

MFA Code

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

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

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

Bin Ranges

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

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

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

Multiple ranges are joined together with semicolons (;).

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

Example ranges:

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

Interchange Rates

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

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

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

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

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

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

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

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

Transactions

Transaction operations

Reverse Transaction

Removes a previously authorized transaction in real time

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

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

libmonetra KVS equivalent for endpoint

  • action_trans = reversal
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 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
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

amount
string
Example: amount=19.92

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

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "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"
}

Adjust Transaction

Modifies transaction data

This allows adding or modifying transaction parameters after authorization.

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

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

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

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

libmonetra KVS equivalent for endpoint

  • action_trans = adjust
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 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
profile_id
string\d+

Merchant profile identifier

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

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

object (Gift_Merchandise_Refund_v9_params_money)

Monetary parameters

object (Adjust_Transaction_v9_params_lodging)

Lodging parameters

object (EBT_Cash_Purchase_v9_params_order)

Order detail parameters

object (Adjust_Transaction_v9_params_shipping)

Shipping detail parameters

object (EBT_Cash_Purchase_v9_params_lane)

Merchant lane parameters

property name*
additional property
string

Responses

Request samples

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

Response samples

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

Balance

Balance inquiry

Applies to:

  • Credit
  • Debit
  • Gift

libmonetra KVS equivalent for endpoint

  • action_trans = balanceinq
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

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

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

object (Add_to_Allow_List_v9_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_v9_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
rcpt
string

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

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

Responses

Request samples

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

Response samples

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

Capture

Add an uncaptured sale to a batch

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

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

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

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

libmonetra KVS equivalent for endpoint

  • action_trans = capture
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 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
profile_id
string\d+

Merchant profile identifier

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

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

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

Processing priority.

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

Values:

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

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

rcpt
string

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

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

property name*
additional property
string

Responses

Request samples

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

Response samples

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

Duplicate a Pre-Authorize

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

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

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

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

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

libmonetra KVS equivalent for endpoint

  • action_trans = preauth
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 18446744073709551615

Identifier for transaction to duplicate

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

Merchant profile identifier

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

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

object (Balance_v9_params_verification)

Verification parameters

object (Adjust_Transaction_v9_params_shipping)

Shipping detail parameters

object (Duplicate_a_Pre_Authorize_v9_params_ecomm)

E-commerce parameters

object (Duplicate_a_Pre_Authorize_v9_params_health)

Healthcare parameters

object (Adjust_Transaction_v9_params_lodging)

Lodging parameters

object (EBT_Cash_Purchase_v9_params_merchant_descriptors)

Merchant descriptor parameters

object (EBT_Cash_Purchase_v9_params_lane)

Merchant lane parameters

required
object (Duplicate_a_Pre_Authorize_v9_params_money)

Monetary parameters

object (EBT_Cash_Purchase_v9_params_order)

Order detail parameters

object (Duplicate_a_Pre_Authorize_v9_params_pin_data)

PIN data parameters

object (EBT_Cash_Purchase_v9_params_processing_options)

Processing options

object (Duplicate_a_Pre_Authorize_v9_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.
rcpt_user_notes
string

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

property name*
additional property
string

Responses

Request samples

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

Response samples

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

Duplicate a Purchase

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

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

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

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

libmonetra KVS equivalent for endpoint

  • action_trans = sale
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 18446744073709551615

Identifier for transaction to duplicate

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

Merchant profile identifier

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

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

object (Balance_v9_params_verification)

Verification parameters

object (Adjust_Transaction_v9_params_shipping)

Shipping detail parameters

object (Duplicate_a_Pre_Authorize_v9_params_ecomm)

E-commerce parameters

object (Duplicate_a_Pre_Authorize_v9_params_health)

Healthcare parameters

object (Adjust_Transaction_v9_params_lodging)

Lodging parameters

object (EBT_Cash_Purchase_v9_params_merchant_descriptors)

Merchant descriptor parameters

object (EBT_Cash_Purchase_v9_params_lane)

Merchant lane parameters

required
object (Duplicate_a_Pre_Authorize_v9_params_money)

Monetary parameters

object (EBT_Cash_Purchase_v9_params_order)

Order detail parameters

object (Duplicate_a_Pre_Authorize_v9_params_pin_data)

PIN data parameters

object (EBT_Cash_Purchase_v9_params_processing_options)

Processing options

object (Duplicate_a_Pre_Authorize_v9_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.
rcpt_user_notes
string

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

property name*
additional property
string

Responses

Request samples

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

Response samples

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

Merchant profile identifier

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

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

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

Response samples

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

Incremental

Operation used to increase amount for an existing authorization

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

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

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

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

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

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

libmonetra KVS equivalent for endpoint

  • action_trans = incremental
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 18446744073709551615

Identifier for transaction to increase amount

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

Merchant profile identifier

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

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

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

New total amount, not amount being added

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

Amount of tax that applies to the order

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

nsf
string
Enum: "yes" "no"

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

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

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

Values:

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

Lodging parameters

object (EBT_Cash_Purchase_v9_params_merchant_descriptors)

Merchant descriptor parameters

object (EBT_Cash_Purchase_v9_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.
rcpt_user_notes
string

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

property name*
additional property
string

Responses

Request samples

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

Response samples

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

Merchant profile identifier

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

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

object (Adjust_Transaction_v9_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_v9_params_lodging)

Lodging parameters

object (EBT_Cash_Purchase_v9_params_lane)

Merchant lane parameters

object (Gift_Merchandise_Refund_v9_params_money)

Monetary parameters

object (EBT_Cash_Purchase_v9_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.
rcpt_user_notes
string

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

property name*
additional property
string

Responses

Request samples

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

Response samples

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

Merchant profile identifier

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

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

object (Add_to_Allow_List_v9_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_v9_params_verification)

Verification parameters

object (Adjust_Transaction_v9_params_shipping)

Shipping detail parameters

object (Duplicate_a_Pre_Authorize_v9_params_ecomm)

E-commerce parameters

object (Duplicate_a_Pre_Authorize_v9_params_health)

Healthcare parameters

object (Adjust_Transaction_v9_params_lodging)

Lodging parameters

object (EBT_Cash_Purchase_v9_params_merchant_descriptors)

Merchant descriptor parameters

object (EBT_Cash_Purchase_v9_params_lane)

Merchant lane parameters

required
object (Duplicate_a_Pre_Authorize_v9_params_money)

Monetary parameters

object (EBT_Cash_Purchase_v9_params_order)

Order detail parameters

object (Duplicate_a_Pre_Authorize_v9_params_pin_data)

PIN data parameters

object (EBT_Cash_Purchase_v9_params_processing_options)

Processing options

object (Duplicate_a_Pre_Authorize_v9_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.
rcpt_user_notes
string

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

property name*
additional property
string

Responses

Request samples

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

Response samples

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

Merchant profile identifier

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

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

object (Add_to_Allow_List_v9_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_v9_params_verification)

Verification parameters

object (Adjust_Transaction_v9_params_shipping)

Shipping detail parameters

object (Duplicate_a_Pre_Authorize_v9_params_ecomm)

E-commerce parameters

object (Duplicate_a_Pre_Authorize_v9_params_health)

Healthcare parameters

object (Adjust_Transaction_v9_params_lodging)

Lodging parameters

object (EBT_Cash_Purchase_v9_params_merchant_descriptors)

Merchant descriptor parameters

object (EBT_Cash_Purchase_v9_params_lane)

Merchant lane parameters

required
object (Duplicate_a_Pre_Authorize_v9_params_money)

Monetary parameters

object (EBT_Cash_Purchase_v9_params_order)

Order detail parameters

object (Duplicate_a_Pre_Authorize_v9_params_pin_data)

PIN data parameters

object (EBT_Cash_Purchase_v9_params_processing_options)

Processing options

object (Duplicate_a_Pre_Authorize_v9_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.
rcpt_user_notes
string

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

property name*
additional property
string

Responses

Request samples

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

Response samples

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

Refund Existing Transaction

Refunds a prior purchase

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

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

libmonetra KVS equivalent for endpoint

  • action_trans = refund
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 18446744073709551615

Identifier for transaction to refund

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

Merchant profile identifier

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

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

object (EBT_Cash_Purchase_v9_params_merchant_descriptors)

Merchant descriptor parameters

object (EBT_Cash_Purchase_v9_params_lane)

Merchant lane parameters

object (Gift_Merchandise_Refund_v9_params_money)

Monetary parameters

object (EBT_Cash_Purchase_v9_params_order)

Order detail parameters

object (Duplicate_a_Pre_Authorize_v9_params_pin_data)

PIN data parameters

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

Expiration date of the card (MMYY format)

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

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

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

object (Duplicate_a_Pre_Authorize_v9_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.
rcpt_user_notes
string

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

property name*
additional property
string

Responses

Request samples

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

Response samples

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

Unlinked Refund

Unlinked Refund

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

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

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

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

libmonetra KVS equivalent for endpoint

  • action_trans = refund
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

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

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

object (Add_to_Allow_List_v9_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 (EBT_Cash_Purchase_v9_params_merchant_descriptors)

Merchant descriptor parameters

object (EBT_Cash_Purchase_v9_params_lane)

Merchant lane parameters

object (Gift_Merchandise_Refund_v9_params_money)

Monetary parameters

object (EBT_Cash_Purchase_v9_params_order)

Order detail parameters

object (Duplicate_a_Pre_Authorize_v9_params_pin_data)

PIN data parameters

object (Duplicate_a_Pre_Authorize_v9_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.
rcpt_user_notes
string

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

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
{
  • "profile_id": "78965743785967",
  • "account_data": {
    },
  • "merchant_descriptors": {
    },
  • "lane": {
    },
  • "money": {
    },
  • "order": {
    },
  • "pin_data": {
    },
  • "recurring_data": {
    },
  • "priority": "normal",
  • "timeout": "30",
  • "tokenize": "no",
  • "matching_token": "yes",
  • "rcpt": "yes",
  • "rcpt_user_notes": "Review your order at http://...",
  • "ttid": "18446744073709551615",
  • "property1": "string",
  • "property2": "string"
}

Response samples

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

Merchant profile identifier

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

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

object (Add_to_Allow_List_v9_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_v9_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
{
  • "profile_id": "78965743785967",
  • "account_data": {
    },
  • "verification": {
    },
  • "tokenize": "no",
  • "matching_token": "yes",
  • "carddenylist_check": "no",
  • "carddenylist_decline": "no",
  • "property1": "string",
  • "property2": "string"
}

Response samples

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

Void Transaction

Removes a previously authorized transaction

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

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

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

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

libmonetra KVS equivalent for endpoint

  • action_trans = void
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 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
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "phard_code": "SUCCESS",
  • "card_currency": "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"
}

Gift

Gift specific operations

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

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

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

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

Gift Activate

Activate a Gift card

See description for the gift card issue operation for details.

Processors supporting activate

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

libmonetra KVS equivalent for endpoint

  • action_trans = activate
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

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

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

object (Add_to_Allow_List_v9_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 (EBT_Cash_Purchase_v9_params_merchant_descriptors)

Merchant descriptor parameters

object (EBT_Cash_Purchase_v9_params_lane)

Merchant lane parameters

object (EBT_Cash_Purchase_v9_params_order)

Order detail parameters

object (EBT_Cash_Purchase_v9_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.
rcpt_user_notes
string

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

Responses

Request samples

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

Response samples

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

Merchant profile identifier

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

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

object (Add_to_Allow_List_v9_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 (EBT_Cash_Purchase_v9_params_merchant_descriptors)

Merchant descriptor parameters

object (EBT_Cash_Purchase_v9_params_lane)

Merchant lane parameters

object (EBT_Cash_Purchase_v9_params_order)

Order detail parameters

object (EBT_Cash_Purchase_v9_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.
rcpt_user_notes
string

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

Responses

Request samples

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

Response samples

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

Merchant profile identifier

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

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

object (Add_to_Allow_List_v9_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 (EBT_Cash_Purchase_v9_params_merchant_descriptors)

Merchant descriptor parameters

object (EBT_Cash_Purchase_v9_params_lane)

Merchant lane parameters

object (EBT_Cash_Purchase_v9_params_order)

Order detail parameters

object (EBT_Cash_Purchase_v9_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.
rcpt_user_notes
string

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

Responses

Request samples

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

Response samples

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

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

libmonetra KVS equivalent for endpoint

  • action_trans = merchreturn
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

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

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

object (Add_to_Allow_List_v9_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 (EBT_Cash_Purchase_v9_params_merchant_descriptors)

Merchant descriptor parameters

object (EBT_Cash_Purchase_v9_params_lane)

Merchant lane parameters

object (Gift_Merchandise_Refund_v9_params_money)

Monetary parameters

object (EBT_Cash_Purchase_v9_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.
rcpt_user_notes
string

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

property name*
additional property
string

Responses

Request samples

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

Response samples

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

Identifier for the gift card transaction to refund merchandise

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

Merchant profile identifier

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

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

object (EBT_Cash_Purchase_v9_params_merchant_descriptors)

Merchant descriptor parameters

object (EBT_Cash_Purchase_v9_params_lane)

Merchant lane parameters

object (Gift_Merchandise_Refund_v9_params_money)

Monetary parameters

object (EBT_Cash_Purchase_v9_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.
rcpt_user_notes
string

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

property name*
additional property
string

Responses

Request samples

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

Response samples

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

EBT

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

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

Cash accounts are typically unrestricted.

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

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

EBT Cash Balance

Get the balance on a Cash account

libmonetra KVS equivalent for endpoint

  • action_trans = ebtcbbalance
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

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

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

object (EBT_Cash_Balance_v9_params_account_data)

Account information parameters

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

These are the minimum fields required for each entry method.

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

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

ENCRYPTION

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

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

required
object (EBT_Cash_Balance_v9_params_pin_data)

PIN data parameters

rcpt
string

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

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

property name*
additional property
string

Responses

Request samples

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

Response samples

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

EBT Cash Purchase

Debit funds from a Cash account

libmonetra KVS equivalent for endpoint

  • action_trans = ebtcbsale
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

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

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

object (EBT_Cash_Balance_v9_params_account_data)

Account information parameters

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

These are the minimum fields required for each entry method.

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

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

ENCRYPTION

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

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

object (EBT_Cash_Purchase_v9_params_merchant_descriptors)

Merchant descriptor parameters

object (EBT_Cash_Purchase_v9_params_lane)

Merchant lane parameters

object (EBT_Cash_Purchase_v9_params_order)

Order detail parameters

required
object (EBT_Cash_Balance_v9_params_pin_data)

PIN data parameters

object (EBT_Cash_Purchase_v9_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
carddenylist_check
string
Enum: "yes" "no"

Check the card deny list before going online for authorization

If on the list, decline with msoft_code=CARDDENYLIST.

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

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

Values:

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

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

Values:

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

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

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

property name*
additional property
string

Responses

Request samples

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

Response samples

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

EBT Food Balance

Get the balance on a Food account

libmonetra KVS equivalent for endpoint

  • action_trans = ebtfsbalance
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

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

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

object (EBT_Cash_Balance_v9_params_account_data)

Account information parameters

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

These are the minimum fields required for each entry method.

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

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

ENCRYPTION

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

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

required
object (EBT_Cash_Balance_v9_params_pin_data)

PIN data parameters

rcpt
string

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

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

property name*
additional property
string

Responses

Request samples

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

Response samples

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

EBT Food Purchase

Debit funds from a Food account

libmonetra KVS equivalent for endpoint

  • action_trans = ebtfssale
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

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

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

object (EBT_Cash_Balance_v9_params_account_data)

Account information parameters

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

These are the minimum fields required for each entry method.

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

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

ENCRYPTION

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

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

object (EBT_Cash_Purchase_v9_params_merchant_descriptors)

Merchant descriptor parameters

object (EBT_Cash_Purchase_v9_params_lane)

Merchant lane parameters

object (EBT_Cash_Purchase_v9_params_order)

Order detail parameters

required
object (EBT_Cash_Balance_v9_params_pin_data)

PIN data parameters

object (EBT_Cash_Purchase_v9_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
carddenylist_check
string
Enum: "yes" "no"

Check the card deny list before going online for authorization

If on the list, decline with msoft_code=CARDDENYLIST.

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

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

Values:

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

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

Values:

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

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

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

property name*
additional property
string

Responses

Request samples

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

Response samples

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

EBT Food Refund

Refund to a EBT Food account

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

libmonetra KVS equivalent for endpoint

  • action_trans = ebtfsreturn
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

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

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

object (EBT_Cash_Balance_v9_params_account_data)

Account information parameters

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

These are the minimum fields required for each entry method.

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

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

ENCRYPTION

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

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

object (EBT_Cash_Purchase_v9_params_merchant_descriptors)

Merchant descriptor parameters

object (EBT_Cash_Purchase_v9_params_lane)

Merchant lane parameters

object (EBT_Cash_Purchase_v9_params_order)

Order detail parameters

required
object (EBT_Cash_Balance_v9_params_pin_data)

PIN data parameters

object (EBT_Cash_Purchase_v9_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
carddenylist_check
string
Enum: "yes" "no"

Check the card deny list before going online for authorization

If on the list, decline with msoft_code=CARDDENYLIST.

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

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

Values:

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

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

Values:

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

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

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

property name*
additional property
string

Responses

Request samples

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

Response samples

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

Transaction Details

Transaction detail operations

Get All Payment Details For an Order

Get all order payment transaction details

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

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

libmonetra KVS equivalent for endpoint

  • action_admin = tran_detail
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

Cannot be combined with:

  • ttid
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

ttid
string
Example: ttid=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
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/v2/transaction/order/17485767483/payment' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "account": "XXXXXXXXXXXX1234",
  • "abaroute": "267084131",
  • "checknum": "45678",
  • "accounttype": "PERSONAL|CHECKING",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "cof_transid": "930734056218579",
  • "cof_authamount": "19.22",
  • "installment_num": "17",
  • "installment_total": "149",
  • "recurring": "recurring",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "shipcountry": "840",
  • "shipzip": "32789",
  • "zip": "32606",
  • "action": "SALE",
  • "orig_code": "AUTH",
  • "orig_msoft_code": "INT_SUCCESS",
  • "orig_phard_code": "SUCCESS",
  • "orig_reqamount": "155.34",
  • "orig_verbiage": "Transaction approved",
  • "merch_name": "Pizza Palace",
  • "merch_addr1": "777 77th Ct",
  • "merch_addr2": "Jacksonville FL",
  • "merch_addr3": "32789",
  • "merch_phone": "555-555-5555",
  • "merch_email": "merchant@email",
  • "merch_url": "https://url",
  • "merch_proc": "loopback",
  • "custref": "55",
  • "ordernum": "A13DDES345",
  • "amount": "19.92",
  • "cashbackamount": "20.00",
  • "currency": "124",
  • "examount": "0.33",
  • "surchargeamount": "1.25",
  • "tax": "1.29",
  • "discountamount": "100.00",
  • "dutyamount": "5.07",
  • "freightamount": "225.82",
  • "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",
  • "draft_locator_id": "24FDBDD0902",
  • "property1": "string",
  • "property2": "string"
}

Get Transaction Details

Gets fine-grained detail about a transaction

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

libmonetra KVS equivalent for endpoint

  • action_admin = tran_detail
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 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
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "account": "XXXXXXXXXXXX1234",
  • "abaroute": "267084131",
  • "checknum": "45678",
  • "accounttype": "PERSONAL|CHECKING",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "cof_transid": "930734056218579",
  • "cof_authamount": "19.22",
  • "installment_num": "17",
  • "installment_total": "149",
  • "recurring": "recurring",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "shipcountry": "840",
  • "shipzip": "32789",
  • "zip": "32606",
  • "action": "SALE",
  • "orig_code": "AUTH",
  • "orig_msoft_code": "INT_SUCCESS",
  • "orig_phard_code": "SUCCESS",
  • "orig_reqamount": "155.34",
  • "orig_verbiage": "Transaction approved",
  • "merch_name": "Pizza Palace",
  • "merch_addr1": "777 77th Ct",
  • "merch_addr2": "Jacksonville FL",
  • "merch_addr3": "32789",
  • "merch_phone": "555-555-5555",
  • "merch_email": "merchant@email",
  • "merch_url": "https://url",
  • "merch_proc": "loopback",
  • "custref": "55",
  • "ordernum": "A13DDES345",
  • "amount": "19.92",
  • "cashbackamount": "20.00",
  • "currency": "124",
  • "examount": "0.33",
  • "surchargeamount": "1.25",
  • "tax": "1.29",
  • "discountamount": "100.00",
  • "dutyamount": "5.07",
  • "freightamount": "225.82",
  • "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",
  • "draft_locator_id": "24FDBDD0902",
  • "property1": "string",
  • "property2": "string"
}

Get Transaction Details For Order Payment

Gets fine-grained detail about an order payment

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

libmonetra KVS equivalent for endpoint

  • action_admin = tran_detail
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

payment_id
required
string
Example: 987653645678

Unique ID of a payment for an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "card_currency": "840",
  • "card_cardclass": "CREDIT",
  • "card_cardlevel": "V^",
  • "card_country_code": "840",
  • "card_debit_network": "19N|14N",
  • "card_ebt_state": "HI",
  • "card_fsa": "N",
  • "card_funding_source": "CREDIT",
  • "card_issuer_bank": "1st Bank of Money",
  • "card_msr_cvm": "sig",
  • "card_prepaid": "Y",
  • "card_reloadable": "N",
  • "card_signature_debit": "N",
  • "card_token_card": "N",
  • "auth": "B2DAA3",
  • "batch": "47",
  • "issuer_decline": "Y",
  • "item": "1245",
  • "stan": "994532",
  • "proc": "loopback",
  • "account": "XXXXXXXXXXXX1234",
  • "abaroute": "267084131",
  • "checknum": "45678",
  • "accounttype": "PERSONAL|CHECKING",
  • "cardtype": "VISA",
  • "cardholdername": "John Doe",
  • "language": "en",
  • "pclevel": "0",
  • "cof_transid": "930734056218579",
  • "cof_authamount": "19.22",
  • "installment_num": "17",
  • "installment_total": "149",
  • "recurring": "recurring",
  • "avs": "GOOD",
  • "cv": "GOOD",
  • "shipcountry": "840",
  • "shipzip": "32789",
  • "zip": "32606",
  • "action": "SALE",
  • "orig_code": "AUTH",
  • "orig_msoft_code": "INT_SUCCESS",
  • "orig_phard_code": "SUCCESS",
  • "orig_reqamount": "155.34",
  • "orig_verbiage": "Transaction approved",
  • "merch_name": "Pizza Palace",
  • "merch_addr1": "777 77th Ct",
  • "merch_addr2": "Jacksonville FL",
  • "merch_addr3": "32789",
  • "merch_phone": "555-555-5555",
  • "merch_email": "merchant@email",
  • "merch_url": "https://url",
  • "merch_proc": "loopback",
  • "custref": "55",
  • "ordernum": "A13DDES345",
  • "amount": "19.92",
  • "cashbackamount": "20.00",
  • "currency": "124",
  • "examount": "0.33",
  • "surchargeamount": "1.25",
  • "tax": "1.29",
  • "discountamount": "100.00",
  • "dutyamount": "5.07",
  • "freightamount": "225.82",
  • "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",
  • "draft_locator_id": "24FDBDD0902",
  • "property1": "string",
  • "property2": "string"
}

Transaction Receipts

Receipts can be generated for transactions, payments, and orders

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

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

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

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

Email

Email of receipts will contain a formatted receipt.

SMS

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

Pre-formatted

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

Email Transaction Receipt

Email a receipt for a transaction to the customer

libmonetra KVS equivalent for endpoint

  • action_admin = tran_receipt
Authorizations:
basic_auth(apikey_idapikey)
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
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

email
required
string
Example: email=email@email

Email to send customer receipt copy to

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

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

Values:

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

Responses

Request samples 

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

Response samples

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

Email Transaction Receipt For Order Payment

Email a receipt for an order payment to a customer

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

libmonetra KVS equivalent for endpoint

  • action_admin = tran_receipt
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

payment_id
required
string
Example: 987653645678

Unique ID of a payment for an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

email
required
string
Example: email=email@email

Email to send customer receipt copy to

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

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

Values:

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

Values:

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

Responses

Request samples 

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

Response samples

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

Email an Invoice to Customer

Email a link to view the invoice to a customer

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

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

libmonetra KVS equivalent for endpoint

  • action_admin = tran_receipt
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

email
required
string
Example: email=email@email

Email to send customer receipt copy to

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

Responses

Request samples 

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

Response samples

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

Get Transaction Receipt

Get Pre-formatted receipt for a transaction

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

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

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

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

libmonetra KVS equivalent for endpoint

  • action_admin = tran_receipt
Authorizations:
basic_auth(apikey_idapikey)
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
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

rcpt
string
Example: rcpt=yes

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Cannot be combined with:

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

Values:

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

Values:

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

Responses

Request samples 

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

Response samples

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

Get Transaction Receipt For Order Payment

Get Pre-formatted receipt for an order payment

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

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

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

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

libmonetra KVS equivalent for endpoint

  • action_admin = tran_receipt
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

payment_id
required
string
Example: 987653645678

Unique ID of a payment for an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

rcpt
string
Example: rcpt=yes

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

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

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

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

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

rcpt=type=plain|html

Receipt configuration options:

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

Values:

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

Values:

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

Responses

Request samples 

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

Response samples

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

SMS an Invoice to Customer

SMS a link to view the invoice to a customer

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

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

libmonetra KVS equivalent for endpoint

  • action_admin = tran_receipt
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

sms
required
string
Example: sms=555-555-5555

Send SMS for order invoices

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

Requires:

  • order_id

Cannot be combined with:

  • ttid
  • payment_id

Responses

Request samples 

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

Response samples

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

Transaction Reports

Transaction Report operations

List Declined Transactions

Lists all failed transactions for the requested profile

The resulting report will contain these headers:

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

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

libmonetra KVS equivalent for endpoint

  • action_admin = report_tran
  • txnstatus = DECLINED
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

acct
string
Example: acct=5454

Account number for auditing

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

amount
string
Example: amount=19.92

Amount of money, including decimal. E.g 1.00

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

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder

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

Cardtypes

Pipe (|) separated.

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

Flag values (pipe separated):

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

Identifier for the clerk running the transaction

comments
string
Example: comments=Extra beef

User-defined comments related to the transaction

ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to 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.

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/v2/report/declined' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

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

List Device Journal

Lists all transactions for the requested device

The resulting report will contain these headers:

timestamp, user_id, group_id, device_type, device_sn, device_kernver,
device_firmware, device_app, device_appver, action, ttid, profile_id

Note: only 30 days of this history is retained.

libmonetra KVS equivalent for endpoint

  • action_admin = report_device
  • report_device = journal
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
id
string
Example: id=5678967654

Conditional. User id of user to operate on, if not provided, user will be used if it was provided

Cannot be combined with:

  • user
user
string
Example: user=user2

Conditional. Username of user to operate on, if not provided, id will be used if it was provided

Cannot be combined with:

  • id
group_id
string
Example: group_id=36789654543

Group identifier

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.

profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

device_sn
string
maxdepth
string
Example: maxdepth=4

Maximum depth to display

Default is unlimited. Specify 1 to see only self and children.

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/v2/device/journal' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

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

List Settled Transactions

Lists all settled transactions for the requested profile

The resulting report will contain these headers:

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

libmonetra KVS equivalent for endpoint

  • action_admin = report_tran
  • txnstatus = COMPLETE
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

acct
string
Example: acct=5454

Account number for auditing

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

amount
string
Example: amount=19.92

Amount of money, including decimal. E.g 1.00

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

batch
string
Example: batch=47

The batch number associated with the transaction

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder

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

Cardtypes

Pipe (|) separated.

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

Flag values (pipe separated):

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

Identifier for the clerk running the transaction

comments
string
Example: comments=Extra beef

User-defined comments related to the transaction

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

Indicates the level of payment card

Values:

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

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to 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.

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.

ttid_ref
string

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

order_id
string
Example: order_id=7654323456

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

token
string
Example: token=6789656783904467894

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

type
string
Example: type=sale

Type of action that was taken.

Can be a pipe (|) separated list of actions

last_modified_bdate
string
Example: last_modified_bdate=-9 days

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

last_modified_edate
string
Example: last_modified_edate=-4 days

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

user
string
Example: user=user19

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

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

Whether or not the report should include reversible transactions

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

Values:

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

Whether or not the report should include voids

Values:

  • yes - Include voided transactions
  • no - Do not include voided transactions
  • only - Only show voided transactions
route_id
string
Example: route_id=0

Processing route

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

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

Include interchange response data

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

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

Values:

  • yes - Include interchange response data
  • no - Do not include interchange response data
tranflags
object
Enum: "HASAVS" "CAVVFULL" "CAVVBAD" "DATATRACK1" "DATATRACK2" "DATAKEYED" "DATAMICR" "CARDNOTPRESENT" "ADVANCEDEPOSIT" "NONTAXABLE" "RFID" "NSF" "RECURRING" "RECURRING_FIRST" "INSTALLMENT" "PINLESS" "HEALTHCARE" "SNF_APPROVED" "SNF_DENY" "ACCT_BUSINESS" "PARTIALAUTH" "NOSHOW" "RFIDCAPABLE" "DIGITAL_GOODS" "PROC_E2E" "CNP_ECOMM" "CARDSHIELD_E2E" "ICC" "EMV_FALLBACK" "EMV_OFFLINE" "DEBTREPAYMENT" "PROC_TOKEN" "MOBILEINAPP" "CARDONFILE" "STANDIN" "PINBYPASS" "ENCPROV_E2E" "INCREMENTAL" "ACCT_SAVINGS" "EMV_FALLBACK_NOAID" "HOSTEDPAGE"
Example: tranflags=CAPTURED|ONLINE|SENSITIVEDATA

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

Flag values (pipe separated):

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

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

Flag values (pipe separated):

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

Responses

Request samples 

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

Response samples

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

List Transactions

Lists all transactions for the requested profile

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

The resulting report will contain these headers:

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

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

txnstatus
required
object
Enum: "DECLINED" "UNCAPTURED" "CAPTURED" "COMPLETE"
Example: txnstatus=DECLINED|UNCAPTURED|CAPTURED|COMPLETE

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

Flag values (pipe separated):

  • DECLINED - Transaction has been declined
  • UNCAPTURED - Transaction is in the unsettled and uncaptured state
  • CAPTURED - Transaction is in the unsettled, but captured (ready for settlement) state
  • COMPLETE - Transaction is complete (settled or voided)
acct
string
Example: acct=5454

Account number for auditing

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

amount
string
Example: amount=19.92

Amount of money, including decimal. E.g 1.00

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

batch
string
Example: batch=47

The batch number associated with the transaction

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder

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

Cardtypes

Pipe (|) separated.

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

Flag values (pipe separated):

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

Identifier for the clerk running the transaction

comments
string
Example: comments=Extra beef

User-defined comments related to the transaction

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

Indicates the level of payment card

Values:

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

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to 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.

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.

ttid_ref
string

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

order_id
string
Example: order_id=7654323456

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

token
string
Example: token=6789656783904467894

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

type
string
Example: type=sale

Type of action that was taken.

Can be a pipe (|) separated list of actions

last_modified_bdate
string
Example: last_modified_bdate=-9 days

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

last_modified_edate
string
Example: last_modified_edate=-4 days

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

user
string
Example: user=user19

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

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

Whether or not the report should include reversible transactions

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

Values:

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

Whether or not the report should include voids

Values:

  • yes - Include voided transactions
  • no - Do not include voided transactions
  • only - Only show voided transactions
route_id
string
Example: route_id=0

Processing route

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

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

Include interchange response data

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

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

Values:

  • yes - Include interchange response data
  • no - Do not include interchange response data
tranflags
object
Enum: "HASAVS" "CAVVFULL" "CAVVBAD" "DATATRACK1" "DATATRACK2" "DATAKEYED" "DATAMICR" "CARDNOTPRESENT" "ADVANCEDEPOSIT" "NONTAXABLE" "RFID" "NSF" "RECURRING" "RECURRING_FIRST" "INSTALLMENT" "PINLESS" "HEALTHCARE" "SNF_APPROVED" "SNF_DENY" "ACCT_BUSINESS" "PARTIALAUTH" "NOSHOW" "RFIDCAPABLE" "DIGITAL_GOODS" "PROC_E2E" "CNP_ECOMM" "CARDSHIELD_E2E" "ICC" "EMV_FALLBACK" "EMV_OFFLINE" "DEBTREPAYMENT" "PROC_TOKEN" "MOBILEINAPP" "CARDONFILE" "STANDIN" "PINBYPASS" "ENCPROV_E2E" "INCREMENTAL" "ACCT_SAVINGS" "EMV_FALLBACK_NOAID" "HOSTEDPAGE"
Example: tranflags=CAPTURED|ONLINE|SENSITIVEDATA

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

Flag values (pipe separated):

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

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

Flag values (pipe separated):

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

Responses

Request samples 

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

Response samples

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

List Unsettled Transactions

Lists all unsettled transactions for the requested profile

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

The resulting report will contain these headers:

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

libmonetra KVS equivalent for endpoint

  • action_admin = report_tran
  • txnstatus = CAPTURED|UNCAPTURED
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

acct
string
Example: acct=5454

Account number for auditing

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

amount
string
Example: amount=19.92

Amount of money, including decimal. E.g 1.00

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

batch
string
Example: batch=47

The batch number associated with the transaction

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder

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

Cardtypes

Pipe (|) separated.

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

Flag values (pipe separated):

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

Identifier for the clerk running the transaction

comments
string
Example: comments=Extra beef

User-defined comments related to the transaction

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

Indicates the level of payment card

Values:

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

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to 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.

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.

ttid_ref
string

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

order_id
string
Example: order_id=7654323456

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

token
string
Example: token=6789656783904467894

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

type
string
Example: type=sale

Type of action that was taken.

Can be a pipe (|) separated list of actions

last_modified_bdate
string
Example: last_modified_bdate=-9 days

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

last_modified_edate
string
Example: last_modified_edate=-4 days

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

user
string
Example: user=user19

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

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

Whether or not the report should include reversible transactions

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

Values:

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

Whether or not the report should include voids

Values:

  • yes - Include voided transactions
  • no - Do not include voided transactions
  • only - Only show voided transactions
route_id
string
Example: route_id=0

Processing route

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

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

Include interchange response data

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

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

Values:

  • yes - Include interchange response data
  • no - Do not include interchange response data
tranflags
object
Enum: "HASAVS" "CAVVFULL" "CAVVBAD" "DATATRACK1" "DATATRACK2" "DATAKEYED" "DATAMICR" "CARDNOTPRESENT" "ADVANCEDEPOSIT" "NONTAXABLE" "RFID" "NSF" "RECURRING" "RECURRING_FIRST" "INSTALLMENT" "PINLESS" "HEALTHCARE" "SNF_APPROVED" "SNF_DENY" "ACCT_BUSINESS" "PARTIALAUTH" "NOSHOW" "RFIDCAPABLE" "DIGITAL_GOODS" "PROC_E2E" "CNP_ECOMM" "CARDSHIELD_E2E" "ICC" "EMV_FALLBACK" "EMV_OFFLINE" "DEBTREPAYMENT" "PROC_TOKEN" "MOBILEINAPP" "CARDONFILE" "STANDIN" "PINBYPASS" "ENCPROV_E2E" "INCREMENTAL" "ACCT_SAVINGS" "EMV_FALLBACK_NOAID" "HOSTEDPAGE"
Example: tranflags=CAPTURED|ONLINE|SENSITIVEDATA

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

Flag values (pipe separated):

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

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

Flag values (pipe separated):

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

Responses

Request samples 

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

Response samples

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

Chart Data

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

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

Card Type Chart Data

Totals for card types used to generate charts

The resulting report will contain these headers:

cardtype count

libmonetra KVS equivalent for endpoint

  • action_admin = report_chartdata
  • chartdata = cardtype
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

bdate
required
string
Example: bdate=-6 months

Start of date range

edate
required
string
Example: edate=now

End of date range

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

Group chart data within a time period

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

Values:

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

Responses

Request samples 

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

Response samples

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

Order Chart Data

Totals for orders used to generate charts

The resulting report will contain these headers:

ts_begin, ts_end, sale_count, sale_amount, return_count, return_amount

libmonetra KVS equivalent for endpoint

  • action_admin = report_chartdata
  • chartdata = orders
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

bdate
required
string
Example: bdate=-6 months

Start of date range

edate
required
string
Example: edate=now

End of date range

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

Group chart data within a time period

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

Values:

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

Responses

Request samples 

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

Response samples

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

Transaction Chart Data

Totals for transactions used to generate charts

The resulting report will contain these headers:

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

libmonetra KVS equivalent for endpoint

  • action_admin = report_chartdata
  • chartdata = transactions
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

bdate
required
string
Example: bdate=-6 months

Start of date range

edate
required
string
Example: edate=now

End of date range

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

Group chart data within a time period

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

Values:

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

Responses

Request samples 

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

Response samples

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

Level 3

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

Limitations

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

Not all processors support Level 3 line items.

Adding line items

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

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

A transaction can be associated in two ways:

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

Line item pre-populate

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

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

List Line Items

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

The resulting report will contain these headers:

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

libmonetra KVS equivalent for endpoint

  • action_admin = level3
  • level3 = list
Authorizations:
basic_auth(apikey_idapikey)
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
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

Responses

Request samples 

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

Response samples

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

Add Line Item

Adds Level 3 line item to an unsettled transaction

libmonetra KVS equivalent for endpoint

  • action_admin = level3
  • level3 = add
Authorizations:
basic_auth(apikey_idapikey)
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
profile_id
string\d+

Merchant profile identifier

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

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

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

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

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

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

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

Merchant-defined description of the item or service being sold

This is a free-form field.

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

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

qty
required
string

Quantity of the item being purchased

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

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

unit
required
string

Free-form unit of measure

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

unitprice
required
string

Item price per Unit

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

Minimum amount is 0.00005. Maximum amount is 9999999.99.

discountamount
string

Discount amount per line item

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

Minimum amount is 0.00. Maximum amount is 9999999.99.

discountrate
string

Discount rate per line item

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

Minimum rate is 0.00. Maximum rate is 99.99.

amount
required
string

Line item total amount

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

Minimum amount is 0.01. Maximum amount is 9999999.99.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "commoditycode": "50301700",
  • "description": "Pickles",
  • "productcode": "7456",
  • "qty": "1",
  • "unit": "1",
  • "unitprice": "0.25",
  • "discountamount": "2.53",
  • "discountrate": "4.05",
  • "amount": "1.51"
}

Response samples

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

Delete Line Item

Deletes Level 3 line item from an unsettled transaction

libmonetra KVS equivalent for endpoint

  • action_admin = level3
  • level3 = del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 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

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

Responses

Request samples 

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

Response samples

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

Get Line Item Details

Gets the specified line item for the transaction

libmonetra KVS equivalent for endpoint

  • action_admin = level3
  • level3 = list
Authorizations:
basic_auth(apikey_idapikey)
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

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "l3id": "56789673",
  • "ttid": "18446744073709551615",
  • "commoditycode": "50301700",
  • "description": "Pickles",
  • "productcode": "7456",
  • "qty": "1",
  • "unit": "1",
  • "unitprice": "0.25",
  • "discountamount": "2.53",
  • "discountrate": "4.05",
  • "amount": "1.51"
}

Batch

Basic and advanced batch management operations.

Basic operations manual settlement and reports.

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

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

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

Clear a Batch

Marks the batch as settled within TranSafe without ever requesting funding

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

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

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

libmonetra KVS equivalent for endpoint

  • action_admin = batch_clear
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
batch
required
string
Example: 47

The batch number associated with the transaction

route_id
required
string
Example: 0

Processing route

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

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

Merchant profile identifier

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

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

Responses

Request samples

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

Response samples

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

Close a Batch

Close the currently open batch without sending it to the processor

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

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

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

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

libmonetra KVS equivalent for endpoint

  • action_admin = batch_close
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
batch
required
string
Example: 47

The batch number associated with the transaction

route_id
required
string
Example: 0

Processing route

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

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

Merchant profile identifier

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

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

Responses

Request samples

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

Response samples

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

Get Settled Batch Totals

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

The resulting report will contain these headers:

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

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

batch
string
Example: batch=47

The batch number associated with the transaction

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

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

Whether or not the report should include reversible transactions

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

Values:

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

Responses

Request samples 

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

Response samples

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

Get Unsettled Batch Totals

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

The resulting report will contain these headers:

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

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

batch
string
Example: batch=47

The batch number associated with the transaction

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

Responses

Request samples 

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

Response samples

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

Renumber Single Batch

Change an individual batch's number.

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

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

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

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

libmonetra KVS equivalent for endpoint

  • action_admin = batch_set
  • batch_set = renumber
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
batch
required
string
Example: 47

The batch number associated with the transaction

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

Merchant profile identifier

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

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

newbatch
required
string
route_id
string\d+

Processing route

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

Responses

Request samples

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

Response samples

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

Resequence Open Batch Numbers

Set open batch numbering to the given value

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

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

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

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

libmonetra KVS equivalent for endpoint

  • action_admin = batch_set
  • batch_set = batchnum
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

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

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

batch
required
string\d+

The batch number associated with the transaction

route_id
string\d+

Processing route

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

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "batch": "47",
  • "route_id": "0"
}

Response samples

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

Settle Batch

Submits transactions for funding

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

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

libmonetra KVS equivalent for endpoint

  • action_trans = settle
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
batch
required
string
Example: 47

The batch number associated with the transaction

route_id
required
string
Example: 0

Processing route

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

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

Merchant profile identifier

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

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

Responses

Request samples

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

Response samples

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

Unsettle Batch

Marks a batch in TranSafe as unsettled

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

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

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

libmonetra KVS equivalent for endpoint

  • action_admin = batch_rescind
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
batch
required
string
Example: 47

The batch number associated with the transaction

route_id
required
string
Example: 0

Processing route

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

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

Merchant profile identifier

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

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

Responses

Request samples

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

Response samples

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

Image

Image operations

Delete Check

Delete a check image

libmonetra KVS equivalent for endpoint

  • action_admin = image_del
  • image_type = check
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 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
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

Responses

Request samples 

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

Response samples

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

Delete Signature

Delete a signature image

libmonetra KVS equivalent for endpoint

  • action_admin = image_del
  • image_type = signature
Authorizations:
basic_auth(apikey_idapikey)
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
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

Responses

Request samples 

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

Response samples

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

Store Signature

Stores a signature.

Typically used for receipts

libmonetra KVS equivalent for endpoint

  • action_admin = image_add
  • image_type = signature
Authorizations:
basic_auth(apikey_idapikey)
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
profile_id
string\d+

Merchant profile identifier

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

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

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

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

Responses

Request samples

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

Response samples

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

Get Images

Gets images for the specified transaction.

See List Images for report output

libmonetra KVS equivalent for endpoint

  • action_admin = image_get
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
ttid
required
string
Example: 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
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/v2/image/4783758439245' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

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

List Images

Lists stored images

The resulting report will contain these headers:

ttid, ts, status, ptrannum, batch, image_type, image

libmonetra KVS equivalent for endpoint

  • action_admin = image_get
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
batch
string
Example: batch=47

The batch number associated with the transaction

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

Transaction status

Values:

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

Start of date range

edate
string
Example: edate=now

End of date range

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

Image format

Values:

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

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/image?bdate=-5%20months&edate=now' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

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

Account Vault

The account vault allows for security storing customer accounts. Both cards and ACH information.

When storing an account it is recommended to tokenize the as part of a transaction instead of manually creating an entry. If no charge is taking place at the time, it is recommended to use the verification transaction to at least verify the card is valid.

Stored accounts can be referenced when processing transactions to charge the card. They can also be attached to a schedule for an installment or recurring payment. Additionally, they can be attached to a customer.

When working with customers in the customer system, a default_token can be associated with the customer for using the customer to process payments. Additionally a stored account can have a customer_id set to associate the account to a customer. A customer can have multiple stored accounts associated with them.

It is recommend that a zip code be added to the stored account to ensure proper interchange rates.

Remove Account

Permanently removes a stored account from the vault

libmonetra KVS equivalent for endpoint

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

Referent to the account data that's been stored

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

Responses

Request samples 

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

Response samples

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

Get Account Details

Gets details for the specified stored account

libmonetra KVS equivalent for endpoint

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

Referent to the account data that's been stored

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

Responses

Request samples 

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

Response samples

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

Edit Account

Edits a stored account

libmonetra KVS equivalent for endpoint

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

Referent to the account data that's been stored

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

Merchant profile identifier

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

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

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

Token status

Values:

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

cust_regdate
string

E-commerce only

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

Responses

Request samples

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

Response samples

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

Export Accounts

Export stored account tokens

Stored accounts are exported per group and are only exported encrypted. A PGP public key must be provided in order to encrypt the report data.

Stored account tokens can only be exported by users within the top most group. Users within a sub group cannot export stored accounts.

The resulting PGP encrypted data will contain a report which will contain these headers:

token, create_ts, update_ts, flags, status, cardtype, abaroute, account,
expdate, cardholdername, descr, clientref, customer_id, street, zip, descmerch,
descloc

libmonetra KVS equivalent for endpoint

  • action_su = token_export
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
pgp_pubkey
required
string

PGP public key

group_id
required
string\d+

Group identifier

Responses

Request samples

Content type
application/json
{
  • "pgp_pubkey": "...",
  • "group_id": "36789654543"
}

Response samples

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

Get Stored Account Count

Get count of stored accounts for the user's group

libmonetra KVS equivalent for endpoint

  • action_admin = token_list
  • token_list = count
Authorizations:
basic_auth(apikey_idapikey)

Responses

Request samples 

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

Response samples

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

List Accounts

Lists stored account details

The resulting report will contain these headers:

token, tokengroup_id, create_profile_id, create_ts, update_ts, type, flags,
status, cardtype, abaroute, account, expdate, cardholdername, descr, clientref,
customer_id, au_ts, au_status, street, zip, descmerch, descloc, cust_regdate

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

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

Token active status

Values:

  • yes - The token is active
  • no - The token is not active
clientref
string
Example: clientref=55

Reference number associated with the customer

id
string
Example: id=56789687564

Customer identifier

expdate_end
string
Example: expdate_end=1022

Maximum expiration date a card can have. Limit all expiration dates to before this time.

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder.

Will be read from account data (EMV, Track 1, etc.) but is not guaranteed to be present. Some presentation methods, such as keyed, do not have any way to capture the name as part of the account data.

Further, Visa explicitly does not allow the cardholder name to be transmitted as part of a contactless read. Typically, a contactless read will result in a cardholder name of "/".

If the name is known by another means, it can be entered in this parameter to override what was read (or not read) from the card.

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/v2/vault/account?active=no&cardtypes=VISA%7CMC' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

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

Store Account

Stores an account

Allows for manually tokenizing a payment method and storing it in the token vault. The token can be used for later transaction processing.

Note: Tokenization can happen at time of authorization or verification by using the tokenize=yes parameter as part of the transaction.

libmonetra KVS equivalent for endpoint

  • action_admin = token_add
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

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

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

object (Store_Account_v9_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.

ttid
string [ 1 .. 38 ] characters [a-zA-Z0-9+ _-{}]{1,38}

Transaction identifier of previously authorized transaction to load account data from

Cannot be combined with:

  • account_data
  • carddenylist_id
carddenylist_id
string\d+

ID in the card deny/allow list

Cannot be combined with:

  • account_data
  • ttid
street
string

Street address for AVS.

Typically, only numbers need to be passed in this field, as letters and other characters are ignored by the processor

zip
string <= 32 characters

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

clientref
string\d+

Reference number associated with the customer

matching_token
string
Enum: "yes" "no"

When enabled, the token vault will be searched for tokens matching this account. If found, the token will be updated instead of a new token being added.

Values:

  • yes - Try to match an existing token with this account
  • no - Do not try to match an existing token with this account
customer_id
string[0-9]+

Customer identifier, numeric only

cof_transid
string

Transaction ID from initial transaction

cof_authamount
string

Authorized amount from initial transaction

cust_regdate
string

E-commerce only

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

descr
string <= 128 characters

Description of the account

Responses

Request samples

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

Response samples

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

Scheduled Payments

Scheduled payments allow using a stored account to be charged on a configured period. Both recurring and installment payments are supported.

Scheduled payments are a schedule and instructions on how much, how often, and what to charge. They are linked to a stored account stored in TranSafe. The stored account a schedule is using for the charge can be changed to a different account. This allows updating schedules without disrupting them.

List Installment Payments

Lists installment payment details

The resulting report will contain these headers:

id, token, create_ts, update_ts, type, flags, status, cardtype, account,
cardholdername, bdate, edate, frequency, installment_total, amount, last_run,
last_run_success, last_run_ttid, next_run, installment_num, total_paid, notes

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

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

clientref
string
Example: clientref=55

Reference number associated with the customer

customer_id
string
Example: customer_id=56789687564

Customer identifier, numeric only

expdate_end
string
Example: expdate_end=1022

Maximum expiration date a card can have. Limit all expiration dates to before this time.

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder.

Will be read from account data (EMV, Track 1, etc.) but is not guaranteed to be present. Some presentation methods, such as keyed, do not have any way to capture the name as part of the account data.

Further, Visa explicitly does not allow the cardholder name to be transmitted as part of a contactless read. Typically, a contactless read will result in a cardholder name of "/".

If the name is known by another means, it can be entered in this parameter to override what was read (or not read) from the card.

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

status
object
Enum: "ACTIVE" "DISABLED" "ERROR" "DONE" "PENDING"
Example: status=ACTIVE

Status of scheduled payment

Values:

  • ACTIVE - Payment will process at the next scheduled time
  • DISABLED - Payment will not process at the next scheduled time. Payment can be re-activated to continue processing. If the RECURRING_SKIPMISSED flag is not set a catchup for all missed payments will take place.
  • ERROR - Payment will not process at the next scheduled time. Payment has failed in a way that corrective action must be taken. For example, account closed.
  • DONE - Payment will not process at the next scheduled time. Payment sequence has been completed based on configured schedule.
  • PENDING - Payment is enabled but has not processed any payments

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/vault/payment/installment?active=yes' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

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

Add Installment Payment

Adds an installment payment

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = add
  • type = installment
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

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

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

customer_id
string[0-9]+

Customer identifier, numeric only

token
required
string\d+

Reference to the stored account that's being charged for the scheduled payment

clientref
string\d+

Reference number associated with the customer

cof_transid
string

Transaction ID from initial transaction

cof_authamount
string

Authorized amount from initial transaction

descr
string <= 128 characters

Description of the payment

bdate
string

Start of date range

installment_total
required
string\d+

Total number of installment payments to make

frequency
required
string
Enum: "daily" "weekly" "biweekly" "monthly" "bimonthly" "quarterly" "semiannually" "annually"

Frequency of payment

Values:

  • daily - Takes place every day
  • weekly - Takes place every week on the given day of week. Ex. Every Wednesday
  • biweekly - Takes place every two weeks on the given day. Ex. Every other Friday
  • monthly - Takes place every month on the given day of the month. If the day is after the last day of the month (e.g. 31st when the month only has 30 days), the last day of the month will be used for that month
  • bimonthly - Takes place every two months on the given day of the month
  • quarterly - Takes place every three months on the given day of the month
  • semiannually - Takes place every six months
  • annually - Takes place once a year
amount
required
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

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

status
string
Enum: "active" "disabled"

Schedule active status

Values:

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

Responses

Request samples

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

Response samples

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

List Recurring Payments

Lists recurring payment details

The resulting report will contain these headers:

id, token, create_ts, update_ts, type, flags, status, cardtype, account,
cardholdername, bdate, edate, frequency, installment_total, amount, last_run,
last_run_success, last_run_ttid, next_run, installment_num, total_paid, notes

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

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

clientref
string
Example: clientref=55

Reference number associated with the customer

customer_id
string
Example: customer_id=56789687564

Customer identifier, numeric only

expdate_end
string
Example: expdate_end=1022

Maximum expiration date a card can have. Limit all expiration dates to before this time.

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder.

Will be read from account data (EMV, Track 1, etc.) but is not guaranteed to be present. Some presentation methods, such as keyed, do not have any way to capture the name as part of the account data.

Further, Visa explicitly does not allow the cardholder name to be transmitted as part of a contactless read. Typically, a contactless read will result in a cardholder name of "/".

If the name is known by another means, it can be entered in this parameter to override what was read (or not read) from the card.

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

status
object
Enum: "ACTIVE" "DISABLED" "ERROR" "DONE" "PENDING"
Example: status=ACTIVE

Status of scheduled payment

Values:

  • ACTIVE - Payment will process at the next scheduled time
  • DISABLED - Payment will not process at the next scheduled time. Payment can be re-activated to continue processing. If the RECURRING_SKIPMISSED flag is not set a catchup for all missed payments will take place.
  • ERROR - Payment will not process at the next scheduled time. Payment has failed in a way that corrective action must be taken. For example, account closed.
  • DONE - Payment will not process at the next scheduled time. Payment sequence has been completed based on configured schedule.
  • PENDING - Payment is enabled but has not processed any payments

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/vault/payment/recurring?clientref=55' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

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

Add Recurring Payment

Adds a recurring payment

libmonetra KVS equivalent for endpoint

  • action_admin = token_schedule
  • token_schedule = add
  • type = recurring
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

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

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

status
string
Enum: "active" "disabled"

Schedule active status

Values:

  • active - The schedule is active
  • disabled - The schedule is disabled
token
required
string\d+

Reference to the stored account that's being charged for the scheduled payment

clientref
string\d+

Reference number associated with the customer

cof_transid
string

Transaction ID from initial transaction

cof_authamount
string

Authorized amount from initial transaction

descr
string <= 128 characters

Description of of the payment

bdate
string

Start of date range

edate
string

End of date range

frequency
required
string
Enum: "daily" "weekly" "biweekly" "monthly" "bimonthly" "quarterly" "semiannually" "annually"

Frequency of payment

Values:

  • daily - Takes place every day
  • weekly - Takes place every week on the given day of week. Ex. Every Wednesday
  • biweekly - Takes place every two weeks on the given day. Ex. Every other Friday
  • monthly - Takes place every month on the given day of the month. If the day is after the last day of the month (e.g. 31st when the month only has 30 days), the last day of the month will be used for that month
  • bimonthly - Takes place every two months on the given day of the month
  • quarterly - Takes place every three months on the given day of the month
  • semiannually - Takes place every six months
  • annually - Takes place once a year
amount
required
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

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

property name*
additional property
string

Responses

Request samples

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

Response samples

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

Get Installment Payment Details

Gets details for the specified installment payment

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

libmonetra KVS equivalent for endpoint

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

Schedule ID

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "id": "565432",
  • "token": "765432767",
  • "create_ts": "2022-05-24 15:06:13 -0400",
  • "update_ts": "2022-05-24 15:06:13 -0400",
  • "type": "NORMAL",
  • "flags": "ACCT_BUSINESS",
  • "status": "ACTIVE",
  • "cardtype": "VISA",
  • "account": "XXXXXXXXXXXX1234",
  • "cardholdername": "John Doe",
  • "bdate": "-6 months",
  • "edate": "now",
  • "installment_total": "149",
  • "amount": "19.92",
  • "last_run": "2022-05-24 15:06:13 -0400",
  • "last_run_success": "2022-05-24 15:06:13 -0400",
  • "last_run_ttid": "214372416680781",
  • "next_run": "2022-06-24 15:06:13 -0400",
  • "installment_num": "17",
  • "total_paid": "155.34",
  • "notes": "This is a note",
  • "property1": "string",
  • "property2": "string"
}

Edit Installment Payment

Edits a stored installment payment

libmonetra KVS equivalent for endpoint

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

Schedule ID

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

Merchant profile identifier

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

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

status
string
Enum: "active" "disabled"

Schedule active status

Values:

  • active - The schedule is active
  • disabled - The schedule is disabled
customer_id
string[0-9]+

Customer identifier, numeric only

token
string\d+

Referent to the account data that's been stored

clientref
string\d+

Reference number associated with the customer

cof_transid
string

Transaction ID from initial transaction

cof_authamount
string

Authorized amount from initial transaction

descr
string <= 128 characters

Description of the payment

bdate
string

Start of date range

installment_total
string\d+

Total number of installment payments to make

frequency
string
Enum: "daily" "weekly" "biweekly" "monthly" "bimonthly" "quarterly" "semiannually" "annually"

Frequency of payment

Values:

  • daily - Takes place every day
  • weekly - Takes place every week on the given day of week. Ex. Every Wednesday
  • biweekly - Takes place every two weeks on the given day. Ex. Every other Friday
  • monthly - Takes place every month on the given day of the month. If the day is after the last day of the month (e.g. 31st when the month only has 30 days), the last day of the month will be used for that month
  • bimonthly - Takes place every two months on the given day of the month
  • quarterly - Takes place every three months on the given day of the month
  • semiannually - Takes place every six months
  • annually - Takes place once a year
amount
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

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

property name*
additional property
string

Responses

Request samples

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

Response samples

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

Get Recurring Payment Detail

Gets details for the specified recurring payment

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

libmonetra KVS equivalent for endpoint

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

Schedule ID

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

Responses

Request samples 

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

Response samples

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

Edit Recurring Payment

Edits a stored recurring payment

libmonetra KVS equivalent for endpoint

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

Schedule ID

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

Merchant profile identifier

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

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

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

Whether missed payments should be skipped

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

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

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

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

Values:

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

Schedule active status

Values:

  • active - The schedule is active
  • disabled - The schedule is disabled
token
string\d+

Reference to the stored account that's being charged for the scheduled payment

clientref
string\d+

Reference number associated with the customer

cof_transid
string

Transaction ID from initial transaction

cof_authamount
string

Authorized amount from initial transaction

descr
string <= 128 characters

Description of of the payment

bdate
string

Start of date range

edate
string

End of date range

frequency
string
Enum: "daily" "weekly" "biweekly" "monthly" "bimonthly" "quarterly" "semiannually" "annually"

Frequency of payment

Values:

  • daily - Takes place every day
  • weekly - Takes place every week on the given day of week. Ex. Every Wednesday
  • biweekly - Takes place every two weeks on the given day. Ex. Every other Friday
  • monthly - Takes place every month on the given day of the month. If the day is after the last day of the month (e.g. 31st when the month only has 30 days), the last day of the month will be used for that month
  • bimonthly - Takes place every two months on the given day of the month
  • quarterly - Takes place every three months on the given day of the month
  • semiannually - Takes place every six months
  • annually - Takes place once a year
amount
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

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

property name*
additional property
string

Responses

Request samples

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

Response samples

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

List Payment History

Lists transactions that have been run by the recurring billing system

This includes both recurring and installment payments but does not include transactions run using stored accounts.

The resulting report will contain these headers:

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

libmonetra KVS equivalent for endpoint

  • action_admin = report_tran
  • token = yes
  • txnstatus = CAPTURED|UNCAPTURED|COMPLETE|DECLINED
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

token
string
Example: token=6789656783904467894

Referent to the account data that's been stored

customer_id
string
Example: customer_id=56789687564

Customer identifier, numeric only

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/vault/payment/history?bdate=-1%20year&edate=now' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

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

Remove Stored Payment

Permanently removes a stored payment from the vault

libmonetra KVS equivalent for endpoint

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

Schedule ID

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

Responses

Request samples 

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

Response samples

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

Card Deny List

The card deny list is an internal, merchant maintained, list of cards or ACH accounts. Card deny list entries are shared among the token sharing group. Entries indicate accounts that are problematic and should no longer be transacted with.

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

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

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

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

List Deny List

Lists accounts on the card deny list

The resulting report will contain these headers:

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

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

expdate_bdate
string
Example: expdate_bdate=-5 months

Used to filter report by card expiration date range. Expiration is when the card expires, the expdate parameter sent with account. This is the beginning date of the expiration date range to match.

expdate_edate
string
Example: expdate_edate=-2 months

Used to filter report by card expiration date range. Expiration is when the card expires, the expdate parameter sent with account. This is the ending date of the expiration date range to match.

added_bdate
string
Example: added_bdate=-5 months

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

added_edate
string
Example: added_edate=-2 months

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

last_seen_bdate
string
Example: last_seen_bdate=-5 months

Used to filter report by last seen date range. This is the beginning date of the last seen date range to match.

last_seen_edate
string
Example: last_seen_edate=-2 months

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

expire_bdate
string
Example: expire_bdate=-5 months

Used to filter report by expire date range

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

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

expire_edate
string
Example: expire_edate=-2 months

Used to filter report by expire date range

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

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

Responses

Request samples 

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

Response samples

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

Add to Deny List

Add a card to the deny list

libmonetra KVS equivalent for endpoint

  • action_admin = carddenylist
  • carddenylist = add
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

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

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

object (Add_to_Allow_List_v9_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.

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

Reason an account was added to the deny list

Values:

  • UNSPECIFIED - Manual or API entry with no reason specified
  • DECLINE - Due to decline
  • TESTCARD - Identified as a test card
  • CHARGEBACK - Due to receiving a chargeback
  • FRAUDCHECK - Due to a fraud check failing
expire
string

How long to keep a card on file before being automatically removed

Standard date format accepted by the payment server. Can be a specific date to expire on or a relative data (E.g "+10 days").

Default is 180 days if not specified. Smallest amount of time allowed is 1 day. Anything shorter will be rounded up to 1 day.

The deny list is automatically cleaned up on a regular basis. Anything added to the list will have an expiration associated with it for how long it should be on the list. This expiration is different than the card's expiration date associated with the account number. This is how long the entry will remain in the list. It can be set to a very long time such as 50+ years.

Card expiration date is not used for removal for several reasons.

  1. Test cards do not have a "real" expiration date and should not necessarily be removed when the account expdate is reached.
  2. When cards are close to expiring the issuer will send new cards with an updated expdate but the same account number. A merchant may still want to deny these cards and a separate removal expiration is intended to handle this situation.
comment
string

Arbitrary comment related to deny list entry

Responses

Request samples

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

Response samples

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

Check Deny List

Check if account is on the card deny list

Will return details about the card if it is on the list.

No fields returned indicates it is not on the list. Use the presence of the id response key to determine if a record was found.

libmonetra KVS equivalent for endpoint

  • action_admin = carddenylist
  • carddenylist = list
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

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

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

object (Add_to_Allow_List_v9_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.

Responses

Request samples

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

Response samples

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

Remove from Deny List

Remove a card from the deny list

libmonetra KVS equivalent for endpoint

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

ID in the card deny/allow list

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

Responses

Request samples 

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

Response samples

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

Get Deny List Entry

Account detail for a card on the card deny list

libmonetra KVS equivalent for endpoint

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

ID in the card deny/allow list

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

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

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

Responses

Request samples 

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

Response samples

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

Card Allow List

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

Accounts can be added to the allow list:

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

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

  • Manually
  • Automatically before attempting automated fraud screening checks

List Allow List

Lists accounts on the card allow list

The resulting report will contain these headers:

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

libmonetra KVS equivalent for endpoint

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

Merchant profile identifier

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

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

expdate_bdate
string
Example: expdate_bdate=-5 months

Used to filter report by card expiration date range. Expiration is when the card expires, the expdate parameter sent with account. This is the beginning date of the expiration date range to match.

expdate_edate
string
Example: expdate_edate=-2 months

Used to filter report by card expiration date range. Expiration is when the card expires, the expdate parameter sent with account. This is the ending date of the expiration date range to match.

added_bdate
string
Example: added_bdate=-5 months

Used to filter report by added date range. This is the beginning date of the added date rate to match.

added_edate
string
Example: added_edate=-2 months

Used to filter report by added date range. This is the ending date of the added date range to match.

last_seen_bdate
string
Example: last_seen_bdate=-5 months

Used to filter report by last seen date range. This is the beginning date of the last seen date range to match.

last_seen_edate
string
Example: last_seen_edate=-2 months

Used to filter report by last seen date range. This is the ending date of the last seen date range to match.

expire_bdate
string
Example: expire_bdate=-5 months

Used to filter report by expire date range

Expiration is when the entry in the list will be removed.

Corresponds expire parameter sent with an add operation. This is the beginning of the expire range to match."

expire_edate
string
Example: expire_edate=-2 months

Used to filter report by expire date range

Expiration is when the entry in the list should be removed.

Corresponds expire parameter sent with an add operation. This is the ending of the expire range to match."

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/cardlist/allow' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Add to Allow List

Add a card to the allow list

libmonetra KVS equivalent for endpoint

  • action_admin = cardallowlist
  • cardallowlist = add
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object (Add_to_Allow_List_v9_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.

reason_code
string
Default: "UNSPECIFIED"
Enum: "UNSPECIFIED" "FRAUDCHECK"

Reason an account was added to the allow list

Values:

  • UNSPECIFIED - Manual or API entry with no reason specified
  • FRAUDCHECK - An automated fraud check passed
expire
string

How long to keep a card on file before being automatically removed

Standard date format accepted by the payment server. Can be a specific date to expire on or a relative data (E.g "+10 days").

Default is 180 days if not specified. Smallest amount of time allowed is 1 day. Anything shorter will be rounded up to 1 day.

The deny list is automatically cleaned up on a regular basis. Anything added to the list will have an expiration associated with it for how long it should be on the list. This expiration is different than the card's expiration date associated with the account number. This is how long the entry will remain in the list. It can be set to a very long time such as 50+ years.

Card expiration date is not used for removal for several reasons.

  1. Test cards do not have a "real" expiration date and should not necessarily be removed when the account expdate is reached.
  2. When cards are close to expiring the issuer will send new cards with an updated expdate but the same account number. A merchant may still want to deny these cards and a separate removal expiration is intended to handle this situation.
comment
string

Arbitrary comment related to allow list entry

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    },
  • "reason_code": "UNSPECIFIED",
  • "expire": "+90 days",
  • "comment": "false positive on fraud check"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "cardallowlist_id": "67898765"
}

Check Allow List

Check if account is on the card allow list

Will return details about the card if it is on the list.

No fields returned indicates it is not on the list. Use the presence of the id response key to determine if a record was found.

libmonetra KVS equivalent for endpoint

  • action_admin = cardallowlist
  • cardallowlist = list
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

object (Add_to_Allow_List_v9_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.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "account_data": {
    }
}

Response samples

Content type
application/json
{
  • "id": "167643643",
  • "last4": "5454",
  • "expdate": "0129",
  • "cardtype": "VISA",
  • "added": "2022-05-24 15:06:13 -0400",
  • "last_seen": "2022-05-24 15:06:13 -0400",
  • "expire": "+90 days",
  • "cardholdername": "John Doe",
  • "reason_code": "UNSPECIFIED",
  • "comment": "false positive on fraud check"
}

Remove from Allow List

Remove a card from the allow list

libmonetra KVS equivalent for endpoint

  • action_admin = cardallowlist
  • cardallowlist = remove
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
cardallowlist_id
required
string
Example: 67898765

ID in the card allow list

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/cardlist/allow/134543245543' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Allow List Entry

Account detail for a card on the card allow list

libmonetra KVS equivalent for endpoint

  • action_admin = cardallowlist
  • cardallowlist = list
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
cardallowlist_id
required
string
Example: 67898765

ID in the card allow list

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/cardlist/allow/143432' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "167643643",
  • "last4": "5454",
  • "expdate": "0129",
  • "cardtype": "VISA",
  • "added": "2022-05-24 15:06:13 -0400",
  • "last_seen": "2022-05-24 15:06:13 -0400",
  • "expire": "+90 days",
  • "cardholdername": "John Doe",
  • "reason_code": "UNSPECIFIED",
  • "comment": "false positive on fraud check"
}

Customer

The Customer database is a limited Client Management System (CMS) with a focus on payments. It is not a full replacement for a dedicated CMS but is intended for smaller merchants that only need payment handling functionality of a CMS.

This system allows creating customer, managing metadata about the customer. For example, addresses, stored cards, and scheduled payments. Customer can optionally be utilized by TranSafe's order system. This is to aid in creating and notification of invoices.

Larger business with an existing CMS are expected to use the TranSafe customer database for helping manage customer payments. The external CMS would include the ID for the customer created in TranSafe's system. The external CMS then be able to use the TranSafe system to manage payment information and initiate transactions.

List Customers

Lists customers

The billing and shipping address information provided by the report are the customer's default addresses. They may not be present if no addresses were set as defaults.

The resulting report will contain these headers:

id, tokengroup_id, create_profile_id, ts_created, ts_modified, flags,
display_name, name_company, name_prefix, name_first, name_middle, name_last,
name_suffix, phone_work, phone_home, phone_mobile, phone_fax, email, website,
business_id, accounting_id, notes, default_billing_id, default_shipping_id,
default_token, billing_display_name, billing_address1, billing_address2,
billing_city, billing_state, billing_country, billing_postal_code,
billing_delivery_notes, shipping_display_name, shipping_address1,
shipping_address2, shipping_city, shipping_state, shipping_country,
shipping_postal_code, shipping_delivery_notes

Additional columns may be present if profile custom fields are in use.

libmonetra KVS equivalent for endpoint

  • action_admin = customer_list
  • customer_list = customer
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/customer' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Add Customer

Adds a customer to the customer database for the merchant or token group

libmonetra KVS equivalent for endpoint

  • action_admin = customer_add
  • customer_add = customer
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

display_name
required
string <= 128 characters

Display name

name_company
string <= 128 characters

Company name

name_prefix
string <= 32 characters

Name prefix, Mr. Mrs. Ms. Dr...

Free-form field

name_first
string <= 32 characters

First name

name_middle
string <= 32 characters

Middle name

name_last
string <= 32 characters

Last name

name_suffix
string <= 32 characters

Name suffix, Jr. Sr. III...

Free-form field

phone_work
string <= 32 characters [-+0-9() .]*

Work phone

phone_home
string <= 32 characters [-+0-9() .]*

Home phone

phone_mobile
string <= 32 characters [-+0-9() .]*

Mobile phone

phone_fax
string <= 32 characters [-+0-9() .]*

Fax number

email
string <= 128 characters

email

website
string <= 128 characters

Website

business_id
string <= 32 characters

Business ID - FEIN

accounting_id
string <= 128 characters

ID used in external accounting system for customer

notes
string <= 1024 characters

General free-form information

flags
string
Enum: "TAXEXEMPT" "EMAIL_RECEIPT_RECURRING"

flags controlling behavior

Values:

  • TAXEXEMPT - Customer is non-taxable
  • EMAIL_RECEIPT_RECURRING - Send receipt email for recurring transactions. The following conditions must be met for customers to receive recurring receipt emails. + This flag must be enabled. + Customer must have an email on file. + The merchant profile must have a name configured. + The merchant profile must have a public reply email configured.
property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "display_name": "James Dean",
  • "name_company": "Dean Industries",
  • "name_prefix": "Mr.",
  • "name_first": "James",
  • "name_middle": "Byron",
  • "name_last": "Dean",
  • "name_suffix": "string",
  • "phone_work": "555-555-5555",
  • "phone_home": "555-555-5555",
  • "phone_mobile": "555-555-5555",
  • "phone_fax": "555-555-5555",
  • "email": "email@email",
  • "website": "https://web",
  • "business_id": "XX-XXXXXXX",
  • "accounting_id": "1474",
  • "notes": "This is a note",
  • "flags": "EMAIL_RECEIPT_RECURRING",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "56789687564"
}

Delete Customer

Deletes a customer

WARNING: This will purge tokens associated with the customer! If tokens need to be retained, remove them from the customer before deleting.

libmonetra KVS equivalent for endpoint

  • action_admin = customer_del
  • customer_del = customer
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56789687564

Customer identifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/customer/19266575665036873' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Customer Details

Details for a specific customer

libmonetra KVS equivalent for endpoint

  • action_admin = customer_list
  • customer_list = customer
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56789687564

Customer identifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/customer/19266575665036873' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "56789687564",
  • "tokengroup_id": "654356543",
  • "create_profile_id": "654765436",
  • "ts_created": "2022-05-24 15:06:13 -0400",
  • "ts_modified": "2022-05-24 15:06:13 -0400",
  • "flags": "EMAIL_RECEIPT_RECURRING",
  • "display_name": "James Dean",
  • "name_company": "Dean Industries",
  • "name_prefix": "Mr.",
  • "name_first": "James",
  • "name_middle": "Byron",
  • "name_last": "Dean",
  • "name_suffix": "string",
  • "phone_work": "555-555-5555",
  • "phone_home": "555-555-5555",
  • "phone_mobile": "555-555-5555",
  • "phone_fax": "555-555-5555",
  • "email": "email@email",
  • "website": "https://web",
  • "business_id": "XX-XXXXXXX",
  • "accounting_id": "1474",
  • "notes": "This is a note",
  • "default_billing_id": "648563845659663",
  • "default_shipping_id": "84569365",
  • "default_token": "44975464745966",
  • "billing_display_name": "string",
  • "billing_address1": "string",
  • "billing_address2": "string",
  • "billing_city": "string",
  • "billing_state": "string",
  • "billing_country": "string",
  • "billing_postal_code": "string",
  • "billing_delivery_notes": "string",
  • "shipping_display_name": "string",
  • "shipping_address1": "string",
  • "shipping_address2": "string",
  • "shipping_city": "string",
  • "shipping_state": "string",
  • "shipping_country": "string",
  • "shipping_postal_code": "string",
  • "shipping_delivery_notes": "string",
  • "property1": "string",
  • "property2": "string"
}

Edit Customer

Edits an existing customer

libmonetra KVS equivalent for endpoint

  • action_admin = customer_edit
  • customer_edit = customer
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56789687564

Customer identifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

display_name
string <= 128 characters

Display name

name_company
string <= 128 characters

Company name

name_prefix
string <= 32 characters

Name prefix, Mr. Mrs. Ms. Dr...

Free-form field

name_first
string <= 32 characters

First name

name_middle
string <= 32 characters

Middle name

name_last
string <= 32 characters

Last name

name_suffix
string <= 32 characters

Name suffix, Jr. Sr. III...

Free-form field

phone_work
string <= 32 characters [-+0-9() .]*

Work phone

phone_home
string <= 32 characters [-+0-9() .]*

Home phone

phone_mobile
string <= 32 characters [-+0-9() .]*

Mobile phone

phone_fax
string <= 32 characters [-+0-9() .]*

Fax number

email
string <= 128 characters

email

website
string <= 128 characters

Website

business_id
string <= 32 characters

Business ID - FEIN

accounting_id
string <= 128 characters

ID used in external accounting system for customer

notes
string <= 1024 characters

General free-form information

flags
string
Enum: "TAXEXEMPT" "EMAIL_RECEIPT_RECURRING"

flags controlling behavior

Values:

  • TAXEXEMPT - Customer is non-taxable
  • EMAIL_RECEIPT_RECURRING - Send receipt email for recurring transactions. The following conditions must be met for customers to receive recurring receipt emails. + This flag must be enabled. + Customer must have an email on file. + The merchant profile must have a name configured. + The merchant profile must have a public reply email configured.
default_token
string[0-9]*

Default token/payment to use

default_billing_id
string[0-9]+

Default ID of billing address in use from customer_addresses

0 means no default

default_shipping_id
string[0-9]+

Default ID of shipping address in use from customer_addresses

0 means no default

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "display_name": "James Dean",
  • "name_company": "Dean Industries",
  • "name_prefix": "Mr.",
  • "name_first": "James",
  • "name_middle": "Byron",
  • "name_last": "Dean",
  • "name_suffix": "string",
  • "phone_work": "555-555-5555",
  • "phone_home": "555-555-5555",
  • "phone_mobile": "555-555-5555",
  • "phone_fax": "555-555-5555",
  • "email": "email@email",
  • "website": "https://web",
  • "business_id": "XX-XXXXXXX",
  • "accounting_id": "1474",
  • "notes": "This is a note",
  • "flags": "EMAIL_RECEIPT_RECURRING",
  • "default_token": "44975464745966",
  • "default_billing_id": "648563845659663",
  • "default_shipping_id": "84569365",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

List Customer's Tokens

Lists all stored accounts associated with this customer

The resulting report will contain these headers:

token, tokengroup_id, create_profile_id, create_ts, update_ts, type, flags,
cardtype, abaroute, account, expdate, cardholdername, descr, clientref,
customer_id, street, zip, descmerch, descloc

libmonetra KVS equivalent for endpoint

  • action_admin = token_list
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56789687564

Customer identifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/customer/19266575665036873/tokens' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Customer Address

Customer address operations

List Customer Addresses

Lists a customer's addresses

The resulting report will contain these headers:

id, customer_id, display_name, address1, address2, city, state, country,
postal_code, delivery_notes

Additional fields may be present if profile custom fields are in use.

libmonetra KVS equivalent for endpoint

  • action_admin = customer_list
  • customer_list = customer_address
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
customer_id
required
string
Example: 56789687564

Customer identifier, numeric only

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/customer/19266575665036873/address' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Add Customer Address

Adds an address to a customer

libmonetra KVS equivalent for endpoint

  • action_admin = customer_add
  • customer_add = customer_address
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
customer_id
required
string
Example: 56789687564

Customer identifier, numeric only

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

display_name
string <= 128 characters

Display name

address1
required
string <= 128 characters

Address line 1

address2
string <= 128 characters

Address line 2

city
string <= 128 characters

City

state
string <= 128 characters

State

country
string <= 3 characters [a-zA-Z]{0,3}

Country

ISO 3166-1 alpha-3 country code

postal_code
string

Postal code

delivery_notes
string <= 1024 characters

Delivery notes

default_billing
string
Default: "no"
Enum: "yes" "no"

Specifies whether or not this is the default billing address

Values:

  • yes - Set this address as the customer's default billing address
  • no - This is not the default billing address
default_shipping
string
Default: "no"
Enum: "yes" "no"

Specifies whether or not this is the default shipping address

Values:

  • yes - Set this address as the customer's default shipping address
  • no - This is not the default shipping address
property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "display_name": "James Dean",
  • "address1": "673 2nd St",
  • "address2": "STE 4",
  • "city": "Winter Haven",
  • "state": "FL",
  • "country": "USA",
  • "postal_code": "33839",
  • "delivery_notes": "Don't ring bell",
  • "default_billing": "yes",
  • "default_shipping": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "67899767789"
}

Delete Customer Address

Deletes a customer's address

libmonetra KVS equivalent for endpoint

  • action_admin = customer_del
  • customer_del = customer_address
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
customer_id
required
string
Example: 56789687564

Customer identifier, numeric only

id
required
string
Example: 67899767789

Customer address identifier

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/customer/19266575665036873/address/19266578682904270' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Customer Address Details

Details for a specific customer address

Additional fields may be present if profile custom fields are in use.

libmonetra KVS equivalent for endpoint

  • action_admin = customer_list
  • customer_list = customer_address
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
customer_id
required
string
Example: 56789687564

Customer identifier, numeric only

id
required
string
Example: 67899767789

Customer address identifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/customer/19266575665036873/address/19266578682904270' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "67899767789",
  • "customer_id": "56789687564",
  • "display_name": "James Dean",
  • "address1": "673 2nd St",
  • "address2": "STE 4",
  • "city": "Winter Haven",
  • "state": "FL",
  • "country": "USA",
  • "postal_code": "33839",
  • "delivery_notes": "Don't ring bell",
  • "property1": "string",
  • "property2": "string"
}

Edit Customer Address

Edits an existing customer's address

libmonetra KVS equivalent for endpoint

  • action_admin = customer_edit
  • customer_edit = customer_address
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
customer_id
required
string
Example: 56789687564

Customer identifier, numeric only

id
required
string
Example: 67899767789

Customer address identifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

display_name
string <= 128 characters

Display name

address1
string <= 128 characters

Address line 1

address2
string <= 128 characters

Address line 2

city
string <= 128 characters

City

state
string <= 128 characters

State

country
string <= 3 characters [a-zA-Z]{0,3}

Country

ISO 3166-1 alpha-3 country code

postal_code
string

Postal code

delivery_notes
string <= 1024 characters

Delivery notes

default_billing
string
Default: "no"
Enum: "yes" "no"

Specifies whether or not this is the default billing address

Values:

  • yes - Set this address as the customer's default billing address
  • no - This is not the default billing address
default_shipping
string
Default: "no"
Enum: "yes" "no"

Specifies whether or not this is the default shipping address

Values:

  • yes - Set this address as the customer's default shipping address
  • no - This is not the default shipping address
property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "display_name": "James Dean",
  • "address1": "673 2nd St",
  • "address2": "STE 4",
  • "city": "Winter Haven",
  • "state": "FL",
  • "country": "USA",
  • "postal_code": "33839",
  • "delivery_notes": "Don't ring bell",
  • "default_billing": "yes",
  • "default_shipping": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Inventory Bulk

Inventory bulk operations

Bulk Inventory Operation

Allows for grouping multiple inventory operations into a single operation

The bulk operation is "atomic" and if any steps fail everything will fail.

Bulk operations take any of the actions for the category as KVS pairs.

Actions to be performed are structured as a JSON-array of objects, with the key/value pairs matching the field definitions, plus a prodmanage key with value set to the appropriate action being taken. Reference the libMonetra KVS for the appropriate values. This JSON object is passed in to the bulk key on the request.

Back references can be used for ids and timestamps in the format of: :id[{idx}] or :timestamp_ms[{idx}] Where the {idx} is the array index of the response for a member being referenced.

The result of a bulk operation will also return a bulk key in the response with JSON output containing: result, id, timestamp_ms, error if appropriate.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = bulk
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

bulk
required
string

Bulk data encoded as JSON

If the bulk JSON data is being sent in a protocol which itself is JSON data (ReST submitting JSON) the data within this key must be escaped as a string.

This also applies to JSON response data. If the protocol is JSON the data will be escaped as a string and will need to be decoded.

E.g. when using a JSON protocol for transport

JSON Data
[ { "action": "sub_action_1", "key1": "val1", "key2": "val2" }, { "action": "sub_action_2", "key1": "val1", "key2": "val2" }, { "action": "sub_action_3", "key1": "val1", "key2": "val2" } ]

Encoded for JSON transport protocol
{
    "key": "val",
    "bulk": "[{\"action\":\"sub_action_1\",\"key1\":\"val1\",\"key2\":\"val2\"},{\"action\":\"sub_action_2\",\"key1\":\"val1\",\"key2\":\"val2\"},{\"action\":\"sub_action_3\",\"key1\":\"val1\",\"key2\":\"val2\"}]"
}

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "bulk": "{ ... }"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "bulk": "{ ... }"
}

Inventory Categories

All inventory discounts and products are grouped into categories. Before anything can be added to the system categories must be created to hold them.

Categories allow for logical grouping of similar types of items and make it easier to find items. Specifically in a POS setting where the items will be displayed for a clerk to select.

Example categories for a restaurant

  • Drinks
  • Sandwiches
  • Deserts
  • Discounts

List Categories

List inventory categories

The resulting report will contain these headers:

id, name, timestamp_ms, description, sortorder, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = category
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string
Example: name=Fruit

Name of the category

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/category' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Add Category

Add an inventory category

Products, and discounts are added to categories. The category allows for grouping similar products and discounts that apply specifically to those products.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = category_add
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
required
string <= 32 characters

Name of the category

description
string <= 128 characters

Description of the category

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "name": "Fruit",
  • "description": "Fruits",
  • "sortorder": "7"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "567896543",
  • "timestamp_ms": "1653340525"
}

Delete Category

Delete an inventory category

The category must be empty.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = category_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 567896543

Unique ID of the category

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/inventory/category/20120539065950458?timestamp_ms=1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS"
}

Get Category Detail

Gets details for the specified category

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = category
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 567896543

Unique ID of the category

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/category/1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "567896543",
  • "name": "Fruit",
  • "timestamp_ms": "1653340525",
  • "description": "Fruits",
  • "sortorder": "7",
  • "is_deleted": "no"
}

Edit Category

Edit an inventory category

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = category_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 567896543

Unique ID of the category

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the category

description
string <= 128 characters

Description of the category

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "name": "Fruit",
  • "description": "Fruits",
  • "sortorder": "7"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "timestamp_ms": "1653340525"
}

Inventory Discounts

Multiple types of discounts are supported and can be applied in different ways.

Specifically discounts can be:

  • Fixed
  • Percentage

They can apply to:

  • Items
  • The entire order
  • Both items and the entire order
  • A cash discount

Cash discounts

A cash discount can be added to an order to reduce the total to account for the discount offered when paying with cash. This should be a percentage discount.

Except in special cases, per brand processing rules the amount shown to customer must be the total when paying with a credit card. There are special cases for certain MCC designations that can show the credit card processing as a separate additional fee.

However, the vast majority of merchants do not qualify these special cases and instead need to show the credit card price and that paying with cash will result in a discount.

This is purely how the price is presented to the customer. Whether notifying there is an additional credit card fee or a discount when paying with cash the customer is paying the difference for the convince of using a credit card.

The discount is offered when paying with cash due to the merchant not incurring some credit card processing fees when accepting cash. However, the merchant is not required to offer a cash discount. They can charge the same price for credit card and cash. Or they can offer a discount less than the credit card processing fee would cost them.

This discount does not have to be specifically for credit card processing fees either. The merchant is free to cash discount for any reason. The requirement that the total is the credit card total. A second cash total can still be presented to the customer.

If a merchant is not accepting cash the total needs to be inclusive all credit card fees. Except in special cases. If a merchant is unsure if they qualify for any special cases, they most likely don't.

List Discounts

List inventory category discounts

The resulting report will contain these headers:

id, name, timestamp_ms, category_id, amount, type, usecase, description,
sortorder, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = discount
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string
Example: name=$5 Off

Name of the discount

category_id
string
Example: category_id=567896543

Unique ID of the product category

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/discount' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Add Discount

Add a discount to an inventory category

Discounts can be applied to products, orders or both. They can be percentage based or a fixed amount.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = discount_add
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

category_id
required
string\d+

Unique ID of the product category

name
required
string <= 32 characters

Name of the discount

description
string <= 128 characters

Description of the discount

type
required
string
Default: "percentage"
Enum: "percentage" "fixed"

How the discount amount is applied

Values:

  • percentage - Amount is applied as a percentage
  • fixed - Discount is applied as a fixed amount
usecase
required
string
Enum: "item" "order" "both" "cashdiscount"

What the discount applies to in the order

Values:

  • item - The discount is applied to a specific item in the order
  • order - The discount is applied to the total order amount
  • both - The discount can be applied to either a specific item or the total order amount
  • cashdiscount - The discount applies exclusivly to full cash payments
amount
required
string\d*(\.\d{0,5})?

Amount (up to 5 decimal places)

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "category_id": "567896543",
  • "name": "$5 Off",
  • "description": "$5 off promotion",
  • "type": "fixed",
  • "usecase": "order",
  • "amount": "5.00",
  • "sortorder": "7"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "834678965675",
  • "timestamp_ms": "1653340525"
}

Delete Discount

Delete an inventory category discount

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = discount_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 834678965675

Unique ID of the discount

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v1/inventory/discount/26863859502458458?timestamp_ms=1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS"
}

Get Discount Detail

Gets details for the specified discount

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = discount
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 834678965675

Unique ID of the discount

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/discount/1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "834678965675",
  • "name": "$5 Off",
  • "timestamp_ms": "1653340525",
  • "category_id": "567896543",
  • "amount": "5.00",
  • "type": "fixed",
  • "usecase": "order",
  • "description": "$5 off promotion",
  • "sortorder": "7",
  • "is_deleted": "no"
}

Edit Discount

Edit an inventory category discount

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = discount_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 834678965675

Unique ID of the discount

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the discount

description
string <= 128 characters

Description of the discount

type
string
Default: "percentage"
Enum: "percentage" "fixed"

How the discount amount is applied

Values:

  • percentage - Amount is applied as a percentage
  • fixed - Discount is applied as a fixed amount
usecase
string
Enum: "item" "order" "both" "cashdiscount"

What the discount applies to in the order

Values:

  • item - The discount is applied to a specific item in the order
  • order - The discount is applied to the total order amount
  • both - The discount can be applied to either a specific item or the total order amount
  • cashdiscount - The discount applies exclusivly to full cash payments
amount
string\d*(\.\d{0,5})?

Amount (up to 5 decimal places)

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "name": "$5 Off",
  • "description": "$5 off promotion",
  • "type": "fixed",
  • "usecase": "order",
  • "amount": "5.00",
  • "sortorder": "7"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "timestamp_ms": "1653340525"
}

Inventory Products

Products are high level metadata about items being sold by the merchant.

Products must have at least one SKU added to them in order to be sold. Due to the potential for product variations having different barcodes but still being considered the same product, SKUs are necessary.

Price is not set on the products but instead on SKUs.

Multiple tax rates can be set on a product in order to account for products that are untaxed vs taxed. Multiple tax rates can be applied.

List Products

List inventory products

The resulting report will contain these headers:

id, name, timestamp_ms, category_id, taxrates, modifiersets,
fractional_qty, description, commoditycode, unit, req_modifiersets, sortorder,
image_type, image_data, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = product
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string
Example: name=Large pizza

Name of the product

category_id
string
Example: category_id=567896543

Unique ID of the product category

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

fetch_images
object
Enum: "yes" "no"
Example: fetch_images=no

Include base64-encoded image data

Values:

  • yes - Return image data
  • no - Do not return image data

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/product' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Add Product

Add an inventory product

Products represent base items. All products will have SKUs which are the actual item's. All products are part of a category.

For example

  • Category = Classic Literature
    • Product = A Tale of Two Cities
      • SKU = Hard cover
      • SKU = Paperback
      • SKU = Audio

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = product_add
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
required
string <= 32 characters

Name of the product

category_id
required
string\d+

Unique ID of the product category

description
string <= 128 characters

Description of the product

taxrates
string

comma separated list of taxrate ids (up to 4)

modifiersets
string

comma separated list of modifierset ids (up to 8)

req_modifiersets
string

comma separated list of required modifierset ids (must exist in modifiersets)

commoditycode
string[0-9a-zA-Z]{8,12}

Contains an international description code of the individual good or service being supplied

The acquiring bank or processor should provide the merchant an updated listing of currently defined codes. Please note that this is different from the 4-character summary commodity code. Codes can be found online at http://www.unspsc.org

The code itself will not be validated; only the format is validated.

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

sortorder
string\d+

UI sort order (display purposes only)

image_data
string[a-zA-Z0-9+/\n]+={0,2}[\n]*

Base64-encoded image data. Supports JPG and PNG formats. 300x300, 256KB max size.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "name": "Large pizza",
  • "category_id": "567896543",
  • "description": "A really big pizza",
  • "taxrates": "5654367654",
  • "modifiersets": "65789837657843,1456543456,14567876543",
  • "req_modifiersets": "6578943,456543",
  • "commoditycode": "50301700",
  • "unit": "1",
  • "sortorder": "7",
  • "image_data": "ABC="
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "6789646596763",
  • "timestamp_ms": "1653340525"
}

Delete Product

Delete an inventory product

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = product_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 6789646596763

Unique ID of the product

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/inventory/product/27589475894035458?timestamp_ms=1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS"
}

Get Product Detail

Gets details for the specified product

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = product
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 6789646596763

Unique ID of the product

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

fetch_images
object
Enum: "yes" "no"
Example: fetch_images=no

Include base64-encoded image data

Values:

  • yes - Return image data
  • no - Do not return image data

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/product/1758939453334' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "6789646596763",
  • "name": "Large pizza",
  • "timestamp_ms": "1653340525",
  • "category_id": "567896543",
  • "taxrates": "5654367654",
  • "modifiersets": "65789837657843,1456543456,14567876543",
  • "fractional_qty": "no",
  • "description": "A really big pizza",
  • "commoditycode": "50301700",
  • "unit": "1",
  • "req_modifiersets": "6578943,456543",
  • "sortorder": "7",
  • "image_type": "PNG",
  • "image_data": "ABC=",
  • "is_deleted": "no"
}

Edit Product

Edit an inventory product

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = product_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 6789646596763

Unique ID of the product

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the product

category_id
string\d+

Unique ID of the product category

description
string <= 128 characters

Description of the product

taxrates
string

comma separated list of taxrate ids (up to 4)

modifiersets
string

comma separated list of modifierset ids (up to 8)

req_modifiersets
string

comma separated list of required modifierset ids (must exist in modifiersets)

commoditycode
string[0-9a-zA-Z]{8,12}

Contains an international description code of the individual good or service being supplied

The acquiring bank or processor should provide the merchant an updated listing of currently defined codes. Please note that this is different from the 4-character summary commodity code. Codes can be found online at http://www.unspsc.org

The code itself will not be validated; only the format is validated.

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

sortorder
string\d+

UI sort order (display purposes only)

image_data
string[a-zA-Z0-9+/\n]+={0,2}[\n]*

Base64-encoded image data. Supports JPG and PNG formats. 300x300, 256KB max size.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "name": "Large pizza",
  • "category_id": "567896543",
  • "description": "A really big pizza",
  • "taxrates": "5654367654",
  • "modifiersets": "65789837657843,1456543456,14567876543",
  • "req_modifiersets": "6578943,456543",
  • "commoditycode": "50301700",
  • "unit": "1",
  • "sortorder": "7",
  • "image_data": "ABC="
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "timestamp_ms": "1653340525"
}

Inventory SKUs

SKUs are the actual item being sold and are contained within a product.

Product variations can be manufacturing variations of the same product. For example a refreshed version of a product with the same name and functionality.

Another possibility is a product with multiple variations. For example, a vacuum cleaner. Model is XYZ but there are three SKUs that different based on accessory bundles offered as part of the SKU. While it is one product it has multiple SKUs. This is typically manufacturer bundles where each SKU has a different accompanying UPC code.

In both examples the price may differ between the SKUs. This is why price is set on the SKU and not on the product.

List SKUs

List inventory product SKUs

The resulting report will contain these headers:

id, name, timestamp_ms, product_id, inventory, price, in_stock,
inventory_timestamp_ms, barcode, description, sortorder, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = sku
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string
Example: name=Large hand tossed

Name of the SKU

product_id
string
Example: product_id=6789646596763

Unique ID of the product

in_stock
object
Enum: "yes" "no"
Example: in_stock=yes

Whether the in stock status should be evaulated as a condition

Values:

  • yes - Only return in-stock skus
  • no - Only return out-of-stock skus
timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/sku' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Add SKU

Add an inventory product SKU

A SKU is a specific version of a product. For example, if the product is a book, there could be hardcover and paperback SKUs.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = sku_add
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

product_id
required
string\d+

Unique ID of the product

name
required
string <= 32 characters

Name of the SKU

price
required
string\d*(\.\d{0,5})?

Price (up to 5 decimal places)

inventory
string
Default: "unlimited"
Enum: "unlimited" "tracked" "outofstock"

Type of item stocking

Values:

  • unlimited - The item quantity is not tracked
  • tracked - The item quantity is tracked and there is a finite number available at a given time
  • outofstock - The item is not currently in stock
barcode
string <= 32 characters

Decoded Barcode. E.g. 2d barcode decoded to the UPC number

description
string <= 128 characters

Description of the SKU

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "product_id": "6789646596763",
  • "name": "Large hand tossed",
  • "price": "25.00",
  • "inventory": "unlimited",
  • "barcode": "015000071356",
  • "description": "Large hand tossed pizza",
  • "sortorder": "7"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "5784936543",
  • "timestamp_ms": "1653340525"
}

Delete SKU

Delete an inventory product SKU

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = sku_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 5784936543

Unique ID of the SKU

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/inventory/sku/13748493859345458?timestamp_ms=57849320845' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS"
}

Get SKU Detail

Gets details for the specified SKU

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = sku
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 5784936543

Unique ID of the SKU

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/sku/1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "5784936543",
  • "name": "Large hand tossed",
  • "timestamp_ms": "1653340525",
  • "product_id": "6789646596763",
  • "inventory": "unlimited",
  • "price": "25.00",
  • "in_stock": "yes",
  • "inventory_timestamp_ms": "1653421798000",
  • "barcode": "015000071356",
  • "description": "Large hand tossed pizza",
  • "sortorder": "7",
  • "is_deleted": "no"
}

Edit SKU

Edit an inventory product SKU

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = sku_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 5784936543

Unique ID of the SKU

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the SKU

price
string\d*(\.\d{0,5})?

Price (up to 5 decimal places)

inventory
string
Default: "unlimited"
Enum: "unlimited" "tracked" "outofstock"

Type of item stocking

Values:

  • unlimited - The item quantity is not tracked
  • tracked - The item quantity is tracked and there is a finite number available at a given time
  • outofstock - The item is not currently in stock
barcode
string <= 32 characters

Decoded Barcode. E.g. 2d barcode decoded to the UPC number

description
string <= 128 characters

Description of the SKU

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "name": "Large hand tossed",
  • "price": "25.00",
  • "inventory": "unlimited",
  • "barcode": "015000071356",
  • "description": "Large hand tossed pizza",
  • "sortorder": "7"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "timestamp_ms": "1653340525"
}

Set SKU Quantity

Set the quantity for SKU

Tracking for the number of items in stock

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = inventory_set
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 5784936543

Unique ID of the SKU

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

cnt
required
string\d+

Exact count of inventory in stock

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "cnt": "17"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "timestamp_ms": "1653340525"
}

Inventory Modifier Sets

Modifier sets are similar to categories. In that they are a logical grouping of modifiers.

Modifier sets are attached to products in order to allow modifying products.

In the SKU section an example of a vacuum cleaner with multiple accessory bundle variations was used. In that case the SKUs were due to manufacturer bundles with different UPC codes.

Building on that example, a product might have a single SKU for the item because the manufacturer only produces one item. Instead the merchant has their on add on bundles they sell with the item. A modifier set can be used with a modifier for each add on.

List Modifier Sets

List inventory modifier sets

The resulting report will contain these headers:

id, name, timestamp_ms, description, multiselect, maxselect, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = modifierset
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string
Example: name=Toppings

Name of the modifier set

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/modifierset' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Add Modifier Set

Add an inventory modifier set

A grouping of like modifiers. For example, pizza toppings. Where each topping is a modifier within the set.

Modifier sets are applied to products. It can be applied to multiple products. For example, a pizza topping modifier set could apply to product pizza and product calzone (which is like a pizza but harder to eat and they're dumb). Both can and often use the same topping modifiers.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifierset_add
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
required
string <= 32 characters

Name of the modifier set

description
string <= 128 characters

Description of the modifier set

multiselect
string
Default: "no"
Enum: "yes" "no"

Whether or not multiple selection is allowed

Values:

  • yes - Multiple selection is allowed
  • no - Multiple selection is NOT allowed
maxselect
string\d+

How many items may be selected at once (only if multiselect, default=unlimited)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "name": "Toppings",
  • "description": "Pizza toppings",
  • "multiselect": "no",
  • "maxselect": "5"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "6756394857674839",
  • "timestamp_ms": "1653340525"
}

Delete Modifier Set

Delete an inventory modifier set

The modifier set must be empty.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifierset_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 6756394857674839

Unique ID of the modifier set

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/inventory/modifierset/84578903855643344?timestamp_ms=1895849024551' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS"
}

Get Modifier Set Detail

Gets details for the specified modifier set

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = modifierset
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 6756394857674839

Unique ID of the modifier set

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/modifierset/1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "6756394857674839",
  • "name": "Toppings",
  • "timestamp_ms": "1653340525",
  • "description": "Pizza toppings",
  • "multiselect": "no",
  • "maxselect": "5",
  • "is_deleted": "no"
}

Edit Modifier Set

Edit an inventory modifier set

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifierset_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 6756394857674839

Unique ID of the modifier set

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the modifier set

description
string <= 128 characters

Description of the modifier set

multiselect
string
Default: "no"
Enum: "yes" "no"

Whether or not multiple selection is allowed

Values:

  • yes - Multiple selection is allowed
  • no - Multiple selection is NOT allowed
maxselect
string\d+

How many items may be selected at once (only if multiselect, default=unlimited)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "name": "Toppings",
  • "description": "Pizza toppings",
  • "multiselect": "no",
  • "maxselect": "5"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "timestamp_ms": "1653340525"
}

Inventory Modifiers

Modifiers are ways a product can be altered. They belong to modifier sets to better group the modifiers. A common term for a modifier is an add on.

Modifiers can have their own price that can increase the total price of a product. They are not required to have a price and will not increase the product price if added.

An example is a pizza where a topping modifier set is created and within the set is a modifier representing each topping and it's additional price per topping.

List Modifiers

List inventory modifiers

The resulting report will contain these headers:

id, name, timestamp_ms, modifierset_id, price, description, unit, sortorder,
is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = modifier
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string
Example: name=Pepperoni

Name of the modifier

modifierset_id
string
Example: modifierset_id=6756394857674839

Unique ID of the modifier set

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/modifier' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Add Modifier

Add an inventory modifier to a modifier set

Modifiers augment a product and are typically add ons. This is different than a SKU.

For example, a pizza topping would be a modifier. Pepperoni, mushroom, or bacon. Multiple modifiers can be applied to an order.

All modifiers are part of a modifier set in order to provide logical groupings for modifiers.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifier_add
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

modifierset_id
required
string\d+

Unique ID of the modifier set

name
required
string <= 32 characters

Name of the modifier

description
string <= 128 characters

Description of the modifier

price
string\d*(\.\d{0,5})?

Price (up to 5 decimal places)

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "modifierset_id": "6756394857674839",
  • "name": "Pepperoni",
  • "description": "Pepperoni pizza topping",
  • "price": "25.00",
  • "unit": "1",
  • "sortorder": "7"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "6789646596763",
  • "timestamp_ms": "1653340525"
}

Delete Modifier

Delete an inventory modifier

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifier_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 39836566395734

Unique ID of the modifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/inventory/modifier/82859028592849248?timestamp_ms=1895849024551' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS"
}

Get Modifier Detail

Gets details for the specified modifier

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = modifier
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 39836566395734

Unique ID of the modifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/modifier/1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "39836566395734",
  • "name": "Pepperoni",
  • "timestamp_ms": "1653340525",
  • "modifierset_id": "6756394857674839",
  • "price": "25.00",
  • "description": "Pepperoni pizza topping",
  • "unit": "1",
  • "sortorder": "7",
  • "is_deleted": "no"
}

Edit Modifier

Edit an inventory modifier

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = modifier_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 39836566395734

Unique ID of the modifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the modifier

description
string <= 128 characters

Description of the modifier

price
string\d*(\.\d{0,5})?

Price (up to 5 decimal places)

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "name": "Pepperoni",
  • "description": "Pepperoni pizza topping",
  • "price": "25.00",
  • "unit": "1",
  • "sortorder": "7"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "timestamp_ms": "1653340525"
}

Inventory Tax Rates

Tax rates are the amount of tax that is charged to an item. This is used for automatic calculation of tax when the inventory system is used in conjunction with the order system.

Multiple tax rates may be necessary and multiple can be applied to products. There may be a state and county tax that are tracked and remitted separately. Two tax rates would be created and both added to a product. When the inventory is used with the order system, this allows generating tax rate reports to aid with remittance to the relevant governments.

List Tax Rates

List inventory tax rates

The resulting report will contain these headers:

id, name, timestamp_ms, percentage, default, roundmethod, sortorder, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = taxrate
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
string
Example: name=County tax

Name of the tax rate

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/taxrate' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Add Tax Rate

Add an inventory tax rate

Allows creating a tax rate that can be applied to products. Multiple tax rates could be necessary for reporting purposes.

For example, separate rates for state, county, and city. Multiple tax rates can be applied to products.

Having several tax rates my be necessary if products are taxed differently based on their type. For example, some places have digital and physical goods rates.

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = taxrate_add
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

name
required
string <= 32 characters

Name of the tax rate

percentage
required
string\d*(\.\d{0,5})?

Percentage of tax rate (up to 5 decimal places)

default
string
Default: "no"
Enum: "yes" "no"

Whether this should be applied by default to new products (UI)

Values:

  • yes - Apply by default to new products
  • no - Do not apply by default to new products
roundmethod
string
Enum: "normal" "bankers"

Method used for rounding

Values:

  • normal - Round to the nearest whole number
  • bankers - Round to the nearest even whole number
sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "name": "County tax",
  • "percentage": "1.254",
  • "default": "yes",
  • "roundmethod": "normal",
  • "sortorder": "7"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "65748376543",
  • "timestamp_ms": "1653340525"
}

Delete Tax Rate

Delete an inventory tax rate

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = taxrate_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 65748376543

Unique ID of the tax rate

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/inventory/taxrate/14859438593544438?timestamp_ms=1859386643324' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS"
}

Get Tax Rate Detail

Gets details for the specified tax rate

libmonetra KVS equivalent for endpoint

  • action_admin = prodlist
  • json = false
  • prodlist = taxrate
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 65748376543

Unique ID of the tax rate

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/inventory/taxrate/1588258706031' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "65748376543",
  • "name": "County tax",
  • "timestamp_ms": "1653340525",
  • "percentage": "1.254",
  • "default": "yes",
  • "roundmethod": "normal",
  • "sortorder": "7",
  • "is_deleted": "no"
}

Edit Tax Rate

Edit an inventory tax rate

libmonetra KVS equivalent for endpoint

  • action_admin = prodmanage
  • prodmanage = taxrate_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 65748376543

Unique ID of the tax rate

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

name
string <= 32 characters

Name of the tax rate

percentage
string\d*(\.\d{0,5})?

Percentage of tax rate (up to 5 decimal places)

default
string
Default: "no"
Enum: "yes" "no"

Whether this should be applied by default to new products (UI)

Values:

  • yes - Apply by default to new products
  • no - Do not apply by default to new products
roundmethod
string
Enum: "normal" "bankers"

Method used for rounding

Values:

  • normal - Round to the nearest whole number
  • bankers - Round to the nearest even whole number
sortorder
string\d+

UI sort order (display purposes only)

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "name": "County tax",
  • "percentage": "1.254",
  • "default": "yes",
  • "roundmethod": "normal",
  • "sortorder": "7"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "timestamp_ms": "1653340525"
}

Orders

The order system allows creating orders

The profile flag ALLOW_INVOICING must be set.

Order types

There are three types of 'orders':

  • Order - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • Quick - Single or no line item orders. Typically used for single amount payments
  • Invoice - Billing invoice for later payment

The line items can be based on inventory items from the inventory system or a custom (one off) line item. Customers who have an external product system and only need the invoice for billing will often use a single custom line item for the order amount. You can attach the external system generated PDF so the customer will be able to view it from the link they get sent to pay. This is useful in the external invoice generation scenario where TranSafe is only being used to send and collect the payment.

Order flow

  • Create the order (specifying the type as order)
  • Add line items
  • Edit the order to put the order into an open status
  • Link payment to order

Quick flow

  • Create the order (specifying the type as quick)
  • Add single custom line item with the order amount
  • Edit the order to put the order into an open status
  • Link payment to order

Invoice flow

  • Create the order (specifying the type as invoice)
  • Add line items
  • Edit the order to put the order into an open status
  • Provide invoice to customer (email or SMS)
  • Accept payment
  • Link payment to order

Typically the last two steps will be handled by the customer using the invoice link emailed or SMS messaged to the customer. The customer can make payment online using that link.

Payments

Payments are a way to link transactions to orders so the order can be closed. Accepting transactions does not require the use of the order system.

There are two ways a payment can be linked to an order.

  1. The order_id can be specified with a transaction, such as purchase at the time the transaction is processed. This will automatically update the order and create a payment linking the transaction to the order.
  2. A payment can be manually added to the order by specifying the ttid of the transaction being linked.

Emailing or SMS sending orders

It is possible to email or SMS send an order to a customer. This applies to all order types. The customer will receive a link that will take them to the payment server to view and pay the order. If the order is closed they will be able to view receipts. Additionally, if an external invoice PDF was added to the order they will be able to download the PDF here.

Sending orders to customers is handled by the "Receipt" system. They can be sent by email or SMS message. Orders are sent as a links to TranSafe for viewing. Since it's the same link for open orders to allow payment and closed orders for viewing receipts, sending is contained in one place ("Receipts").

Invoices will be automatically email to the customer when closed. This requires a customer from the customer system to be associated with the order and that customer must have an email on file. Further, if the profile has the RECEIVE_RECEIPTS_INVOICE flag set, an email will be sent to the notify_email.

timestamp_ms

The timestamp_ms parameter is used to ensure changes do not create conflicts. The value for timestamp_ms is either returned by an operation and is then used in the next. Or it can be retrieved by getting an order details or when listing orders.

Cancel an Order or Invoice

Cancel an order in the OPEN or PENDING states

The order is not removed from the system. Must be used instead of order delete if there have been payments attempted against it.

It is recommended to delete orders if possible as it doesn't leave stale records.

NOTE: must cancel all applied payments before canceling an order or invoice.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = order_cancel
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 58445676543

Order identifier, numeric only

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

cancel_reason
required
string
Enum: "CANCEL" "RETURN" "SATISFACTION"

Reason for order cancellation

Values:

  • CANCEL - Generic cancel
  • RETURN - All items in the order were returned
  • SATISFACTION - Customer was not satisfied
timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "cancel_reason": "RETURN",
  • "timestamp_ms": "1653340525"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS"
}

List Orders

List orders

The resulting report will contain these headers:

id, timestamp_ms, user, id_base62, type, flags, status, cancel_reason,
merch_status, customer_id, customer_display_name, ordernum, ponumber,
allowed_cardtypes, securitytoken, timestamp_create, timestamp_close,
timestamp_sent, timestamp_viewed, invoice_date, invoice_due, taxrates,
taxamounts, total_amount, total_tax, total_discount, total_paid, total_tip,
total_amount_cash, total_amount_noncash, notes, total_tax_override, ship_name,
ship_address1, ship_address2, ship_city, ship_state, ship_zip, ship_country,
ship_notes, invoice_filename, invoice_data, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = orders
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

customer_id
string
Example: customer_id=54345,567043,31567

Comma separated list of customer identifiers

ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to 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.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Create an Order or Invoice

Create an order or invoice

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = order_add
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

type
required
string
Enum: "ORDER" "QUICK" "INVOICE"

Type of order

Values:

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
required
string
Enum: "PENDING" "OPEN"

Status of the order

Values:

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
flags
string
Value: "NOTIP"

Type of order

Flag values (pipe separated):

  • NOTIP - Do not attempt to perform tip prompting when collecting payment
merch_status
string
Enum: "PENDING" "COMPLETE" "PREPARING" "BACKORDERED"

Merchant status of the order

Values:

  • PENDING - Order is pending
  • COMPLETE - Order is complete
  • PREPARING - Order is being prepared
  • BACKORDERED - Order is delayed while waiting for back ordered items
customer_id
string[0-9]+

Customer identifier, numeric only

Required when type = Invoice

ordernum
string <= 128 characters [0-9a-zA-Z]+

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to 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

Will be shown to customers!

total_tax_override
string0?\.\d{2}

Tax override amount, only used if all line items have no tax rates

ship_name
string <= 32 characters

Shipping name of recipient

"To" field on shipping label.

ship_address1
string <= 32 characters

Shipping street address of recipient

Line 1

ship_address2
string <= 32 characters

Shipping street address of recipient

Line 2

ship_city
string <= 32 characters

Shipping city of recipient

ship_state
string <= 32 characters

Shipping state / provence of recipient

ship_zip
string <= 32 characters

Shipping zip / postal Code of recipient

Used for tax zones

ship_country
string <= 32 characters

Shipping country of recipient

ship_notes
string <= 128 characters

Shipping delivery instructions

invoice_filename
string <= 32 characters

Filename of externally attached invoice PDF

Requires:

  • invoice_data
invoice_data
string[a-zA-Z0-9+/\n]+={0,2}[\n]*

PDF base64 encoded invoice PDF

Used for externally generated invoice billing.

Max file size is 512 KB.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "type": "INVOICE",
  • "status": "OPEN",
  • "flags": "NOTIP",
  • "merch_status": "PREPARING",
  • "customer_id": "56789687564",
  • "ordernum": "A13DDES345",
  • "ponumber": "P4567",
  • "allowed_cardtypes": "VISA|MC|DISC",
  • "invoice_date": "+2 days",
  • "invoice_due": "+45 days",
  • "notes": "Gift wrap all items in order",
  • "total_tax_override": "0.07",
  • "ship_name": "Robert Redford",
  • "ship_address1": "244 90th Pl",
  • "ship_address2": "Unit 42",
  • "ship_city": "Orlando",
  • "ship_state": "FL",
  • "ship_zip": "32789",
  • "ship_country": "USA",
  • "ship_notes": "Leave with security",
  • "invoice_filename": "Invoice_Dean_4875.pdf",
  • "invoice_data": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "58445676543",
  • "timestamp_ms": "1653340525"
}

Delete an Order or Invoice

Completely remove an order or invoice from the system

Cannot be used if an order has had payments applied. If payments have been applied the order must be canceled.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = order_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 58445676543

Order identifier, numeric only

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/order/1456543256' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS"
}

Get Order Detail

Gets details for the specified order

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = orders
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 58445676543

Order identifier, numeric only

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

fetch_invoices
object
Enum: "yes" "no"
Example: fetch_invoices=no

Include base64-encoded invoice data

Applies to invoices with external (PDF) invoice documents.

Values:

  • yes - Return invoice data
  • no - Do not return invoice data
timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/789567654256' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "58445676543",
  • "timestamp_ms": "1653340525",
  • "user": "benny",
  • "id_base62": "1dPwZv08nt",
  • "type": "INVOICE",
  • "flags": "NOTIP",
  • "status": "OPEN",
  • "cancel_reason": "RETURN",
  • "merch_status": "PREPARING",
  • "customer_id": "56789687564",
  • "customer_display_name": "James Dean",
  • "ordernum": "A13DDES345",
  • "ponumber": "P4567",
  • "allowed_cardtypes": "VISA|MC|DISC",
  • "securitytoken": "x4TIeLxv",
  • "timestamp_create": "2022-05-24 15:06:13 -0400",
  • "timestamp_close": "2022-05-24 15:06:13 -0400",
  • "timestamp_sent": "2022-05-24 15:06:13 -0400",
  • "timestamp_viewed": "2022-05-24 15:06:13 -0400",
  • "invoice_date": "+2 days",
  • "invoice_due": "+45 days",
  • "taxrates": "5654367654",
  • "taxamounts": "1.02,0.49,0.22",
  • "total_amount": "155.34",
  • "total_tax": "5.04",
  • "total_discount": "15.00",
  • "total_paid": "155.34",
  • "total_tip": "0.50",
  • "total_amount_cash": "142.97",
  • "total_amount_noncash": "155.34",
  • "notes": "Gift wrap all items in order",
  • "total_tax_override": "0.07",
  • "ship_name": "Robert Redford",
  • "ship_address1": "244 90th Pl",
  • "ship_address2": "Unit 42",
  • "ship_city": "Orlando",
  • "ship_state": "FL",
  • "ship_zip": "32789",
  • "ship_country": "USA",
  • "ship_notes": "Leave with security",
  • "invoice_filename": "Invoice_Dean_4875.pdf",
  • "invoice_data": "string",
  • "is_deleted": "no"
}

Edit an Order or Invoice

Edit and order or invoice

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = order_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 58445676543

Order identifier, numeric only

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

type
string
Enum: "ORDER" "QUICK" "INVOICE"

Type of order

Values:

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment
status
string
Enum: "PENDING" "OPEN"

Status of the order

Values:

  • PENDING - Order is in process of being built, not eligible for payment
  • OPEN - Order is open and ready for payment (can still accept changes, but typically you won't)
flags
string
Value: "NOTIP"

Type of order

Flag values (pipe separated):

  • NOTIP - Do not attempt to perform tip prompting when collecting payment
merch_status
string
Enum: "PENDING" "COMPLETE" "PREPARING" "BACKORDERED"

Merchant status of the order

Values:

  • PENDING - Order is pending
  • COMPLETE - Order is complete
  • PREPARING - Order is being prepared
  • BACKORDERED - Order is delayed while waiting for back ordered items
customer_id
string[0-9]+

Customer identifier, numeric only

ordernum
string <= 128 characters [0-9a-zA-Z]+

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to 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

Will be shown to customers!

total_tax_override
string0?\.\d{2}

Tax override amount, only used if all line items have no tax rates

ship_name
string <= 32 characters

Shipping name of recipient

"To" field on shipping label.

ship_address1
string <= 32 characters

Shipping street address of recipient

Line 1

ship_address2
string <= 32 characters

Shipping street address of recipient

Line 2

ship_city
string <= 32 characters

Shipping city of recipient

ship_state
string <= 32 characters

Shipping state / provence of recipient

ship_zip
string <= 32 characters

Shipping zip / postal Code of recipient

Used for tax zones

ship_country
string <= 32 characters

Shipping country of recipient

ship_notes
string <= 128 characters

Shipping delivery instructions

invoice_filename
string <= 32 characters

Filename of externally attached invoice PDF

Requires:

  • invoice_data
invoice_data
string[a-zA-Z0-9+/\n]+={0,2}[\n]*

PDF base64 encoded invoice PDF

Used for externally generated invoice billing.

Max file size is 512 KB.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "type": "INVOICE",
  • "status": "OPEN",
  • "flags": "NOTIP",
  • "merch_status": "PREPARING",
  • "customer_id": "56789687564",
  • "ordernum": "A13DDES345",
  • "ponumber": "P4567",
  • "allowed_cardtypes": "VISA|MC|DISC",
  • "invoice_date": "+2 days",
  • "invoice_due": "+45 days",
  • "notes": "Gift wrap all items in order",
  • "total_tax_override": "0.07",
  • "ship_name": "Robert Redford",
  • "ship_address1": "244 90th Pl",
  • "ship_address2": "Unit 42",
  • "ship_city": "Orlando",
  • "ship_state": "FL",
  • "ship_zip": "32789",
  • "ship_country": "USA",
  • "ship_notes": "Leave with security",
  • "invoice_filename": "Invoice_Dean_4875.pdf",
  • "invoice_data": "string",
  • "timestamp_ms": "1653340525"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "timestamp_ms": "1653340525"
}

Order Bulk

Order bulk operations

Bulk Order Operation

Allows for grouping multiple order operations into a single operation

The bulk operation is "atomic" and if any steps fail everything will fail.

Bulk operations take any of the actions for the category as KVS pairs.

Actions to be performed are structured as a JSON-array of objects, with the key/value pairs matching the field definitions, plus a ordermanage key with value set to the appropriate action being taken. Reference the libMonetra KVS for the appropriate values. This JSON object is passed in to the bulk key on the request.

Back references can be used for ids and timestamps in the format of: :id[{idx}] or :timestamp_ms[{idx}] Where the {idx} is the array index of the response for a member being referenced.

The result of a bulk operation will also return a bulk key in the response with JSON output containing: result, id, timestamp_ms, error if appropriate.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = bulk
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

bulk
required
string

Bulk data encoded as JSON

If the bulk JSON data is being sent in a protocol which itself is JSON data (ReST submitting JSON) the data within this key must be escaped as a string.

This also applies to JSON response data. If the protocol is JSON the data will be escaped as a string and will need to be decoded.

E.g. when using a JSON protocol for transport

JSON Data
[ { "action": "sub_action_1", "key1": "val1", "key2": "val2" }, { "action": "sub_action_2", "key1": "val1", "key2": "val2" }, { "action": "sub_action_3", "key1": "val1", "key2": "val2" } ]

Encoded for JSON transport protocol
{
    "key": "val",
    "bulk": "[{\"action\":\"sub_action_1\",\"key1\":\"val1\",\"key2\":\"val2\"},{\"action\":\"sub_action_2\",\"key1\":\"val1\",\"key2\":\"val2\"},{\"action\":\"sub_action_3\",\"key1\":\"val1\",\"key2\":\"val2\"}]"
}

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "bulk": "{ ... }"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "bulk": "{ ... }"
}

Order Discounts

Order discount management. This is for managing discounts applied to the entire order. Discounts can be added to an order using a custom discount or by referencing a discount from the inventory system. An inventory system discount must be of a type that can be applied to orders.

When operating on a discount, such as edit or delete, the id of the discount within the order is referenced. Not the discount id within the inventory system if the inventory system was used.

Add a Custom Fixed Discount

Add a custom fixed discount to the order

For adding discounts that are not in the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_add
  • ref_id = 0
  • type = DISCOUNT_FIXED
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

amount
required
string\d*(\.\d{0,5})?

Amount of money, including up to 5 decimal places. E.g 1.00 or 2.399

This is the amount of 1 unit.

taxrates
string

comma separated list of taxrate ids (up to 4)

name
required
string <= 32 characters

Name of the discount

productcode
string[0-9a-zA-Z ]{1,12}

Merchant-defined code for the item being purchased, such as a UPC #, SKU #, or Item #

commoditycode
string[0-9a-zA-Z]{8,12}

Contains an international description code of the individual good or service being supplied

The acquiring bank or processor should provide the merchant an updated listing of currently defined codes. Please note that this is different from the 4-character summary commodity code. Codes can be found online at http://www.unspsc.org

The code itself will not be validated; only the format is validated.

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "ringorder": "2",
  • "qty": "1",
  • "amount": "199.95",
  • "taxrates": "5654367654",
  • "name": "Employee discount",
  • "productcode": "7456",
  • "commoditycode": "50301700",
  • "unit": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "67876547364567"
}

Add a Custom Percent Discount

Add a custom percent discount to the order

For adding discounts that are not in the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_add
  • ref_id = 0
  • type = DISCOUNT_PERCENT
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

amount
required
string\d*(\.\d{0,5})?

Amount of money, including up to 5 decimal places. E.g 1.00 or 2.399

This is the amount of 1 unit.

taxrates
string

comma separated list of taxrate ids (up to 4)

name
required
string <= 32 characters

Name of the discount

productcode
string[0-9a-zA-Z ]{1,12}

Merchant-defined code for the item being purchased, such as a UPC #, SKU #, or Item #

commoditycode
string[0-9a-zA-Z]{8,12}

Contains an international description code of the individual good or service being supplied

The acquiring bank or processor should provide the merchant an updated listing of currently defined codes. Please note that this is different from the 4-character summary commodity code. Codes can be found online at http://www.unspsc.org

The code itself will not be validated; only the format is validated.

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "ringorder": "2",
  • "qty": "1",
  • "amount": "199.95",
  • "taxrates": "5654367654",
  • "name": "Employee discount",
  • "productcode": "7456",
  • "commoditycode": "50301700",
  • "unit": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "67876547364567"
}

Add a Fixed Discount

Add a fixed amount discount to the order

The discount references a discount from the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_add
  • type = DISCOUNT_FIXED
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ref_id
required
string[0-9]+

Unique ID of the discount

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "ref_id": "765432",
  • "ringorder": "2",
  • "qty": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "67876547364567"
}

Add a Percent Discount

Add a percentage discount to the order

The discount references a discount from the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_add
  • type = DISCOUNT_PERCENT
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ref_id
required
string[0-9]+

Unique ID of the discount

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "ref_id": "765432",
  • "ringorder": "2",
  • "qty": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "67876547364567"
}

Remove a Discount

Remove a discount form an order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 67876547364567

Order discount identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/order/20245528771333405/discount/5894387586' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS"
}

Edit a Discount

Edit a discount for an order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 67876547364567

Order discount identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

ringorder
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "ringorder": "2",
  • "qty": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS"
}

Order Items

Order item management. This is for managing items added to an order. Items can be added to an order using a custom item or by referencing a SKU from the inventory system.

When operating on a item, such as edit or delete, the id of the item within the order is referenced. Not the SKU id within the inventory system if the inventory system was used.

Add a Custom Item

Add a custom line item to the order

For adding line items that are not SKUs in the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_add
  • ref_id = 0
  • type = ADDON
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

amount
required
string\d*(\.\d{0,5})?

Amount of money, including up to 5 decimal places. E.g 1.00 or 2.399

This is the amount of 1 unit.

taxrates
string

comma separated list of taxrate ids (up to 4)

name
required
string <= 32 characters

Name of the line item

productcode
string[0-9a-zA-Z ]{1,12}

Merchant-defined code for the item being purchased, such as a UPC #, SKU #, or Item #

commoditycode
string[0-9a-zA-Z]{8,12}

Contains an international description code of the individual good or service being supplied

The acquiring bank or processor should provide the merchant an updated listing of currently defined codes. Please note that this is different from the 4-character summary commodity code. Codes can be found online at http://www.unspsc.org

The code itself will not be validated; only the format is validated.

unit
string

Free-form unit of measure

Merchant's description for a unit of measurement. If no good description, use 'Unit'

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "ringorder": "2",
  • "qty": "1",
  • "amount": "199.95",
  • "taxrates": "5654367654",
  • "name": "Colored Pencils",
  • "productcode": "7456",
  • "commoditycode": "50301700",
  • "unit": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "785676543"
}

List Items

List order items

Gets Items for the specified Order.

The resulting report will contain these headers:

id, timestamp_ms, order_id, type, ringorder, ref_id, qty, amount,
total_modifiers, total_mod_disc, total_ord_disc, taxrates, name,
productcode, commoditycode, unit, notes, group_name, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = items
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

customer_id
string
Example: customer_id=54345,567043,31567

Comma separated list of customer identifiers

ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to 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/v2/order/7589432567654/item' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Add an Item

Add a line item to the order

The line item references a SKU from the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_add
  • type = ADDON
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ref_id
required
string[0-9]+

Unique ID of the inventory SKU

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "ref_id": "86956395206",
  • "ringorder": "2",
  • "qty": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "785676543"
}

Remove an Item

Remove a line item form an order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/order/item/675894315' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS"
}

Get Item Detail

Gets details for the specified Item in an order

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = items
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to 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.

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/v2/order/item/8594387568950432' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "58445676543",
  • "timestamp_ms": "1653340525",
  • "type": "ADDON",
  • "ringorder": "2",
  • "ref_id": "476543",
  • "qty": "1",
  • "amount": "19.92",
  • "total_modifiers": "string",
  • "total_mod_disc": "string",
  • "total_ord_disc": "string",
  • "taxrates": "5654367654",
  • "name": "Colored Pencils",
  • "productcode": "7456",
  • "commoditycode": "50301700",
  • "unit": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products",
  • "is_deleted": "no"
}

Edit an Item

Edit a line item for an order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = item_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

ringorder
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

notes
string <= 1024 characters

General free-form information

group_name
string <= 32 characters

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "ringorder": "2",
  • "qty": "1",
  • "notes": "This is a note",
  • "group_name": "Art Products"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS"
}

Order Item Discounts

Order item discount management. This is for managing item discounts added to an item in an order. Item discounts can be added to an order using a custom item discount or by referencing discount from the inventory system. An inventory system discount must be of a type that can be applied to items.

When referencing an item to apply a discount, the item must be added to the order first. The item id within the order, not the inventory SKU id, is referenced when adding the discount.

When operating on a item discount, such as edit or delete, the id of the item discount within the order is referenced. Not the discount id within the inventory system if the inventory system was used.

Add a Custom Item Fixed Discount

Add a custom fixed discount to a line item

For adding discounts that are not in the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_add
  • ref_id = 0
  • type = DISCOUNT_FIXED
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

amount
required
string\d*(\.\d{0,5})?

Amount of money, including up to 5 decimal places. E.g 1.00 or 2.399

This is the amount of 1 unit.

name
required
string <= 32 characters

Name of line item discount

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "ringorder": "2",
  • "qty": "1",
  • "amount": "199.95",
  • "name": "10% off"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "24566437"
}

Add a Custom Item Percent Discount

Add a custom percent discount to a line item

For adding discounts that are not in the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_add
  • ref_id = 0
  • type = DISCOUNT_PERCENT
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

amount
required
string\d*(\.\d{0,5})?

Amount of money, including up to 5 decimal places. E.g 1.00 or 2.399

This is the amount of 1 unit.

name
required
string <= 32 characters

Name of line item discount

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "ringorder": "2",
  • "qty": "1",
  • "amount": "199.95",
  • "name": "10% off"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "24566437"
}

Add an Item Fixed Discount

Add a fixed discount to a line item

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_add
  • type = DISCOUNT_FIXED
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ref_id
required
string\d+

Unique ID of the inventory discount

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "ref_id": "15676543",
  • "ringorder": "2",
  • "qty": "1"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "24566437"
}

Add an Item Percent Discount

Add a percent discount to a line item

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_add
  • type = DISCOUNT_PERCENT
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ref_id
required
string\d+

Unique ID of the inventory discount

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "ref_id": "15676543",
  • "ringorder": "2",
  • "qty": "1"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "24566437"
}

Remove an Item Discount

Remove a discount from a line item in the order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 24566437

Order item discount identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

item_id
required
string
Example: 785676543

Order item identifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/order/item/discount/76789625' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS"
}

Edit an Item Discount

Edit a line item discount

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 24566437

Order item discount identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

item_id
required
string
Example: 785676543

Order item identifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

ringorder
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "ringorder": "2",
  • "qty": "1"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS"
}

Order Item Modifiers

Order item modifier management. This is for managing item modifiers added to an item in an order. Item modifier can be added to an order using a custom item modifier or by referencing modifiers from the inventory system.

When referencing an item to apply a modifier, the item must be added to the order first. The item id within the order, not the inventory SKU id, is referenced when adding the modifier.

When operating on a item modifier, such as edit or delete, the id of the item modifier within the order is referenced. Not the modifier id within the inventory system if the inventory system was used.

Add a Custom Item Modifier

Add a custom modifier to a line item

For adding modifiers that are not in the inventory system.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_add
  • ref_id = 0
  • type = ADDON
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

amount
required
string\d*(\.\d{0,5})?

Amount of money, including up to 5 decimal places. E.g 1.00 or 2.399

This is the amount of 1 unit.

name
required
string <= 32 characters

Name of line item modifier

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "ringorder": "2",
  • "qty": "1",
  • "amount": "199.95",
  • "name": "Extra veggies"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "63676598"
}

List Order Item Modifiers

List order item modifiers

The resulting report will contain these headers:

id, timestamp_ms, item_id, order_id, type, ringorder, ref_id, qty, amount, name, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = modifiers
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

customer_id
string
Example: customer_id=54345,567043,31567

Comma separated list of customer identifiers

ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to 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/v2/order/item/7584933567654/modifier' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Add an Item Modifier

Add an item modifier to a line item

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_add
  • type = ADDON
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ref_id
required
string\d+

Unique ID of the inventory modifier

ringorder
required
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "ref_id": "46789525",
  • "ringorder": "2",
  • "qty": "1"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "63676598"
}

Remove an Item Modifier

Remove a modifier from a line item in the order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 63676598

Order item modifier identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

item_id
required
string
Example: 785676543

Order item identifier

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string
Example: timestamp_ms=1653340525

Last updated Unix timestamp in milliseconds

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/order/item/modifier/785903676' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS"
}

Get Item Modifier Detail

Gets details for the specified modifier

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = modifiers
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 63676598

Order item modifier identifier

item_id
required
string
Example: 785676543

Order item identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
string
Example: timestamp_ms=1653408007

The maximum recorded timestamp_ms of the last fetch. Will only return records newer than this.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/modifier/75849356543' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "63676598",
  • "timestamp_ms": "1653340525",
  • "item_id": "785676543",
  • "order_id": "58445676543",
  • "type": "ADDON",
  • "ringorder": "2",
  • "ref_id": "6786567",
  • "qty": "1",
  • "amount": "19.92",
  • "name": "Pepperoni",
  • "is_deleted": "no"
}

Edit an Item Modifier

Edit a line item modifier

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = modifier_edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 63676598

Order item modifier identifier

order_id
required
string
Example: 58445676543

Unique ID of an order

item_id
required
string
Example: 785676543

Order item identifier

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

timestamp_ms
required
string\d+

Last updated Unix timestamp in milliseconds

ringorder
string

Order in which item needs to be displayed. Does not need to be sequential. But must be unique for the line item

qty
string

Quantity of the item being purchased

This field allows up to 5 decimal places of precision. If the card brand does not allow that level of precision, the number will be rounded.

Minimum quantity is 0.00005. Maximum quantity is 99999.00.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "timestamp_ms": "1653340525",
  • "ringorder": "2",
  • "qty": "1"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS"
}

Order Payments

Allows associating payments to an order. As well as manging the payments applied to orders. Payments can be previous transactions made through TranSafe or external payments (cash and check) that are being recorded for reporting purposes.

Add a Cash Payment

Add a cash payment to the order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = payment_add
  • tendertype = CASH
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

amount
required
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

tip
required
string\d+(\.\d{0,2})?

Tip amount

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "amount": "19.92",
  • "tip": "0.33"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "987653645678"
}

Add a Check Payment

Add a check payment to the order

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = payment_add
  • tendertype = CHECK
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

amount
required
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

tip
required
string\d+(\.\d{0,2})?

Tip amount

checknum
required
string\d+

Check number

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "amount": "19.92",
  • "tip": "0.33",
  • "checknum": "45678"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "987653645678"
}

List Payments

List order payments

Gets the Payments for the specified order.

The resulting report will contain these headers:

id, timestamp_ms, user, order_id, tendertype, amount, tip, status, ttid,
timestamp, cardtype, last4, cardholdername, checknum, is_deleted

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = payments
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

customer_id
string
Example: customer_id=54345,567043,31567

Comma separated list of customer identifiers

ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to 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/v2/order/5784392456/payment' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Add a Payment

Add a payment to the order

References an existing transaction.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = payment_add
  • tendertype = TXN
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
order_id
required
string
Example: 58445676543

Unique ID of an order

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

ttid
required
string [ 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
{
  • "profile_id": "78965743785967",
  • "ttid": "18446744073709551615"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS",
  • "id": "987653645678"
}

Cancel a Payment

Cancels a cash or check payment associated with the order

A transaction that was applied to the order using a ttid cannot be canceled directly. It must be reversed which will automatically mark it as canceled in the order.

External payments, such as cash and check, that were made outside of TranSafe are removed from the order using this operation. It is the responsibility of the merchant to take any further action that is necessary when canceling a payment. For example, providing cash to the customer if a cash payment was accepted.

libmonetra KVS equivalent for endpoint

  • action_admin = ordermanage
  • ordermanage = payment_cancel
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 987653645678

Unique ID of a payment for an order

order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/order/20245528771333405/payment/758493245430' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "result": "SUCCESS"
}

Get Payment Detail

Gets details for the specified payment

libmonetra KVS equivalent for endpoint

  • action_admin = orderlist
  • json = no
  • orderlist = payments
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 987653645678

Unique ID of a payment for an order

order_id
required
string
Example: 58445676543

Unique ID of an order

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/payment/758493245430' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "987653645678",
  • "timestamp_ms": "1653340525",
  • "user": "benny",
  • "order_id": "58445676543",
  • "tendertype": "TXN",
  • "amount": "19.92",
  • "tip": "0.33",
  • "status": "OPEN",
  • "ttid": "18446744073709551615",
  • "timestamp": "2022-05-24 15:06:13 -0400",
  • "cardtype": "VISA",
  • "last4": "5454",
  • "cardholdername": "John Doe",
  • "checknum": "45678",
  • "is_deleted": "no"
}

Order Reports

Order reports allow reporting of not only orders but other systems that are utilized by orders. These reports offer insight into the use of orders to allow merchant to tailor their offerings, or meet other obligations (tip, and tax remittance).

Reports are about usage within orders. For example, the customer report allows determining how many, how often, and how much specific customers are spending.

Or the SKU activity report allows determining which SKUs are most or least popular.

Aging

Aging report for unpaid invoices grouped by customer

The resulting report will contain these headers:

customer_id, customer_display_name, current, 1-30, 31-60, 61-90,
91-120, 120+

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = aging
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string
Example: id=56789687564

Customer identifier

type
object
Enum: "ORDER" "QUICK" "INVOICE"
Example: type=ORDER,QUICK

Comma separated list of order types

Flag values (comma separated):

  • ORDER - Order comprising line items. Typically created by a POS system utilizing products from the inventory system.
  • QUICK - Single or no line item orders. Typically used for single amount payments
  • INVOICE - Billing invoice for later payment

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/report/aging' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Customers

Customer summary

The resulting report will contain these headers:

customer_id, customer_display_name, count, total_amount

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = customersummary
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string
Example: id=56789687564

Customer identifier

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

limit
string
Example: limit=4

Maximum number of rows to return

has_count
object
Enum: "yes" "no"
Example: has_count=yes

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/report/modifier?customer=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Item Discounts

Item discount summary

The resulting report will contain these headers:

discount_id, discount_name, usecase, category_id, category_name, count

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = itemdiscountsummary
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string
Example: id=67876547364567

Order discount identifier

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

limit
string
Example: limit=4

Maximum number of rows to return

has_count
object
Enum: "yes" "no"
Example: has_count=yes

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/report/discount/item?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Item Modifier Activity

Item Modifier activity

The resulting report will contain these headers:

modifier_id, modifier_name, modifierset_id, modifierset_name,
count

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = modifiersummary
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string
Example: id=63676598

Order item modifier identifier

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

limit
string
Example: limit=4

Maximum number of rows to return

has_count
object
Enum: "yes" "no"
Example: has_count=yes

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/report/modifier?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Order Discounts

Order discount summary

The resulting report will contain these headers:

discount_id, discount_name, usecase, category_id, category_name, count

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = orderdiscountsummary
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string
Example: id=67876547364567

Order discount identifier

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

limit
string
Example: limit=4

Maximum number of rows to return

has_count
object
Enum: "yes" "no"
Example: has_count=yes

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/report/discount/order?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Payments

Payment report grouped by user

The resulting report will contain these headers:

user, sale_amount, refund_amount

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = payments
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

order_in
string
tendertype
object
Enum: "TXN" "CASH" "CHECK"
Example: tendertype=TXN

Type of payment tender

Values:

  • TXN - 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/v2/order/report/payment?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Product Activity

Product activity

The resulting report will contain these headers:

product_id, product_name, category_id, category_name, count

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = productsummary
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string
Example: id=6789646596763

Unique ID of the product

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

limit
string
Example: limit=4

Maximum number of rows to return

has_count
object
Enum: "yes" "no"
Example: has_count=yes

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/report/product?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

SKU Activity

SKU activity

The resulting report will contain these headers:

sku_id, sku_name, product_id, product_name, category_id,
category_name, count

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = skusummary
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string
Example: id=5784936543

Unique ID of the SKU

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

limit
string
Example: limit=4

Maximum number of rows to return

has_count
object
Enum: "yes" "no"
Example: has_count=yes

Whether or not the report should include items with or without orders

If not present, show both with and without are included

Values:

  • yes - Only include items with orders
  • no - Only include items without orders

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/report/sku?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Tax History

Tax history report

The resulting report will contain these headers:

taxrate_id, taxrate_name, order_id, timestamp, amount

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = taxhistory
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string
Example: id=65748376543

Unique ID of the tax rate

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/report/tax/history?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Tax Summary

Tax summary report

The resulting report will contain these headers:

taxrate_id, taxrate_name, amount

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = taxsummary
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

id
string
Example: id=65748376543

Unique ID of the tax rate

order_id
string
Example: order_id=58445676543

Unique ID of an order

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/order/report/tax?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Tips

Tip report grouped by user

The resulting report will contain these headers:

user, sale_tip, refund_tip

libmonetra KVS equivalent for endpoint

  • action_admin = orderreport
  • orderreport = tip
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

order_in
string
tendertype
object
Enum: "TXN" "CASH" "CHECK"
Example: tendertype=TXN

Type of payment tender

Values:

  • TXN - 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/v2/order/report/tip?bdate=-30%20days' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Hosted Paypage

The hosted payment page is a page provided by TranSafe associated with a profile which can take blind payments. Anyone with the link (which is not in any way specific to the customer) can make a payment.

Typically, when using the hosted payment page, customers will be asked to enter a customer identifier for the payment. Such as an invoice number, customer number, patient number, etc. Since this is free form and provided by the customer, with no validation, there is a high likelihood of incorrect information being entered. Regular reconciliation with manual matching of payments to customers is necessary.

This is not a recommended method to request payments from customers. While this method of payment is popular with many merchants due to its ease of deployment, it should be avoided if possible. This payment method is ideally suited for one off semi-anonymous donations.

Alternatives

It's highly recommended one of the alternatives below are used instead of the hosted payment page. The hosted payment page should only be used in limited circumstances.

Secure iFrame

Using TranSafe's secure iFrame is a good choice and allows the merchant to integrate payment information collection directly into their web site. The payment information is sent directly to TranSafe and is never handled by the merchant's web server.

This prevents credit card data from ever touching the merchant's systems, while allowing customers to complete seamless ecommerce transactions on the merchant's website.

This is ideal for merchants using a shopping cart style checkout. Or who have their own invoice billing system.

Invoice system

TranSafe supports an integrated invoice system. This allows the creation of invoices which can then be sent to the customer. The customer can be sent a link to pay the invoice. The customer will interact solely with TranSafe for paying the invoice. Thereby ensuring the merchant never has to collect payment information directly.

Due to each customer having a unique payment link there is no confusion about which customer is making a payment. Also, the merchant can be automatically notified about successfully paid invoices. Further, it is very easy to see which invoices are outstanding or have been paid.

This is a secure payment method and allows detailed information about the order. It can be used in conduction with external invoicing systems for the payment portion. The merchant's invoice system will generate the invoice which can then be attached as a PDF to the TranSafe's invoice. TranSafe's invoice will be sent to the customer who will then make their payment and receive their invoice PDF that was generated by the merchant's system. Reconciliation is still necessary to mark invoices as paid in the merchant's system.

Merchants who use an invoice instead of checkout payment flow are ideal candidates for this method. Especially those who either do not have their own invoice system or who do not want payments going through their invoice system.

Possible fraud

Another major issue with using the hosted payment page is the potential for fraud. The page is not unique to a customer or order, nor are payments authenticated. This can lead to abuse of the page to facilitate fraud.

Mitigation measures

To prevent this several fraud methods prevention rules must be in place for each page:

  1. The maximum number of transactions that are allowed within a single calendar day.
  2. The maximum amount of money that can be submitted per payment.
  3. The maximum total aggregate amount of money that can be collected by the page within a single calendar day.
  4. The page is protected by a captcha.

The totals for each of these is tracked on a per attempt basis. Regardless if the payment is authorized or declined.

In all cases the merchant will be charged standard transaction fees and can incur a large number of chargebacks.

If fraud is a concern, the iFrame or invoice or another secure system should be used.

Types of fraud

This is a non-exhaustive list of the types of fraud that can take place when a hosted payment page is abused.

Carding

In this case, a fraudster will use the page to test stolen credit cards. The fraudster will use the outcome of approved or declined to determine if the card information they have is valid. Approved cards are valid and declined cards are not.

Fee abuse

Attackers know that merchants pay processing fees for each payment. They also know that merchant's are charged when a customer wins a chargeback dispute. Which is nearly 100% of the time in stolen card situations. Further, the merchant will most likely need to issue refunds for the fraudulent transactions which also have a fee to process.

The goal is to cause harm to the merchant through a monetary loss. This loss can be signification, especially for smaller merchants.

Damage to reputation

If a merchant accepts fraudulent payments the merchant's reputation may be damaged. The merchant is often blamed for not taking adequate steps in order to protect the public and prevent fraud form occurring. Anger toward the merchant can be compounded if there are a large number of fraudulent charges. Trust in the merchant may be reduced which can result in potential customers deciding to use the merchant's competitors.

Processing account closure

There are multiple entities that can be involved in payment processing. For example, gateway, processor, card brand. Each of these entities have fraud tolerance levels associated with their merchants. If the amount of fraud associated with a merchant exceeds these limits one or more of these entities may discontinue service to the merchant.

This will cause disruption to the merchant because they will be unable to accept payments for a period of time. They will need to establish a new processing account with another provider. This could entail integration work if the merchant needs to use a different gateway which uses a different processing protocol. Leading to more time the merchant will be unable to accept payments.

Further, merchants who have their processing accounts closed due to excessive fraud may be viewed as higher risk by other processing companies. They may find it difficult to open a new account or potentially need to pay higher fees.

Amount alteration

The page can have the amount specified either as a fixed amount associated with the page configuration, an amount passed into the page as a parameter by the merchant, or editable by the customer. When editable, the amount is either passed into the page by the merchant or left empty for the customer to fill in.

In cases where the amount is not configured for the page as a fixed amount, and the amount is not set as editable. The merchant must provide the amount was a parameter. In this situation the amount used to run the payment is the amount submitted by the page. While the amount is not editable, this is visually only. The customer an use a developer tool, that is built into nearly all web browsers, and still edit the amount. There is no way to prevent this.

It is imperative when payments are reconciled, not only the customer identifier but also the amount is verified. If the amount is not verified during reconciliation, the customer may be able to pay less than requested and still have their "invoice" considered fully paid.

Pre-filled data

Fields on the page can be pre-filled when the page is requested. This is useful if some information is already known. Such as an order number. This prevents the customer from having to type this information into the form.

Payment information cannot be pre-filled because the merchant should not have that information. Otherwise use of the hosted payment page would be unnecessary.

Merchant custom fields as well as the following can be passed into the page as either query arguments with a GET request or as body parameters with a POST request.

  • amount
  • cardholdername
  • street
  • zip
  • email
  • comments
  • ordernum
  • custref

If a field is not listed as shown on the page, and is passed into the page as a parameter, the field and it's value will be present when the form is submitted. A field does not have to be listed as shown to be pre-filled and received as part of the payment.

Note, providing any field that is not a merchant customer field or in the above list will result in an error.

Customer email

Customers are required to provide an email address which will automatically generate an email for approved transactions.

Page error codes

The page does not provide descriptive error text and instead provides error codes. The customer not the merchant is the one using the page making a number of possible errors not something the customer would care to know the details. The possible error codes are as follows

  • F902 - Failed to load failure page template
  • F903 - Failed to run failure page template
  • F904 - Failed to load result page template
  • F905 - Failed to run result page template
  • P401 - Redirect URL missing
  • L600 - Failed to load page template
  • L601 - Failed to run page template
  • P444 - Request parse failed
  • E300 - Generic failure
  • C100 - Network error getting captcha response
  • C101 - HTTP response error getting captcha response
  • C200 - Failed to parse captcha response JSON
  • C201 - Captcha response was not successful
  • C202 - Captcha indicates incorrect action
  • C203 - Captcha challenge time outside allowed window
  • C204 - Captcha score lower than minimum allowed
  • P600 - Page id does not exist
  • D599 - Could not load page configuration
  • D460 - Restriction failed
  • D462 - Required field data missing or not shown and editable
  • D463 - Required field data missing
  • D464 - Input parameter not allowed
  • D465 - Amount should not be specified
  • D466 - Input parameter not allowed
  • D467 - Missing amount and not customer editable
  • C205 - System not configured for captcha
  • C206 - Captcha response not present in data
  • C207 - Customer's IP not present in data
  • C208 - Captcha verification request could not be created
  • C209 - Captcha verification request failed to send

List Hosted Paypage Pages

List hosted paypage pages

The resulting report will contain these headers:

id, profile_id, group_id, descr, trantype, fee_type, amount, fields_shown,
fields_editable, fields_returned, max_count, max_amount,
max_total_amount, total_count, total_amount, last_payment_ts,
redirect_url, terms_url, privacy_url, fee_value, fee_title

libmonetra KVS equivalent for endpoint

  • action_admin = hosted_paypage
  • hosted_paypage = list
Authorizations:
basic_auth(apikey_idapikey)

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/paypage/hosted' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Create a hosted paypage page

Create a hosted paypage page

This defines the page configuration and how it will act when presented to the customer.

libmonetra KVS equivalent for endpoint

  • action_admin = hosted_paypage
  • hosted_paypage = add
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

descr
string

Description of the page to know what it is used for

trantype
required
string
Enum: "sale" "preauth"

Transaction type the paypage should use for authorization

Values:

  • sale - Purchase transaction
  • preauth - Preauthorization transaction. Will need to be completed to receive funds
allowed_cardtypes
string
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "GIFT" "CUP" "ACH"

Allowed Cardtypes

Pipe (|) separated.

Cardtypes that can be accepted on the hosted paypage page. If not specified, all cardtypes supported by the profile will be allowed.

Flag values (pipe separated):

  • VISA - Visa credit
  • MC - Mastercard credit
  • AMEX - American Express credit
  • DISC - Discover credit
  • DINERS - Diners credit
  • JCB - JCB credit. Formerly Japan Credit Bureau
  • GIFT - Private label Gift. Not cards backed by a credit card brand such as Visa, Mastercard, etc.
  • CUP - China Union Pay credit
  • ACH - Bank transfer
amount
string\d*(\.\d{0,2})?

Any passed in, amount parameters, will be displayed to the customer as a fixed and non-editable amount field. However, if amount is passed a parameter of 0, or left blank, the paypage will display a customer editable amount field.

fields_shown
string

Fields that should be shown on the hosted paypage

Payment information fields do not need to be defined here because they are always shown.

Comma delimited list of field names.

Fields allowed:

  • comments
  • ordernum
  • custref

Additionally merchant custom fields can be included in this list.

Shown fields can be used to allow customers to enter additional information. Such as an order number. It can also be used to display information to the customer. If a field is not marked as editable.

fields_editable
string

Fields that should be editable on the hosted paypage

Payment information fields do not need to be defined here because they are always shown.

Comma delimited list of field names. Only applied to fields that are shown.

fields_required
string

Fields that should be requried on the hosted paypage

Payment information fields do not need to be defined here because they are always required.

Comma delimited list of field names. If a field is not listed as shown or editable, the field and value must be passed to the page when it is requested. Either as query arguments or POST arguments.

fields_returned
string

Fields that should be returned as part of the redirect back to the merchant after page processing

Comma delimited list of field names.

This is response fields that TranSafe will return from purchase or pre-authorization requests. Only some response fields can be returned.

Response fields that can be returned:

  • code
  • msoft_code
  • phard_code
  • auth
  • issuer_decline
  • timestamp
  • ttid

Some input parameters can be returned.

Request fields that can be returend:

  • amount
  • cardholdername
  • street
  • zip
  • email
  • comments
  • ordernum
  • custref

Additionally merchant custom fields as defined on the profile can be returned as part of the response if they were provided as part of the request.

These fields and their value will be returned as query arguments with the GET request to the merchant's web site. Note that these fields will be visible to the customer in the redirect URL. Also, note the customer could refresh the page causing multiple GET requests to be submitted. This should be used for informational purposes and not as a way to determine if a payment was made.

fee_type
string
Enum: "none" "percent" "amount"

Fee type (if any) that should be assessed as part of the payment

Values:

  • none - No fee will be accessed
  • percent - Fee is a percentage
  • amount - Fee is a fixed dollar amount
fee_title
string

Description of the fee to show the customer

The text should be short can clear that a fee is being accessed. If a title is not provided a default title of "Processing fee" will be used.

This field is only used if a fee is being accessed.

fee_value
string\d*(\.\d{0,2})?

Fee to be assessed if use of the hosted payment page charges a fee.

The fee can be up to 2 decimal digits. The type of fee, percent or fixed amount, is determined by the fee_type parameter.

Percentages are percentage values and should not be normalized to a decimal.

E.g values:

  • 1 = 1%
  • 10 = 10%
  • 2.54 = 2.54%

Fixed amounts are fixed amounts of dollars and cents.

E.g values:

  • 1 = $1
  • 10 = $10
  • 2.54 = $2.54
max_count
required
string

Maximum number of transactions that can be processed within a day.

This is to prevent abuse of the hosted paypage page and prevent fraudulent actives, such as carding. If this number of transactions (attempted, authorized, or declined) is exceeded, the page will not process any further requests that day.

If set to 0, then no transactions can process for the page and effectively disables its use.

The maximum should be based on the estimated number of transactions that will be processed per day.

max_amount
required
string\d*(\.\d{0,2})?

Maximum amount of a single transaction that can be processed by the page

This is to prevent abuse of the hosted paypage page and prevent fraudulent actives, such as attempting to have large fees accessed by initiating fraudulent charges that will be disputed later.

If set to 0, then no transactions can process for the page and effectively disables its use.

The maximum should be based on the estimated largest transaction amount that will be processed by the page.

If a fixed page amount is configured, this should be set to the same value.

max_total_amount
required
string\d*(\.\d{0,2})?

Maximum amount of all attempted transactions that can be processed within a day

This is the total of all the amounts of attempted transactions once added together. For example, txn a for $4, txn b for $9, txn c for $12 = a total of $25. If the maximum is set to $15 then txn c would not be accepted because it would exceed the maximum total amount.

This is to prevent abuse of the hosted paypage page and prevent fraudulent actives, such as attempting to have large fees accessed by initiating fraudulent charges that will be disputed later.

If set to 0, then no transactions can process for the page and effectively disables its use.

The maximum should be based on the estimated total amount of attempted payments. The total is based on attempted, authorized, and declined transactions.

redirect_url
string

URL to redirect the customer to after processing

This should be a URL to the merchant's web site. Any returned fields will be added to the URL as query parameters when redirecting the customer.

terms_url
required
string

URL to the merchant's terms and conditions

privacy_url
required
string

URL to the merchant's privacy policy

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "descr": "$50 donation button",
  • "trantype": "sale",
  • "allowed_cardtypes": "VISA|MC",
  • "amount": "19.92",
  • "fields_shown": "string",
  • "fields_editable": "string",
  • "fields_required": "string",
  • "fields_returned": "string",
  • "fee_type": "none",
  • "fee_title": "Processing Fee",
  • "fee_value": "19.92",
  • "max_count": "1000",
  • "max_amount": "51.48",
  • "max_total_amount": "19500.77",
  • "redirect_url": "string",
  • "terms_url": "string",
  • "privacy_url": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "987653645678"
}

Delete an Hosted Payment Page

Delete a payment page configuration

Once deleted the page will no longer be usable.

libmonetra KVS equivalent for endpoint

  • action_admin = hosted_paypage
  • hosted_paypage = del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 987653645678

Unique ID of a hosted paypage page

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/paypage/hosted/767562957658' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Hosted Paypage Page Detail

Get details for the specified hosted paypage page

libmonetra KVS equivalent for endpoint

  • action_admin = hosted_paypage
  • hosted_paypage = list
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 987653645678

Unique ID of a hosted paypage page

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/paypage/hosted/767562957658' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "id": "987653645678",
  • "profile_id": "78965743785967",
  • "group_id": "36789654543",
  • "descr": "$50 donation button",
  • "trantype": "sale",
  • "allowed_cardtypes": "VISA|MC",
  • "amount": "19.92",
  • "fields_shown": "string",
  • "fields_editable": "string",
  • "fields_required": "string",
  • "fields_returned": "string",
  • "fee_type": "none",
  • "fee_title": "Processing Fee",
  • "fee_value": "19.92",
  • "max_count": "1000",
  • "max_amount": "51.48",
  • "max_total_amount": "19500.77",
  • "total_count": "string",
  • "total_amount": "string",
  • "redirect_url": "string",
  • "terms_url": "string",
  • "privacy_url": "string"
}

Edit a hosted paypage page

Edit a hosted paypage page

libmonetra KVS equivalent for endpoint

  • action_admin = hosted_paypage
  • hosted_paypage = edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 987653645678

Unique ID of a hosted paypage page

Request Body schema: application/json
descr
string

Description of the page to know what it is used for

trantype
string
Enum: "sale" "preauth"

Transaction type the paypage should use for authorization

Values:

  • sale - Purchase transaction
  • preauth - Preauthorization transaction. Will need to be completed to receive funds
allowed_cardtypes
string
Enum: "VISA" "MC" "AMEX" "DISC" "DINERS" "JCB" "GIFT" "CUP" "ACH"

Allowed Cardtypes

Pipe (|) separated.

Cardtypes that can be accepted on the hosted paypage page. If not specified, all cardtypes supported by the profile will be allowed.

Flag values (pipe separated):

  • VISA - Visa credit
  • MC - Mastercard credit
  • AMEX - American Express credit
  • DISC - Discover credit
  • DINERS - Diners credit
  • JCB - JCB credit. Formerly Japan Credit Bureau
  • GIFT - Private label Gift. Not cards backed by a credit card brand such as Visa, Mastercard, etc.
  • CUP - China Union Pay credit
  • ACH - Bank transfer
amount
string\d*(\.\d{0,2})?

Any passed in, amount parameters, will be displayed to the customer as a fixed and non-editable amount field. However, if amount is passed a parameter of 0, or left blank, the paypage will display a customer editable amount field.

fields_shown
string

Fields that should be shown on the hosted paypage

Payment information fields do not need to be defined here because they are always shown.

Comma delimited list of field names.

Fields allowed:

  • comments
  • ordernum
  • custref

Additionally merchant custom fields can be included in this list.

Shown fields can be used to allow customers to enter additional information. Such as an order number. It can also be used to display information to the customer. If a field is not marked as editable.

fields_editable
string

Fields that should be editable on the hosted paypage

Payment information fields do not need to be defined here because they are always shown.

Comma delimited list of field names. Only applied to fields that are shown.

fields_required
string

Fields that should be requried on the hosted paypage

Payment information fields do not need to be defined here because they are always required.

Comma delimited list of field names. If a field is not listed as shown or editable, the field and value must be passed to the page when it is requested. Either as query arguments or POST arguments.

fields_returned
string

Fields that should be returned as part of the redirect back to the merchant after page processing

Comma delimited list of field names.

This is response fields that TranSafe will return from purchase or pre-authorization requests. Only some response fields can be returned.

Response fields that can be returned:

  • code
  • msoft_code
  • phard_code
  • auth
  • issuer_decline
  • timestamp
  • ttid

Some input parameters can be returned.

Request fields that can be returend:

  • amount
  • cardholdername
  • street
  • zip
  • email
  • comments
  • ordernum
  • custref

Additionally merchant custom fields as defined on the profile can be returned as part of the response if they were provided as part of the request.

These fields and their value will be returned as query arguments with the GET request to the merchant's web site. Note that these fields will be visible to the customer in the redirect URL. Also, note the customer could refresh the page causing multiple GET requests to be submitted. This should be used for informational purposes and not as a way to determine if a payment was made.

fee_type
string
Enum: "none" "percent" "amount"

Fee type (if any) that should be assessed as part of the payment

Values:

  • none - No fee will be accessed
  • percent - Fee is a percentage
  • amount - Fee is a fixed dollar amount
fee_title
string

Description of the fee to show the customer

The text should be short can clear that a fee is being accessed. If a title is not provided a default title of "Processing fee" will be used.

This field is only used if a fee is being accessed.

fee_value
string\d*(\.\d{0,2})?

Fee to be assessed if use of the hosted payment page charges a fee.

The fee can be up to 2 decimal digits. The type of fee, percent or fixed amount, is determined by the fee_type parameter.

Percentages are percentage values and should not be normalized to a decimal.

E.g values:

  • 1 = 1%
  • 10 = 10%
  • 2.54 = 2.54%

Fixed amounts are fixed amounts of dollars and cents.

E.g values:

  • 1 = $1
  • 10 = $10
  • 2.54 = $2.54
max_count
string

Maximum number of transactions that can be processed within a day.

This is to prevent abuse of the hosted paypage page and prevent fraudulent actives, such as carding. If this number of transactions (attempted, authorized, or declined) is exceeded, the page will not process any further requests that day.

If set to 0, then no transactions can process for the page and effectively disables its use.

The maximum should be based on the estimated number of transactions that will be processed per day.

max_amount
string\d*(\.\d{0,2})?

Maximum amount of a single transaction that can be processed by the page

This is to prevent abuse of the hosted paypage page and prevent fraudulent actives, such as attempting to have large fees accessed by initiating fraudulent charges that will be disputed later.

If set to 0, then no transactions can process for the page and effectively disables its use.

The maximum should be based on the estimated largest transaction amount that will be processed by the page.

If a fixed page amount is configured, this should be set to the same value.

max_total_amount
string\d*(\.\d{0,2})?

Maximum amount of all attempted transactions that can be processed within a day

This is the total of all the amounts of attempted transactions once added together. For example, txn a for $4, txn b for $9, txn c for $12 = a total of $25. If the maximum is set to $15 then txn c would not be accepted because it would exceed the maximum total amount.

This is to prevent abuse of the hosted paypage page and prevent fraudulent actives, such as attempting to have large fees accessed by initiating fraudulent charges that will be disputed later.

If set to 0, then no transactions can process for the page and effectively disables its use.

The maximum should be based on the estimated total amount of attempted payments. The total is based on attempted, authorized, and declined transactions.

redirect_url
string

URL to redirect the customer to after processing

This should be a URL to the merchant's web site. Any returned fields will be added to the URL as query parameters when redirecting the customer.

terms_url
string

URL to the merchant's terms and conditions

privacy_url
string

URL to the merchant's privacy policy

Responses

Request samples

Content type
application/json
{
  • "descr": "$50 donation button",
  • "trantype": "sale",
  • "allowed_cardtypes": "VISA|MC",
  • "amount": "19.92",
  • "fields_shown": "string",
  • "fields_editable": "string",
  • "fields_required": "string",
  • "fields_returned": "string",
  • "fee_type": "none",
  • "fee_title": "Processing Fee",
  • "fee_value": "19.92",
  • "max_count": "1000",
  • "max_amount": "51.48",
  • "max_total_amount": "19500.77",
  • "redirect_url": "string",
  • "terms_url": "string",
  • "privacy_url": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

User

User management

Accessing profiles

Users within the group will be able to access and process the profiles within the group they are in. Users can have a default profile set so they do not need to specify a profile with every transaction.

Additionally users can be locked to only allow processing with a specific profile. This allows a clerk to only process transactions for their work location while allowing someone like a floating manager to process at whichever store they happen to be at.

Change User Password

Change User Password

User's are able to change their own password provided they have the necessary permissions.

If changing another user's password, this can fail under the following conditions:

  • User whose password is being changed has greater permissions than the authenticated user
  • The RESET_PEER_PASSWD flag is not set

libmonetra KVS equivalent for endpoint

  • action_sys = user_passwd
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
id
string\d+

Conditional. User id of user to operate on, if not provided, user is required

Cannot be combined with:

  • user
user
string <= 128 characters

Conditional. Username of user to operate on, if not provided, id is required

Cannot be combined with:

  • id
pwd
string <= 256 characters

New password to set for user being edited

temporary
string
Default: "no"
Enum: "yes" "no"

Whether the user's password is a temporary password

By default if changing another user's password, the password is temporary, meaning the user must change it immediately upon initial login. This may be set to no to make the password permanent, however this is only allowed if the user's password being modified is an UNATTENDED user. When changing a user's own password, it is always permanent and this flag is ignored.

Values:

  • yes - Password is temporary and required to be changed on first login
  • no - Password is not temporary and does not need to be changed on first login

Responses

Request samples

Content type
application/json
{
  • "id": "5678967654",
  • "user": "user2",
  • "pwd": "sTnn56Wve79&#%q#K4GF9Z",
  • "temporary": "yes"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Delete User

Delete a user

Deleting a user can fail for the following conditions:

  • Cannot delete self
  • Cannot delete someone with greater perms than themselves

libmonetra KVS equivalent for endpoint

  • action_sys = user_del
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
id
string
Example: id=5678967654

Conditional. User id of user to operate on, if not provided, user is required

Cannot be combined with:

  • user
user
string
Example: user=user2

Conditional. Username of user to operate on, if not provided, id is required

Cannot be combined with:

  • id

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/user' \
  --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=' \
  -d '
    {
      "user": "james"
    }' \
  -H 'Content-Type: application/json; charset=utf-8'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

List Users

List users

The resulting report will contain these headers:

id, username, group_id, group_depth, status, flags, create_ts, upd_ts,
lastlogin_ts, pwchange_ts, login_fail_cnt, lock_ts, su_perms, sys_perms,
admin_perms, trans_perms, default_profile_id, name, mobilephone

status can be one of:

  • ACTIVE - good standing
  • DISABLED - administratively disabled
  • LOCKED - locked due to login failures

libmonetra KVS equivalent for endpoint

  • action_sys = user_list
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
id
string
Example: id=5678967654

Query a specific user id

Cannot be combined with:

  • user
user
string
Example: user=user2

Query a specific user by name

Cannot be combined with:

  • id
default_profile_id
string
Example: default_profile_id=7584476584356

Profile id of the default profile the user is assigned to use

So they can run transactions without specifying a profile.

If not specified, will auto-link to the profile at the same group level, if there is only one. If there are none or more than 1, will remain unlinked.

When searching allows filtering by users that share a given default profile id.

flags
object
Enum: "UNATTENDED" "SELFVIEWONLY" "MFA" "ALLOW_UNLINKED_REFUND" "ALLOW_GROUP_APIKEYS" "RESET_PEER_PASSWD"
Example: flags=MFA|ALLOW_UNLINKED_REFUND|RESET_PEER_PASSWD

Flag values (pipe separated):

  • UNATTENDED - Meant for system/application/integration accounts
  • SELFVIEWONLY - Cannot see anything about other users such as the users themselves nor any transactions other users have performed
  • MFA - The user is enabled for multifactor authentication. Cannot be enabled or disabled on a user unless the current user has the flag set, unless the group mandates MFA on users (in which case that takes precedence and cannot be disabled). Unattended users cannot have MFA enabled.
  • ALLOW_UNLINKED_REFUND - Allow refunds via key or card entry rather than requiring them be linked to a prior transaction. If this flag is not set, even when linked to a prior transaction it will ensure that the prior transaction is a SALE and the total amounts of the refunds for all linked never exceed the original total
  • ALLOW_GROUP_APIKEYS - Allow creation API keys representing groups.
  • RESET_PEER_PASSWD - The user is allowed to change the password of a peer that has less than or equal permissions
status
object
Enum: "ACTIVE" "DISABLED" "LOCKED"
Example: status=ACTIVE

Status of the user

Values:

  • ACTIVE - User is active and can process
  • DISABLED - User is disabled and cannot process
  • LOCKED - User is disabled and cannot process
group_id
string
Example: group_id=36789654543

Query starting at a specific group id, if not specified, defaults to user's group id.

maxdepth
string
Example: maxdepth=4

Maximum depth to display

Default is unlimited. Specify 1 to see only self and children.

search
string

Will perform a substring search across multiple fields

phone_mobile
string
Example: phone_mobile=555-555-5555

Mobile phone

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/user?user=james' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "report": "..."
}

Edit User

Edits a user

If id is specified user can also be specified in order to change the username.

If editing self, cannot edit perms, or flags. Can edit other fields though.

libmonetra KVS equivalent for endpoint

  • action_sys = user_edit
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
id
string\d+

Conditional. User id of user to operate on, if not provided, user is required

Cannot be combined with:

  • user
user
string <= 128 characters

Conditional. Username of user to operate on, if not provided, id is required

Cannot be combined with:

  • id
default_profile_id
string\d+

Profile id of the default profile the user is assigned to use

So they can run transactions without specifying a profile.

If not specified, will auto-link to the profile at the same group level, if there is only one. If there are none or more than 1, will remain unlinked.

When searching allows filtering by users that share a given default profile id.

email
string <= 128 characters

email

flags
string
Enum: "UNATTENDED" "SELFVIEWONLY" "MFA" "ALLOW_UNLINKED_REFUND" "ALLOW_GROUP_APIKEYS" "RESET_PEER_PASSWD"

Flag values (pipe separated):

  • UNATTENDED - Meant for system/application/integration accounts
  • SELFVIEWONLY - Cannot see anything about other users such as the users themselves nor any transactions other users have performed
  • MFA - The user is enabled for multifactor authentication. Cannot be enabled or disabled on a user unless the current user has the flag set, unless the group mandates MFA on users (in which case that takes precedence and cannot be disabled). Unattended users cannot have MFA enabled.
  • ALLOW_UNLINKED_REFUND - Allow refunds via key or card entry rather than requiring them be linked to a prior transaction. If this flag is not set, even when linked to a prior transaction it will ensure that the prior transaction is a SALE and the total amounts of the refunds for all linked never exceed the original total
  • ALLOW_GROUP_APIKEYS - Allow creation API keys representing groups.
  • RESET_PEER_PASSWD - The user is allowed to change the password of a peer that has less than or equal permissions
su_perms
string
Enum: "ALL" "BIGBATCH" "BIGBATCH_MANAGE" "BIGBATCH_SETTLE" "E2EE_KEY_DEACTIVATE" "E2EE_KEY_EDIT" "E2EE_KEY_GENERATE" "E2EE_KEY_LIST" "IMPORTEXPORT" "INFO" "MAINTENANCE" "P2PE_BDK_DEACTIVATE" "P2PE_BDK_EDIT" "P2PE_BDK_EXPORT" "P2PE_BDK_GENERATE" "P2PE_BDK_KCV" "P2PE_BDK_LIST" "P2PE_BDK_PRINT" "P2PE_DEVICE_DEACTIVATE" "P2PE_DEVICE_EDIT" "P2PE_DEVICE_LIST" "P2PE_DEVICE_PROVISION" "PRODUCT_LICENSE" "PUSHNOTIFICATION" "TOKEN_EXPORT"

System restricted access permissions

Pipe (|) separate list of permissions.

ALL keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • BIGBATCH - Big Batch Reporting
  • BIGBATCH_MANAGE - Manage Big Batch accounts
  • BIGBATCH_SETTLE - Settle Big Batch batches
  • E2EE_KEY_DEACTIVATE - Deactivate E2EE keys used for encrypted transport.
  • E2EE_KEY_EDIT - Edit E2EE keys used for encrypted transport.
  • E2EE_KEY_GENERATE - Generate E2EE keys used for encrypted transport. Such a transaction export and import between multiple installations of TranSafe
  • E2EE_KEY_LIST - List E2EE keys used for encrypted transport.
  • IMPORTEXPORT - Allow importing and exporting database data
  • INFO - Monetra information
  • MAINTENANCE - Enable maintains mode to prevent transaction processing. Primarily used in conjunction with IMPORTEXPORT permission
  • P2PE_BDK_DEACTIVATE - Deactivate a P2PE Base Derivation Key
  • P2PE_BDK_EDIT - Edit a P2PE Base Derivation Key
  • P2PE_BDK_EXPORT - Export a P2PE Base Derivation Key for sharing with a Key Injection Facility
  • P2PE_BDK_GENERATE - Generate a Base Derivation Key for P2PE device encryption
  • P2PE_BDK_KCV - P2PE Base Derivation Key Check Value
  • P2PE_BDK_LIST - List P2PE Base Derivation Key
  • P2PE_BDK_PRINT - Print encrypted P2PE Base Derivation Key on a compatible printer. Only applies when keys are managed by an HSM
  • P2PE_DEVICE_DEACTIVATE - Deactivate a P2PE Device
  • P2PE_DEVICE_EDIT - Edit P2PE device
  • P2PE_DEVICE_LIST - List P2PE devices
  • P2PE_DEVICE_PROVISION - Provision a device in TranSafe that uses P2PE. Provisioning is required for Validated P2PE, non validated P2PW TranSafe will auto provision devices on first use
  • PRODUCT_LICENSE - Manage products that have been registered with TranSafe
  • PUSHNOTIFICATION - Manage push notification endpoints
  • TOKEN_EXPORT - Store account export
sys_perms
string
Enum: "ALL" "V8_COMPLEX_EMULATION" "GETPERMS" "GROUP_ADD" "GROUP_EDIT" "GROUP_MOVE" "GROUP_DEL" "GROUP_LIST" "USER_ADD" "USER_EDIT" "USER_MOVE" "USER_DEL" "USER_LIST" "USER_ENABLE" "USER_DISABLE" "USER_PASSWD" "USER_UNLOCK" "PROFILE_ADD" "PROFILE_EDIT" "PROFILE_MOVE" "PROFILE_DEL" "PROFILE_LIST" "PROFILE_STATS" "PROFILE_ENABLE" "PROFILE_DISABLE" "ROUTE_ADD" "ROUTE_EDIT" "ROUTE_DEL" "ROUTE_LIST" "ROUTE_FIELDS" "CRON" "INFO" "SETLOGGING" "REGISTER_CLIENT" "SKYLINK_MANAGE" "APIKEYS" "MFA_GENERATE" "MFA_RESET" "SECURITY_QUESTIONS"

System access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • V8_COMPLEX_EMULATION - Allow TranSafe v8 protocol emulation. Allows equivalent v8 protocol actions to be used
  • GETPERMS - Get user permissions
  • GROUP_ADD - Create a group
  • GROUP_EDIT - Edit a group
  • GROUP_MOVE - Move a group to a different group
  • GROUP_DEL - Delete a group
  • GROUP_LIST - List groups
  • USER_ADD - Create a user
  • USER_EDIT - Edit a user
  • USER_MOVE - Move a user to a different group
  • USER_DEL - Delete a user
  • USER_LIST - List users
  • USER_ENABLE - Enable a user
  • USER_DISABLE - Disable a user
  • USER_PASSWD - Change a user's password. Includes self
  • USER_UNLOCK - Unlock a user
  • PROFILE_ADD - Add a profile
  • PROFILE_EDIT - Edit a profile
  • PROFILE_MOVE - Move a profile to a different group
  • PROFILE_DEL - Delete a profile
  • PROFILE_LIST - List profiles
  • PROFILE_STATS - Profile statistics
  • PROFILE_ENABLE - Enable a profile
  • PROFILE_DISABLE - Disable a profile
  • ROUTE_ADD - Add a route
  • ROUTE_EDIT - Edit a route
  • ROUTE_DEL - Delete a route
  • ROUTE_LIST - List routes
  • ROUTE_FIELDS - Get processor specific fields for use with adding or editing a route
  • CRON - System task scheduler operations
  • INFO - TranSafe information
  • SETLOGGING - Start / Stop an in memory logging buffer
  • REGISTER_CLIENT - Registers use of a product with TranSafe
  • SKYLINK_MANAGE - Manage SkyLink product licences
  • APIKEYS - API key management
  • MFA_GENERATE - Enable or change MFA method
  • MFA_RESET - Reset MFA so it needs to be generated
  • SECURITY_QUESTIONS - User security questions
admin_perms
string
Enum: "ALL" "REPORT_TRAN" "REPORT_TOTALS" "REPORT_CHARTDATA" "REPORT_QUEUE" "BATCH_CLEAR" "BATCH_SET" "BATCH_RESCIND" "BATCH_CLOSE" "TRAN_EDIT" "TRAN_NULLIFY" "TRAN_DETAIL" "TRAN_RECEIPT" "MERCH_INFO" "IMAGE_ADD" "IMAGE_DEL" "IMAGE_GET" "TOKEN_ADD" "TOKEN_EDIT" "TOKEN_DEL" "TOKEN_SCHEDULE" "TOKEN_LIST" "CUSTOMER_ADD" "CUSTOMER_EDIT" "CUSTOMER_DEL" "CUSTOMER_LIST" "TICKETREQUEST" "LEVEL3" "PRODMANAGE" "PRODLIST" "ORDERMANAGE" "ORDERLIST" "ORDERREPORT" "CARDDENYLIST" "P2PE" "STANDINKEY_GENERATE" "REPORT_DEVICE"

Administrative access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • REPORT_TRAN - Transaction and batch detail reports
  • REPORT_TOTALS - Transaction and batch total reports
  • REPORT_CHARTDATA - Card data breakdown for report views
  • REPORT_QUEUE - List queued transactions pending authorization
  • BATCH_CLEAR - Mark batch as settled without funding
  • BATCH_SET - Change batch number
  • BATCH_RESCIND - Unsettle a batch (can double charge customers)
  • BATCH_CLOSE - Close a batch so new transactions are not added but do not settle
  • TRAN_EDIT - Edit a transaction
  • TRAN_NULLIFY - Delete a previously-authorized transaction without any attempt to go online and remove an authorization hold. Similar to a void.
  • TRAN_DETAIL - Transaction details
  • TRAN_RECEIPT - Transaction receipts. Generating and sending receipts, and invoices
  • MERCH_INFO - Profile information
  • IMAGE_ADD - Store an image. Check, signature, etc
  • IMAGE_DEL - Delete an image. Check, signature, etc
  • IMAGE_GET - Get an image. Check, signature, etc
  • TOKEN_ADD - Store an account
  • TOKEN_EDIT - Edit a stored account
  • TOKEN_DEL - Delete a stored account
  • TOKEN_SCHEDULE - Manage recurring and installment payments
  • TOKEN_LIST - List stored accounts
  • CUSTOMER_ADD - Add a customer
  • CUSTOMER_EDIT - Edit a customer
  • CUSTOMER_DEL - Delete a customer
  • CUSTOMER_LIST - List customers
  • TICKETREQUEST - Request temporary cardshieldticket representing a customer's account
  • LEVEL3 - Level 3 line item operations
  • PRODMANAGE - Manage products (sku, amount, etc) in the inventory system
  • PRODLIST - List product details in the inventory system
  • ORDERMANAGE - Manage orders and invoices
  • ORDERLIST - List orders and invoices
  • ORDERREPORT - Reports for orders and invoices
  • CARDDENYLIST - Manage the card deny list
  • P2PE - P2PE device management
  • STANDINKEY_GENERATE - Generate an encryption key used for encrypting account data as part of stand-in authorization
  • REPORT_DEVICE - Device-level transaction journals
trans_perms
string
Enum: "ALL" "VERIFYONLY" "SALE" "PREAUTH" "REVERSAL" "INCREMENTAL" "PREAUTHCOMPLETE" "FORCE" "CAPTURE" "VOID" "ADJUST" "REFUND" "ACTIVATE" "BALANCEINQ" "CASHOUT" "TOREVERSAL" "MERCHRETURN" "ISSUE" "TIP" "EBTFSSALE" "EBTFSRETURN" "EBTFSVOUCHER" "EBTFSBALANCE" "EBTCBSALE" "EBTCBCASH" "EBTCBBALANCE" "CHECKVERIFY" "CHECKCONVONLY" "CHECKCONVVRFY" "CHECKCONVGUAR" "CHECKCONVOVER" "CHECKIMAGEUPLOAD" "SETTLE" "SETTLERFR" "TERMLOAD" "INTERACMAC" "EMVCOMPLETE" "ALTPAYMENTINIT" "CARDTYPE"

Transaction access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • VERIFYONLY - Card verification
  • SALE - Purchase
  • PREAUTH - Authorization only (preauth)
  • REVERSAL - Reverse a transaction
  • INCREMENTAL - Incremental
  • PREAUTHCOMPLETE - Complete an authorization only (preauth) transaction
  • FORCE - Force purchase without online authorization
  • CAPTURE - Capture an un-captured transaction
  • VOID - Void a trasnaction
  • ADJUST - Adjust a transaction
  • REFUND - Refund
  • ACTIVATE - Activate a private label gift card
  • BALANCEINQ - Request account balance
  • CASHOUT - Remove all funds from a gift card in order to provide the customer with cash for the value
  • TOREVERSAL - Timeout reversal
  • MERCHRETURN - Merchandise return. Used by gift cards
  • ISSUE - Issue a gift card
  • TIP - Add a tip to a gift card
  • EBTFSSALE - Electronic Benefits Transfer food purchase
  • EBTFSRETURN - Electronic Benefits Transfer food refund
  • EBTFSVOUCHER - Electronic Benefits Transfer food voucher (paper food stamps) purchase
  • EBTFSBALANCE - Electronic Benefits Transfer food balance
  • EBTCBSALE - Electronic Benefits Transfer cash purchase
  • EBTCBCASH - Electronic Benefits Transfer cash withdrawal
  • EBTCBBALANCE - Electronic Benefits Transfer cash balance
  • CHECKVERIFY - Check verification only (without conversion)
  • CHECKCONVONLY - Check conversion only (without verification)
  • CHECKCONVVRFY - Check verification and conversion
  • CHECKCONVGUAR - Check conversation guarantee
  • CHECKCONVOVER - Convert a check with override
  • CHECKIMAGEUPLOAD - Upload check image
  • SETTLE - Settle
  • SETTLERFR - Request Settlement Status (limited processor support)
  • TERMLOAD - Terminal loading data
  • INTERACMAC - Interac MACing parameters
  • EMVCOMPLETE - EMV completion transaction
  • ALTPAYMENTINIT - Init an alternative payment method
  • CARDTYPE - Determine cardtype of presented account
name
string <= 128 characters

User's real name

phone_mobile
string <= 32 characters [-+0-9() .]*

Mobile phone

Responses

Request samples

Content type
application/json
{
  • "id": "5678967654",
  • "user": "user2",
  • "default_profile_id": "7584476584356",
  • "email": "email@email",
  • "flags": "MFA|ALLOW_UNLINKED_REFUND|RESET_PEER_PASSWD",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "ALL",
  • "trans_perms": "ALL",
  • "name": "Alan Alda",
  • "phone_mobile": "555-555-5555"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Create User

Creates a user

Fail if there are explicitly specified perms and perms are greater than allowed.

libmonetra KVS equivalent for endpoint

  • action_sys = user_add
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
user
required
string <= 128 characters

User name of user to add

pwd
required
string <= 256 characters

Password to set for user being added

group_id
string\d+

Group user should be added to. If not specified, defaults to the same group as the current user

default_profile_id
string\d+

Profile id of the default profile the user is assigned to use

So they can run transactions without specifying a profile.

If not specified, will auto-link to the profile at the same group level, if there is only one. If there are none or more than 1, will remain unlinked.

When searching allows filtering by users that share a given default profile id.

email
string <= 128 characters

email

flags
string
Enum: "UNATTENDED" "SELFVIEWONLY" "MFA" "ALLOW_UNLINKED_REFUND" "ALLOW_GROUP_APIKEYS" "RESET_PEER_PASSWD"

Flag values (pipe separated):

  • UNATTENDED - Meant for system/application/integration accounts
  • SELFVIEWONLY - Cannot see anything about other users such as the users themselves nor any transactions other users have performed
  • MFA - The user is enabled for multifactor authentication. Cannot be enabled or disabled on a user unless the current user has the flag set, unless the group mandates MFA on users (in which case that takes precedence and cannot be disabled). Unattended users cannot have MFA enabled.
  • ALLOW_UNLINKED_REFUND - Allow refunds via key or card entry rather than requiring them be linked to a prior transaction. If this flag is not set, even when linked to a prior transaction it will ensure that the prior transaction is a SALE and the total amounts of the refunds for all linked never exceed the original total
  • ALLOW_GROUP_APIKEYS - Allow creation API keys representing groups.
  • RESET_PEER_PASSWD - The user is allowed to change the password of a peer that has less than or equal permissions
su_perms
string
Enum: "ALL" "BIGBATCH" "BIGBATCH_MANAGE" "BIGBATCH_SETTLE" "E2EE_KEY_DEACTIVATE" "E2EE_KEY_EDIT" "E2EE_KEY_GENERATE" "E2EE_KEY_LIST" "IMPORTEXPORT" "INFO" "MAINTENANCE" "P2PE_BDK_DEACTIVATE" "P2PE_BDK_EDIT" "P2PE_BDK_EXPORT" "P2PE_BDK_GENERATE" "P2PE_BDK_KCV" "P2PE_BDK_LIST" "P2PE_BDK_PRINT" "P2PE_DEVICE_DEACTIVATE" "P2PE_DEVICE_EDIT" "P2PE_DEVICE_LIST" "P2PE_DEVICE_PROVISION" "PRODUCT_LICENSE" "PUSHNOTIFICATION" "TOKEN_EXPORT"

System restricted access permissions

Pipe (|) separate list of permissions.

ALL keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • BIGBATCH - Big Batch Reporting
  • BIGBATCH_MANAGE - Manage Big Batch accounts
  • BIGBATCH_SETTLE - Settle Big Batch batches
  • E2EE_KEY_DEACTIVATE - Deactivate E2EE keys used for encrypted transport.
  • E2EE_KEY_EDIT - Edit E2EE keys used for encrypted transport.
  • E2EE_KEY_GENERATE - Generate E2EE keys used for encrypted transport. Such a transaction export and import between multiple installations of TranSafe
  • E2EE_KEY_LIST - List E2EE keys used for encrypted transport.
  • IMPORTEXPORT - Allow importing and exporting database data
  • INFO - Monetra information
  • MAINTENANCE - Enable maintains mode to prevent transaction processing. Primarily used in conjunction with IMPORTEXPORT permission
  • P2PE_BDK_DEACTIVATE - Deactivate a P2PE Base Derivation Key
  • P2PE_BDK_EDIT - Edit a P2PE Base Derivation Key
  • P2PE_BDK_EXPORT - Export a P2PE Base Derivation Key for sharing with a Key Injection Facility
  • P2PE_BDK_GENERATE - Generate a Base Derivation Key for P2PE device encryption
  • P2PE_BDK_KCV - P2PE Base Derivation Key Check Value
  • P2PE_BDK_LIST - List P2PE Base Derivation Key
  • P2PE_BDK_PRINT - Print encrypted P2PE Base Derivation Key on a compatible printer. Only applies when keys are managed by an HSM
  • P2PE_DEVICE_DEACTIVATE - Deactivate a P2PE Device
  • P2PE_DEVICE_EDIT - Edit P2PE device
  • P2PE_DEVICE_LIST - List P2PE devices
  • P2PE_DEVICE_PROVISION - Provision a device in TranSafe that uses P2PE. Provisioning is required for Validated P2PE, non validated P2PW TranSafe will auto provision devices on first use
  • PRODUCT_LICENSE - Manage products that have been registered with TranSafe
  • PUSHNOTIFICATION - Manage push notification endpoints
  • TOKEN_EXPORT - Store account export
sys_perms
string
Enum: "ALL" "V8_COMPLEX_EMULATION" "GETPERMS" "GROUP_ADD" "GROUP_EDIT" "GROUP_MOVE" "GROUP_DEL" "GROUP_LIST" "USER_ADD" "USER_EDIT" "USER_MOVE" "USER_DEL" "USER_LIST" "USER_ENABLE" "USER_DISABLE" "USER_PASSWD" "USER_UNLOCK" "PROFILE_ADD" "PROFILE_EDIT" "PROFILE_MOVE" "PROFILE_DEL" "PROFILE_LIST" "PROFILE_STATS" "PROFILE_ENABLE" "PROFILE_DISABLE" "ROUTE_ADD" "ROUTE_EDIT" "ROUTE_DEL" "ROUTE_LIST" "ROUTE_FIELDS" "CRON" "INFO" "SETLOGGING" "REGISTER_CLIENT" "SKYLINK_MANAGE" "APIKEYS" "MFA_GENERATE" "MFA_RESET" "SECURITY_QUESTIONS"

System access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • V8_COMPLEX_EMULATION - Allow TranSafe v8 protocol emulation. Allows equivalent v8 protocol actions to be used
  • GETPERMS - Get user permissions
  • GROUP_ADD - Create a group
  • GROUP_EDIT - Edit a group
  • GROUP_MOVE - Move a group to a different group
  • GROUP_DEL - Delete a group
  • GROUP_LIST - List groups
  • USER_ADD - Create a user
  • USER_EDIT - Edit a user
  • USER_MOVE - Move a user to a different group
  • USER_DEL - Delete a user
  • USER_LIST - List users
  • USER_ENABLE - Enable a user
  • USER_DISABLE - Disable a user
  • USER_PASSWD - Change a user's password. Includes self
  • USER_UNLOCK - Unlock a user
  • PROFILE_ADD - Add a profile
  • PROFILE_EDIT - Edit a profile
  • PROFILE_MOVE - Move a profile to a different group
  • PROFILE_DEL - Delete a profile
  • PROFILE_LIST - List profiles
  • PROFILE_STATS - Profile statistics
  • PROFILE_ENABLE - Enable a profile
  • PROFILE_DISABLE - Disable a profile
  • ROUTE_ADD - Add a route
  • ROUTE_EDIT - Edit a route
  • ROUTE_DEL - Delete a route
  • ROUTE_LIST - List routes
  • ROUTE_FIELDS - Get processor specific fields for use with adding or editing a route
  • CRON - System task scheduler operations
  • INFO - TranSafe information
  • SETLOGGING - Start / Stop an in memory logging buffer
  • REGISTER_CLIENT - Registers use of a product with TranSafe
  • SKYLINK_MANAGE - Manage SkyLink product licences
  • APIKEYS - API key management
  • MFA_GENERATE - Enable or change MFA method
  • MFA_RESET - Reset MFA so it needs to be generated
  • SECURITY_QUESTIONS - User security questions
admin_perms
string
Enum: "ALL" "REPORT_TRAN" "REPORT_TOTALS" "REPORT_CHARTDATA" "REPORT_QUEUE" "BATCH_CLEAR" "BATCH_SET" "BATCH_RESCIND" "BATCH_CLOSE" "TRAN_EDIT" "TRAN_NULLIFY" "TRAN_DETAIL" "TRAN_RECEIPT" "MERCH_INFO" "IMAGE_ADD" "IMAGE_DEL" "IMAGE_GET" "TOKEN_ADD" "TOKEN_EDIT" "TOKEN_DEL" "TOKEN_SCHEDULE" "TOKEN_LIST" "CUSTOMER_ADD" "CUSTOMER_EDIT" "CUSTOMER_DEL" "CUSTOMER_LIST" "TICKETREQUEST" "LEVEL3" "PRODMANAGE" "PRODLIST" "ORDERMANAGE" "ORDERLIST" "ORDERREPORT" "CARDDENYLIST" "P2PE" "STANDINKEY_GENERATE" "REPORT_DEVICE"

Administrative access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • REPORT_TRAN - Transaction and batch detail reports
  • REPORT_TOTALS - Transaction and batch total reports
  • REPORT_CHARTDATA - Card data breakdown for report views
  • REPORT_QUEUE - List queued transactions pending authorization
  • BATCH_CLEAR - Mark batch as settled without funding
  • BATCH_SET - Change batch number
  • BATCH_RESCIND - Unsettle a batch (can double charge customers)
  • BATCH_CLOSE - Close a batch so new transactions are not added but do not settle
  • TRAN_EDIT - Edit a transaction
  • TRAN_NULLIFY - Delete a previously-authorized transaction without any attempt to go online and remove an authorization hold. Similar to a void.
  • TRAN_DETAIL - Transaction details
  • TRAN_RECEIPT - Transaction receipts. Generating and sending receipts, and invoices
  • MERCH_INFO - Profile information
  • IMAGE_ADD - Store an image. Check, signature, etc
  • IMAGE_DEL - Delete an image. Check, signature, etc
  • IMAGE_GET - Get an image. Check, signature, etc
  • TOKEN_ADD - Store an account
  • TOKEN_EDIT - Edit a stored account
  • TOKEN_DEL - Delete a stored account
  • TOKEN_SCHEDULE - Manage recurring and installment payments
  • TOKEN_LIST - List stored accounts
  • CUSTOMER_ADD - Add a customer
  • CUSTOMER_EDIT - Edit a customer
  • CUSTOMER_DEL - Delete a customer
  • CUSTOMER_LIST - List customers
  • TICKETREQUEST - Request temporary cardshieldticket representing a customer's account
  • LEVEL3 - Level 3 line item operations
  • PRODMANAGE - Manage products (sku, amount, etc) in the inventory system
  • PRODLIST - List product details in the inventory system
  • ORDERMANAGE - Manage orders and invoices
  • ORDERLIST - List orders and invoices
  • ORDERREPORT - Reports for orders and invoices
  • CARDDENYLIST - Manage the card deny list
  • P2PE - P2PE device management
  • STANDINKEY_GENERATE - Generate an encryption key used for encrypting account data as part of stand-in authorization
  • REPORT_DEVICE - Device-level transaction journals
trans_perms
string
Enum: "ALL" "VERIFYONLY" "SALE" "PREAUTH" "REVERSAL" "INCREMENTAL" "PREAUTHCOMPLETE" "FORCE" "CAPTURE" "VOID" "ADJUST" "REFUND" "ACTIVATE" "BALANCEINQ" "CASHOUT" "TOREVERSAL" "MERCHRETURN" "ISSUE" "TIP" "EBTFSSALE" "EBTFSRETURN" "EBTFSVOUCHER" "EBTFSBALANCE" "EBTCBSALE" "EBTCBCASH" "EBTCBBALANCE" "CHECKVERIFY" "CHECKCONVONLY" "CHECKCONVVRFY" "CHECKCONVGUAR" "CHECKCONVOVER" "CHECKIMAGEUPLOAD" "SETTLE" "SETTLERFR" "TERMLOAD" "INTERACMAC" "EMVCOMPLETE" "ALTPAYMENTINIT" "CARDTYPE"

Transaction access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • VERIFYONLY - Card verification
  • SALE - Purchase
  • PREAUTH - Authorization only (preauth)
  • REVERSAL - Reverse a transaction
  • INCREMENTAL - Incremental
  • PREAUTHCOMPLETE - Complete an authorization only (preauth) transaction
  • FORCE - Force purchase without online authorization
  • CAPTURE - Capture an un-captured transaction
  • VOID - Void a trasnaction
  • ADJUST - Adjust a transaction
  • REFUND - Refund
  • ACTIVATE - Activate a private label gift card
  • BALANCEINQ - Request account balance
  • CASHOUT - Remove all funds from a gift card in order to provide the customer with cash for the value
  • TOREVERSAL - Timeout reversal
  • MERCHRETURN - Merchandise return. Used by gift cards
  • ISSUE - Issue a gift card
  • TIP - Add a tip to a gift card
  • EBTFSSALE - Electronic Benefits Transfer food purchase
  • EBTFSRETURN - Electronic Benefits Transfer food refund
  • EBTFSVOUCHER - Electronic Benefits Transfer food voucher (paper food stamps) purchase
  • EBTFSBALANCE - Electronic Benefits Transfer food balance
  • EBTCBSALE - Electronic Benefits Transfer cash purchase
  • EBTCBCASH - Electronic Benefits Transfer cash withdrawal
  • EBTCBBALANCE - Electronic Benefits Transfer cash balance
  • CHECKVERIFY - Check verification only (without conversion)
  • CHECKCONVONLY - Check conversion only (without verification)
  • CHECKCONVVRFY - Check verification and conversion
  • CHECKCONVGUAR - Check conversation guarantee
  • CHECKCONVOVER - Convert a check with override
  • CHECKIMAGEUPLOAD - Upload check image
  • SETTLE - Settle
  • SETTLERFR - Request Settlement Status (limited processor support)
  • TERMLOAD - Terminal loading data
  • INTERACMAC - Interac MACing parameters
  • EMVCOMPLETE - EMV completion transaction
  • ALTPAYMENTINIT - Init an alternative payment method
  • CARDTYPE - Determine cardtype of presented account
name
string <= 128 characters

User's real name

phone_mobile
string <= 32 characters [-+0-9() .]*

Mobile phone

Responses

Request samples

Content type
application/json
{
  • "user": "user2",
  • "pwd": "sTnn56Wve79&#%q#K4GF9Z",
  • "group_id": "36789654543",
  • "default_profile_id": "7584476584356",
  • "email": "email@email",
  • "flags": "MFA|ALLOW_UNLINKED_REFUND|RESET_PEER_PASSWD",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "ALL",
  • "trans_perms": "ALL",
  • "name": "Alan Alda",
  • "phone_mobile": "555-555-5555"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "5678967654"
}

Disable User

Disable User that is enabled

Will return failure if user is disabled or locked.

Admistratively disables a user. The user cannot be used until enabled. This will not expire and the user must be manually enabled.

libmonetra KVS equivalent for endpoint

  • action_sys = user_disable
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
id
string\d+

Conditional. User id of user to operate on, if not provided, user is required

Cannot be combined with:

  • user
user
string <= 128 characters

Conditional. Username of user to operate on, if not provided, id is required

Cannot be combined with:

  • id

Responses

Request samples

Content type
application/json
{
  • "id": "5678967654",
  • "user": "user2"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Enable User

Enable User that was disabled

Will return failure if user is not currently disabled.

Admistratively enable a user. The user must have been previously disabled. Locked user's are not considered disabled and should be unlocked using the unlock action.

libmonetra KVS equivalent for endpoint

  • action_sys = user_enable
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
id
string\d+

Conditional. User id of user to operate on, if not provided, user is required

Cannot be combined with:

  • user
user
string <= 128 characters

Conditional. Username of user to operate on, if not provided, id is required

Cannot be combined with:

  • id

Responses

Request samples

Content type
application/json
{
  • "id": "5678967654",
  • "user": "user2"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Permissions

Gets the user's permissions

This is the permissions for the authenticating user. In order to get permissions for a specific user, use the "List Users" report filtering on the user in question.

This action should be used for password / API key verification if needing to verify before further processing take place.

libmonetra KVS equivalent for endpoint

  • action_sys = getperms
Authorizations:
basic_auth(apikey_idapikey)

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/user/permissions' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "pass_expire_secs": "4676",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "ALL",
  • "trans_perms": "ALL"
}

Unlock User

Unlock a locked user

Will return failure if user not locked.

Users are automatically locked after too many login failures. Locking is temporary and will expire automatically after a set amount of time. The unlock action unlocks the user without having to wait for the lock time period to elapse.

libmonetra KVS equivalent for endpoint

  • action_sys = user_unlock
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
id
string\d+

Conditional. User id of user to operate on, if not provided, user is required

Cannot be combined with:

  • user
user
string <= 128 characters

Conditional. Username of user to operate on, if not provided, id is required

Cannot be combined with:

  • id

Responses

Request samples

Content type
application/json
{
  • "id": "5678967654",
  • "user": "user2"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

MFA

User multi factor authentication management

Multi Factor Authentication (MFA) is supported using a variety of methods. See "Generating" for more information about each method. Also see the "MFA Code" section under the main "Authentication" information.

MFA can be enabled for any user at any time. Groups can mandate that all users within the group and in any subgroup must enable MFA.

This section is for managing MFA not generating an MFA code. MFA code generation is an out of band process.

Generate Multi Factor Authentication

Generate (or replace) the existing Multi Factor Authentication mechanism

This requires the full username and password, an APIKey cannot be used to call this function. If MFA is already set up on the account, the existing MFA code must also be provided.

phone_mobile or email can be provided if the corresponding type is chosen to explictly set where the code should be sent. It is not required if the user account already has these configured.

When an action is attempted that requires MFA but an MFA code is not provided an msoft_code=ACCT_MFA_REQUIRED will be returned. If sms or email codes methods were chosen, an sms or email will automatically be trigered to send the MFA code to the user.

If the user does not already have the MFA user flag, it will be automatically added to the account.

libmonetra KVS equivalent for endpoint

  • action_sys = mfa_generate
  • mfa_generate = totp
Authorizations:
basic_auth
Request Body schema: application/json
type
required
string
Enum: "TOTP_APP" "TOTP_SMS" "TOTP_EMAIL"

Values:

  • TOTP_APP - Using external application, such as Google Authenticator, Authy, or Last Pass Authenticator
  • TOTP_SMS - Send TOTP-based text messages with 6 digit code to phone_mobile configured on user account
  • TOTP_EMAIL - TOTP-based email messages with 6 digit code to email configured on user account
phone_mobile
string <= 32 characters [-+0-9() .]*

Mobile phone

email
string <= 128 characters

email

Responses

Request samples

Content type
application/json
{
  • "type": "TOTP_APP",
  • "phone_mobile": "555-555-5555",
  • "email": "email@email"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "key": "otpauth://totp/Super%20ISO:doug?secret=WZA5UAPCTESR3IR6&algorithm=SHA1&digits=6&period=30&issuer=Payment%20Server"
}

Generate Multi Factor Authentication Cookie

MFA timed bypass with authentication cookie

It is desirable for many web interfaces to not constantly prompt for MFA, but instead let a user choose that they are on a private trusted device and to store a cookie on the system for a duration that can be used in place of MFA.

A real MFA code is required to request a cookie that will be valid for the desired duration, specified in seconds. The maximum duration allowed to be specified is 30 days (2592000s), minimum is 15 minutes (900s), though periods less than 24hrs may be a questionable use.

The cookie will need to be presented instead of the MFA code, and will be passed in the same API field of mfa_code, just as the TOTP code normally is.

This is NOT an API key, it still requires the valid username and password to be specified when using it. This is purely an MFA code.

A single user account may have up to 5 generated cookies that are valid at any time, if a new one is requested and the limit is exceeded, it will replace the old one. (multiples are allowed to allow logins from multiple devices or browsers).

The cookie should be stored in a browser cookie for web UIs (perhaps encrypted, but implementation dependent)

Generally, upon logging into a web system, an integrator should generate a temporary auto-extending api key. The cookie can be used for this purpose.

If the cookie is expired, the user will only get the msoft_code=ACCT_MFA_INVALID response and it will be treated as an error so a validity period should also be tracked by the cookie so as to not cause authentication failures that could lead to blacklisting.

libmonetra KVS equivalent for endpoint

  • action_sys = mfa_generate
  • mfa_generate = cookie
Authorizations:
basic_auth
Request Body schema: application/json
expire_s
required
string\d+

Number of seconds this cookie is requested to be valid for

The valid range is 15 minutes to 30 days (900s - 2592000s). Generally an expiration period will be 24hrs or more.

Responses

Request samples

Content type
application/json
{
  • "expire_s": "172800"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "key": "676574637485697",
  • "expire_ts": "2022-05-24 15:06:13 -0400"
}

Reset Multi Factor Authentication

Reset Multi Factor Authentication so it needs to be generated

MFA will remain enabled requiring the user to generate an MFA key.

user or id must be provided to reset the MFA for the specified user. MFA self reset is not allowed. Self reset requres the user to utilize the 3-step self reset process.

Subsequent operations will return the msoft_code=MFA_GENERATE indicating MFA needs to be generated.

libmonetra KVS equivalent for endpoint

  • action_sys = mfa_reset
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
id
string\d+

Conditional. User id of user to operate on, if not provided, user will be used if it was provided

Cannot be combined with:

  • user
user
string <= 128 characters

Conditional. Username of user to operate on, if not provided, id will be used if it was provided

Cannot be combined with:

  • id

Responses

Request samples

Content type
application/json
{
  • "id": "5678967654",
  • "user": "user2"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Self Reset

User self password and MFA reset management. Users are able to initiate a reset request for their password and MFA tokens when they've forgotten one or the other.

In order to do this, they must have security questions on file and know the answers. They also must have a phone number for SMS or an email on file because part of the process involves sending them a verification code.

The reset processes are multi-step with, as indicated, out of band verification of the user.

List Security Questions

List security questions

libmonetra KVS equivalent for endpoint

  • action_sys = security_questions
  • security_questions = list
Authorizations:
basic_auth(apikey_idapikey)

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/user/security_questions' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "question1": "Question 1?",
  • "question2": "Question 2?",
  • "question3": "Question 3?",
  • "created_ts": "2022-05-24 15:06:13 -0400",
  • "upd_ts": "2022-05-24 15:06:13 -0400"
}

Edit Security Questions

Edit security questions

libmonetra KVS equivalent for endpoint

  • action_sys = security_questions
  • security_questions = edit
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
question1
string [ 3 .. 128 ] characters .{3,128}

Security question

question2
string [ 3 .. 128 ] characters .{3,128}

Security question

question3
string [ 3 .. 128 ] characters .{3,128}

Security question

answer1
string

Security answer

answer2
string

Security answer

answer3
string

Security answer

Responses

Request samples

Content type
application/json
{
  • "question1": "Question 1?",
  • "question2": "Question 2?",
  • "question3": "Question 3?",
  • "answer1": "Answer 1",
  • "answer2": "Answer 2",
  • "answer3": "Answer 3"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Create Security Questions

Create user's security questions

  • Operates only on the logged-in user
  • User must be a normal attended user
  • Unattended users are not allowed
  • Questions may not be duplicates nor contain the username
  • Answers may not be duplicates nor contain the username or password, and must be at least 3 alpha-numeric characters (excluding whitespace and punctuation)

libmonetra KVS equivalent for endpoint

  • action_sys = security_questions
  • security_questions = add
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
question1
required
string [ 3 .. 128 ] characters .{3,128}

Security question

question2
required
string [ 3 .. 128 ] characters .{3,128}

Security question

question3
required
string [ 3 .. 128 ] characters .{3,128}

Security question

answer1
required
string

Security answer

answer2
required
string

Security answer

answer3
required
string

Security answer

Responses

Request samples

Content type
application/json
{
  • "question1": "Question 1?",
  • "question2": "Question 2?",
  • "question3": "Question 3?",
  • "answer1": "Answer 1",
  • "answer2": "Answer 2",
  • "answer3": "Answer 3"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Self MFA Reset - Step 1: Code

User self-reset of multi factor authentication

This is a multi-step process consisting of several steps.

  1. code
  2. security_questions
  3. reset

This relies on a one-time use verification code to initiate the reset attempt which will be emailed or sent via SMS to the user. This code is then entered into a follow-up request to retrieve the user's security questions. The final follow-up will pass the same verification code and all 3 security question answers.

The reset operation may be initiated at most 3 times in a 24hr period. The emailed or sms code may only be used once for each step of the reset operation.

The user is required to authenticate using their username and password.

If the user does not have security questions configured this action will fail with an error. Also, the user must have an email or phone number capable of receiving sms messages on file (based on the method chosen for receiving the security code).

libmonetra KVS equivalent for endpoint

  • action_sys = auth_reset
  • auth_reset = mfa
  • phase = code
Authorizations:
basic_auth
query Parameters
method
required
object
Enum: "EMAIL" "SMS"
Example: method=SMS

Values:

  • EMAIL - Send reset code by email
  • SMS - send reset code by sms

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/user/self/reset/mfa/code?reset_method=email' --basic -u 'test_retail:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Self MFA Reset - Step 2: Security Questions

Retrieve security questions for a user for self password reset

libmonetra KVS equivalent for endpoint

  • action_sys = auth_reset
  • auth_reset = mfa
  • phase = security_questions
Authorizations:
basic_auth
Request Body schema: application/json
reset_code
required
string

Self reset authentication code sent to the user via email or sms

Responses

Request samples

Content type
application/json
{
  • "reset_code": "46602473"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "question1": "Question 1?",
  • "question2": "Question 2?",
  • "question3": "Question 3?"
}

Self MFA Reset - Step 3: Reset

Request the finalization of the self MFA reset operation

libmonetra KVS equivalent for endpoint

  • action_sys = auth_reset
  • auth_reset = mfa
  • phase = reset
Authorizations:
basic_auth
Request Body schema: application/json
reset_code
required
string

Self reset authentication code sent to the user via email or sms

answer1
required
string

Security answer

answer2
required
string

Security answer

answer3
required
string

Security answer

Responses

Request samples

Content type
application/json
{
  • "reset_code": "46602473",
  • "answer1": "Answer 1",
  • "answer2": "Answer 2",
  • "answer3": "Answer 3"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Self Password Reset - Step 1: Code

User self-reset of password

This is a multi-step process consisting of several steps.

  1. code
  2. security_questions
  3. reset

This relies on a one-time use verification code to initiate the reset attempt which will be emailed or sent via SMS to the user. This code is then entered into a follow-up request to retrieve the user's security questions and an indicator stating if the user has MFA enabled and configured. The final follow-up will pass the same verification code, all 3 security question answers, and possibly the mfa_code if the account has MFA enabled.

The reset operation may be initiated at most 3 times in a 24hr period. The emailed or sms code may only be used once for each step of the reset operation.

Password resets require the username of the user requesting the reset. The user's password is not used for authentication in any of the three steps. For ReST neither API Key or Basic authentication is used. Instead the authentication parameters are passed in the request itself per the requirements of each step.

If the user does not have security questions configured this action will fail silently without error. Also, the user must have an email or phone number capable of receiving sms messages on file (based on the method chosen for receiving the security code).

libmonetra KVS equivalent for endpoint

  • action_sys = auth_reset
  • auth_reset = password
  • phase = code
Authorizations:
None
query Parameters
username
required
string
Example: username=user1

The username to perform a reset operation on

method
required
object
Enum: "EMAIL" "SMS"
Example: method=SMS

Values:

  • EMAIL - Send reset code by email
  • SMS - send reset code by sms

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/user/self/reset/password/code?username=user1&reset_method=email'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Self Password Reset - Step 2: Security Questions

Retrieve security questions for a user for self password reset

libmonetra KVS equivalent for endpoint

  • action_sys = auth_reset
  • auth_reset = password
  • phase = security_questions
Authorizations:
None
Request Body schema: application/json
username
required
string

The username to perform a reset operation on

reset_code
required
string

Self reset authentication code sent to the user via email or sms

Responses

Request samples

Content type
application/json
{
  • "username": "user1",
  • "reset_code": "46602473"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "question1": "Question 1?",
  • "question2": "Question 2?",
  • "question3": "Question 3?",
  • "mfa_enabled": "yes"
}

Self Password Reset - Step 3: Reset

Request the finalization of the self password reset operation

libmonetra KVS equivalent for endpoint

  • action_sys = auth_reset
  • auth_reset = password
  • phase = reset
Authorizations:
None
Request Body schema: application/json
username
required
string

The username to perform a reset operation on

reset_code
required
string

Self reset authentication code sent to the user via email or sms

answer1
required
string

Security answer

answer2
required
string

Security answer

answer3
required
string

Security answer

pwd
required
string <= 256 characters

Password

mfa_code
required
string

If mfa_enabled was true, then the current mfa code (either from APP, EMAIL or SMS). Cannot be an MFA cookie

Responses

Request samples

Content type
application/json
{
  • "username": "user1",
  • "reset_code": "46602473",
  • "answer1": "Answer 1",
  • "answer2": "Answer 2",
  • "answer3": "Answer 3",
  • "pwd": "sTnn56Wve79&#%q#K4GF9Z",
  • "mfa_code": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

API Keys

API keys are used to provide an alternative authentication method for users and Point of Sale (POS) systems. This will allow a user to disassociate their username and password from authentication.

API keys are composed of two parts. A public key id and a private key secret. The key secret must be protected.

API keys can also be created specifically for profiles and are intended for use by POS systems that use external user management. A profile API key has functionality only allowing payment transactions. Other operations are restricted.

Profile API keys allow a POS or other system to not be linked to a user for processing transactions. That way if the user is disabled or removed the system will continue to operate.

Whereas a user API key can be created with any permissions already afforded to the user. It is possible to create user API keys with further lower permissions than the user currently has.

A group API key is primarily intended for integrations that need wide ranging automated reporting. For example, a group representing a company may want to have sales reports generated at the end of each day across all sub-groups and profiles. sub-groups could be franchise locations, for example. The group API key will allow the integration to be able to access this data. It would be inadvisable to use a user key in this situation because the key will be invalidated if the user ever leaves the company. Group API keys must be limited to the minimum permissions necessary to accomplish the integration requirements. Often this involves only some action_sys actions.

API keys can be configured for limited duration, after which the specific key will no longer function. There is also an EXTEND_ON_USE flag which can extend the life of the key on use.

Some intended uses for API keys:

iFrame

The iFrame currently uses HMAC authentication to verify the request is being generated by a valid user. A profile API key can be generated and used instead of a username and password for authentication.

POS

A POS system with external user management can be configured to use a profile API key to unlink the system from a specific user. The POS will be able to process transactions without having an "unattended" user that needs a password stored somewhere.

Web Interface and Mobile Apps

One way a web interface or mobile app could operate is by having the user login with their username and password, then request an API key representing the user. The integration would not store the username and password. Instead it would store the API key and further operations would be performed using the API key. An expiration combined with the EXTEND_ON_USE flag is recommended for this scenario.

Remove API Key

Deletes an API Key

libmonetra KVS equivalent for endpoint

  • action_sys = apikeys
  • apikeys = del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
apikey_id
required
string
Example: 96785456789765

API key id

Used in conjunction with apikey_secret

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/apikey/U123' --basic -u 'test_retail:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

API Key Detail

Get API Keys Details

libmonetra KVS equivalent for endpoint

  • action_sys = apikeys
  • apikeys = list
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
apikey_id
required
string
Example: 96785456789765

API key id

Used in conjunction with apikey_secret

query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/apikey/U123' --basic -u 'test_retail:publ1ct3st'

Response samples

Content type
application/json
{
  • "apikey_id": "96785456789765",
  • "type": "user",
  • "group_id": "36789654543",
  • "name": "POS Key 54-5",
  • "user_id": "977564336543",
  • "profile_id": "65433565432",
  • "flags": "EXTEND_ON_USE",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "ALL",
  • "trans_perms": "ALL",
  • "created_uid": "78654356",
  • "created_ts": "2022-05-24 15:06:13 -0400",
  • "last_used_ts": "2022-05-24 15:06:13 -0400",
  • "expire_ts": "2022-05-24 15:06:13 -0400",
  • "extend_sec": "180",
  • "descr": "Unattended POS key. Store 54 POS station 5"
}

List API Keys

List API Keys

The resulting report will contain these headers:

apikey_id, type, group_id, name, user_id, profile_id, flags, su_perms, sys_perms,
admin_perms, trans_perms, created_uid, created_ts, last_used_ts, expire_ts,
extend_sec, descr

libmonetra KVS equivalent for endpoint

  • action_sys = apikeys
  • apikeys = list
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

user_id
string
Example: user_id=67869543676543

User identifier

group_id
string
Example: group_id=36789654543

Group identifier

name
string
Example: name=POS Key 54-5

API Key name

maxdepth
string
Example: maxdepth=4

Maximum depth to display

Default is top level only. Specify 1 to see only self and children.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/apikey' --basic -u 'test_retail:publ1ct3st'

Response samples

Content type
application/json
{
  • "report": "..."
}

Create API Key

Creates an API Key

There are three key types that can be created, user, profile, and group. A user key represents the user. A profile key represents a profile. A group key represents a group.

Allowed:

  • A user can create user keys for themselves.
  • A user can create profile keys for any profile they have access to.
  • A user can create group keys for any group they have access to if they havei the user flag ALLOW_GROUP_APIKEYS.
  • A user key can create profile keys for any profiles they have access to.

Disallowed:

  • A user cannot create user keys for other users.
  • A user key cannot create user keys.
  • A profile key cannot create either user or profile keys.
  • A group key cannot create either user keys.

Up to 100 API keys can be created per user, per profile or per group.

libmonetra KVS equivalent for endpoint

  • action_sys = apikeys
  • apikeys = add
Authorizations:
basic_auth
Request Body schema: application/json
type
required
string
Enum: "user" "profile" "group"

Type of API Key

Values:

  • user - Key represents a user. Uses the current user that is authenticated
  • profile - key represents a profile. Uses the profile_id specified, or if none, the default profile id for the current user.
  • group - key represents a group
name
required
string <= 256 characters

API Key name

descr
string <= 128 characters

Description of the key and its intended use

flags
string
Enum: "EXTEND_ON_USE" "ALLOW_UNLINKED_REFUND"

flags controlling behavior

Values:

  • EXTEND_ON_USE - On use of the key, it's expiration will be extended. Expiration of the key will become now plus the value of expire_sec provided during key creation. Extension is based on expiration lifetime. 30 days, will update once per day. 24 hrs, will update once per hour. 1 hr will update once per minute. Less than 1 hour will update every 10 s.
  • ALLOW_UNLINKED_REFUND - Allow the API key to perform unlinked refunds. Necessary when generating a Profile API Key if a profile key is intended to issue unlinked refunds. The user creating the key is required to have the ALLOW_UNLINKED_REFUND user flag set in order to enable this API key flag.
su_perms
string
Enum: "ALL" "BIGBATCH" "BIGBATCH_MANAGE" "BIGBATCH_SETTLE" "E2EE_KEY_DEACTIVATE" "E2EE_KEY_EDIT" "E2EE_KEY_GENERATE" "E2EE_KEY_LIST" "IMPORTEXPORT" "INFO" "MAINTENANCE" "P2PE_BDK_DEACTIVATE" "P2PE_BDK_EDIT" "P2PE_BDK_EXPORT" "P2PE_BDK_GENERATE" "P2PE_BDK_KCV" "P2PE_BDK_LIST" "P2PE_BDK_PRINT" "P2PE_DEVICE_DEACTIVATE" "P2PE_DEVICE_EDIT" "P2PE_DEVICE_LIST" "P2PE_DEVICE_PROVISION" "PRODUCT_LICENSE" "PUSHNOTIFICATION" "TOKEN_EXPORT"

System restricted access permissions

Pipe (|) separate list of permissions.

ALL keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • BIGBATCH - Big Batch Reporting
  • BIGBATCH_MANAGE - Manage Big Batch accounts
  • BIGBATCH_SETTLE - Settle Big Batch batches
  • E2EE_KEY_DEACTIVATE - Deactivate E2EE keys used for encrypted transport.
  • E2EE_KEY_EDIT - Edit E2EE keys used for encrypted transport.
  • E2EE_KEY_GENERATE - Generate E2EE keys used for encrypted transport. Such a transaction export and import between multiple installations of TranSafe
  • E2EE_KEY_LIST - List E2EE keys used for encrypted transport.
  • IMPORTEXPORT - Allow importing and exporting database data
  • INFO - Monetra information
  • MAINTENANCE - Enable maintains mode to prevent transaction processing. Primarily used in conjunction with IMPORTEXPORT permission
  • P2PE_BDK_DEACTIVATE - Deactivate a P2PE Base Derivation Key
  • P2PE_BDK_EDIT - Edit a P2PE Base Derivation Key
  • P2PE_BDK_EXPORT - Export a P2PE Base Derivation Key for sharing with a Key Injection Facility
  • P2PE_BDK_GENERATE - Generate a Base Derivation Key for P2PE device encryption
  • P2PE_BDK_KCV - P2PE Base Derivation Key Check Value
  • P2PE_BDK_LIST - List P2PE Base Derivation Key
  • P2PE_BDK_PRINT - Print encrypted P2PE Base Derivation Key on a compatible printer. Only applies when keys are managed by an HSM
  • P2PE_DEVICE_DEACTIVATE - Deactivate a P2PE Device
  • P2PE_DEVICE_EDIT - Edit P2PE device
  • P2PE_DEVICE_LIST - List P2PE devices
  • P2PE_DEVICE_PROVISION - Provision a device in TranSafe that uses P2PE. Provisioning is required for Validated P2PE, non validated P2PW TranSafe will auto provision devices on first use
  • PRODUCT_LICENSE - Manage products that have been registered with TranSafe
  • PUSHNOTIFICATION - Manage push notification endpoints
  • TOKEN_EXPORT - Store account export
sys_perms
string
Enum: "ALL" "V8_COMPLEX_EMULATION" "GETPERMS" "GROUP_ADD" "GROUP_EDIT" "GROUP_MOVE" "GROUP_DEL" "GROUP_LIST" "USER_ADD" "USER_EDIT" "USER_MOVE" "USER_DEL" "USER_LIST" "USER_ENABLE" "USER_DISABLE" "USER_PASSWD" "USER_UNLOCK" "PROFILE_ADD" "PROFILE_EDIT" "PROFILE_MOVE" "PROFILE_DEL" "PROFILE_LIST" "PROFILE_STATS" "PROFILE_ENABLE" "PROFILE_DISABLE" "ROUTE_ADD" "ROUTE_EDIT" "ROUTE_DEL" "ROUTE_LIST" "ROUTE_FIELDS" "CRON" "INFO" "SETLOGGING" "REGISTER_CLIENT" "SKYLINK_MANAGE" "APIKEYS" "MFA_GENERATE" "MFA_RESET" "SECURITY_QUESTIONS"

System access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • V8_COMPLEX_EMULATION - Allow TranSafe v8 protocol emulation. Allows equivalent v8 protocol actions to be used
  • GETPERMS - Get user permissions
  • GROUP_ADD - Create a group
  • GROUP_EDIT - Edit a group
  • GROUP_MOVE - Move a group to a different group
  • GROUP_DEL - Delete a group
  • GROUP_LIST - List groups
  • USER_ADD - Create a user
  • USER_EDIT - Edit a user
  • USER_MOVE - Move a user to a different group
  • USER_DEL - Delete a user
  • USER_LIST - List users
  • USER_ENABLE - Enable a user
  • USER_DISABLE - Disable a user
  • USER_PASSWD - Change a user's password. Includes self
  • USER_UNLOCK - Unlock a user
  • PROFILE_ADD - Add a profile
  • PROFILE_EDIT - Edit a profile
  • PROFILE_MOVE - Move a profile to a different group
  • PROFILE_DEL - Delete a profile
  • PROFILE_LIST - List profiles
  • PROFILE_STATS - Profile statistics
  • PROFILE_ENABLE - Enable a profile
  • PROFILE_DISABLE - Disable a profile
  • ROUTE_ADD - Add a route
  • ROUTE_EDIT - Edit a route
  • ROUTE_DEL - Delete a route
  • ROUTE_LIST - List routes
  • ROUTE_FIELDS - Get processor specific fields for use with adding or editing a route
  • CRON - System task scheduler operations
  • INFO - TranSafe information
  • SETLOGGING - Start / Stop an in memory logging buffer
  • REGISTER_CLIENT - Registers use of a product with TranSafe
  • SKYLINK_MANAGE - Manage SkyLink product licences
  • APIKEYS - API key management
  • MFA_GENERATE - Enable or change MFA method
  • MFA_RESET - Reset MFA so it needs to be generated
  • SECURITY_QUESTIONS - User security questions
admin_perms
string
Enum: "ALL" "REPORT_TRAN" "REPORT_TOTALS" "REPORT_CHARTDATA" "REPORT_QUEUE" "BATCH_CLEAR" "BATCH_SET" "BATCH_RESCIND" "BATCH_CLOSE" "TRAN_EDIT" "TRAN_NULLIFY" "TRAN_DETAIL" "TRAN_RECEIPT" "MERCH_INFO" "IMAGE_ADD" "IMAGE_DEL" "IMAGE_GET" "TOKEN_ADD" "TOKEN_EDIT" "TOKEN_DEL" "TOKEN_SCHEDULE" "TOKEN_LIST" "CUSTOMER_ADD" "CUSTOMER_EDIT" "CUSTOMER_DEL" "CUSTOMER_LIST" "TICKETREQUEST" "LEVEL3" "PRODMANAGE" "PRODLIST" "ORDERMANAGE" "ORDERLIST" "ORDERREPORT" "CARDDENYLIST" "P2PE" "STANDINKEY_GENERATE" "REPORT_DEVICE"

Administrative access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • REPORT_TRAN - Transaction and batch detail reports
  • REPORT_TOTALS - Transaction and batch total reports
  • REPORT_CHARTDATA - Card data breakdown for report views
  • REPORT_QUEUE - List queued transactions pending authorization
  • BATCH_CLEAR - Mark batch as settled without funding
  • BATCH_SET - Change batch number
  • BATCH_RESCIND - Unsettle a batch (can double charge customers)
  • BATCH_CLOSE - Close a batch so new transactions are not added but do not settle
  • TRAN_EDIT - Edit a transaction
  • TRAN_NULLIFY - Delete a previously-authorized transaction without any attempt to go online and remove an authorization hold. Similar to a void.
  • TRAN_DETAIL - Transaction details
  • TRAN_RECEIPT - Transaction receipts. Generating and sending receipts, and invoices
  • MERCH_INFO - Profile information
  • IMAGE_ADD - Store an image. Check, signature, etc
  • IMAGE_DEL - Delete an image. Check, signature, etc
  • IMAGE_GET - Get an image. Check, signature, etc
  • TOKEN_ADD - Store an account
  • TOKEN_EDIT - Edit a stored account
  • TOKEN_DEL - Delete a stored account
  • TOKEN_SCHEDULE - Manage recurring and installment payments
  • TOKEN_LIST - List stored accounts
  • CUSTOMER_ADD - Add a customer
  • CUSTOMER_EDIT - Edit a customer
  • CUSTOMER_DEL - Delete a customer
  • CUSTOMER_LIST - List customers
  • TICKETREQUEST - Request temporary cardshieldticket representing a customer's account
  • LEVEL3 - Level 3 line item operations
  • PRODMANAGE - Manage products (sku, amount, etc) in the inventory system
  • PRODLIST - List product details in the inventory system
  • ORDERMANAGE - Manage orders and invoices
  • ORDERLIST - List orders and invoices
  • ORDERREPORT - Reports for orders and invoices
  • CARDDENYLIST - Manage the card deny list
  • P2PE - P2PE device management
  • STANDINKEY_GENERATE - Generate an encryption key used for encrypting account data as part of stand-in authorization
  • REPORT_DEVICE - Device-level transaction journals
trans_perms
string
Enum: "ALL" "VERIFYONLY" "SALE" "PREAUTH" "REVERSAL" "INCREMENTAL" "PREAUTHCOMPLETE" "FORCE" "CAPTURE" "VOID" "ADJUST" "REFUND" "ACTIVATE" "BALANCEINQ" "CASHOUT" "TOREVERSAL" "MERCHRETURN" "ISSUE" "TIP" "EBTFSSALE" "EBTFSRETURN" "EBTFSVOUCHER" "EBTFSBALANCE" "EBTCBSALE" "EBTCBCASH" "EBTCBBALANCE" "CHECKVERIFY" "CHECKCONVONLY" "CHECKCONVVRFY" "CHECKCONVGUAR" "CHECKCONVOVER" "CHECKIMAGEUPLOAD" "SETTLE" "SETTLERFR" "TERMLOAD" "INTERACMAC" "EMVCOMPLETE" "ALTPAYMENTINIT" "CARDTYPE"

Transaction access permissions

Pipe ('|') separate list of permissions.

'ALL' keyword indicates all available permissions.

When adding or editing a user or group, if not specified, defaults to same perms as the parent group. Cannot exceed the perms of the parent group. May exceed permissions of user performing request.

When creating an API Key, must set explicitly requested permissions, no inheritance.

In any add or edit operation, specify as an empty string if no permissions of this classification are desired.

Flag values (pipe separated):

  • ALL - All available permissions
  • VERIFYONLY - Card verification
  • SALE - Purchase
  • PREAUTH - Authorization only (preauth)
  • REVERSAL - Reverse a transaction
  • INCREMENTAL - Incremental
  • PREAUTHCOMPLETE - Complete an authorization only (preauth) transaction
  • FORCE - Force purchase without online authorization
  • CAPTURE - Capture an un-captured transaction
  • VOID - Void a trasnaction
  • ADJUST - Adjust a transaction
  • REFUND - Refund
  • ACTIVATE - Activate a private label gift card
  • BALANCEINQ - Request account balance
  • CASHOUT - Remove all funds from a gift card in order to provide the customer with cash for the value
  • TOREVERSAL - Timeout reversal
  • MERCHRETURN - Merchandise return. Used by gift cards
  • ISSUE - Issue a gift card
  • TIP - Add a tip to a gift card
  • EBTFSSALE - Electronic Benefits Transfer food purchase
  • EBTFSRETURN - Electronic Benefits Transfer food refund
  • EBTFSVOUCHER - Electronic Benefits Transfer food voucher (paper food stamps) purchase
  • EBTFSBALANCE - Electronic Benefits Transfer food balance
  • EBTCBSALE - Electronic Benefits Transfer cash purchase
  • EBTCBCASH - Electronic Benefits Transfer cash withdrawal
  • EBTCBBALANCE - Electronic Benefits Transfer cash balance
  • CHECKVERIFY - Check verification only (without conversion)
  • CHECKCONVONLY - Check conversion only (without verification)
  • CHECKCONVVRFY - Check verification and conversion
  • CHECKCONVGUAR - Check conversation guarantee
  • CHECKCONVOVER - Convert a check with override
  • CHECKIMAGEUPLOAD - Upload check image
  • SETTLE - Settle
  • SETTLERFR - Request Settlement Status (limited processor support)
  • TERMLOAD - Terminal loading data
  • INTERACMAC - Interac MACing parameters
  • EMVCOMPLETE - EMV completion transaction
  • ALTPAYMENTINIT - Init an alternative payment method
  • CARDTYPE - Determine cardtype of presented account
expire_sec
required
string\d+|infinite

How long the API key should be valid.

Can be a numeric whole number of seconds or they key word infinite to indicate the key should never expire. Once a key has expired, it can no longer be used.

Minimum allowed value is 30 indicating the key will only be valid for 30 seconds.

Will be used as the extend time when combined with the extend_on_use flag.

profile_id
string\d+

Profile ID the key should represent instead of the user.

Can only be present when type=profile and is not valid when type=user

Responses

Request samples

Content type
application/json
{
  • "type": "user",
  • "name": "POS Key 54-5",
  • "descr": "Unattended POS key. Store 54 POS station 5",
  • "flags": "EXTEND_ON_USE",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "ALL",
  • "trans_perms": "ALL",
  • "expire_sec": "3600",
  • "profile_id": "78965743785967"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "apikey_id": "96785456789765",
  • "apikey_secret": "..."
}

Boarding Groups

All user, and profiles are contained in a Hierarchical system comprised of Groups. Each group is a level in the hierarchy and groups can be contained within groups. The hierarchical system controls the 'view' that users have access to.

A user at a higher level group can view anything they have permissions for within their and any lower level group.

Profiles, users, and push notifications are all contained within a group.

Groups can have permissions set on the group itself. User's within the group will not be able to perform actions with higher permissions than the group.

Example flow for adding a merchant

  • Create a group for the merchant
  • Create users under the group for the merchant's personnel
  • Create a profile for the merchant's stores
    • Add processing routes to each profile

Users within the group will be able to access and process the profiles within the group they are in. Users can have a default profile set so they do not need to specify a profile with every transaction.

Additionally users can be locked to only allow processing with a specific profile. This allows a clerk to only process transactions for their work location while allowing someone like a floating manager to process at whichever store they happen to be at.

Get Group Detail

Get Group Detail

libmonetra KVS equivalent for endpoint

  • action_sys = group_list
  • json = no
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 36789654543

Group id

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/boarding/group/123' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "id": "36789654543",
  • "name": "ISO - Maverick Systems",
  • "parent_group_id": "67895432456",
  • "flags": "SHARE_TOKENS|REQUIRE_MFA",
  • "create_ts": "2022-05-24 15:06:13 -0400",
  • "upd_ts": "2022-05-24 15:06:13 -0400",
  • "su_perms": "ALL",
  • "sys_perms": "ALL",
  • "admin_perms": "ALL",
  • "trans_perms": "ALL",
  • "pushnotification_id": "56789098765",
  • "custom_customer_fields": "height,weight",
  • "company": "Company LLC.",
  • "gateway_name": "Gateway Product",
  • "contact_email": "email@email",
  • "contact_phone": "555-555-5555",
  • "contact_street": "124 6th Ln",
  • "contact_city": "Jacksonville",
  • "contact_state": "FL",
  • "contact_zip": "32789",
  • "contact_country": "USA",
  • "support_email": "support@email",
  • "support_phone": "555-555-5555",
  • "support_url": "https://url",
  • "website_url": "https://url",
  • "portal_url": "https://url",
  • "tos_url": "https://url",
  • "privacy_url": "https://url",
  • "from_email": "from@email",
  • "notice_email": "notice@email",
  • "order_domain": "https://url",
  • "silent_whitelabel": "yes"
}

List Groups

List groups

The resulting report will contain these headers:

id, name, parent_group_id, group_depth, create_ts, upd_ts, flags, su_perms,
sys_perms, admin_perms, trans_perms, num_tokens, pushnotification_id,
custom_customer_fields, company, contact_name, contact_phone, contact_street,
contact_city, contact_state, contact_zip, contact_country, contact_email,
support_phone, support_url, website_url, support_email, portal_url, tos_url,
privacy_url, from_email, notice_email, order_domain, silent_whitelabel

When using JSON ouput the the groups under the specified group will be placed in a groups array. Each object in the arrary contains the above group headers. If include_users is specified then a users list will be included in the output. The user objects within the array will include the same fields as "Get User Details". If include_profiles is specified then a profiles list will be included in the output. The user objects within the array will include the same fields as "Get Profile Details".

libmonetra KVS equivalent for endpoint

  • action_sys = group_list
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
name
string

Query for specific group name

Cannot be combined with:

  • id
id
string
Example: id=36789654543

Group id

Cannot be combined with:

  • name
json
object
Enum: "yes" "no"
Example: json=yes

Output the data in a hierarchical json format instead of CSV

Values:

  • yes - Output in JSON format instead of CSV
  • no - Do not output in JSON format
flags
object
Enum: "MODIFY_SELF" "SHARE_TOKENS" "PUSH_NOTIFICATION" "ACCOUNT_UPDATER" "WHITELABEL_BRANDING" "REQUIRE_MFA"
Example: flags=SHARE_TOKENS|REQUIRE_MFA

Flag values (pipe separated):

  • MODIFY_SELF - Users can modify the group they are part of
  • SHARE_TOKENS - Share tokenized cards across all profiles under this group
  • PUSH_NOTIFICATION - Send push notifications for transactions under this group. Requires pushnotification_id to be set.
  • ACCOUNT_UPDATER - Automatically update stored accounts when the card number changes (requires SHARE_TOKENS). Uses an external card updater service. Not all card issuers participate and submit card account updates to the program
  • WHITELABEL_BRANDING - The group is white label branding the service and branding should reflect this
  • REQUIRE_MFA - Multi Factor Authentication is required for all user accounts
empty_groups
object
Enum: "yes" "no"
Example: empty_groups=no

Used to locate 'dangling' groups with no subgroups and no profiles. It will, however, return groups that may contain users, but since these users couldn't access anything at all, this is expected as it is likely stale.

Values:

  • yes - Output empty groups
  • no - Do not output empty groups
ancestor_of
string
Example: ancestor_of=56789654367

Group ID to list ancestors of (including specified group id)

maxdepth
string
Example: maxdepth=4

Maximum depth to display

Default is unlimited. Specify 1 to see only self and children.

include_users
object
Enum: "yes" "no"
Example: include_users=yes

Include users in output. Can only be specified with JSON output.

Values:

  • yes - Include users in output
  • no - Do not include users in output
include_profiles
object
Enum: "yes" "no"
Example: include_profiles=yes

Include profiles in output. Can only be specified with JSON output.

Values:

  • yes - Include profiles in output
  • no - Do not include profiles in output
include_token_stats
object
Enum: "yes" "no"
Example: include_token_stats=yes

Include tokekn statistics in output

Values:

  • yes - Include token statistics in output
  • no - Do not include tokekn statistics in output
merge_recommendations
object
Enum: "yes" "no"
Example: merge_recommendations=no

List recommended groups for merging into other groups

Find groups that have exactly 1 sub group, no propagatable flags (PUSH_NOTIFICATION, SHARE_TOKENS, WHITELABEL_BRANDING), no merchant profiles, and no users. Its parent must not be the top level as this is likely intentional organization. Any groups in this list may serve no purpose and should be merged into its parent.

So taking a hierarchy like:

TOPLEVEL
|
|--PARTNER
   |-- ISO
      |-- MERCHANT 1
      |  |-- SUBGROUP1A
      |  |  |-- SUBSUBGROUP1A1
      |  |     |-- PROFILE(123)
      |  |     |-- USER(someone)
      |  |-- SUBGROUP1B
      |     |-- USER(someoneelse)
      |     |-- SUBSUBGROUP1B1
      |        |-- PROFILE(345)
      |-- MERCHANT 2
         |-- SUBGROUP2A (flags=PUSH_NOTIFICATION)
         |  |-- SUBSUBGROUP2A1
         |     |-- PROFILE(678)
         |     |-- USER(someone)
         |-- SUBGROUP2B
            |-- USER(someoneelse)
            |-- SUBSUBGROUP2B1
               |-- PROFILE(901)

SUBGROUP1A would be the only group in the list recommended as it only contains 1 subgroup, no profiles, no users, and no propagatable flags. "PARTNER" would not be listed as its parent is "TOPLEVEL" even though it meets the other conditions.

Values:

  • yes - Produce recommendation list
  • no - Do not produce recommendation list. Default behavior.
search
string

Will perform a substring search across multiple fields

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/boarding/group' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "report": "..."
}

Merge Groups

Merge the source group into the specified group. Can only merge into a parent or sibling.

libmonetra KVS equivalent for endpoint

  • action_sys = group_merge
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 36789654543

Group id

source_group_id
required
string
Example: 67895432456

Source group to merge groups, users, and profiles from.

Responses

Request samples 

curl -X PATCH 'https://test.transafe.com/api/v2/boarding/group/123/merge/456' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=' -d ''

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Profiles

Profiles define a "merchant", the terminal configuration, and processing options. The "merchant" is often defined as a store. Since there are store specific information, such as address, that can be defined for operations like receipt printing.

A profile will contain routes which define transaction routing for authorization and settlement. For example, a profile may have different routes (processors) for credit, gift and ACH.

Get Profile Card Configuration

Gets the profile's card configuration

The resulting report will contain these headers:

cardtype, auth_proc, settle_proc, auth_merchid, settle_merchid, auth_route_id,
settle_route_id, indcode, trantypes, emv, mac_required, gift_binrange,
can_standin, auth_procfeatures, settle_procfeatures

libmonetra KVS equivalent for endpoint

  • action_admin = merch_info
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/boarding/profile/configuration/card' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Get Profile Details

Profile details

libmonetra KVS equivalent for endpoint

  • action_sys = profile_list
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 78965743785967

Merchant profile identifier

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/boarding/profile/974893' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "id": "78965743785967",
  • "profile_name": "Pizza Palace",
  • "name": "Pizza Palace",
  • "group_id": "36789654543",
  • "group_depth": "99",
  • "flags": "SHARE_TOKENS|REQUIRE_MFA",
  • "status": "ACTIVE",
  • "indcode": "R",
  • "create_ts": "2022-05-24 15:06:13 -0400",
  • "upd_ts": "2022-05-24 15:06:13 -0400",
  • "notify_email": "email@email",
  • "custom_trans_fields": "alpha,omega",
  • "req_trans_fields": "ordernum",
  • "custom_order_fields": "special_instructions",
  • "req_order_fields": "ordernum",
  • "vanity_url_prefix": "pizza_palace",
  • "tokengroup_id": "654356543",
  • "tokengroup_name": "Pizza Palace Vault",
  • "pushnotification_id": "56789098765",
  • "whitelabelgroup_id": "647435678765",
  • "fraudautodeny": "DENY_NOAUTO",
  • "emv_termcaps": "NOSIG|ONLINEPIN|PINBYPASSCREDIT|PINBYPASSUSDEBIT",
  • "emv_testmode": "no",
  • "emv_contact_nocvm_limit": "100.00",
  • "emv_ctls_nocvm_limit": "9999.99",
  • "countrycode": "840",
  • "currencycode": "840",
  • "descr": "BB Books store 4",
  • "addr1": "152 Main St",
  • "addr2": "Jacksonville FL",
  • "addr3": "32034",
  • "phone": "555-555-5555",
  • "email": "email@email",
  • "external_id": "string",
  • "url": "https://url",
  • "tz": "America/New_York",
  • "lang": "EN",
  • "cashback": "5|10|20",
  • "cashbackmax": "50.00",
  • "cashback_purchmin": "25.00",
  • "tippercent": "15|20|25|O",
  • "msr_nosig_limit": "200.00",
  • "enc_provider": "bluefin",
  • "l3_commoditycode": "R676D2452X",
  • "l3_description": "Fork",
  • "l3_productcode": "GHF7653",
  • "tax_rate_autopop": "NT"
}

Get Profile Terminal Configuration

Gets the profile's terminal configuration

libmonetra KVS equivalent for endpoint

  • action_admin = merch_info
  • merch_info = termparams
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

fetch_logo
object
Enum: "yes" "no"
Example: fetch_logo=yes

Values:

  • yes - Retrieve merchant logo image
  • no - Do not retrieve merchant logo image

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/boarding/profile/configuration/terminal' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "name": "Pizza Palace",
  • "addr1": "152 Main St",
  • "addr2": "Jacksonville FL",
  • "addr3": "32034",
  • "phone": "555-555-5555",
  • "email": "email@email",
  • "url": "https://url",
  • "countrycode": "840",
  • "currencycode": "840",
  • "indcode": "R",
  • "lang": "EN",
  • "cashback": "5|10|20",
  • "cashback_purchmin": "25.00",
  • "cashbackmax": "50.00",
  • "tippercent": "15|20|25|O",
  • "l3_description": "Fork",
  • "l3_commoditycode": "R676D2452X",
  • "l3_productcode": "GHF7653",
  • "tax_rate": "1.14",
  • "custom_fields": "alpha,omega",
  • "req_fields": "ordernum,zip",
  • "flags": "EMVSUPRESSSIG|EMVPIN_STANDIN_ALLOWED|EMVODA_NONE_STANDIN_ALLOWED|DEBIT_STANDIN_ALLOWED|RECURRING_SKIPMISSED|ALLOW_INVOICE_SMS|ALLOW_INVOICING",
  • "logo": "...",
  • "logo_type": "PNG"
}

List Profile Merchant IDs

List profile Merchant IDs

The resulting report will contain these headers:

id, profile_name, route_id, proc, mode, cardtypes, merchid, termid, divnum, authuser

libmonetra KVS equivalent for endpoint

  • action_sys = profile_list_mids
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
id
string
profile_name
string
Example: profile_name=Pizza Palace

Name for profile

Internal name within the system

Not required to be unique

group_id
string
Example: group_id=36789654543

Group identifier

maxdepth
string
Example: maxdepth=4

Maximum depth to display

Default is unlimited. Specify 1 to see only self and children.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/boarding/profile_mids' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "report": "..."
}

List Profiles

List profiles

The resulting report will contain these headers:

id, profile_name, group_id, group_depth, flags, status, indcode, create_ts,
upd_ts, notify_email, custom_trans_fields, req_trans_fields, vanity_url_prefix,
tokengroup_id, pushnotification_id, whitelabelgroup_id, fraudautodeny,
emv_termcaps, emv_testmode, emv_contact_nocvm_limit, emv_ctls_nocvm_limit,
countrycode, currencycode, name, descr, addr1, addr2, addr3, phone, email, url,
tz, lang, cashback, cashbackmax, cashback_purchmin, tippercent,
msr_nosig_limit, enc_provider, l3_commoditycode, l3_description, l3_productcode,
3ds_provider, 3ds_provider_merchid

libmonetra KVS equivalent for endpoint

  • action_sys = profile_list
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
group_id
string
Example: group_id=36789654543

Group identifier

profile_name
string
Example: profile_name=Pizza Palace

Name for profile

Internal name within the system

Not required to be unique

flags
object
Enum: "ENCRYPTEDONLY" "EMVSUPRESSSIG" "EMVPIN_STANDIN_ALLOWED" "EMVODA_NONE_STANDIN_ALLOWED" "DEBIT_STANDIN_ALLOWED" "PREPOP_LEVEL3" "PREPOP_TAX" "ACCOUNT_UPDATER" "RECEIVE_RECEIPTS_DETAIL" "RECEIVE_RECEIPTS_RECURRING" "RECEIVE_RECEIPTS_INVOICE" "RECEIVE_RECEIPTS_HOSTEDPAGE" "RECURRING_SKIPMISSED" "ORDERS_REQ_LEVEL3" "RATEQUAL_NONTAX" "ALLOW_INVOICE_SMS" "ALLOW_INVOICING" "DISABLE_MSR_ENTRY" "CARDDENYLIST_CHECK" "CARDDENYLIST_DECLINE" "SETTLE_EMAIL_DETAILS" "AUTO_PINLESS_DEBIT" "3DS_DISABLE_CHALLENGES" "3DS_AUTO_DECLINE" "VERIFY_ACH"
Example: flags=EMVSUPRESSSIG|EMVPIN_STANDIN_ALLOWED|EMVODA_NONE_STANDIN_ALLOWED|DEBIT_STANDIN_ALLOWED|RECURRING_SKIPMISSED|ALLOW_INVOICE_SMS|ALLOW_INVOICING

Merchant flags

Flags can be combined into a pipe ('|') separate list.

Flag values (pipe separated):

  • ENCRYPTEDONLY - Account data will only be accepted if it is encrypted. Clear account data will be rejected.
  • EMVSUPRESSSIG - Inform a payment device never prompt for signature for EMV transactions
  • EMVPIN_STANDIN_ALLOWED - Allow stand-in authorizations for EMV when online PIN is entered
  • EMVODA_NONE_STANDIN_ALLOWED - Allow stand-in authorizations for EMV when ODA not performed
  • DEBIT_STANDIN_ALLOWED - Allow stand-in authorizations for debit cards
  • PREPOP_LEVEL3 - Automatically populate Level 3 transaction data (if configured) at settlement for transactions that are Level 3 capable but do not have Level 3 line items
  • PREPOP_TAX - Automatically populate tax information (if configured) at settlement for transactions
  • ACCOUNT_UPDATER - Automatically update stored accounts when the card number changes. Uses an external card updater service. Not all card issuers participate and submit card account updates to the program.
  • RECEIVE_RECEIPTS_DETAIL - Merchant should receive merchant receipt copies by email for receipt actions. Sent to notify_email. The following conditions must be met receive receipt emails. + This flag must be enabled. + The merchant profile must have a name configured. + The profile must have a public reply email configured. + The profile must have notify_email configured.
  • RECEIVE_RECEIPTS_RECURRING - Merchant should receive merchant receipt copies by email for recurring transactions. Sent to notify_email. The following conditions must be met receive receipt emails. + This flag must be enabled. + The merchant profile must have a name configured. + The profile must have a public reply email configured. + The profile must have notify_email configured.
  • RECEIVE_RECEIPTS_INVOICE - Merchant should receive merchant receipt copies by email for paid invoices (NOT ORDER/QUICK). Sent to notify_email. The following conditions must be met receive receipt emails. + This flag must be enabled. + The merchant profile must have a name configured. + The profile must have a public reply email configured. + The profile must have notify_email configured.
  • RECEIVE_RECEIPTS_HOSTEDPAGE - Merchant should receive merchant receipt copies by email for approved payments made through the hosted payment page. Sent to notify_email. The following conditions must be met receive receipt emails. + This flag must be enabled. + The merchant profile must have a name configured. + The profile must have a public reply email configured. + The profile must have notify_email configured.
  • RECURRING_SKIPMISSED - Skip missed recurring payments when enabling previously disabled payment. If this is not set all payments between the last payment and now will be attempted.
  • ORDERS_REQ_LEVEL3 - Requires level3 data on orders. Only supported on Retail, Moto, and Ecomm.
  • RATEQUAL_NONTAX - Force Best Rate Qualification for Non Taxable transactions
  • ALLOW_INVOICE_SMS - Merchant is allowed to send SMS message for invoices. This is not automatic, it allows SMS to be used.
  • ALLOW_INVOICING - Merchant is allowed to create invoices and products
  • DISABLE_MSR_ENTRY - Don't accept MSR (swipe) entry
  • CARDDENYLIST_CHECK - Check card deny list before online auth before attempting the transaction
  • CARDDENYLIST_DECLINE - Add to card decline list on issuer decline
  • SETTLE_EMAIL_DETAILS - Include report with transaction details for each settled batch with automatic settlement emails
  • AUTO_PINLESS_DEBIT - Automatically mark debit transactions as PIN less for CNP if determined to be debit and can route over a pinless network. Pinless debit is only allowed for a specific set of MCC codes. Check with the merchant processor to determine if this can be enabled. Otherwise the merchant could be fined for using pinless debit when not allowed for their MCC.
  • 3DS_DISABLE_CHALLENGES - Disable 3DS challenges with external 3DS provider
  • 3DS_AUTO_DECLINE - Automatically decline any sale, preauth, or verifyonly transaction without 3DS data. This applies regardless of an external 3DS provider being specified.
  • VERIFY_ACH - Verify ACH details. Any ACH transaction not explicitly permitted by the ACH verification provider will be declined, including if it is inaccessible or unable to provide a decision.
status
object
Enum: "ACTIVE" "DISABLED"
Example: status=ACTIVE

Status of the profile

Values:

  • ACTIVE - Profile is active and can process
  • DISABLED - Profile is disabled and cannot process
maxdepth
string
Example: maxdepth=4

Maximum depth to display

Default is unlimited. Specify 1 to see only self and children.

search
string

Will perform a substring search across multiple fields

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/boarding/profile' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a=''

Response samples

Content type
application/json
{
  • "report": "..."
}

Deactivate SkyLink Device

Deactivates a SkyLink device

When deactivated the license seat used by that device will be immediately available for use by another installation.

libmonetra KVS equivalent for endpoint

  • action_sys = skylink_manage
  • skylink_manage = deactivate
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
device_id
required
string
Example: 65432456

ID of registered SkyLink device

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/system/licensing/skylink/12543' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get SkyLink Device List

Gets a list devices registered for SkyLink

The resulting report will contain these headers:

device_id, active, deactivated_ts, last_used_user, last_used_ts, version, name,
manuf, model, os, osver, deactivation_cnt

libmonetra KVS equivalent for endpoint

  • action_sys = skylink_manage
  • skylink_manage = list
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
show_deactivated
object
Enum: "yes" "no"
Example: show_deactivated=yes

Show deactivated devices

Values:

  • yes - Include deactived devices
  • no - Do not include deactived devices

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/system/licensing/skylink' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Get SkyLink Limit

Get the current number SkyLink instances used with a profile

libmonetra KVS equivalent for endpoint

  • action_sys = skylink_manage
  • skylink_manage = getlimit
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/system/licensing/skylink/limit' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "limit": "45"
}

Set SkyLink Limit

Set the maximum number of SkyLink instances that can be used with a profile

libmonetra KVS equivalent for endpoint

  • action_sys = skylink_manage
  • skylink_manage = setlimit
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

limit
required
string\d+

Maximum number of SkyLink devices

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "limit": "45"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Get SkyLink Max Limit During Time Period

Gets the highest limit set across a period of time

Will show results for all profiles visible to the caller

The resulting report will contain these headers:

profile_id, limit

libmonetra KVS equivalent for endpoint

  • action_sys = skylink_manage
  • skylink_manage = limitmax
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/system/licensing/skylink/limit/max' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Get SkyLink Set Limit History

Get history of limit changes for SkyLink

Applies to a single profile.

The resulting report will contain these headers:

ts, is_current, limit, request_user

libmonetra KVS equivalent for endpoint

  • action_sys = skylink_manage
  • skylink_manage = limithistory
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

show_deactivated
object
Enum: "yes" "no"
Example: show_deactivated=yes

Show deactivated devices

Values:

  • yes - Include deactived devices
  • no - Do not include deactived devices

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/system/licensing/skylink/limit/history' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

System Scheduler

System scheduler operations

Create Automated Settlement

Automatic batch settlement

Settle batches in the open or closed state automatically.

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = add
  • type = settle
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "sched": "07:40|*"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "56543565"
}

Create Device Journal Purge

Clear entries from the device journal

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = add
  • type = devicejournalpurge
Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "07:40|*",
  • "keep_days": "90"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "56543565"
}

Delete a Scheduled Task

Delete a scheduled task

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = del
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

ID of scheduled task

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/system/schedule/567865678' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Edit Automated Settlement

Edit a settlement scheduled task

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

ID of scheduled task

Request Body schema: application/json
profile_id
string\d+

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*

Responses

Request samples

Content type
application/json
{
  • "profile_id": "78965743785967",
  • "sched": "07:40|*"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Edit Device Journal Purge

Edit a purge of device journal entries task

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = edit
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

ID of scheduled task

Request Body schema: application/json
sched
string\d{4}\|((sun|mon|tue|wed|thu|fri|sat|;\*)+|(\...

When a scheduled task should run

Format of schedule is HHMM|(days, *, day of month) where:

  • days = sun;mon;tue;wed;thu;fri;sat semi-colon separated list
  • * = everyday
  • day of month = singular numeric day of month (1-31)

Examples:

  • 1233|mon;wed;fri
  • 0001|15
  • 22:55|sun
  • 07:40|*
keep_days
string\d+

Number of days to keep

Responses

Request samples

Content type
application/json
{
  • "sched": "07:40|*",
  • "keep_days": "90"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

List Scheduled Tasks

List scheduled tasks

The resulting report will contain these headers:

id, type, profile_id, sched, last_ts, next_ts, keep_days

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = list
Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=78965743785967

Merchant profile identifier

User's may have access to run transactions across multiple profiles. This allows the user to specify which profile a given action should apply to.

If not provided the default profile associated with the user will be used. If a default profile is not associated with the user this parameter is mandatory.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/system/schedule' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Run an Automated Task

Runs an automated task immediately

libmonetra KVS equivalent for endpoint

  • action_sys = cron
  • cron = run_task
Authorizations:
basic_auth(apikey_idapikey)
path Parameters
id
required
string
Example: 56543565

ID of scheduled task

Responses

Request samples 

curl -X PATCH 'https://test.transafe.com/api/v2/system/schedule/567865678/run' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved"
}

Velocity Rules

Velocity rules are user-configurable fraud prevention checks. A velocity rule specifies a transaction volume metric, a period over which to analyze the metric, and a threshold at which to trigger.

By default, triggered rules block related transactions from being performed, though they can be configured to only send alerts.

Rules are hierarchical: group rules apply to all profiles under that group, and intermediate groups or individual profiles can override rules for the needs of subgroups or merchants.

Delete Velocity Rule

Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=1234

profile_id the rule applies to. If present, group_id takes precedence.

group_id
string
Example: group_id=1234

group_id the rule applies to. Takes precedence over any profile_id passed.

id
required
string
Example: id=765432198

ID assigned to the velocity rule.

Responses

Request samples 

curl -X DELETE 'https://test.transafe.com/api/v2/velocity?profile_id=...&id=...' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

List Velocity Rules

Authorizations:
basic_auth(apikey_idapikey)
query Parameters
profile_id
string
Example: profile_id=1234

profile_id the rule applies to. If present, group_id takes precedence.

group_id
string
Example: group_id=1234

group_id the rule applies to. Takes precedence over any profile_id passed.

Responses

Request samples 

curl -X GET 'https://test.transafe.com/api/v2/velocity?profile_id=...' --header 'X-API-KEY-ID: X123' --header 'X-API-KEY: b64a='

Response samples

Content type
application/json
{
  • "report": "..."
}

Edit a Velocity Rule

Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string

profile_id the rule applies to. If present, group_id takes precedence.

group_id
string

group_id the rule applies to. Takes precedence over any profile_id passed.

id
required
string

ID assigned to the velocity rule.

name
string

Arbitrary name for the rule, up to 40 bytes. Will be displayed to others above and below in the group hierarchy in notification emails.

threshold
string

Threshold at which the rule triggers. 0 = disabled.

alert_only
string
Default: "no"
Enum: "no" "yes"

Only send alerts; do not block transactions from proceeding.

Values:

  • no - Block relevant transactions until the rule is no longer triggered, and send alerts on rule trigger.
  • yes - Do not block relevant transactions; only send alerts.
restrict_override
string
Default: "no"
Enum: "no" "yes"

Restrict further rules from decreasing the trigger threshold.

Values:

  • no - Overriding rules are not restricted, and can reduce the trigger threshold.
  • yes - Overriding rules cannot reduce the trigger threshold.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "1234",
  • "group_id": "1234",
  • "id": "765432198",
  • "name": "Amex Amount Limit",
  • "threshold": "100",
  • "alert_only": "yes",
  • "restrict_override": "no"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "765432198"
}

Add a Velocity Rule

Authorizations:
basic_auth(apikey_idapikey)
Request Body schema: application/json
profile_id
string

profile_id the rule applies to. If present, group_id takes precedence.

group_id
string

group_id the rule applies to. Takes precedence over any profile_id passed.

override_of
string

ID of a parent group's rule that this rule overrides.

name
required
string

Arbitrary name for the rule, up to 40 bytes. Will be displayed to others above and below in the group hierarchy in notification emails.

metrics
required
string
Enum: "VISA" "MC" "AMEX" "DISC" "JCB" "CUP" "DEBIT" "EBT" "GIFT" "ACH" "CHECK" "DECLINE" "UNLINKED_REFUND" "TRANSACTION_AMOUNT"

Card types or other metrics the rule applies to.

Values:

  • VISA - Visa credit transactions
  • MC - Mastercard credit transactions
  • AMEX - American Express credit transactions
  • DISC - Discover credit transactions
  • JCB - JCB credit transactions
  • CUP - CUP credit transactions
  • DEBIT - Debit transactions, both branded (VISADEBIT, MCDEBIT, ...) and unbranded (OTHERDEBIT)
  • EBT - EBT transactions, both cash and food
  • GIFT - Gift card transactions
  • ACH - ACH transactions
  • CHECK - Check transactions
  • DECLINE - Declined transactions
  • UNLINKED_REFUND - Unlinked refunds
  • TRANSACTION_AMOUNT - Individual transaction amount
metric_unit
required
string
Enum: "COUNT" "SALE_AMOUNT" "REFUND_AMOUNT"

Unit of measurement for the specified metric.

Values:

  • COUNT - Number of transactions; for card types, this counts authorized transactions
  • SALE_AMOUNT - Aggregate authorized sale amount
  • REFUND_AMOUNT - Aggregate authorized refund amount
period
required
string

Period over which to measure.

period_unit
required
string
Enum: "TRANSACTION" "MINUTES" "HOURS" "DAYS"

Unit of measurement for the specified period.

Values:

  • TRANSACTION - Each individual transaction. period must be 1.
  • MINUTES - Period measured in minutes, 15-90.
  • HOURS - Period measured in hours, 1-23.
  • DAYS - Period measured in days, 1-31.
threshold
required
string

Threshold at which the rule triggers. 0 = disabled.

alert_only
string
Default: "no"
Enum: "no" "yes"

Only send alerts; do not block transactions from proceeding.

Values:

  • no - Block relevant transactions until the rule is no longer triggered, and send alerts on rule trigger.
  • yes - Do not block relevant transactions; only send alerts.
restrict_override
string
Default: "no"
Enum: "no" "yes"

Restrict further rules from decreasing the trigger threshold.

Values:

  • no - Overriding rules are not restricted, and can reduce the trigger threshold.
  • yes - Overriding rules cannot reduce the trigger threshold.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "1234",
  • "group_id": "1234",
  • "override_of": "987654321",
  • "name": "Amex Amount Limit",
  • "metrics": "VISA|MC|AMEX|DISC",
  • "metric_unit": "COUNT",
  • "period": "1",
  • "period_unit": "HOURS",
  • "threshold": "100",
  • "alert_only": "yes",
  • "restrict_override": "no"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "msoft_code": "INT_SUCCESS",
  • "verbiage": "Transaction approved",
  • "id": "765432198"
}