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

<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: 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.
  • To release the uncaptured remainder without capturing more, send a final capture with total_amount: 0 and empty item_details, or void the session. A zero-amount final capture is accepted only after at least one earlier capture.
  • 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 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 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.