Payment request

The first step in the payment process is sending a request for payment initiation. When you place this request, we’ll validate the details you provided and, if there aren’t any discrepancies, send you an ID that you can use to track the payment throughout its lifecycle.

Initiate a payment request

Request location

Payments can be requested from either the Sandbox or Production environment. We recommend starting with Sandbox, where you can choose one of the model banks and test the end-to-end process without making real payments.

  • Sandbox
  • Production
POST https://api.sandbox.volt.io/v2/payments
POST https://api.volt.io/v2/payments

Request headers

Supply an Authorization header containing your access token, and an appropriate content-type.

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijc2MGEwNDRkMDkwZmUxNmE0YzRkMWRjMWE5NDU1MTgxMzgxZDRkNDIyZGUyNDY5NjQ0NDI4NWNkZjk1NWJkMzBjMjcxYzYxNjE0MzkyMmI0In0
Content-type: application/json

Request body

If you’d like the payer to select their bank on the Volt hosted checkout (our preferred option), the payment request requires four key pieces of payment information, the currency, payment amount, type of purchase the payer will be making and a unique reference for the payment, plus the reference you use to identify the payer in your system.  

If the payer will pre-select their bank on your website or app, you should pass the ID of the payer’s bank to this endpoint in a field called bank. This should be supplied as a uuid, a list of which can be found in the response from the GET /banks endpoint.  Passing the bank ID in the request will prevent the payer selecting a country or bank on the Volt checkout page.

Payment fields
  • Regular checkout
  • With pre-selected bank
{
  "currencyCode": "GBP",
  "amount": 12345,
  "type": "OTHER",
  "uniqueReference": "test54321",
  "payer": {
    "reference": "u59kt9yh",
    "email": "john.smith@example.com",
    "name": "John Smith",
    "ip": "192.168.0.1"
  }
}
Field Status Description
currencyCode Required The three-letter ISO code for the payment currency.  A complete set of ISO currency codes can be found here.
For testing purposes, we suggest you start with a payment that uses the GBP currency.
amount Required Should be specified in minor units (cents, pence etc), with no decimal point.  
In the example, £123.45 is being requested, so is formatted as 12345 in the payment request.
type Required This indicates the purpose of payment.
Available options are BILL, GOODS (for physical goods only), PERSON_TO_PERSON, SERVICES or OTHER.
uniqueReference Required Create a reference of up to 18 characters, using letters and numbers only.
Each payment requires a unique reference and, to prevent duplicate payments, we’ll automatically reject requests where you’ve used the reference before.
{
  "currencyCode": "GBP",
  "amount": 12345,
  "type": "OTHER",
  "uniqueReference": "test54321",
  "bank": "017a72d2-82bb-4d0e-8306-f2d1b86b9c75",  
  "payer": {
    "reference": "u59kt9yh",
    "email": "john.smith@example.com",
    "name": "John Smith",
    "ip": "192.168.0.1"
  }
}
Field Status Description
currencyCode Required The three-letter ISO code for the payment currency.  A complete set of ISO currency codes can be found here.
For testing purposes, we suggest you start with a payment that uses the GBP currency.
amount Required Should be specified in minor units (cents, pence etc), with no decimal point.  
In the example, £123.45 is being requested, so is formatted as 12345 in the payment request.
type Required This indicates the purpose of payment.
Available options are BILL, GOODS (for physical goods only), PERSON_TO_PERSON, SERVICES or OTHER.
uniqueReference Required Create a reference of up to 18 characters, using letters and numbers only.
Each payment requires a unique reference and, to prevent duplicate payments, we’ll automatically reject requests where you’ve used the reference before.
bank Required A uuid representing the bank the payer wants to use.  Sending this parameter will lock the country and bank selection on the Volt checkout page.
Payer identification fields

The Volt payment process also requires you to include additional information about the payer.  The minimum we require is payer.reference, the unique ID you use to identify the payer in your system.  You may also include the payer’s name, email address and ip address if you’re using Circuit Breaker, our fraud prevention plugin. 

Field Status Description
reference Required This should uniquely identify the payer in your system, and can be between 3 and 36 alphanumeric characters.
email Optional A valid email address for the payer, up to 255 characters.
name Optional The payer’s full name, also up to 255 characters.
ip Optional The payer’s IP address, in IPV4 format (xxx.xxx.xxx.xxx)

Additional callback redirect parameters

You can specify any custom parameters you’d like us to set in your redirect URLs by specifying a callback parameter, containing the values you’d like us to pass back in parameter=value format like this :-

"callback": "order_id=662384a0&sample=parameter"

Sample payload with callback parameter
{
  "currencyCode": "GBP",
  "amount": 12345,
  "type": "OTHER",
  "uniqueReference": "test54321",
  "bank": "017a72d2-82bb-4d0e-8306-f2d1b86b9c75",
  "callback": "order_id=662384a0&sample=parameter",
  "payer": {
    "reference": "u59kt9yh",
    "email": "john.smith@example.com",
    "name": "John Smith",
    "ip": "192.168.0.1"
  }
}

When we redirect the payer to your success, failure or pending URLs, we will include the parameters and values you specified, alongside the payment information, like this :-

http://success.url?order_id=662384a0&sample=parameter&volt={payment_information}

Reserved callback parameter name

We’ll ignore the value of any callback parameter named volt, as it’s the reserved name for the payment information we pass back.

Responses

Successful request

If the payment request was successful, you’ll be returned a 201 Created status with an ID and a checkout URL. You’ll need this information in the next step, redirecting to Volt

201 Created
{
  "id": "93b85f3c-76eb-4316-b1ae-f3370ddc59bc",
  "checkoutUrl": "https://checkout.volt.io/{paymentId}?auth=jwtToken"
}
International variants
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.

 

Unsuccessful request

If the payment request wasn’t successful, you’ll see one of the following response codes, instead of 201

Code Meaning Action
400 Bad request Check the body of your request to make sure it’s valid Json and that you’ve supplied all the required fields.
401 Not authenticated Check that you have included the Authorization header containing a valid access token.
404 Not found Check that you’re posting to api.volt.io/v2/payments for the production environment, or api.sandbox.volt.io/v2/payments for sandbox.

Need help?

If your payment request is not being accepted, or you need help implementing any other feature of our API, we’re here to help.  Please send an email to our support team and we’ll get back to you as soon as we can.