Volt notifications

About Volt Notifications

We inform you of a payment’s success/failure/pending status by sending a POST request that contains a digitally signed payment notification to a secure URL on your server. This happens in the background and is not visible to the shopper.

You should always rely on the information sent in notifications rather than the return URL the shopper was redirected to. This is especially important for embedded checkouts where the return URLs are not used.

By using a secret key that you receive during application setup, you can check the signature of the message to confirm that it came from Volt and is a genuine notification. Never process any message that appears to originate at Volt without performing this verification step first.

If a status was originally pending, we’ll send you another notification when it changes to success or failure. Each notification will be digitally signed, and you’ll then need to confirm that you have received the notification and the signature is correct.

Important!

The success notification is only a confirmation that the payment was successfully initiated at the bank. Some banks allow payments to be cancelled after they are initiated so this is not a guarantee that the funds will arrive in your account. Note, however, that we do issue payment received notifications via Connect.

Payment notifications

For our core Gateway and Pay by Link products, we’ll send a notification to your payment notification URL if:

A payment initiation is complete
A payment is delayed
The payment initiation fails for any reason

Notification fields

The body of the notification contains a JSON formatted data structure, which has the following fields:

payment is Volt’s internal ID for the payment, as returned in your initial payment request
reference is the uniqueReference you specified in the initial payment request
amount is the payment amount; always in minor units of currency (pence, cents) rather than pounds, euros or dollars (1000 = $10.00)
status refers to a broad classification of transactions based on their detailed status; it provides a high-level overview of where each transaction stands; each group encompasses multiple detailed statuses that share similar characteristics or states
detailedStatus is a more specific and in-depth update that provides finer details about the payment’s status
currency is the currency of the payment (is applicable only for Received notification)
timestamp is when the notification was generated (is applicable only for Received notification)
merchantInternalReference is an optional longer reference you can specify for the payment. It can be up to 100 characters, including special characters. If this value is provided during payment creation, then it will be a part of the notification.

Example notification body

If the payment was refused by the shopper's bank

{
  "payment": "292d48f6-90f3-450b-93eb-0b480b8b70dd",
  "reference": "Invoice-12345",
  "merchantInternalReference": "Order for a trip to Greece 20-27.08.2023",
  "amount": 1000,
  "status": "FAILED",
  "detailedStatus": "REFUSED_BY_BANK"
}

What each status means

The status categories presented in the status field of the notification (COMPLETED, FAILED, and PENDING) provide a high-level overview of the transaction’s current status. A more specific update can be found in the detailedStatus field.

COMPLETED

The COMPLETED status means that the payment has been instructed and your customer’s bank has accepted it. Both the payment request and instruction process are completed.

However, banks are still able to cancel payments after the instruction has been accepted, so a status of COMPLETED does not guarantee that you will receive the funds. It is important to confirm receipt of funds with your receiving bank before releasing the goods or services.

COMPLETED

{
  "payment": "292d48f6-90f3-450b-93eb-0b480b8b70dd",
  "reference": "Invoice-12345",
  "merchantInternalReference": "Order for a trip to Greece 20-27.08.2023",
  "amount": 1000,
  "status": "COMPLETED",
  "detailedStatus": "COMPLETED"
}

FAILED

The FAILED status means that the payment request could not be completed. This could be due to technical reasons in the banking network, the customer cancelled the payment, or the customer’s bank rejected it.

REFUSED_BY_RISK

{
  "payment": "292d48f6-90f3-450b-93eb-0b480b8b70dd",
  "reference": "Invoice-12345",
  "merchantInternalReference": "Order for a trip to Greece 20-27.08.2023",
  "amount": 1000,
  "status": "FAILED",
  "detailedStatus": "REFUSED_BY_RISK"
}

REFUSED_BY_BANK

{
  "payment": "292d48f6-90f3-450b-93eb-0b480b8b70dd",
  "reference": "Invoice-12345",
  "merchantInternalReference": "Order for a trip to Greece 20-27.08.2023",
  "amount": 1000,
  "status": "FAILED",
  "detailedStatus": "REFUSED_BY_BANK"
}

ERROR_AT_BANK

{
  "payment": "292d48f6-90f3-450b-93eb-0b480b8b70dd",
  "reference": "Invoice-12345",
  "merchantInternalReference": "Order for a trip to Greece 20-27.08.2023",
  "amount": 1000,
  "status": "FAILED",
  "detailedStatus": "ERROR_AT_BANK"
}

CANCELLED_BY_USER

{
  "payment": "292d48f6-90f3-450b-93eb-0b480b8b70dd",
  "reference": "Invoice-12345",
  "merchantInternalReference": "Order for a trip to Greece 20-27.08.2023",
  "amount": 1000,
  "status": "FAILED",
  "detailedStatus": "CANCELLED_BY_USER"
}

ABANDONED_BY_USER

{
  "payment": "292d48f6-90f3-450b-93eb-0b480b8b70dd",
  "reference": "Invoice-12345",
  "merchantInternalReference": "Order for a trip to Greece 20-27.08.2023",
  "amount": 1000,
  "status": "FAILED",
  "detailedStatus": "ABANDONED_BY_USER"
}

FAILED (for any other reason)

{
  "payment": "292d48f6-90f3-450b-93eb-0b480b8b70dd",
  "reference": "Invoice-12345",
  "merchantInternalReference": "Order for a trip to Greece 20-27.08.2023",
  "amount": 1000,
  "status": "FAILED",
  "detailedStatus": "FAILED"
}

PENDING

The PENDING status means that payment has not yet been confirmed by the customer’s bank. This can occur for multiple reasons, including the customer’s bank encountering a delay in processing payments or an additional authorisation required for payments – a common setup on business accounts.

When the status changes, you’ll automatically receive another notification, usually with a final status of COMPLETED or FAILED. It is possible that this could be an updated PENDING status with a different detailedStatus reason. If you’d like to manually check for status changes periodically, you can do so using the GET/payments/{id} endpoint.

BANK_REDIRECT

{
  "payment": "292d48f6-90f3-450b-93eb-0b480b8b70dd",
  "reference": "Invoice-12345",
  "merchantInternalReference": "Order for a trip to Greece 20-27.08.2023",
  "amount": 1000,
  "status": "PENDING",
  "detailedStatus": "BANK_REDIRECT"
}

DELAYED_AT_BANK

{
  "payment": "292d48f6-90f3-450b-93eb-0b480b8b70dd",
  "reference": "Invoice-12345",
  "merchantInternalReference": "Order for a trip to Greece 20-27.08.2023",
  "amount": 1000,
  "status": "PENDING",
  "detailedStatus": "DELAYED_AT_BANK"
}

AWAITING_CHECKOUT_AUTHORISATION

{
  "payment": "292d48f6-90f3-450b-93eb-0b480b8b70dd",
  "reference": "Invoice-12345",
  "merchantInternalReference": "Order for a trip to Greece 20-27.08.2023",
  "amount": 1000,
  "status": "PENDING",
  "detailedStatus": "AWAITING_CHECKOUT_AUTHORISATION"
}

Connect statuses

These two additional statuses are provided by our Volt Connect service and are listed here for completeness. These notifications do not include the detailedStatus field by design. The Connect documentation has full information about the RECEIVED and NOT_RECEIVED statuses.

Find out more about Volt Connect

RECEIVED

{
  "payment": "292d48f6-90f3-450b-93eb-0b480b8b70dd",
  "reference": "Invoice-12345",
  "merchantInternalReference": "Order for a trip to Greece 20-27.08.2023",
  "amount": 10000,
  "status": "RECEIVED",
  "currency": "EUR",
  "timestamp": "2023-05-25T15:51:29+00:00",
  "sender": {
    "name": "T.B.M. Van Buuren",
    "location": "NL",
    "iban": "NL54RABO0310400732",
    "swiftBic": null,
    "accountNumber": null,
    "sortCode": null
  }
}

NOT_RECEIVED

{
  "payment": "292d48f6-90f3-450b-93eb-0b480b8b70dd",
  "reference": "Invoice-12345",
  "merchantInternalReference": "Order for a trip to Greece 20-27.08.2023",
  "amount": 10000,
  "status": "NOT_RECEIVED",
  "currency": "EUR",
  "timestamp": "2023-05-25T15:51:29+00:00"
}

Further information is available about when payments are deemed to be not received.

View expected payment processing times

Additional notification content

Volt can provide additional details in your payment notifications. The following table shows the full list of supported fields. It is possible to manage the additional notification content through our merchant portal Fuzebox inside the Application section.

List of available fields:

Field	Json path	Description
bank_id	`sender.bank.id`	The Volt id for the bank
bank_country	`sender.bank.country`	The ISO alpha-2 code of the country where the payment originated
bank_official_name	`sender.bank.groupName`	The official group name of the bank where the payment originated
bank_short_branch_name	`sender.bank.branchName`	The branch name of the bank branch where the payment originated (where applicable)
bank_bic8	`sender.bank.bic8`	The bic8 of the bank where the payment originated
sender_iban	`sender.iban`	The IBAN of the bank account where the payment originated
sender_account_number	`sender.accountNumber`	The Account Number of the bank account where the payment originated
sender_sort_code	`sender.sortCode`	The Sort Code of the bank account where the payment originated (UK Payments)
sender_name	`sender.name`	The Account Holder of the bank account where the payment originated
sender_bsb	`sender.bsb`	The BSB of the bank account where the payment originated
sender_payid	`sender.payId`	The PayID of bank account where the payment originated

Example notification content:

{
   "payment":"f839adfb-4b16-422d-a056-b10d5307660f",
   "reference":"uniquereference",
   "merchantInternalReference": "Order for a trip to Greece 20-27.08.2023",
   "amount":2500,
   "status":"COMPLETED",
   "detailedStatus": "COMPLETED",
   "sender":{
      "iban":"DE63500105173256774934",
      "accountNumber": null,
      "sortCode": null,
      "name":"Mrs Jane Doe",
      "bank":{
         "id":"ea54dc4d-d2e4-481f-8424-a9eb9a2db4ab",
         "country":"DE",
         "groupName":"Norisbank",
         "branchName":"Norisbank Berlin",
         "bic8":"HANDSESS"
      }
   }
}