Calling the API

API Reference

The API is documented by Swagger (OpenAPI):

Making Requests

When calling our API, you can request either individual entities or entity collections, as the following Payments URLs illustrate:

  • /payments retrieves a collection of payments that is optionally filtered
  • /payments?Id=Lbv41UqRo9EBRlgBDBzBNo retrieves a specific payment resource

All Transactive resources are identified by unique, base62-encoded strings.

Use an appropriate web client to call the Transactive API endpoints that your business requires. Some commonly used clients include:

It is not necessary to call our entire API. We suggest calling only those endpoints required to perform and monitor your payment processes.

Available Actions (HTTP Methods)

Use the following subset of standard HTTP methods to access Transactive resources:

Method Endpoint Description
GET /endpoint returns a collection of individual resources, subject to any constraints supplied in the query string
GET /endpoint?Id= returns a single resource, if it exists
POST /endpoint creates a resource, though for certain RPC style endpoints this may return an arbitrary response
PUT /endpoint?Id= updates some properties of a specific resource, e.g. a Contact's family name
DELETE /endpoint?Id= deletes a specified resource

Transactive's API is accessible via HTTPS only; connections via unsecured HTTP are rejected.

Authenticating

Associate all requests with an API Key, supplied by way of an Authorization HTTP request header as shown in the example Postman screenshot below:

Each application has two API keys available at any one time. You have complete control over your own API keys.

Void and rotate your API keys as you see fit using the web portal.

Authorizing

Grant each API key its required level of access by setting up its Authorities, using either the Contacts endpoint or the web portal. The following authorities are available:

  • Reporting - permission to receive information about payments
  • Payment - permission to send payments
  • Admin - permission to modify certain aspects of your contract. Some aspects, such as pricing, are only modifiable by Transactive support

An API key can have any combination of the above, and the resulting capability is the sum of the capabilities of the individual authorities.

Content Types

Pick any of the following supported content types for POST and PUT requests:

  • application/x-www-form-urlencoded
  • application/json
  • application/jwt

Tracking Requests

Supply request IDs in order to track your calls and, in the case of payment requests, to ensure their idempotency.

There are two different types of request IDs, one supplied by you and one automatically supplied by the API.

  • Request ID (optional) - include a custom header called X-Request-ID in order to uniquely identify API calls for your own purposes
  • X-Correlation-ID - every request is automatically associated with a correlation ID which is subsequently included as a customer response header called X-Correlation-ID

All request IDs supplied by you should be unique, e.g. GUID or UUID.

Handling Responses

Expect to receive and handle our subset of standard HTTP status codes.

Common HTTP Response Codes

Applicable to most Transactive endpoints:

Code Definition
200 Successful
400 Invalid - most likely an input validation problem - fix and retry
401 Unauthenticated - a missing or expired API key
403 Unauthorized
404 Not found
429 Too many requests
500 Failed, retry
501 Not supported
5xx Because our endpoints are protected by CloudFlare, certain responses may come from their edge servers, a full list is available here.

All responses use application/json, regardless of the request type.

Error Details

Certain error responses, such as 400 Bad Request, can contain more information in their body as an error response JSON object:

  • Reason - the concise description of the error condition
  • Details - a detailed description of the error condition
  • Errors - an optional list of error messages
  • RequestBody - the original request body
  • Path (optional) - further information about invalid parameters

Filtering Response Collections

Use HTTP query params to filter collections of resources returned by GETrequests. Prepend each entity field value (not key) with one of the following comparison operators:

Comparison Operations

Operator Description Example
eq Equal city=eq_Redmond
ne Not equal city=ne_London
gt Greater than price=gt_20
lt Less than price=lt_20

For example, to find all Payments created after July 29, 2016:

Resources that are unavailable due to permissions are omitted from queries.