Getting Started

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.

Section
Connecting to the API API Idempotency
Example Direct Debit Workflow API Rate Limiting
Verifying Webhook Signature



Connecting to the API

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.


Format of HTTP request header names and values

The name of the HTTP request header you want to send can only contain:

  • Alphanumeric characters: a-z, A-Z, and 0-9
  • The following special characters: - and _

The value of the HTTP request header you want to send can only contain:

  • Alphanumeric characters: a-z, A-Z, and 0-9
  • The following special characters: _ :;.,\/“'?!(){}[]@<>=-+*#$&`|~^%

Example API Request Header

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



API Idempotency

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.


API Rate Limiting

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.



Example Direct Debit Workflow


Step 1 - Create a Customer Account (Optional)

Only necessary if you're planning on linking several bank accounts or payment types together.

  1. The Customer Account is created using the API - Customer Account - POST method.
  2. System replies to the API call with the Customer Account record details, which includes the Customer ID.
  3. If there is a Webhook Subscription setup, an API Actions - Record Creation Webhook will be sent out.


Step 2 - Create a Bank Account (Necessary)

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.

  1. The Bank Account is created using the API - Bank Account - POST method.
  2. System Modulus Checks the account's sort code and account number and replies with the bank details and bank Account ID
  3. If there is a Webhook Subscription setup, a Bank Account - Record Creation Webhook will be sent out.


Step 3 - Create a Mandate (Necessary)

This step uses the Bank Account ID from Step 2.

  1. The Mandate is created by using the API - Mandate - POST method.
  2. The system replies with the Mandate record details.
  3. If there is a Webhook Subscription setup, a Mandate - Record Creation Webhook will be sent out.


Step 4 - Mandate Submission (Automatic)

This is for any Mandate, with an Active bank Account, set to “New Instruction”.

  1. The system will process the Mandate - Submitting it to Bacs.
  2. If there is a Webhook Subscription setup, a Mandate - Sent to Bacs Webhook will be sent out.


Step 5 - Mandate Update (Automatic)

The default of 3 banking days is used for marking a Mandate as successful.


Step 6 - Create an "Ongoing Payments" or "Payment Plan" Schedule (Optional)

Only necessary if you want SmarterPay Cloud to automatically take payments on a regular basis or over a set number of instalments.

  1. The Recurrence Schedule is created by using the API - Recurrence Schedule - POST
  2. The system replies with the Recurrence Schedule record details, including upcoming payments.
  3. If there is a Webhook Subscription setup, a Recurrence Schedule - Record Creation Webhook will be sent out.


Step 7a - Payment Creation (Automatic)

This is for any Schedules, with active Mandate and Bank Account, set to active.

  1. The system will create a payment for collection in 2 banking days time.
  2. If there is a Webhook Subscription setup, a DDMS Service - Recurrence Schedule - Record Updated Webhook will be sent out.
  3. If there is a Webhook Subscription setup, a DDMS Service - Payment - Record Creation Webhook will be sent out.


Step 7b - Create a Payment (Optional)

One off payments can be created as necessary. This step uses the Mandate ID from Step 3.

  1. The Payment is created by using the API - Payment - POST method.
  2. The system replies with the Payment record details.
  3. If there is a Webhook Subscription setup, an API - Payment - Record Creation Webhook will be sent out.


Step 8 - Payment Submission (Automatic)

This is for any Payment, with an Active bank Account and Mandate, set to “Pending Submission”.

  1. The system will process the Payment - Submitting it to Bacs.
  2. If there is a Webhook Subscription setup, a DDMS Service - Payment - Sent to Bacs Webhook will be sent out.


Step 9 - Payment Update (Automatic)

The default of 3 banking days is used for marking a Payment as successful.


Verifying the Webhook Signature

"Signature Auth" Webhook Subscription

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.


Step 1: Extract the Signature from the Webhook

The signature is sent in the “Webhook-Signature” message header of the Webhook.


Step 2: Compute the expected signature
  1. Generate a byte array of the Webhook Key, for the Subscription.
  2. Generate a byte array of the unformatted raw webhook body.
  3. Generate a signature hash, with an instance of HMACSHA256, using the the byte array of the webhook key as the secret key
  4. Remove any “-” characters from the result.
  5. Make the result lowercase.


.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();


Step 3: Compare the Signatures

Compare the signature passed with the Webhook, from Step 1, with the expected signature, from step 2.

  • Last modified: 2024/04/30 09:08