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.




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.


Example API Request Header

Authorization: Bearer <token>
Content-Type: application/json
Accept-Charset: utf-8





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.

  • Last modified: 2021/07/27 15:29