Accept Refunds

Using our Checkout API, you have the ability to refund any successfully processed card payment.

important

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.

Steps

1. Initiate a refund
2. Verify that the refund is successful

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.

https://checkout-online.yoco.com/checkouts/{id}/refund

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
metadata	map	Used to record additional details about the refund, often used to reconcile data with an external system.

Sample request

• cURL

curl --location --request POST 'https://checkout-online.yoco.com/checkouts/ch_9LVKD8GnAj7f39DFbn4F16bE/refund' \

--header 'Content-Type: application/json' \

--header 'Authorization: Bearer <secret-key>'

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

HTTP: 202 Accepted

{

"id" : "ch_9LVKD8GnAj7f39DFbn4F16bE",

"refundId" : "rfd_r72Lbce7jZ46y7HgycNJ5Fvrb",

"message" : "Your refund has been processed",

"status" : "successful"

}

2. Verify that the refund is successful

The status of the refund can be verified by referring to the status field of the Checkout. A refund is considered successful if its Checkout status is marked as refunded or reversed.

Checkout status	Description
created	The Checkout has been created, but the checkout page has not been visited.
started	The checkout page has been visited.
processing	Waiting on payment result.
completed	The payment was completed.
refunded	The payment was refunded.
reversed	The payment was reversed.

important

When a refund is initiated before the customer's funds are settled in your account, it is referred to as a reversal.

In this case the Checkout status would be reversed.

Add an endpoint to get the Checkout using the Checkout id.

https://checkout-online.yoco.com/checkouts/{id}

Headers

Parameter	Type	Description
Authorization	string	The secret key for your account.

Sample request

• cURL

curl --location --request GET 'https://checkout-online.yoco.com/checkouts/ch_9LVKD8GnAj7f39DFbn4F16bE' \

--header 'Authorization: Bearer <secret-key>'

important

Replace <secret-key> with your secret API integration key. For more information, see here.

Sample response

• Successful

HTTP: 200 OK

{

"id": "ch_9LVKD8GnAj7f39DFbn4F16bE",

"redirectUrl": "https://c.yoco.com/checkout/ch_9LVKD8GnAj7f39DFbn4F16bE",

"status": "refunded",

"amount": 900,

"currency": "ZAR",

"cancelUrl": "https://my-cancel-page.com",

"paymentId": "p_bx4bY9JA6r4UwAKFyAjHY2bE",

"successUrl": null,

"failureUrl": null,

"metadata": {

"checkoutId": "ch_9LVKD8GnAj7f39DFbn4F16bE",

"paymentFacilitator": "yoco-online-checkout"

},

"merchantId": "1687579359397-9ecd46a3-83f9-4563-8def-20ac11p67087",

"totalDiscount": null,

"totalTaxAmount": null,

"subtotalAmount": null,

"lineItems": null,

"externalId": null,

"processingMode": "live"

}

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.