Capture a payment

Our two-step authorization and capture process enables you to capture payments either automatically or manually.

When a payment is authorized, the funds are held for seven days. By default, payments are automatically captured. If you wish to manually capture, set the capture field to false when requesting a payment. You can capture an authorized payment either in full or partially. If you don't capture it within seven days, the payment is voided.

👍
Looking to void a payment?
You can void an authorized payment at any time. However, captured payments can only be refunded.

Overview

If a payment is created with "capture": "false", you can either use this endpoint to capture the payment or capture it from the Hub. Manual capture is not allowed if capture is set to true.

📘
Partial captures:
Any capture amount less than the original payment will be treated as a partial capture. You can only make one partial capture per payment.

The request

Use the details below to set up your request.

Endpoints

Live

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

Sandbox

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

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 (prefixed with `pay_`). Returned in the API response when requesting a payment.

Body parameters

Field name	Description
`amount`IntegerOptional	The amount to capture. If not specified, the full payment amount will be captured.
`reference`\ String\ Optional	A reference you can later use to identify this capture request.
`metadata`\ Object\ Optional	A set of key/value pairs that you can attach to the capture request. It can be useful for storing additional information in a structured format.

Request example

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

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

The response

If you receive a 202 Capture accepted response, your capture request has been accepted for processing. To get the full capture response, you will need to subscribe to the payment_captured 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_3kfr4betasbelhjdk346yutxvu",
  "reference": "ORD-5023-4E89",
  "_links": {
    "payment": {
      "href": "https://api.sandbox.checkout.com/payments/pay_kladqdb6hm5ebggtq45rtzjati"
    }
  }
}

{
  "request_id": "0HL80RJLS76I7",
  "error_type": "request_invalid",
  "error_codes": [
    "payment_source_required"
  ]
}

Additional error responses:

403 Capture 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].