Notifications

Notifications are used to send events to merchants’ applications about our verification process. Below, you can see example payloads for use cases. Additionally, we use signatures so you can verify requests that originate from Volt and reject non-authorised requests from elsewhere.

Signature verification should be based on the header: x-volt-signed

Example value:

x-volt-signed: 4d02959a8fbd8bfe661f55cb87e9dede455068f082fe624447f9eb69647ed054

In addition to there are also headers:

  • x-volt-type – type of verification basing on the concatenated prefix verify-identification- with verification process status
  • x-volt-timed – UNIX timestamp of the notification

As a prerequisite, you need to provide us with the URL for us to send you the notifications.

The body of the notification contains a JSON formatted data structure containing the following information: 

  • processId (our ID for verification)
  • uniqueReference (your ID)
  • status (possible statuses are described below)
  • message
  • accountData

Info

 Please note that not all functionalities described on About notifications will be available for Verify notifications.

AccountData can include the following details, depending on the information fetched from a bank: 

  • bank name
  • account holder’s name
  • sort code
  • account number 
  • IBAN
  • account balance amount & type

The attributes in the above list will only be included in the notification when the necessary data has been successfully retrieved from a bank.

What statuses mean

DATA_RETRIEVED
Data Retrieved is an indication that the requested details were successfully fetched from a bank and the verification process is finalised.

FAILED
There are several cases when a process can be marked as Failed. For example, it can happen for technical reasons when integrating with the bank. Such a situation can occur while trying to obtain the bank data (after the shopper has given consent for retrieving the details) or when we get the bank redirection URL (after a user chooses their bank from our list). When specific reasons for the failure are available to Volt, we will display them in the Message portion of the notification.

CANCELLED
Before a user is redirected to the bank from the Checkout, they have an option to cancel the process. If the process is cancelled, the status will change to Cancelled. If the user later decides to go through the verification process again, a new process will need to be started.

EXPIRED
If the user is inactive for 15 minutes, Verify will terminate the process and mark it as Expired. The user will need to start a new process to complete verification.

CONSENT_REJECTED
When a user is redirected to the bank, they have the choice to grant us consent to access their bank details or not. If they choose to decline the request, a Consent Rejected status will be shown.

INSUFFICIENT_CONSENT_GRANTED
The Insufficient Consent Granted status means that a user has provided consent but not for all of the data Volt requires. In this instance, the process cannot continue and the request is terminated.

CONSENT_REVOKED
In the rare occasion that a user revokes the consent after granting it and before we fetch the bank details, Verify will assign the status to Consent Revoked.

Example notifications payload

Successful/Data Retrieved Notification
{
   "processId":"5b04e695-a2c8-4437-95e0-9d57260c5236",
   "uniqueReference":"merchant-external-123",
   "status":"DATA_RETRIEVED",
   "message":"Data Obtained",
   "accountData":{
      "bank":{
         "name":"N26"
      },
      "accountHolderName":"John Smith",
      "accounts":[
         {
            "sortCode":null,
            "accountNumber":null,
            "iban":"DK0718282826129398",
            "bic":null,
            "name":null,
            "balance":[
               {
                  "type":"Available",
                  "dateTime":"2021-07-15T11:48:11.000Z",
                  "amount":"0",
                  "currency":"GBP"
               },
               {
                  "type":"Current",
                  "dateTime":"2021-07-15T11:49:06.000Z",
                  "amount":"2700",
                  "currency":"GBP"
               }
            ]
         },
         {
            "sortCode":"843881",
            "accountNumber":"62636253",
            "iban":null,
            "bic":null,
            "name":"John Smith",
            "balance":[
               {
                  "type":"Other",
                  "dateTime":"2021-07-15T11:48:08.000Z",
                  "amount":"-1.28",
                  "currency":"GBP"
               }
            ]
         }
      ]
   }
}
Failed Notification (Obtaining data)
{
   "processId": "5b04e695-a2c8-4437-95e0-9d57260c5236",
   "uniqueReference": "merchant-external-123",
   "status": "FAILED",
   "message": "Obtaining data failed",
   "accountData": null
}
Failed Notification (Obtaining bank url)
{
   "processId": "5b04e695-a2c8-4437-95e0-9d57260c5236",
   "uniqueReference": "merchant-external-123",
   "status": "FAILED",
   "message": "Cannot connect to bank",
   "accountData": null
}
Cancelled Notification
{
   "processId": "5b04e695-a2c8-4437-95e0-9d57260c5236",
   "uniqueReference": "merchant-external-123",
   "status": "CANCELLED_BY_USER",
   "message": "User cancelled process",
   "accountData": null
}
Expired Notification
{
   "processId": "5b04e695-a2c8-4437-95e0-9d57260c5236",
   "uniqueReference": "merchant-external-123",
   "status": "EXPIRED",
   "message": "Process was abandoned",
   "accountData": null
}
Consent Rejected Notification
{
   "processId": "5b04e695-a2c8-4437-95e0-9d57260c5236",
   "uniqueReference": "merchant-external-123",
   "status": "CONSENT_REJECTED",
   "message": "Consent Rejected",
   "accountData": null
}
Insufficient Consent Granted Notification
{
   "processId": "5b04e695-a2c8-4437-95e0-9d57260c5236",
   "uniqueReference": "merchant-external-123",
   "status": "INSUFFICIENT_CONSENT_GRANTED",
   "message": "Insufficient consent granted",
   "accountData": null
}
Consent Revoked Notification
{
   "processId": "5b04e695-a2c8-4437-95e0-9d57260c5236",
   "uniqueReference": "merchant-external-123",
   "status": "CONSENT_REVOKED",
   "message": "Consent revoked",
   "accountData": null
}