The API & Webhook Sections of the documentation guides you through the structure and usage of the API and Webhooks within SmarterPay Cloud.
The following sections contain useful information regarding the SmarterPay Cloud API and Webhooks.
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.
The name of the HTTP request header you want to send can only contain:
The value of the HTTP request header you want to send can only contain:
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:
After the idempotency key details are removed from the system:
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.
Only necessary if you're planning on linking several bank accounts or payment types together.
The Customer ID, from Step 1, can be used in the API POST, if desired, to connect the Bank Account to the Customer. Or it can be left blank.
This step uses the Bank Account ID from Step 2.
This is for any Mandate, with an Active bank Account, set to “New Instruction”.
The default of 3 banking days is used for marking a Mandate as successful.
Only necessary if you want SmarterPay Cloud to automatically take payments on a regular basis or over a set number of instalments.
This is for any Schedules, with active Mandate and Bank Account, set to active.
One off payments can be created as necessary. This step uses the Mandate ID from Step 3.
This is for any Payment, with an Active bank Account and Mandate, set to “Pending Submission”.
The default of 3 banking days is used for marking a Payment as successful.
SmarterPay Cloud sends a signature with all “Signature Auth” Webhook Subscriptions.
This signature can be used to verify that the contents of the webhook has not been tampered with.
The steps detailed below show one way to verify the Webhook Signature.
The signature is sent in the “Webhook-Signature” message header of the Webhook.
.NET Code Example:
string secret = "ssecretwebhookkey";
string message ="{ \"events\" :[ { \"id\" : \"0\" , \"created_at\" : \"2021-08-25T17:18:03.000Z\", \"resource_type\": \"mandate\", \"event_source\" : \"10044000\", \"customer_account\" : \"\", " +
" \"AUDDIS\" : \"0\", \"status\" : \"new_instruction\", \"description\" : \"Test for webhook Mandate Subscription\", \"bacs_reason_code\" : \"200 OK\", \"bacs_description\" : \"Test\", " +
" \"bacs_reference\" : \"\", \"bacs_filename\" : \"\" } ] }";
// Get Byte Array From Webhook Key AKA Secret Key
byte[] key = Encoding.UTF8.GetBytes(secret);
// Get Byte Array from message
byte[] bytes = Encoding.UTF8.GetBytes(message);
//Generate Instance of 256 using the key array
HMACSHA256 hmacsha256 = new HMACSHA256(key);
// Compute a hash using the instance of the sha256.
byte[] hash = hmacsha256.ComputeHash(bytes);
// Get Hash
string calculatedSignature = BitConverter.ToString(hash).Replace("-", "").ToLower();
Compare the signature passed with the Webhook, from Step 1, with the expected signature, from step 2.