Using our Checkout API, you have the ability to refund any successfully processed card payment.
We do not currently support partial refunds in the Checkout API. The original charge will therefore be fully refunded.
For partial refunds on a payment, kindly reach out to our support team for assistance.
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.
You can find the Checkout id in the payments flow by referring to Step 1: Create the Checkout.
|The secret key for your account.|
|An optional idempotency key enables you to safely retry a request without risking the user being charged multiple times.|
|Used to record additional details about the refund, often used to reconcile data with an external system.|
Replace <secret-key> with your secret API integration key. For more information, see here.
In order to process a refund, the Checkout must have been created using live keys.
A refund request may take some time to complete.
status field value of
successful in the response indicates whether the request has been accepted for processing.
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
For more information about the successful refund event, see here.
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.)
|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 ||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.
|A key is required, but has not been specified.||Secret API key is not included in header, or is incorrect.||Confirm that the |
|Conflict||A request with the same idempotency key is already being processed.||Try again later, or use a different idempotency key.|
|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 |