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 (POST) or updating (PUT) a record.

SmarterPay Cloud API's idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, per endpoint. Subsequent requests with the same key, and endpoint, return the same result.

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. Idempotency keys can be up to 255 characters long, and are case sensitive, for example “ABC123” is not the same as “abc123”.

Idempotency Keys will be removed from the system automatically after they're at least 24 hours old, and a new request is generated if a key is reused after the original has been removed.

To use SmarterPay Clouds API's idempotency, add “Idempotency-Key: <key>” to the header of the request.

If there is a matching idempotency key, for the endpoint, you will receive the response code and response body of the original request, plus an “idempotency-replay: true” in the response header.

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.