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

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.

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 endpoint below to capture a payment.

Endpoints

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

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

Body parameters

Field nameDescription

amount

OPTIONAL

INTEGER

The amount to capture. If not specified, the full payment amount will be captured.

reference

OPTIONAL

STRING

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

metadata

OPTIONAL

OBJECT

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 examples

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

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