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

• total_amount (Required) - The amount in cents to charge, including any tax and fees you’re collecting. Captures together can’t exceed the session’s total_amount; to collect more, void and create a new session.
• item_details (Required) - The units in this capture, each referencing an item_id from the session’s order_items.
  • Without multi-capture, an item keeps the same per-unit cost (total / quantity) in every capture, and total_amount must equal the sum of the total values, except on a single capture of the whole order, the only capture that may also carry order-level shipping, fees and discounts.
• final (Optional, defaults to true) - false keeps the rest of the authorization for a later capture. It requires multicapture_available to be true on the authorized payment_session_complete webhook; otherwise the request fails with ValidationError.
  • A final capture releases whatever it doesn’t collect.
  • To close without collecting more, send total_amount: 0 with empty item_details after at least one earlier capture, or void the session.
• amount_details and item_details[].amount_details (Optional, multi-capture only) - The charges and discounts this capture carries, in the same shape as at session creation. Other sessions reject them with InvalidItemizedData.

Multi-capture sessions

Multi-capture must be enabled for your integration by Truemed Support. See Capturing in multiple parts for setup and integration guidance.

After authorization, split a session only when multicapture_available is true on the payment_session_complete webhook. When it’s false, a final: false capture is rejected and a final capture releases whatever it doesn’t collect.

Each capture may include any remaining quantity of an order item, down to a single unit, and items may be captured in any order. Across all captures, the total quantity for an item_id cannot exceed its quantity in the original order.

Send final: false when more captures will follow. final: true closes the session and releases any uncollected amount. A capture also closes the session if it collects the entire remaining balance.

Without amount_details, Truemed infers the order-level part:

• total_amount can be up to these units’ session totals plus the net order-level money still owed on the session (order_level_charges_remaining less order_level_discounts_remaining).
• Below the units’ totals, the session’s order-level discounts are applied: up to these items’ share on a non-final capture, up to all that remain on a final. Anything lower is money you chose not to collect, and it can’t be captured later.

With amount_details, you declare it. If a session’s first capture sends no amount_details, later captures can’t send them either; a final capture without amount_details collects what’s left. A session whose first capture declares can mix declared and inferred captures.

• amount_details can be declared at the top level of the capture or per item.
• At the item level, the unit price × quantity, plus its charges, minus its discounts, must equal its total. A discount declared on an item belongs to that item.
• At the capture level, the items’ totals plus its charges minus its discounts must equal total_amount.
• In a capture that declares amount_details at either level, an item that omits amount_details or sends amount_details: {} uses the item-level charges and discounts provided to create_payment_session. Its total must equal the unit price × quantity, plus the captured units’ share of those charges, minus their share of those discounts. At the capture level, omitting amount_details or sending amount_details: {} declares no order-level charges or discounts.
• Declared charges must fit within order_level_charges_remaining, and declared discounts must fit within order_level_discounts_remaining; the two are checked separately. An item’s discount beyond what’s left is money you chose not to collect on that item; a capture-level one is rejected.

Partial quantities: the cumulative limit is the captured units’ proportional share of max_capture_amount, rounded half up, plus up to one cent per captured unit, and never more than max_capture_amount. For example, when max_capture_amount is 1000 and quantity is 3, the item’s captures may total up to 334 after one unit, 669 after two, and 1000 after all three. See Partial quantities: why a rounding rule, and which one.

Card minimum: no card is charged less than $0.50 in one capture, so a capture under $0.50 in total is rejected.

Response Notes

Success Case

HTTP Status: 200

• id - The ID of the payment session that was captured, the same value that create_payment_session returned.
• capture_id - The ID of this capture. Pass it as capture_id to Create Refund to refund against this capture. The same ID is returned if the endpoint is called again with the same idempotency_key. It is omitted for a zero-amount final capture, which only releases the uncaptured remainder.

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 amount can’t be accepted: more than these items and the order-level money still owed allow, more than is still authorized, negative, under $0.50, a zero amount where it isn’t allowed, or declared amounts that don’t add up to total_amount or don’t fit the order-level charges or discounts still unused. On a multi-capture session the message explains what to change. A rejected capture records nothing.
  • 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 payment session wasn’t created with kind=authorization.
  • InvalidItemizedData: An item_details entry is invalid (a bad quantity or total, or more than is left of the item), an item’s declared amount_details don’t add up to its total, amount_details on a session without multi-capture, or, on a multi-capture session, the same item_id sent twice, or amount_details on a capture after the session’s first capture declared none. The message names the item and the value.
  • ValidationError: final: false on a session without multi-capture.
  • InvalidRequestParameter: amount_details is malformed, for example total_discounts without discounts_details.
• message - Indication of which field was missing, details on how the total amount was invalid, or details on voided sessions.