Integrate Volt's hosted checkout
There are 3 essential steps for the hosted payment process.
- Request a payment via the API
- Redirect the shopper to the Volt hosted checkout
- Finalise the process back at your website or app
Checkout v3 Beta is now available for merchants in the UK
Please ask your integration specialist for details of our Beta test programme
The initial screen displayed in the hosted checkout flow for UK shoppers now varies based on the shopper’s history and whether you provide bank information.
- First-time shopper with no
Bankprovided – we’ll show a welcome screen outlining how Volt works in three steps. The shopper will be able to select their bank using our beautiful new visual bank list. - First-time shopper with
Bankprovided – we’ll show a welcome screen with information on Volt’s operation in three steps, but the first step is adjusted to ‘review your payment’ instead of ‘select a bank’ - Returning shoppers – we’ll show a summary screen, bypassing the welcome and bank selection screens, but allowing the shopper to change their bank if desired.
You don’t need to do anything extra to enable Checkout v3 Beta, we’ll automatically show the new interface for shoppers paying in GBP and the current v2 interface for shoppers paying in EUR.
Request a payment
Authentication
You should authenticate with the API first to obtain an access token, which you’ll need in order to request a payment.
Find out more about API Authentication
Request header and body
The details of the request header and body are described in our API docs.
Shopper reference
The shopper.reference is used by our systems to identify returning shoppers. It should follow an identifier you already use – a user id for example. If you intend to use sensitive data here, we suggesting hashing it before sharing it with Volt.
Identifying returning shoppers using this reference is especially useful for Circuit Breaker as it allows you to configure rules and limitations for specific shoppers to prevent abnormal or unwanted behaviour.
🇦🇺 In Australia we use this information to show the correct user interface for our one-click checkout.
Additional callback redirect parameters
You can define a string of parameters in callback. Volt appends this string to the payment return URLs. For example:
"callback": "order_id=662384a0&sample=parameter"
Reserved parameter names
Please don’t use the parameters volt, volt-signature and volt-timestamp in your callback as these are reserved for Volt use. If you do send values for these parameters, they’ll be overridden with our data.
Find out more about return URLs
Request details
Select the country you want to integrate to view a sample request…
- EU and UK
- Brazil
- Australia
Required header
You must include the following header (in addition to the Authorization header you already provide).
| Header name | Value |
|---|---|
X-Volt-Api-Version |
4 |
Using this header will take your shopper to our new v3 checkout experience for payments in GBP. For EUR payments, shoppers will see the v2 checkout for now.
Body
{
"currencyCode": "GBP",
"amount": 100,
"type": "OTHER",
"uniqueReference": "99f43dc4-4db2-4442-a50a-286a242cc91c",
"bank": "9dbb9844-8af8-4e78-8752-13f7ba32792f",
"bankEditable": "true",
"shopper": {
"reference": "3316dbbe-7aae-406b-9233-31134cecad33",
"email": "johnny.cage@example.com",
"firstName": "Johnny",
"lastName": "Cage",
"ip": "150.160.170.180",
"documentId":"07127669600123"
},
"summaryDetails": [
// label & value limited to 15 characters each line
{ "label": "Dates", "value": "28 - 31/07/2023" },
{ "label": "Category", "value": "Car Rental" },
{ "label": "Description", "value": "Fiat 500 size" },
{ "label": "Pickup", "value": "Heathrow T1" }
],
"callback": "order_id=662384a0&sample=parameter"
}Field notes
bank(uuid, optional) allows you to pass a pre-selected uuid for the shopper’s bank. If you know the bank for a returning shopper, you could supply this to improve their user experience. This field has no impact on AUD payments as we don’t show a bank list in Australia.shopper(object, required): Includes shopper’s reference*, email, first name*, last name*, IP address, document ID. The contents of this object have changed from previous versions of the checkout. Fields marked * are required in this object.
New fields for Checkout v3 Beta
bankEditable(boolean, default false) is a new field for v3 of the checkout. It allows you to control whether the shopper can change thebankprovided in this request.- If a value for
bankis provided, the default value ofbankEditableis false, unless you choose to override it. - If a value for
bankis not provided, the default value ofbankEditableis true. - If a value for
bankis not provided and you set this to false, you will receive an error code 400 as the shopper will not be able to select a bank.
- If a value for
summaryDetails(object, optional) allows you to add up to 5 custom keys and values which will be displayed on the payment summary screen. Each label and value is limited to 15 characters.
| View request in API docs | Try in our Postman Collection. |
Response – EU and UK
{
"id": "93b85f3c-76eb-4316-b1ae-f3370ddc59bc",
"checkoutUrl": "https://checkout.volt.io/93b...df6"
}Header
No additional headers are required for Brazil.
Body
{
"currencyCode": "BRL",
"amount": "10000", // e.g. sending 10000 represents BRL 100.00)
"type": "BILL", // or any other type supported in Brazil, according to your business profile (Goods, Bill, Other, Services)
"uniqueReference": "123456789", // Unique reference for the payment from the merchant, must contain only alphanumeric characters
"validityPeriod" : 30, //Acceptable values for the validity period are 1 (1 minute) to 43,200 (30 days). This will enable you, for example, to print a QR code on an invoice which the end user will be able to scan at a later date to pay.
"shopper": {
"reference": "user-123", // Your unique reference for the shopper, can contain alphanumeric characters plus selected symbols as shown in the pattern
"documentId": "60898021669", // Customer CPF/CPNJ number
"firstName": "Joe",
"lastName": "Smith"
}
}Response – BR (Brazil)
{
"id": "340e4522-11b1-4a15-ac3c-73c7cbd91c51",
"checkoutUrl": "https://checkout.volt.io/340...pgA",
"qrString": "000...26E"
}Note
The response for Brazil will also contain a parameter called qrString which is used to generate the QR code for Pix.
Required header
You must include the following header (in addition to the Authorization header you already provide).
| Header name | Value |
|---|---|
X-Volt-Api-Version |
4 |
Body
{
"currencyCode": "AUD",
"amount": 10000, // The amount of the transaction in 1/100 units (pence, cents etc)
"type": "OTHER", // Or any other type supported in Australia, according to your business profile
"uniqueReference": "123456789", // Unique reference for the payment from the merchant, must contain only alphanumeric characters
"additionalDescription": "Purchase for new shoes at Shoes.com - brand ABC", // Payment description allowing you to pass some additional data. It is sent to PayTo platform, and presented in the shopper's bank as the payment and payment agreement description. ASCII-printable characters only.
"ultimateBeneficiary": "Billie Jean Senior", // The ultimate creditor name, string of 1-140 characters
"shopper": {
"reference": "user-13489", // Your unique reference for the shopper, can contain alphanumeric characters plus selected symbols as shown in the pattern
"firstName": "Billie",
"lastName": "Jean"
}
}Notes
shopper(object, required): Includes shopper’s reference*, email, first name*, last name*, IP address, document ID. The contents of this object have changed from previous versions of the checkout. Fields marked * are required in this object.additionalDescription(string, required just for AUD payments): Value that represents agreement’s and payment’s description that will be shown to shopper at his bank. Should contain ASCII-printable characters only. Refer to the Australian integration guide for more details.-
ultimateBeneficiary(string, required for certain use cases): The name of the ultimate beneficiary of the payment. For example, for remittance payments this would be the ultimate recipient of the remitted funds.
Response – AU (Australia)
{
"id": "93b85f3c-76eb-4316-b1ae-f3370ddc59bc",
"checkoutUrl": "https://checkout.volt.io/93b...df6",
"token": "eyJ0eXAi......_P7cbShc"
}Redirecting the shopper
A successful payment request returns an id alongside the checkoutUrl. This id is a unique identifier for this payment once it is created. We recommend storing it in your system for any future reference.
You should redirect your shopper immediately to the checkoutUrl. This allows the shopper to complete the payment fast and complete the purchase.
Brazil
If the payment is a Pix payment, in BRL, the response will also contain a parameter called qrString. For further information on instant payments in Brazil, see our guide to PIX payments.
Returning the shopper to you
Once the payment is complete, we’ll return the shopper back to your website or app.