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

Python

import urllib.request

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

password_mgr = urllib.request.HTTPPasswordMgrWithDefaultRealm()
password_mgr.add_password(None, HOST, USER, PASS)
auth_handler = urllib.request.HTTPBasicAuthHandler(password_mgr)
opener = urllib.request.build_opener(auth_handler)
urllib.request.install_opener(opener)

o = urllib.request.urlopen(URL)
print(o.read())

C#

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

class AuthExample
{
    static void Main(string[] args)
    {
        var host = "https://test.transafe.com";
        var url = "https://test.transafe.com/api/v1/report/failed";
        var username = "test_retail|public";
        var password = "publ1ct3st";

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

        var cred = new NetworkCredential(username, password);
        var ccache = new CredentialCache();
        ccache.Add(new Uri(host), "Basic", cred);

        var request = WebRequest.Create(url);
        request.Credentials = ccache;

        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/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