Refund a payment
Using our Checkout API, you have the ability to refund any successfully processed card payment.
Steps
1. Initiate a refund
The Checkout API requires authenticated access, see here for more details.
To initiate a refund for a payment made with our Checkout API, you can add an endpoint on your server that uses the Checkout id as a reference.
important
You can find the Checkout id in the payments flow by referring to Step 1: Create the Checkout.
Headers
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | The secret key for your account. |
| Idempotency-Key | string | An optional idempotency key enables you to safely retry a request without risking the user being charged multiple times. |
Body
| Parameter | Type | Description |
|---|---|---|
| amount | integer | The amount requested to refund the customer, in cents. For a refund of R2.50, specify 250 as the amount (R2.50 × 100 = 250 cents). If not specified, the full remaining refundable balance will be processed. |
| metadata | map | Used to record additional details about the refund, often used to reconcile data with an external system. |
Sample request
- cURL
important
Replace <secret-key> with your secret API integration key. For more information, see here.
important
In order to process a refund, the Checkout must have been created using live keys.
Sample response
A refund request may take some time to complete.
A status field value of successful in the response indicates whether the request has been accepted for processing.
- Successful
2. Verify that the refund is successful
When a refund is successful, we will send a webhook event to your server. It is highly recommended to use webhooks to check the refund status before continuing.
For more information on receiving webhook events, see here.
The status of the refund can be verified by referring to the type field of the webhook event.
A refund is considered successful if its type is marked as refund.succeeded.
important
For more information about the successful refund event, see here.
Errors
The Checkout API uses conventional HTTP response codes to indicate the success or failure of requests. In general, codes in the 2xx range indicate success.
Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.).
Codes in the 5xx range indicate an error with our servers. (These do not happen often.)
General errors
| Description | Reason | Solution |
|---|---|---|
| CORS | The request is not being sent over HTTPS from your server. Browser security prevents a web page from making requests to a different domain than the one that served the web page. This restriction is called the same-origin policy. | Ensure you are making calls to the the Checkout API from your server and use HTTPs for those calls. This also ensures your secret key is not exposed. |
HTTP response errors
Below are potential errors that may occur, along with additional information to assist you in resolving them. Please note that this list is not exhaustive.
| Status code | Description | Reason | Solution |
|---|---|---|---|
403 | A key is required, but has not been specified. | Secret API key is not included in header, or is incorrect. | Confirm that the Authorization header is included in your request and that the API key is correct. For more information, see here. |
409 | Conflict | A request with the same idempotency key is already being processed. | Try again later, or use a different idempotency key. |
422 | The request payload (method, path, parameters) does not match the original request. | An initial request was sent with an idempotency key, followed by a subsequent request with the same idempotency key. | Confirm that the Idempotency-Key header is unique for each request. |