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
andvolt-timestamp
from the query parameters. - Concatenate the value of
volt
with thevolt-timestamp
using a pipe symbol (|
). This will create a payload (volt|volt-timestamp
). Note – you do not need to base64 decode thevolt
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.