Returning the payer to you

Returning the shopper to you

The payment initiation can result in 3 different ways. The shopper confirmed the payment initiation, cancelled or abandoned it or an issue occurred and the payment failed. The shopper expects a different communication for each and so you can define specific urls for each outcome.

You can set the different urls (Payment return URLs) in the application configuration in Fuzebox. Find out how to here.

paymentSuccessUrl - Successful initiation

When the payer has been redirected to their bank, they’ll be asked to approve the payment. Once this is done, a payment is classed as initiation and the process from the payer’s side is complete.

Once the bank informs us that this has completed, we’ll show the payer a confirmation screen and automatically redirect them to your success URL. We’ll also send a payment notification POST, with a COMPLETED status, to your notifications URL. More details on notifications are available here.

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 send these to the return URL. Note that we will pass them 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 four fields.

Structure
Example

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

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

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

{
  "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.

You’ll need to calculate your own version of the signature using the steps below. If your calculated 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 do not need to base64 decode the volt parameter
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 from the following URL.

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

paymentPendingUrl - 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.

{
  "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.

paymentFailureUrl and paymentCancelUrl - Failed, cancelled or abandoned initiation

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.

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

Cancelled by payer

If a payment is cancelled by the payer 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.

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

Abandoned

If the customer abandons the payment process, meaning they’ve either navigated away or closed their browser, they would never be returned to you. We will, however, send you a notification after a certain time, containing the status of ABANDONED.