Home › Connect › Refunds via the API

Checking eligibility

Before you request a refund you should check whether a refund can be given for the payment.  Examples of where a payment may not be eligible could be if you’ve already processed a full or partial refund, or its status is neither RECEIVED or SETTLED. 

Request location

  • Sandbox
  • Production 
GET https://api.sandbox.volt.io/payments/{paymentId}/refund-details
GET https://api.volt.io/payments/{paymentId}/refund-details

Response

The response will contain the following information if the refund is available:

{
  "refundAvailable": true,
  "remainingDays": 365,
  "availableAmount": 500,
  "refundedAmount": 0,
  "numberOfRefunds": 0,
  "message": null,
  "code": null
}

Or a message and code if it’s not:

{
  "refundAvailable": false,
  "remainingDays": 365,
  "availableAmount": 0,
  "refundedAmount": 500,
  "numberOfRefunds": 1,
  "message": "Payment with id: 0da43922-e01d-4c7f-8a63-0d8da56459be has been fully refunded.",
  "code": "PaymentRefundBalanceIsNotAvailable"
}
Response fields
refundAvailable a flag that tells you whether a refund can be created for this payment
remainingDays the number of days before a refund can no longer be processed
availableAmount the amount that can still be refunded
refundedAmount the corresponding amount that has been refunded already
numberOfRefunds the number of refunds applied to the original payment
message optional field that will contain detailed information about why you cannot create a refund for this payment
code optional field that will contain a code for why you cannot create a refund for this payment
Error codes
PaymentRefundBalanceIsNotAvailable Refund could not be processed due to insufficient funds in the Connect account

Requesting a refund

To request a refund via the API you need to use the endpoint below.

If you wish to fully automate the creation and approval of these requests, then the API requests must be signed using a private key, for more details on this please refer to here. 

Request location

  • Sandbox
  • Production 
https://api.sandbox.volt.io/payments/{paymentId}/request-refund
https://api.volt.io/payments/{paymentId}/request-refund

Request header

If you’re using a Volt Account as your Connect account provider, you’ll need to sign your request using an additional header.   If you’re using one of our account partners, such as Clear Junction or ISX, you don’t need to include this header.  You can only test this on production, as this header is ignored on sandbox.

Find out how to sign your request

Request body

For a full refund of the payment amount

If you want to refund the full payment amount, the request body should be an empty JSON (no additional data is required).

Full refund 
{}
For a partial refund

If you only want to refund part of the payment you’ll need to specify the amount and assign your unique external reference to the partial refund.

Partial refund 
{
  "amount": 1,
  "externalReference": "my-external-reference"
}
Request form parameters
  • amount is the amount you want to refund (in minor units)
  • externalReference should be a maximum of 40 characters and should contain letters and numbers only. It is the reference you want to use for this refund

Creating a partial refund for the full payment amount is equivalent to creating a full refund.

← Previous Introduction to refunds
Next → Refunds via Fuzebox