> For the complete documentation index, see [llms.txt](https://docs.commercelayer.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.commercelayer.io/core-api-reference/2026-05/payment_captures.md). # Payment captures The payment capture object and the allowed CRUD operations on the related resource endpoint A payment capture collects funds that were previously reserved by a [payment authorization](/core-api-reference/2026-05/payment_authorizations.md). The transaction is processed asynchronously — on success, the [payment session](/core-api-reference/2026-05/payment_sessions.md) transitions to `paid` (full capture) or `partially_paid` (partial capture), and the capture balance on the authorization is decremented accordingly. {% hint style="info" %} A session that was partially refunded can still capture the rest of its authorization. In that case the session stays `partially_refunded` after the capture succeeds, since part of the captured amount has already been given back. The order's payment status is still refreshed as usual. {% endhint %} {% hint style="success" %} Multiple captures can be created against the same authorization and session until the full amount is collected. {% endhint %} Fetching a payment capture returns all the information and messages provided by the [payment setting](/core-api-reference/2026-05/payment_settings.md). A capture can be partially or fully [refunded](/core-api-reference/2026-05/payment_refunds.md) after it succeeds. ## Capture amount The `amount_cents` is optional and defaults to the full remaining `capture_balance_cents` on the associated authorization. A single capture cannot exceed the authorization amount. Partial captures are supported — multiple captures can be made against the same authorization until the `capture_balance_cents` reaches zero. {% hint style="info" %} A capture must reference a payment authorization at creation time. Only authorizations belonging to the same payment session are accepted. {% endhint %} ## Event-driven creation Gateway webhook events can create a payment capture automatically if one does not already exist for the authorization. This means a transaction does not need to be explicitly created via the API first — Commerce Layer will create it in response to the event, ensuring the session status and order payment status are always kept in sync regardless of whether the flow was API-initiated or event-driven. Incoming events are matched to an existing capture by the gateway's own reference for that operation. A reference already seen updates the capture it belongs to, while a reference not seen before creates a new one. {% hint style="info" %} Gateways don't guarantee delivery order and may send the same event more than once. An event arriving for a capture that has already reached a final status is ignored, so a redelivery can't overwrite a settled outcome or inflate the amount an order counts as captured — receiving the same capture notification twice still only records the capture once. {% endhint %} If a capture event arrives and the corresponding payment authorization is missing, behavior depends on the gateway: * [Adyen](/core-api-reference/2026-05/payment_setting_adyens.md) — the missing authorization is synthesized from the event itself, reusing the `originalReference` Adyen supplies, so the capture can still be created and the session kept in sync. * [Braintree](/core-api-reference/2026-05/payment_setting_braintrees.md) — capture events do **not** cascade. A capture is only created if a `succeeded` payment authorization already exists for the session. Otherwise, the event is silently dropped. * [Checkout.com](/core-api-reference/2026-05/payment_setting_checkout_coms.md) — the missing authorization is synthesized, reusing the event's real payment ID — stable across the whole payment lifecycle — as an accurate token. The amount, though, is still approximated, reusing the capture's own amount instead of the full original authorization amount. * [PayPal](/core-api-reference/2026-05/payment_setting_paypals.md) — the missing authorization is synthesized, but the `PAYMENT.CAPTURE.COMPLETED` event carries no separate authorization reference, so it reuses the capture event's own resource ID and amount as an approximation. * [Stripe](/core-api-reference/2026-05/payment_setting_stripes.md) — the missing authorization is synthesized from the event itself, reusing the real charge ID and its actual authorized amount, so the capture can still be created and the session kept in sync. * [External](/core-api-reference/2026-05/payment_setting_externals.md) (custom gateways) — the webhook payload must explicitly include the `reference_transaction_token` for the authorization. If it's missing, the event is rejected with a `422 Unprocessable Entity` response. ## Auto-capture If the related payment setting has `auto_capture` enabled, a capture is created automatically upon a successful authorization, recorded as already succeeded and bypassing the payment gateway interaction. The `auto` flag in the response data indicates the capture was triggered automatically. ## Refund balance A capture tracks a `refund_balance_cents` attribute representing the amount still available to refund (capture amount minus already refunded amounts). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.commercelayer.io/core-api-reference/2026-05/payment_captures.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.