API Requests & Responses

The SmarterPay Cloud API is based on a REST service using JSON-formatted requests and responses.
The SmarterPay Cloud API is only available over HTTPS. Attempting to access the API over an unsecured HTTP connection will return a TLS_Required error.

To start using the SmarterPay Cloud API, you will require API credentials, which can be found within the SmarterPay Cloud Portal or from your SmarterPay representative.
The API credentials are consumed, in each REST call, by providing it as a Bearer token in the Authorization header.

The “Content-Type” header must also be provided when sending data to the API, using POST and PUT methods, passing either the standard JSON MIME type (application/json), or the JSON-API variant (application/vnd.api+json).

All requests and responses are UTF-8 encoded.

Providing the “Accept-Charset” header is optional, but recommended.

Authorization: Bearer <token>
Content-Type: application/json
Accept-Charset: utf-8
Idempotency-Key: 8abec541-efca-4efa-856b-50ab8679ec0f

The SmarterPay Cloud API can use idempotency to help prevent accidentally performing the same operation twice.
Idempotency can be used on creating a new record (“POST” method) or updating an existing record (“PUT” method).

To use SmarterPay Clouds API's idempotency, add the “Idempotency-Key: <key>” field to the header of the API request.
Idempotency keys can be up to 255 characters long, and are case sensitive, for example “ABC123” is not the same as “abc123”.
It is recommended to use a UUID/GUID for the idempotency key.

On recieving an API request, with an idempotency key header, SmarterPay Cloud API stores the details of the request, including the endpoint, idempotency key, and payload.
These details will be automatically removed from the system after they're at least 24 hours old.

While the idempotency key details are stored:

• Any API request, with the same idempotency key, recieved during the processing of the initial request, will be returned with a “409 Conflict” response code and a “A request with the same Idempotency-Key for the same operation is being processed or is outstanding” message.
• Any API request, with the same idempotency key, but different details, for example different endpoint or payload, will be returned with a “422 Unprocessable Entity” response code and a “Idempotency keys cannot be reused” message.
• Any API request, with the same idempotency key, and exactly the same request details as the initial request, will be returned with the same response, and response code, as the initial request, with the addition of an “idempotency-replay: true” field in the response header.

After the idempotency key details are removed from the system:

• Any request with the same idempotency key is treated as a new request, and the process starts again.

Please Note: SmarterPay strongly advises our clients to use the idempotency feature.

SmarterPay Cloud API employs Key-level Global Rate limiting on it's API endpoints.

“Key-level Global Rate limiting” means that each Client's API key is allowed a certain number of API calls in a given time period, before being rejected/limited.

The default rate, for all of our Clients, is 1000 requests per 60 seconds (1 minute).

Once this limit is reached, subsequent requests will recieve a “429 Too Many Requests” response, with the message “Too many requests. Please try again in 60 seconds.”, until the time windows has expired.
Once the time limit has expired request will be accepted again, with their appropriate response, until the limit is reached again for that time period.

If you want to discuss our rate limiting please contact support, either by telephone on +44 (0)1482 240886, or by email at support@smarterpay.com.