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
}
Or an extra message and code if it’s not:
{
"refundAvailable": false
"message": "Payment with id: 0da43922-e01d-4c7f-8a63-0d8da56459be has been fully refunded.",
"code": "PaymentRefundBalanceIsNotAvailable"
}
Response fields
refundAvailable
is a flag that tells you if a refund can be created for this paymentmessage
is an optional field that will contain detailed information about why you cannot create a refund for this paymentcode
is an 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.
Request location
- Sandbox
- Production
https://api.sandbox.volt.io/payments/{paymentId}/request-refund
https://api.volt.io/payments/{paymentId}/request-refund
Full refunds
If you want to refund the full payment amount, the request body should be an empty JSON (as no additional data is required):
{}
Partial refunds
If you want to refund only a part of the payment you need to specify the amount and assign your unique external reference.
{
"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
Note
Creating a partial refund for the full payment amount is equivalent to creating a full refund.
Refund notifications
Volt will send you one notification per refund request, which will detail its final status.
About the notification
- This notification will be delivered to your payment notification URL
- As this is a Connect notification, the
User-Agent
will beVolt/2.0
- It will contain an
X-Volt-Type
header containingrefund_confirmed
orrefund_failed
so that you can easily identify the message format to process
Completed refund notification
POST /payment_notification_url HTTP/1.1
Host: customer.com
Content-Type: application/json
User-Agent: Volt/2.0
X-Volt-Timed: 20200131123456
X-Volt-Signed: eda5e46baa6a676851975365e12b4ae61ee48442c0cbb8d0e3c3cfd47c3e1085
X-Volt-Type: refund_confirmed
{
"refundId": "026cefa0-a174-4ca3-a1e6-533a129d9c32",
"paymentId": "01dfb01b-c5ab-49e4-bfa4-277c766d5ecc",
"status": "REFUND_CONFIRMED",
"error": "",
"amount": 100,
"currency": "GBP",
"externalReference": null,
"timestamp": "2022-05-12T12:41:12+00:00",
"sender": {
"iban": "DK8389009999910135",
"swiftBic": "ALBPPLPW",
"name": "test customer name"
},
"recipient": {
"accountNumber": "12345678",
"sortCode": "654321",
"iban": "DE33500105173822933531",
"swiftBic": "SXPYDKKKXXX",
"name": "test recipient name"
}
}
Failed refund notification
POST /payment_notification_url HTTP/1.1
Host: customer.com
Content-Type: application/json
User-Agent: Volt/2.0
X-Volt-Timed: 20200131123456
X-Volt-Signed: eda5e46baa6a676851975365e12b4ae61ee48442c0cbb8d0e3c3cfd47c3e1085
X-Volt-Type: refund_failed
{
"refundId": "83a15d24-02b8-11ed-b939-0242ac120002",
"paymentId": "01dfb01b-c5ab-49e4-bfa4-277c766d5ecc",
"status": "REFUND_FAILED",
"error": "Payout Rejected by Provider",
"amount": 100,
"currency": "GBP",
"externalReference": null,
"timestamp": "2022-05-12T12:41:12+00:00",
"sender": {
"iban": "DK8389009999910135",
"swiftBic": "ALBPPLPW",
"name": "test customer name"
},
"recipient": {
"accountNumber": "12345678",
"sortCode": "654321",
"iban": "DE33500105173822933531",
"swiftBic": "SXPYDKKKXXX",
"name": "test recipient name"
}
}
- On this page
- Refunds via the API
- Refund notifications