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