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 request

Use the details below to set up your request.

📘
This endpoint voids an authorized — but not yet captured — payment.

Endpoints

Live

POSThttps://api.checkout.com/payments/{id}/voids

Sandbox

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

Header and path parameters

Header Value

Header	Value
`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`

AuthorizationRequired

secret key

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

Content-Type\ Required application/json

Path	Value
`id`Required	The ID of the payment.

Body parameters

Field name	Description
`reference`StringOptional	A reference you can later use to identify this void request.
`metadata`\ Object\ Optional	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 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. You can view examples of each type of response below.

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"
  ]
}

Additional error responses:

403 Void not allowed
404 Payment not found

Can we help?

Thanks for using Checkout.com. If you need any help or support, then message our support team at [email protected].