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

Do you need help? Do you have any suggestions? Message us!

If you need any 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

This feature is available only in our Fuzebox closed Beta.

If you are not yet signed up to our Beta program, please send a request to support@volt.io with following information:

  • Your name
  • Your email address

Once your merchant account is created we will come back to you with credentials you can use in Fuzebox and move to the next step.


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

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

  • 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 to 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 under Configuration section of the Fuzebox.

application image

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.

create_application image

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.

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 Client Secret. You'll need to use both Client ID and Client 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 Fuzebox.

Step 3. 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

  1. Head to Fuzebox and find the application you set up in step 2. Navigate to Notification section and click Configure notifications.

    • 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

    configure_notification

    Once you configured your notification URL and failure email address test your notification setup by clicking on the Send a test notification button. We'll send a signed notification to you and process your response

  2. If your Notifications secret ever becomes known, you should change it immediately - you can do that by clicking Generate a new notification secret in Notifications section on Fuzebox

Responding to a notification

  • If we receive no response we'll keep trying to send you the notification up to 5 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-enable and re-send any failed notifications from Fuzebox by clicking button Send a test to restart notifications.

Step 4. 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 Client Secret, in combination with the API Username and password which you can retrieve from the Fuzebox.

  • The Client ID should be set in the client_id field and the client 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.

GET /banks

For sandbox, we suggest you use Ozone Modelo Test Bank 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. Hit the /accounts endpoint to get list of test accounts.

GET /accounts

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 in Payments section in this documentation.

POST /payments
{
  "currencyCode": "GBP",
  "amount": 12345,
  "account": "insert your account ID",
  "type": "GOODS",
  "uniqueReference": "sa123456798",
  "bank": "insert your bank ID"
}

create_payment image

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 the ID of your payment.

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
  • ce - Czech
  • de - German
  • en - English
  • es - Spanish
  • fr - French
  • hr - Croatian
  • hu - Hungarian
  • it - Italian
  • lt - Lithuanian
  • lv - Latvian
  • nl - Dutch
  • pl - Polish
  • pt - Portuguese
  • ro - Romanian
  • sl - Slovenian
  • 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.

    checkout_payment image

  • 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).

  • 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}"
}

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.

NOTE: Please do not forget to configure a test notification case so you respond with 200 (OK) status code. In this case you will need to treat a content as an empty string: |time|version

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

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

Remember to set proper data for test signature as it is described in Verifiying the signature section

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

  • 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 can filter by an exact value using a standard query parameter

    ?amount=12345

Greater than / after [gt]=

  • For numeric fields, amounts greater than a value

    ?amount[gt]=12345

  • For date fields, dates later than a given date

    ?createdAt[gt]=20201205

Greater than or equal to / on or later than [gte]=

  • For numeric fields, amounts greater than, or equal to, a value

    ?amount[gte]=12345

  • For date fields, dates on or later than a given date

    ?createdAt[gte]=20201205

Less than / before [lt]=

  • For numeric fields, amounts greater than a value

    ?amount[lt]=12345

  • For date fields, dates later than a given date

    ?createdAt[lt]=20201205

Less than or equal to / before or on [lte]=

  • For numeric fields, amounts less than, or equal to, a value

    ?amount[lte]=12345

  • For date fields, dates on or later than a given date

    ?createdAt[lte]=20201205

Any in a set of values []=, []=

  • Specify the same field more than once in the query string with [] and each value you want to filter by (exact matches only)

    ?status[]=success&status[]=pending

Not equal to a single value [not]=

  • To return values that are not equal to an exact value

    ?status[not]=pending

Not equal to a set of values [][not]=

  • To return values that are not equal to more than one exact value, specify the values in an array by adding the same field multiple times, but with an extra flag of [not].

    ?status[][not]=pending&status[][not]=failed

Sorting lists

For list endpoints, you can specify the sort order by certain fields.

Sort order

  • ASC

    • Numerical from lowest first
    • Text in alphabetical order
    • Dates from earliest first
  • DESC

    • Numerical from highest first
    • Text in reverse alphabetical order
    • Dates from latest first

To sort by a particular field

  • Specify the order parameter and the field name in square brackets and the sort order

    /accounts?order[createdAt]=ASC

To sort by multiple fields

  • specify the order parameter more than once and your data will be sorted in the same order as the parameters

    ?order[createdAt]=ASC&order[name]=DESC

Authentication

oauth

OAuth2 password Grant

Security Scheme Type OAuth2
password OAuth Flow
Token URL: /oauth
Scopes:
  • client -

    client

  • consumer -

    consumer

  • merchant -

    merchant

  • admin -

    admin

Payments

Payments via Open Banking by Volt.

Request for a new payment

This is the first step to making a payment with Volt. Submit the details of the payment you'd like to initiate and we'll validate that this is a payment we can support.

We'll require the following information:-

  • The 3 letter code for the currency you want the payment made in

  • The amount of the payment - this should be a whole number, in minor units (cents, pence etc) rather than dollars, euros, pounds

  • The UUID of the account you'd like the payment sent to

  • A unique reference for this payment.

  • The UUID of the bank the customer would like to pay from - get a list of banks from the /banks endpoint.

Authorizations:
Request Body schema: application/json

Details of the payment you'd like to initiate

currencyCode
required
string 3 characters

Currency in which the payment was requested, in ISO 4217 format (3 uppercase letters)

amount
required
integer

The amount of the transaction in 1/100 units (pence, cents etc)

account
required
string

UUID of the destination bank account for the payment

type
required
string
Enum: "BILL" "GOODS" "PERSON_TO_PERSON" "OTHER" "SERVICES"

The transaction type (these are predefined)

uniqueReference
required
string

Unique reference for the payment from the merchant

bank
required
string <iri-reference>

UUID of the bank selected to originate the payment

callback
string

Query string which will be returned to the merchant

Responses