Capture Session

The capture_payment_session endpoint should be called after create_payment_session has been called with kind of authorization as outlined in Manual/Delayed Capture.

The failure or success status is communicated to the partner via a payment_session_complete webhook as before.

Request Notes

Important

The total_amount field will often not be the sum of the order_item[*].price fields, as you may be charging additional fees or including taxes.

total_amount (Required) - The total amount in cents to charge the user, inclusive of taxes and fees being collected by the partner. Must be less than or equal to the total_amount passed in when creating the payment session.
- If an amount more than the initial authorization should be captured, void the initial auth hold and create a new one.
item_details (Required) - The items included in this capture. Each entry references an item_id from the payment session’s order_items, and total_amount must equal the sum of the entries’ total values.
- A line keeps the same effective per-unit cost (total / quantity) across every capture it appears in.
final (Optional, defaults to true) - Set to false to leave the uncaptured remainder of the authorization held for a later capture. This requires multi-capture: the payment session must have been created with request_multicapture: true, and the card network must have granted multi-capture on the authorization. Otherwise the request fails with ValidationError.
- A capture with final: true releases whatever is still uncaptured back to the customer.
- Order-level shipping, fees, and discounts are only accepted on a single capture that covers the whole order. Under multi-capture, carry them as line items instead.

Response Notes

Success Case

HTTP Status: 200

id - The unique ID for this session capture. This same ID will be returned if the endpoint is called with the same idempotency_key. Associate this id with your internal representation of a checkout session, if applicable.

Bad Request

HTTP Status: 400

If a field is missing or the request otherwise can’t be processed, we’ll return a 400 with the following fields:

error - can be one of:
- MissingField: One of the required fields is not present in the request.
- TotalAmountInvalid: The total_amount field is either not greater than or equal to the sum of the order_item amount fields, is 0, is negative, or is greater than the amount still capturable on the payment session. It is also returned when a non-final capture has a zero total_amount, when a zero-amount final capture is not preceded by another capture, or when order-level amounts are sent on a capture that does not cover the whole order.
- PaymentSessionDoesNotExist: The payment_session_id does not exist.
- ServerError: There was an internal server error. Requests can be retried as long as the idempotency_key is the same.
- SessionVoided: The session has already been voided via a call to /payment_session/{payment_session_id}/void.
- SessionExpired: The auth hold has expired and we were unable to recharge the customer for the amount requested.
- SessionPending: The user hasn’t completed the Truemed checkout flow (survey, CC entry form).
- SessionCaptured: You’re attempting to capture a payment_session that has already been captured. This error will never be returned if reissuing a capture call with the same idempotency key - the return value will be the same as the first call.
- ImmediateCapture: The caller is attempting to void a payment_session that wasn’t created with kind=authorization.
- InvalidItemizedData: An item_details entry is invalid — a non-positive quantity, a negative total, a quantity or total beyond what remains capturable for that item, or a per-unit cost that differs from the item’s existing captures. The message names the item and the rejected value.
- ValidationError: The capture is not permitted in this configuration — for example final: false on an authorization that does not have multi-capture.
message - Indication of which field was missing, details on how the total amount was invalid, or details on voided sessions.

The `capture_payment_session` endpoint should be called after [`create_payment_session`](/api-reference/payment-sessions/create-payment-session) has been called with `kind` of `authorization` as outlined in [Manual/Delayed Capture](/guides/setup/api/payment-sessions/manual-delayed-capture). The failure or success status is communicated to the partner via a [`payment_session_complete`](/api-reference/payment-sessions/payment-session-completed-webhook) webhook as before. ## Request Notes <Warning title="Important"> The `total_amount` field will often not be the sum of the `order_item[*].price` fields, as you may be charging additional fees or including taxes. </Warning> - **`total_amount`** *(Required)* - The total amount in cents to charge the user, inclusive of taxes and fees being collected by the partner. **Must be less than or equal to the `total_amount` passed in when creating the payment session.** - If an amount more than the initial authorization should be captured, void the initial auth hold and create a new one. - **`item_details`** *(Required)* - The items included in this capture. Each entry references an `item_id` from the payment session's `order_items`, and `total_amount` must equal the sum of the entries' `total` values. - A line keeps the same effective per-unit cost (`total / quantity`) across every capture it appears in. - **`final`** *(Optional, defaults to `true`)* - Set to `false` to leave the uncaptured remainder of the authorization held for a later capture. This requires [multi-capture](/guides/setup/api/payment-sessions/manual-delayed-capture#capturing-in-multiple-parts): the payment session must have been created with `request_multicapture: true`, and the card network must have granted multi-capture on the authorization. Otherwise the request fails with `ValidationError`. - A capture with `final: true` releases whatever is still uncaptured back to the customer. - Order-level shipping, fees, and discounts are only accepted on a single capture that covers the whole order. Under multi-capture, carry them as line items instead. ## Response Notes ### Success Case HTTP Status: `200` - **`id`** - The unique ID for this session capture. This same ID will be returned if the endpoint is called with the same `idempotency_key`. Associate this id with your internal representation of a checkout session, if applicable. ### Bad Request HTTP Status: `400` If a field is missing or the request otherwise can't be processed, we'll return a `400` with the following fields: - **`error`** - can be one of: - `MissingField`: One of the required fields is not present in the request. - `TotalAmountInvalid`: The `total_amount` field is either not greater than or equal to the sum of the `order_item` `amount` fields, is 0, is negative, or is greater than the amount still capturable on the payment session. It is also returned when a non-final capture has a zero `total_amount`, when a zero-amount final capture is not preceded by another capture, or when order-level amounts are sent on a capture that does not cover the whole order. - `PaymentSessionDoesNotExist`: The `payment_session_id` does not exist. - `ServerError`: There was an internal server error. Requests can be retried as long as the `idempotency_key` is the same. - `SessionVoided`: The session has already been voided via a call to [`/payment_session/{payment_session_id}/void`](/api-reference/payment-sessions/void-payment-session). - `SessionExpired`: The auth hold has expired and we were unable to recharge the customer for the amount requested. - `SessionPending`: The user hasn't completed the Truemed checkout flow (survey, CC entry form). - `SessionCaptured`: You're attempting to capture a payment_session that has already been captured. This error **will never** be returned if reissuing a capture call **with the same idempotency key** - the return value will be the same as the first call. - `ImmediateCapture`: The caller is attempting to void a payment_session that wasn't created with `kind=authorization`. - `InvalidItemizedData`: An `item_details` entry is invalid — a non-positive quantity, a negative total, a quantity or total beyond what remains capturable for that item, or a per-unit cost that differs from the item's existing captures. The `message` names the item and the rejected value. - `ValidationError`: The capture is not permitted in this configuration — for example `final: false` on an authorization that does not have multi-capture. - **`message`** - Indication of which field was missing, details on how the total amount was invalid, or details on voided sessions.

Authentication

x-truemed-api-keystring

Sales channel API key for merchant server-to-server authentication

Path parameters

business_idstringRequired

The UUID of the payment session returned by create_payment_session.

Request

Request body for PaymentSessionCaptureRequest

idempotency_keystringRequired

Allows the endpoint to be called multiple times. It must be unique to the capture session.

item_detailslist of objectsRequired

A list of items being captured in the capture request.

total_amountintegerRequired

The total amount in cents to charge the user, inclusive of taxes and fees being collected by the partner. Must be less than or equal to the total_amount passed in when creating the payment session. If an amount more than the initial authorization should be captured, void the initial auth hold and create a new one.

finalbooleanOptionalDefaults to true

Whether this is the final capture for the payment session. Set to false to allow additional captures up to the authorized amount — this requires that the session was created with request_multicapture: true and that the card network granted multi-capture on the authorization, and otherwise fails with ValidationError. A final capture releases any uncaptured remainder of the authorization.

Response

Successful response

idstring

The unique ID for this session capture. This same ID will be returned if the endpoint is called with the same idempotency_key. Associate this id with your internal representation of a checkout session, if applicable.

Errors

400

Bad Request Error

404

Not Found Error

405

Method Not Allowed Error

500

Internal Server Error

501

Not Implemented Error