Guides
API Reference

Our reference library for integrating with our API

FAQ

Find answers to our most frequently asked questions

Classic Docs

Documentation for our Classic API

Void a payment

After a card payment has been authorized, the payment is not complete until it has been captured. If you do not wish to capture the payment, you can void it using the void API described below or via the Hub.

The POST request

Use the endpoint below to void an authorized – but not yet captured – payment.

Endpoints

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

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 payment.

Body parameters

Field nameDescription

reference

OPTIONAL

STRING

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

metadata

OPTIONAL

OBJECT

A set of key/value pairs that you can attach to the void 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

If you receive a 202 Void accepted response, your void request has been accepted for processing. To get the full void response, you will need to subscribe to the payment_voided webhook.

If there was a problem with your request, you'll receive an error response such as 422 Invalid data was sent.

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 Void not allowed or 404 Payment not found error.