Skip to main content

Request a payment

This is the first step in the Volt payment process. We'll validate the details of the payment you want to request and, if it's all OK, return you an ID you can use to track the payment through the Volt journey.

Initiate a payment request#

Request location#

At the moment, you should start with the sandbox environment, with one of the model banks. You won't be able to make real payments on sandbox but you can test the end-to-end process.

POST https://api.sandbox.volt.io/payments

Request header#

You should specify a content-type header in your request as follows

Content-type: application/json

Request body#

The body of your request should be in Json format, containing the following fields. For testing, we suggest you start with a GBP payment.

If you're using the Volt checkout, you need to provide basic payment details. When you redirect your customer to the Volt checkout, we'll ask them to select which bank they would like to send the payment from.

{
"currencyCode": "GBP",
"amount": 12345,
"type": "OTHER",
"uniqueReference": "test54321",
"payer": {
"reference": "johndoe"
}
}

Request fields#

currencyCode should be a 3-letter code in ISO 4217 format - for example GBP, EUR, USD.

amount should not include any decimal places but should be an integer number in the minor currency unit - that is cents or pence, rather than dollars, euros or pounds. In the example, we're requesting £123.45.

type should be one of BILL, GOODS, PERSON_TO_PERSON, SERVICES or OTHER - choose the most appropriate code for the payment you're requesting.

uniqueReference should be a maximum of 18 characters and should contain letters and numbers only. As implied, you cannot use the same reference for multiple payments.

payer should include at least the reference field which uniquely identifies a user in your system.

Payer identification#

When creating a payment, you can optionally include additional information about the payer.

{
...
"payer": {
"reference": "u59kt9yh",
"email": "john.smith@example.com",
"name": "John Smith",
"ip": "192.168.0.1"
}
}

Request fields#

reference should be a min 3 and maximum of 36 characters and should contain letters and numbers only. It should uniquely identify a user in your system.

email (optional) The email of the payer. It should be a valid email, a maximum of 255 characters.

name (optional) The full name of the payer. It should be a string, a maximum of 255 characters.

ip (optional) The IP of the payer. Should be a valid IPv4 string.

Response#

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. You'll need the ID in the next step.

{
"id": "93b85f3c-76eb-4316-b1ae-f3370ddc59bc"
}

Didn't get a 201 status?#

  • If you got a 400 error, check the body of your request to make sure it's valid Json
  • If you got a 401 or 403 status, check that you're authenticated and that you passed the Authorization header containing a valid access token.
  • If you got a 404 error, check you're posting to the correct /payments URL

Any other problems, please contact us on support@volt.io