Returning the shopper to you

Once the shopper has been redirected to their bank, the payment process can result in 3 different outcomes:

The shopper confirmed the payment initiation
The shopper cancelled or abandoned the payment
An issue occurred and the payment failed

There could also be a delay, where the payment has been approved but the bank hasn’t marked it as complete yet, which often happens with business or corporate accounts, or for first payments to a merchant. In this case, we’ll mark that payment as pending.

Your shopper will expect a different communication for each outcome, so you can (optionally) define specific URLs for us to redirect them when each of the above scenarios happen. This can be done in Fuzebox.

Find out how to change return URLs

Successful initiation

The shopper will be redirected to their bank to complete the payment process. When this happens, the payment is classed as initiated and the process from the payer’s side is complete.

Once the bank informs us that the payment approval has completed, we’ll show the shopper a confirmation screen and automatically redirect them back to the success URL you configured in Fuzebox.

We’ll also send you a payment notification, with a COMPLETED status, to your previously-configured notifications URL.

Find out more about notifications

Information sent to the success URL

The information we send is base64 encoded into a query parameter called volt.

If you also requested custom parameters, we’ll also send these to the return URL. Note that we will pass these extra parameters back exactly as requested and won’t encode them, so we suggest sensitive information should be encrypted before you send the parameters in your initial payment request.

Once you base64 decode the information contained in the volt parameter, you’ll receive a Json structure, containing three fields.

Structure
Example

URL format

https://{return_url}?volt={string}&volt-signature={string}&volt-timestamp={integer}

Decoding the volt parameter

{
  "id": "{UUID}",
  "uniqueReference": "{string}",
  "status": "{string}"
}

URL example

https://success.customer.com?volt=ewogICAgImlkIjogImVmYWRmZTNhLWU1MjUtNDljYi1hZmNhLWM3Zjc5MWU0NzRiYyIsCiAgICAidW5pcXVlUmVmZXJlbmNlIjogInBheTIwMjMwMTQ2IiwKICAgICJyZWYiOiAicGF5MjAyMzAxNDYiLAogICAgInN0YXR1cyI6ICJDT01QTEVURUQiCn0&volt-signature=845c77b087c3e9105724554fcc5ec15cb252e290b619a7bc8ca57e42031abbf3&volt-timestamp=1676468812

Decoding the volt parameter

{
  "id": "efadfe3a-e525-49cb-afca-c7f791e474bc",
  "uniqueReference": "pay20230146",
  "status": "COMPLETED"
}

Digitally signed return data

So that you can be sure that the data in the volt parameter has not been tampered with, we digitally sign the data and supply you two further fields in the return URL. These fields are named volt-signature and volt-timestamp.

If you want to validate the contents of the volt parameter, you’ll first need to calculate your own version of the signature using the steps below. If your calculated version of signature matches the value returned in volt-signature then you can be sure that the information in the volt parameter is as we sent it. If your signature doesn’t match, then you should not trust the data

Steps to verify the signature

To proceed, you’ll need a signing key which you can obtain by reaching out to Volt support.

Get the values of volt , volt-signature and volt-timestamp from the query parameters.
Concatenate the value of volt with the volt-timestamp using a pipe symbol (|). This will create a payload (volt|volt-timestamp). Note – you should not base64 decode the volt parameter before calculating the signature.
Hash your payload with HMAC SHA256, using your signing key. This will create your calculated version of the signature.
Compare the value of volt-signature with the calculated signature.

Try it

Use the signing key foo to calculate the signature of the following URL parameters. It should match the value contained in the volt-signature parameter.

Example URL

https://success.merchant.com/payment?volt=ewogICAgImlkIjogImVmYWRmZTNhLWU1MjUtNDljYi1hZmNhLWM3Zjc5MWU0NzRiYyIsCiAgICAidW5pcXVlUmVmZXJlbmNlIjogInBheTIwMjMwMTQ2IiwKICAgICJyZWYiOiAicGF5MjAyMzAxNDYiLAogICAgInN0YXR1cyI6ICJDT01QTEVURUQiCn0&volt-signature=845c77b087c3e9105724554fcc5ec15cb252e290b619a7bc8ca57e42031abbf3&volt-timestamp=1676468812

Pending initiation

Sometimes a payment initiation won’t be immediately successful, but might take some time. A payment initiation can have a PENDING status for multiple reasons, but usually it’s because:

For corporate accounts, another person needs to authorise the payment before it can be sent
For payments of a higher value, or sent to a new beneficiary, banks occasionally perform additional checks before releasing the payment.

If the initiation is pending

We’ll send a POST to your notifications URL and redirect your customer to the pending URL you defined when registering your application.

The volt parameter we send will contain the same information as described above, although the status will contain DELAYED_AT_BANK. For your security, the volt parameter will be digitally signed, so you’ll also receive volt-timestamp and volt-signature as query parameters.

Decoding the volt parameter

{
  "id": "efadfe3a-e525-49cb-afca-c7f791e474bc",
  "uniqueReference": "pay20230146",
  "status": "DELAYED_AT_BANK"
}

What happens after pending?

A pending payment’s status will eventually change to be COMPLETED or FAILED (or one of the other failure states detailed below). We’ll send you an updated notification to your notifications URL in either case.

Failed, cancelled or abandoned

A payment initiation could fail for a number of reasons including, but not limited to:

The payer had insufficient funds in their account
The bank refused the payment for some reason (the status will be REFUSED_BY_BANK)
There was a technical error at the bank (the status will be ERROR_AT_BANK)

If a payment couldn’t be completed, we’ll send a POST with a status of FAILED to your notification URL and then redirect your customer to the failure URL you defined when registering your application.

The volt parameter will contain the same information as detailed above, however the status will contain FAILED, or one of the statuses detailed above. For your security, the volt parameter will be digitally signed, so you’ll also receive volt-timestamp and volt-signature as query parameters.

Decoding the volt parameter

{
  "id": "efadfe3a-e525-49cb-afca-c7f791e474bc",
  "uniqueReference": "pay20230146",
  "status": "FAILED"
}

Cancelled by the shopper

If a payment is cancelled by the shopper when they get to the bank, we will redirect them back to the cancellation URL you defined when registering your application.

The volt parameter will contain the same information as detailed above, however the status will contain CANCELLED_BY_USER. For your security, the volt parameter will be digitally signed, so you’ll also receive volt-timestamp and volt-signature as query parameters.

Decoding the volt parameter

{
  "id": "efadfe3a-e525-49cb-afca-c7f791e474bc",
  "uniqueReference": "pay20230146",
  "status": "CANCELLED_BY_USER"
}

Abandoned by the shopper

If the shopper abandons the payment process, meaning they’ve either navigated away or closed their browser, they would never be returned to you. In this case, Volt will you a notification after a certain time (approximately 30 minutes), containing the status of ABANDONED.