Refund a payment

Use a refund to return a payment to a customer. Refunds can be made in the Hub or by using this API endpoint.

There are two types of refunds you might need to process:

  • Full refund. A full refund returns the total amount of the payment to the customer — it can only be performed once.
  • Partial refund. A partial refund returns a sum less than the captured amount. A payment can be refunded multiple times, but cannot exceed the original payment amount.

Refunds are always processed in the same currency as the captured payment.

You cannot cancel a refund after it has been processed.

Overview

To process a refund successfully, you must provide the payment ID of the captured payment. You can find the ID:

  • In the response of the payment request
  • In the webhook notification

The requests are the same for partial and full refunds. Any refunds for less than the original captured amount will be considered partial refunds.

The POST request

Use the endpoint below to request a refund.

If required by the card scheme, we will trigger a refund authorization before processing your refund.

Endpoints

https://api.checkout.com/payments/{id}/refunds
https://api.sandbox.checkout.com/payments/{id}/refunds

Header and path parameters

HeaderValue

Authorization

REQUIRED

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type

REQUIRED

application/json
PathValue

id

REQUIRED

The ID of the captured payment, embedded within the payment response (prefixed by pay_).

Body parameters

Field nameDescription

amount

INTEGER

OPTIONAL

The amount to refund. If not specified, the full payment amount will be refunded.

reference

STRING

OPTIONAL

A reference you can later use to identify this refund request.

metadata

OBJECT

OPTIONAL

A set of key/value pairs that you can attach to the refund request. It can be useful for storing additional information in a structured format.

Request example

{
  "reference": "ORD-5023-4E89",
  "metadata": {
    "coupon_code": "NY2018",
    "partner_id": 123989
  }
}

The POST response

A successful refund request returns a 202 Refund accepted response. However, if there was a problem with your request, you'll receive an error response.

Response examples

{
  "action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
  "reference": "ORD-5023-4E89",
  "_links": {
    "payment": {
      "href": "https://api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
    }
  }
}
{
  "request_id": "0HL80RJLS76I7",
  "error_type": "request_invalid",
  "error_codes": [
    "payment_source_required"
  ]
}

If unsuccessful, you may also receive a 403 Refund not allowed or 404 Payment not found error.

Refund authorization 

If the card scheme requires it, we will automatically trigger a refund authorization on your behalf before processing your refund.

Refund authorizations only apply to card payments.

If a refund authorization is requested, you can find the Retrieval Reference Number (RRN) in refund webhook notifications and in the get payment actions call.

If the refund authorization is declined, you will receive a 422 response, like the one below.

{
   "request_id": "f5feff3f-d2ef-4c82-b4d0-ff443731581f",
   "error_type": "processing_error",
   "error_codes": [
       "refund_authorization_declined"
   ]
}

If you want to know the reason for the decline, you can either subscribe to refund webhook notifications, use our get payment actions endpoint, or view it in your Hub account.

Testing

To test a declined refund authorization, request a refund with the amount set to 3738.

Troubleshooting

If your refund request was unsuccessful, the checklist below may help you identify the problem:

  • Is the refund amount higher than the original payment?
  • Has the payment already been refunded?
  • Did you send the authorization ID instead of the payment ID?

Can we help?

Thanks for using Checkout.com. If you need help or have a question, message our Support team at support@checkout.com.