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.

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 total_amount passed in when creating the payment session.
- 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.
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/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. ## 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 `total_amount` passed in when creating the payment session. - `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`. - **`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.

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