Payments, Supercharged. (1.0.0)

Download OpenAPI specification:Download

Welcome to Open Banking!

Open Banking payments are authenticated directly between consumers and their own bank. Meaning that chargebacks that merchants traditionally pay because of card fraud or rejected card payments just disappear.

Payments powered by Open Banking also offer near-real-time transfers, guaranteeing that the merchant receives the payment quickly and enabling them to ship the product immediately.

Volt has developed a REST API for merchants, allowing you to offer the option to use Open Banking payments on your online checkout.

Simple, secure payments

Step 1. You send an API call to Volt to let us know the payment details and we'll respond with a payment ID, which you'll use when you redirect your customer.

Step 2. Volt will then securely route your customer to their bank's online portal to confirm the payment.

Step 3. The payment is then sent directly from your customer's bank account to your bank account in near-real-time, over the Faster Payments network in the UK, SEPA and similar networks around Europe.

Quick start guide

Help and feedback

If you need assistance during the integration process, please email us at support@volt.io

Let us know your thoughts about our product and integration process at hello@volt.io. Your thoughts will help us shape our product to help you.

Step 1. Register a merchant account

The first thing you'll need to do is register a new merchant account on the Volt Merchant Portal, Fuzebox.

Fuzebox is currently in closed Beta. If you are not yet signed up to our Beta program, please contact Volt support to configure your account

  • You'll need to register a password which you can then use to access the merchant portal.

  • You can create as many additional users as you require on your merchant account.

  • We'll then create you some merchant credentials which you can use to access our sandbox environment. These will be in the form of a Customer ID and secret (the equivalent of a username and password for accessing our API).

Step 2. Register your first application

Once you've got a merchant account, you'll need register an application that you'll use to access the Volt API. This could be a website, mobile app, or any other application you'll be using to consume API resources.

  • This can be done by going to the applications section of the merchant portal. The application you create will be referred to as a client in terms of authenticating using oAuth. The two terms (client and application) are therefore interchangeable in this documentation.

  • We'll give you a Client ID and a secret. You'll need to use both Client ID and secret, along with your merchant credentials, to access the Volt API.

  • Make a note of the secret as you'll only be able to retrieve it once - so keep it secure. If your secret becomes 'not secret' any more, you can generate a new one from the Volt merchant portal.

Step 3. Register your redirect URLs

Once your customer has completed the payment experience it will result in either a success or a failure and we'll redirect them to the appropriate URL on your website if required. This is not required for an app, where you're redirecting the user to a webpage.

  • Register your success URL - this is where the customer will be redirected to once a payment has been confirmed as sent.

  • Register your failure URL - this is where the customer will be redirected if a payment fails or if the customer cancels at any point in the process.

  • Register your pending URL - this is where the customer will be redirected if a payment is left in a pending state for any reason, where it's neither successful or failed but it waiting for.

Note These could be the same URL, in which case, please just copy and paste the same value into each box. We'll send the same details including a status code, to whichever URL we redirect your user to, so that you can identify whether the payment was a success or not.

Step 4. Prepare to receive payment status notifications

IMPORTANT STEP!

The customer being redirected to a success or failure URL should not be taken as confirmation that a payment has succeeded or failed.

  • Just before we redirect your customer to the success or failure URL, Volt will POST a digitally signed status notification to your chosen URL.

  • This message will be signed with a secret notification key which you can retrieve and change from Fuzebox.

  • You'll need to confirm that you have checked the signature and that you accept the notification.

How to setup notifications

  • Head to Fuzebox and find the application you set up in step 2.

  • Register your notification URL for your application - this is the URL that we'll POST a notification message to and should start with https:// (i.e. it must be a secure URL).

  • Register a notification failure email address - this is the email address we'll send a notification to should we be unable to deliver notifications to your URL.

  • Retrieve or change the notification secret - if this secret ever becomes known, you should change it immediately.

  • Test your notification setup by clicking on the send test button. We'll send a signed notification to you and process your response.

Responding to a notification

Once you've received a payment notification you'll need to check the signature is valid and respond with either a 200 (OK) or 400 (Bad Request).

  • If we receive no response we'll keep trying to send you the notification up to 4 more times at 1 minute intervals

  • If we fail to send a notification 5 times we'll send an email to your notification failure email address. Please note that you'll only receive an email for the first notification failure.

  • If you've sent us a 400 (Bad Request) response, we'll send an email to your notification failure email address - again only the first time this happens.

  • If notifications are failing, we'll switch notifications off until you confirm, via Fuzebox, that you have sent and received a test notification.

  • Once you've identified the issue, you can re-send any failed notifications from Fuzebox.

Step 5. Authenticate with the Volt API

To use the Volt API you'll first need to use your secure credentials to authenticate and retrieve an access token.

The Volt API uses the oAuth2.0 standard for authentication.

Getting an access token

  • Authenticate by POSTing to the /oauth endpoint.

  • You'll need to use your Client ID and secret, in combination with the API Username and password which you can retrieve from the Volt merchant portal.

  • The Client ID should be set in the client_id field and the secret in the client_secret field.

  • The value of the grant_type field should be password

  • For formatting guidelines, please see the API documentation for the oAuth2 Authentication endpoint.

  • Once you've successfully authenticated, you'll be returned an access token in the response, which you'll then use as authorisation for your subsequent API calls.

Using your token to access the rest of the API

To use the rest of the Volt API you'll need to send the access token in a header called Authorization, with the format Bearer {token}, for example :-

Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ2MmFQNDdIQXVTUi1 ...

Requesting your first payment

Now you're authenticated and have an access token, you're ready to make your first Open Banking payment.

Step 1. Pull the list of supported banks

To get a list of banks that we currently support for payment initiation, send a GET request to the /banks endpoint. The list is provided in Json format and will contain an id you'll need when initiating your payment from that bank.

You should start by using one of the model test banks on the sandbox API. In the sandbox bank list that's all you'll see by default. On the production bank list they're hidden by default but can be obtained by calling the list by changing the real parameter to false in the URL.

GET /banks/?real=false

For sandbox, we suggest you use Ozone or Wood Bank to make test payments in GBP first. Once you're happy that your integration works, you can move on to adding more accounts and currencies to test.

Step 2. Pull the list of your test bank accounts

We've created you a test bank account to send payments to in GBP. Send a GET request to the /accounts endpoint. The list is provided in Json format and again will contain the id you'll need when initiating your payment.

Step 3. Send a payment initiation request

  • You can initiate a payment request from your customer by POSTing a payment initiation request to the /payments endpoint as detailed below.

  • NOTE that the amount should not include any decimal places but should be an integer number in the minor currency unit - that is cents, pence etc, rather than dollars, euros or pounds.

  • If your request was successful, the response from this endpoint will contain a 201 Created status and the body will contain a json object with details of the payment, which will include a unique identifier (UUID) in the id field.

  • We can now send your customer to their bank, so let's begin the the Volt checkout process for your customer.

  • You'll need to grab the ID we returned and base64 encode it. Then redirect your customer's browser to the Checkout by Volt page - for the sandbox :-

https://checkout.sandbox.volt.io/{token}

where {token} is a base64 encoded version of the ID of your payment.

Setting the language for the checkout page

To set the language that the checkout page is displayed in, add the preferred language to the path as follows :-

https://checkout.sandbox.volt.io/{language}/{token}

where language can be one of :-

  • bg - Bulgarian
  • de - German
  • en - English
  • es - Spanish
  • fr - French
  • hr - Croatian
  • it - Italian
  • lt - Lithuanian
  • lv - Latvian
  • nl - Dutch
  • pl - Polish
  • pt - Portuguese
  • ro - Romanian
  • sk - Slovak

Step 4. The customer journey

  • Your customer will be shown the details of the payment they're about to make and confirm that this is their intent.

  • Once they've confirmed, they'll be taken to their bank's authentication page to complete the payment, where they'll need to authenticate using their normal bank security procedure. This procedure varies from bank to bank and may need the customer to provide 2-factor authentication via their phone or hardware device.

  • Your customer will then review the payment and may have to select the account they'll make the payment from. This part varies from bank to bank.

  • Once the customer has confirmed the payment and it's been made, Volt will show your customer a quick confirmation and redirect them back to your website or application (the success URL you defined on Fuzebox)

  • At this point we'll also POST to your notification URL and process your response. You can see more details about this below.

Note

  • Other outcomes at this point might be that the payment was not authorised, the payment could not be completed for some reason or, for corporates, that we're waiting for another person to also authorise that payment.

Step 5. Returning to your website or application

Once the customer has returned to your website, their Volt journey is complete.

  • We'll send a single field called volt in the querystring to your appropriate return URL (success, failure or pending).

  • This field contains the same base-64 encoded Json string comprising 3 fields like this, regardless of the URL we redirect to :-

{
  "id": "{Volt's payment UUID}",
  "uniqueReference": "{your id for the payment}",
  "status": "{COMPLETED|FAILED|PENDING}"
}

Payment notifications

Important!

You should not trust the fact that a customer has reached your payment success URL, but ensure you wait until you receive a digitally signed notification via this webhook from Volt.

Signed notifications

If you get a notification from Volt, it’ll be signed using a secret notification key that's unique to your app, so that you can verify that it’s come from Volt. You shouldn’t process any message that appears to originate at Volt without performing this verification step.

  • To sign the notification, we’ll first generate a notification secret and share it with you via Fuzebox.

  • You’ll get a different secret for each client application you use to access Volt.

  • And it will be different to the client secret you use to identify your client to the API.

  • If you think your notification secret is not so secret any more, no problem, you can generate a new one on Fuzebox.

What the signature contains

The Volt signature is created by combining your notification secret with the body of the notification, and a timestamp. It won’t contain any useful, sensitive or personal information.

  • On each notification request that we send you, we’ll include a custom HTTP header called X-Volt-Signed, which will contain the Volt signature.

How the signature works

  • You will get a POST message from Volt to your preconfigured notification URL.

  • You’ll then need to calculate what you think the signature should be, based on the body of the notification itself and your notification secret.

  • You’ll then check that the Volt signature you received in the X-Volt-Signed header of the notification matches the signature that you calculated.

  • If they match, return an empty HTTP response with a status code of 200 (OK)

  • If they don’t match, then you should return an empty HTTP response with a code of 400 (Bad Request) and do not process the notification.

Verifiying the signature

Calculating the verification hash for a signature is based on three things, which are all included as part of the notification.

  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 version, which is the part after the word Volt

  3. You'll then need to combine X-Volt-Timed with the notification body itself and the version

  4. Concatenate these items in that order (body|time|version) using a pipe (|) delimiter – this is exactly how we create the signature before we send it so you can be sure that if you create your version the same way, they will match.

  5. Hash the check string with HMAC SHA256, using your notification secret.

  6. And then compare your signature to the value in the notification’s X-Volt-Signed header.

Notification content

The body of the notification contains a Json formatted data structure containing 4 fields; payment (our ID), reference (your id), amount (of the payment) and status (COMPLETED, FAILED, PENDING)

{
  "payment": "00000000-0000-0000-0000-000000000000",
  "reference": "Invoice-12345",
  "amount": 1000,
  "status": "COMPLETED"
}

PLEASE NOTE

At the moment, banks do not supply Volt with any personally identifiable information about your customer.

The PENDING status

If the status returned in the notification is PENDING, it means that the payment has not yet been confirmed by the customer's bank. This may be for a number of reasons and you should not count on receiving the funds until the status changes to COMPLETED.

  • As an example, the customer's bank may have encountered a delay in processing payments or the account used might require a second person to approve payments.

  • If Volt is made aware that the payment status has changed, we'll send another notification to you with the final status. The payment status could therefore change to COMPLETED or FAILED.

  • You may also poll us for status changes periodically using the GET /payments/{id} endpoint.

Not receiving notifications?

Volt will try to deliver the notification up to 5 times, hoping to get a 200 (OK) response from you. We'll leave a few seconds before we try sending again, in case it was a technical glitch at your end, or somewhere in the middle. The first retry will be after 3 seconds, the next after 6 seconds, 10 seconds, 15 seconds and 30 seconds.

If we fail to deliver any notification 5 times then

  • We’ll assume there's a technical issue somewhere between Volt and you - and we'll stop sending you all notifications temporarily.

  • We’ll send an email to your technical and/or primary contact, plus we'll raise a support ticket at Volt on your behalf.

  • If we don’t hear from you to let us know the problem is fixed, then someone from Volt will be in touch.

  • If it's a problem your end then, once you've fixed the issue, go into Fuzebox and send a test notification (see below) to yourself and if that works we'll automatically switch notifications back on.

Don't worry, we'll send you any notifications you may have missed, once we know you're able to receive them.

Sending test notifications

You can request a test notification from the Applications section of Fuzebox.

  • We'll send a test notification to your configured URL

  • All you need to do when you receive the notification is respond with either a 200 or 400 status code, as appropriate.

  • Once we receive a 200 response for you, then we'll start to send you live payment notifications

  • This function also acts as a trigger to restart notifications if they've been stopped after we've failed to deliver them to you.

No payment notifications?

Let's do a few quick troubleshooting checks for some common causes...

  • Have you sent a test notification to the correct URL and responded to it with a HTTP 200 status?

    • We won't start (or restart) sending 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 you're still not receiving payment notifications, then please get in touch with our support team and we'll get to the bottom of it!

If you're making payments and not receiving the notifications, we'll automatically store and buffer those notifications so you'll never miss one. Once we've figured out what's wrong, all the notifications you missed will be sent (unless you ask us not to of course!)

Going into production

Step 1. Switch on production mode!

You'll need to enable your Volt system for production use, which you can do in Fuzebox.

Step 2. Register at least one real bank account

To request a payment on the production system, you'll need to have at least one real bank account registered for payments to be sent to.

  • You can do this online at Fuzebox

Step 3. Test your production integration!

Make sure that everything works!

  • Give it a test with the model banks first - you can still use them in production, just make sure you request the bank list with a query parameter of real=false.

  • Make some small test payments to your live bank account.

  • If you have multiple accounts or multiple currencies setup, test them all to make sure that the payments are routing in to the accounts you're expecting them to.

  • Test your notifications - make sure they work - both from a test and live payment point of view.

Step 4. Go live!

When you're happy, put your new checkout live and start taking payments using Open Banking.

Filtering lists

In endpoints that return a list, we offer various ways of filtering the information returned, depending on the field type. Filterable fields are listed in the relevant endpoint documentation.

Equal to =

  • For all field types you ca