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

Retrying

Feel free to resubmit requests. Transactive is designed to ignore duplicate requests.

With regard to submitting payments, we ensure idempotency by requiring unique payment IDs. Payments may be retried as long as the ID and body of the payment stay the same.

If no response is received, repeat your call. No harm can come from doing so.

Tracking Requests

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

There are three different types of request IDs. Two are supplied by you, one is automatically supplied by the API.

User-Supplied Request IDs

  • Request ID (optional) - include a custom header called X-Request-ID in order to uniquely identify API calls for your own purposes
  • Payment Request ID (required for payment requests) - include a field called InstructionId to uniquely identify payment submissions, regardless of the number of retries

API Supplied Request IDs

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

Payment Specific HTTP Response Codes

When submitting payments to external banking systems, you may encounter a few additional response codes.

Code Definition
201 Payment created but in a rejected state - no recourse
202 Payment accepted but processing incomplete - no recourse except to contact Transactive
409 Payment exists but its body is changed - retry with new request ID or with identical details

201

A payment has been permanently rejected. This is most likely because of an issue originating within one of our clearing systems. For example, a target bank might reject a perfectly good payment request because a target account has recently been closed.

202

A payment cannot be completed. Most likely this will need to be resolved by our customer service staff.

409

The details of a payment retry have been changed. This is not allowed. A retry must be effectively the same as the original payment.

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.