Payment request

The first step in our payment process is requesting the money. When you place the request, we’ll validate its details and, if there aren’t any discrepancies, send you an ID that you can use to track the payment throughout the Volt journey.

Initiate a payment request

Important note!

The below URL is for payments V2. For payments V1, the URL doesn’t have ‘v2’ in the path: https://api.sandbox.volt.io/payments

Request location

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

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.

Request header

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

Content-type: application/json

Request body and fields

The Volt checkout requires only basic payment details: currency, payment amount, type of purchase, and unique reference.

If you’re not using the Volt checkout, your customer’s bank ID will also be required in UUID form. It can be found in the GET /banks response.

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

The body of your request should be in JSON format, containing the following fields (for testing, we suggest you start with a payment that uses the GBP currency):

The request fields are as follows:

  • CurrencyCode: A three-letter code using the internationally recognised ISO 4217 format. For example, GBP instead of pounds, USD instead of American dollar, and EUR instead of euro
    Amount: This needs to be written without any decimal places. In the example, £123.45 is being requested, so is written as 12345. If the sum was £1234.50, it would be written as 123450
  • Type: This indicates what the payment is for. You choose the most appropriate code from BILL, GOODS (for physical goods only), PERSON_TO_PERSON, SERVICES or OTHER
  • UniqueReference: Create a reference of up to 18 characters, using letters and numbers only. Each payment requires a unique reference, and the same one can’t be used more than once
  • Bank: Required if you aren’t using the Volt checkout, this is the ID of the bank that your customer is sending their payment from

Payer identification and request fields

The Volt payment process also requires you to include additional information about the payer. You can include the following:

  • Email: A valid email address for the payer, up to 255 characters
  • Name: The payer’s full name, also up to 255 characters
{
    ...
    "payer": {
        "reference": "u59kt9yh",
        "email": "john.smith@example.com",
        "name": "John Smith",
        "ip": "192.168.0.1"
    }
}
  • Reference: This is optional unless a name or email have been provided, in which case a reference is required. It should uniquely identify a payer in your system, and must be between three and 36 characters using numbers and letters only

Response

{
  "id": "93b85f3c-76eb-4316-b1ae-f3370ddc59bc",
  "checkoutUrl": "https://checkout.volt.io/{paymentId}?auth=jwtToken"
}

If the payment is in BRL, the response will also contain:

{
  "qrString": "valueOfQrString"
}

If the payment request was successful, you’ll see a 201 Created status with:

  • "checkoutUrl": "https://checkout.volt.io/{id}". You’ll need this ID in the next step, redirecting to Volt

Didn’t get a 201 Created status? If the payment request wasn’t successful, you’ll see one of the following error statuses:

  • 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 that you’re posting to the correct /v2/payments URL of api.volt.io/v2/payments for a Production URL, and api.sandbox.volt.io/v2/payments for a Sandbox URL

If you’re still experiencing issues, please send us an email: support@volt.io.