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

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.

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

• formatted time
• Unix timestamp

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

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.

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.

Only HTTP Basic authentication is currently supported.

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

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

E.g.

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

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

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

Colon escaping

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

If a username contains a pipe, please contact support.

user:sub -> user|sub

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

Programming language examples

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

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

Python

import urllib.request

URL = 'https://test.transafe.com/api/v1/report/failed'
USER = 'test_retail|public'
PASS = 'publ1ct3st'

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

req = urllib.request.Request(URL, headers=headers)
with urllib.request.urlopen(req) as o:
    print(o.read().decode('utf-8'))

C#

using System;
using System.IO;
using System.Net;
using System.Text;

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

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

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

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

            using (var dataStream = response.GetResponseStream()) {
                using (var reader = new StreamReader(dataStream)) {
                    Console.WriteLine(reader.ReadToEnd());
                }
            }
        }
    }
}

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

PHP

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

Transaction operations