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.

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.

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:

Example notification content:

The Volt signature is created by combining your notification secret, the body of the notification, and a timestamp. It will never contain personal or sensitive information. Each notification request that we send you will also include a custom HTTP header – called X-Volt-Signed – which will contain the Volt signature.

How the signature works

• You will receive a POST message from Volt to your preconfigured notification URL
• Based on the body of the notification and your notification secret, you calculate what you think the signature should be
• You then check your calculation against the signature received in the X-Volt-Signed to confirm they match
• If they do match, return an empty HTTP response with a status code of 200 (OK)
• If they do not match, return an empty HTTP response with a code of 400 (Bad Request) and do not process the notification

Verifying the signature

Calculating the verification hash for a signature is based on three things, all of which are included in the notification. To verify, follow these simple steps:

1. Extract the User-Agent, X-Volt-Timed and X-Volt-Signed headers and the body of the notification
2. From the User-Agent header, extract the notification version (this is the part after the forward Slash (/) and will be a numeric value. For example, if the User-Agent is Volt/2.0, the version is 2.0)
3. Link the notification body with the content of the X-Volt-Timed header and the version, using the pipe delimiter | between them, like this: body|X-Volt-Timed|version. This creates your check string
4. Hash the check string with HMAC SHA256, using your notification secret (see below for an example)
5. Finally, compare your signature to the value in the notification’s X-Volt-Signed header

Ensure you can respond to an empty test at any time

Your system should always be able to respond to a test notification and respond with a 200 (OK) status code. In the test notification, we’ll send an empty JSON object in the request body, so your check string should look like this:

{}|X-Volt-Timed|version

A quick example to test your HMAC hashing

Using example values, here’s a quick test to ensure your signature check works correctly:

• The version you extracted from the User-Agent: 1.0
• X-Volt-Timed: 1631525064
• X-Volt-Signed: ed22494369277d25cf8c2293d142e5fddb9cecbea1f54e28ac16db0bee3b8009
• The complete, unmodified, body of the notification: {}
• Your notification secret: 9c0c8c97-c224-45ed-a195-23b54b1c67e5

Next, use the pipe delimiter to join the body, X-Volt-Timed and version:

{}|1631525064|1.0

Then, hash this string using SHA256 and your notification secret of 9c0c8c97-c224-45ed-a195-23b54b1c67e5. If everything is correct, you should receive an HMAC that is identical to your X-Volt-Signed key:

ed22494369277d25cf8c2293d142e5fddb9cecbea1f54e28ac16db0bee3b8009

We will make up to 6 attempts to deliver a notification with the aim of receiving a 200 (OK) response from you. A small delay will be added between each attempt in case a technical glitch is preventing the notifications arriving. The first retry will be after 5 seconds, the next after 30 seconds, 3 minutes, 10 minutes and every further will be after 15 minutes.

We will not stop sending you the notifications but all those that failed in the delivery attempt will be queued by us.

If we fail to deliver any notification 6 times in a row

• We will monitor if any notification was not delivered to you 6 times in a row or failed to be delivered after the last retrial. 
• If such an event occurred, there will be a summary report sent to you via email listing all payments for which notifications have not been successfully received by you. As the report will be sent once per hour, it will gather the notifications that failed within this particular time.
• The email will be sent to your technical and/or primary contact, on the address you specified in Fuzebox.
• If we don’t hear from you that the problem is fixed, then someone from Volt will be in touch.
• If it’s a problem at your end then, once you’ve fixed the issue, go into Fuzebox and send a test notification (see below) to yourself. If that works, don’t worry, we’ll automatically send you any notifications you may have missed. 

If you still aren’t receiving previously failed notifications

• Have you sent a test notification to the correct URL and responded with an HTTP 200 status? We won’t send any queued live payment notifications until we know you can process the test notification properly.
• Are notifications showing as enabled in Fuzebox?
• If you responded to the test notification and it was a success but payment notifications are not being delivered, please contact our support team and we’ll get to the bottom of it.