Home › Connect › Refunds via API

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 payment
  • message is an optional field that will contain detailed information about why you cannot create a refund for this payment
  • code 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 be Volt/2.0
  • It will contain an X-Volt-Type header containing refund_confirmed or refund_failed so that you can easily identify the message format to process

Completed refund notification

Headers 
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
Body 
{
  "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

Headers 
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
Body 
{
  "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"
  }
}
← Previous Introduction to refunds
Next → Refunds via Fuzebox