Release Notes - 2022

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.

Bank Accounts can now be enabled or disabled through the API.

• “Transaction code” has been added, to the List API filters, for
  • Payments
  • File Submission Lines
• “indemnity_claimed” added to the list of options available for “Status” for the Payment list API

We have introduced Webhooks V2 to SmarterPay Cloud. The key differences between the versions are as follows:

Version 1 Webhooks have one event per webhook. For example, the creation of a Bank Account, Mandate and a Payment will generate three events and will be sent out in three seperate Webhooks.

Version 2 Webhooks can have more than one event, across objects, per webhook. for example, the creation of a Bank Account, Mandate, and a Payment will generate three events but can all be sent out in one Webhook.
Please see “V2 Webhook Structure” for more details.

The number of Events in a single webhook varies, depending on how many Events are ready when the system sends out a Webhook.
The maximum number of Events that can be in a Webhook is set in the Subscription settings.

Version 2 Webhooks contain more information in an Event than a version 1 Webhook has.

The information in the version 2 event is also organised better, for example, Bank account information in a Mandate is in it's own Object rather than being just a bunch of properties on the Event.

Version 2 Webhooks contain an Idempotency Key that can be used to prevent duplicate actions occurring when SmarterPay Cloud is integrated to other platforms or Software.

All records now have a 19+ character Id. These new ids are always in the Id column on a v2 webhook. Any record created before this change will have a 'new' Id and a Legacy Id. This will be represented in the v2 webhook in the Id and Legacy Id fields. Any new records will not have a Legacy Id.

It is recommended that if you receive a webhook with a Legacy Id that you update your copy of the data with the new Id and use that moving forward. Legacy Ids will still continue to work with API, Portal and Search and there is no current timescale to deprecate these.

The following changes have been made to the Subscriptions area:

• Improvements have been made to the way Subscriptions are managed and it is now easier to Create and Update subscriptions and the events they are listening for.
• V2 Webhook options have been added to the Subscription Setup page.
• A new Logs Tab has been added to show all Webhooks for the Subscription.
• A new Testing Tab has been added to allow for sending test webhooks to the Subscription endpoint.

The main SmarterPay Cloud Record details pages have been changed, as follows:

• The Events Tab has been removed.
• The Email Tab has been added. This shows emails that have been sent out that link to the record.
• The History Tab has been added. This shows updates to the record and links through to any outbound messages linked to the record.

This affects the following objects:

• Customers
• Accounts
• Mandates
• Payments
• Scheduled Payments
• Credits
• Cards

Outbound Messages have been added to the List API functionality.

As part of improvements to the file submission process, we have separated the presentation of data coming into SmarterPay Cloud from the data transmitted out of SmarterPay Cloud.
These will be accessible through two new menu items called “File Upload”, for data coming in, and “Submissions”, for data going out.

The new File Upload menu item is based on the old “File Submissions” functionality, but we have taken the opportunity to improve the File Upload List View to make it simpler to use, and bring it more in-line with the rest of the system.

SmarterPay Cloud now displays details for files that have been submitted to the relevant authority, for example Bacs.
Included within this area SmarterPay Cloud allows the user to view the Submission created via file upload, the API or Portal.
These submissions are also linked to Input Reports to provide an accurate status of the Submission.

To help our integrated customers we have also added notifications, via Webhook, of these submissions.

Smarterpay Cloud will now process BACS input reports as part of its standard functionality – the handling of these reports can be tailored to your business needs.
Input reports are generated on Day 1 (Input Day) of the Bacs 3-day collection cycle. The report provides information on accepted and rejected instructions and confirms the processing dates for the file.
The new input report codes have been added to the BACS Codes page.

Areas that have been added:

• Submission List View
• Submission API
• Submission Webhooks
• Input Report handling customisation

Multi-factor authentication (MFA) is an electronic authentication method in which a user is granted access to a website or application only after successfully presenting two or more pieces of evidence (or factors) to an authentication mechanism.

A good example of two-factor authentication is the withdrawing of money from an ATM; only the correct combination of a bank card and a PIN allows the transaction to be carried out.

SmarterPay Cloud supplements a user-controlled password with either a memorable word and/or a one-time code, delivered either by Email and/or an authentication app that only the user possesses.

Links to MFA in SmarterPay Cloud

• Getting Started
• Profiles
• Users
• User Settings

Functionality has been added to the API to allow lists of records to be retrieved from SmarterPay Cloud.

Up to 500 records per page, filtered and sorted by various items per object, for example, all successful payments for a mandate sorted by collection date, can be generated as required.

Links to List API Functionality in SmarterPay Cloud

• Bank Accounts
• Cards
• Credits
• Customer Accounts
• Mandates
• Payments
• Recurrence Schedules