Calling the API
The API is documented by Swagger (OpenAPI):
When calling our API, you can request either individual entities or entity collections, as the following Payments URLs illustrate:
/paymentsretrieves a collection of payments that is optionally filtered
/payments?Id=Lbv41UqRo9EBRlgBDBzBNoretrieves 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:
|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.
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.
- 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.
Pick any of the following supported content types for
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.
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-IDin order to uniquely identify API calls for your own purposes
- Payment Request ID (required for payment requests) - include a field called
InstructionIdto 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
Expect to receive and handle our subset of standard HTTP status codes.
Common HTTP Response Codes
Applicable to most Transactive endpoints:
|400||Invalid - most likely an input validation problem - fix and retry|
|401||Unauthenticated - a missing or expired API key|
|429||Too many requests|
|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.
|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|
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.
A payment cannot be completed. Most likely this will need to be resolved by our customer service staff.
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.
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:
For example, to find all Payments created after July 29, 2016:
Resources that are unavailable due to permissions are omitted from queries.