API Requests & Responses

This page, and it's links, gives details on how to use SmarterPay Cloud API.

If you have issues with SmarterPay Cloud API please contact support, either by telephone on +44 (0)1482 240886, or by email at support@smarterpay.com

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

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.

The following REST URLs are available to connect to SmarterPay Cloud API. For more information, including API request and response parameters, please use the Rest Service or Option Links below.

Rest Service Base URL Options
Account Validation https://api.smarterpaycloud.com/service.svc/accountvalidation Details (Singular)
Bank Account https://api.smarterpaycloud.com/service.svc/bankaccount Create, Update, Details (Singular), Disable, Details (List)
Card https://api.smarterpaycloud.com/service.svc/cards Details (List)
Client Bank Account https://api.smarterpaycloud.com/service.svc/clientbankaccount Details (Singular), Details (List), Details (By SUN)
Credit https://api.smarterpaycloud.com/service.svc/credit Create, Details (Singular), Update, Details (List)
Customer Account https://api.smarterpaycloud.com/service.svc/customeraccount Create, Details (Singular), Update, Details (List)
Ecommerce Branding (V2) https://api.smarterpaycloud.com/service.svc/ecommercebranding Details (Singular)
Ecommerce Page Setup (V2) https://api.smarterpaycloud.com/service.svc/ecommercepagesetup Details (Singular)
Mandate https://api.smarterpaycloud.com/service.svc/mandate Create, Details (Singular), Update, Details (List)
Modulus Check https://api.smarterpaycloud.com/service.svc/moduluscheck Check
Payment https://api.smarterpaycloud.com/service.svc/payment Create, Details (Singular), Update, Details (List)
Payment Link https://api.smarterpaycloud.com/service.svc/paymentlink Create, Details (Singular), Update, Details (List)
Payment Re-present https://api.smarterpaycloud.com/service.svc/payment/{ID}/represent Create
Recurrence Schedule https://api.smarterpaycloud.com/service.svc/recurrenceschedule Create, Details (Singular), Disable, Update, Details (List)
Service User Number https://api.smarterpaycloud.com/service.svc/serviceusernumber Details (Singular), Details (List)
File Submission https://api.smarterpaycloud.com/service.svc/submission Details (Singular), Details (List)
File Submission Line https://api.smarterpaycloud.com/service.svc/submissionline Details (Singular), Details (List)
Outbound Message https://api.smarterpaycloud.com/service.svc/outboundmessage Details (Singular), Details (List), Resend Outbound Message

{ID} denotes ID of record.

If you have UAT facilities with SmarterPay, please replace “api.smarterpaycloud.com” with “uatapi.smarterpaycloud.com” in the URL to access the testing environment.

Each API request will result in a response code and response text. You may encounter the following response codes. Any unsuccessful response codes will contain more information to help you identify the cause of the problem

A “200 OK” is the standard response for a successful API request.
A “503 Service Unavailable” response will be returned when the API is in maintenance mode, for example when updates are being applied. The dates for SmarterPay Cloud API updates are published on the Cloud login page and sent via email in advance.

Other error codes may require further investigation.

200OKStandard response for successful HTTP requests.
202AcceptedThe request has been received but not yet acted upon. The request may or may not eventually be acted upon, as it may be disallowed when processing actually takes place.
204No ContentThe server successfully processed the request, and is not returning any content.
400Bad RequestThe server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing).
405Method Not AllowedA request method is not supported for the requested resource; for example, a GET request on a form that requires data to be presented via POST, or a PUT request on a read-only resource.
406Not AcceptableThe requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request.
498Invalid TokenCode 498 indicates an expired or otherwise invalid token.
500Internal Server ErrorA generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
503Service UnavailableThe server is not ready to handle the request.
  • Last modified: 2023/11/09 10:41