Payment SessionsPayment behavior

Manual/Delayed Capture

Manual capture is the process of placing an authorization hold on a card, and then capturing the payment later, typically at the time of fulfillment.

The initial invocation of create_payment_session requires that the customer be present in the checkout flow. Additional calls for capture or voids don’t require customer-in-flow.

Authorization holds for manual capture are created and managed using the same create_payment_session endpoint outlined in Accept Your First Payment.

Manual capture relies on your system storing the id field from the payment session response and calling /payments/v1/payment_session/{business_id}/capture when the payment should be captured, or /payments/v1/payment_session/{business_id}/void to release the authorization hold.

Suggested implementation

Use manual capture when your order should be authorized at checkout, but charged later after a fulfillment decision.

1

Create the payment session as an authorization

Pass kind: "authorization" to create_payment_session. Store the returned payment session id on your order.

2

Wait for the authorization webhook

Listen for payment_session_complete. For manual capture, the key post-checkout webhook status is authorized. This means the authorization hold is ready to capture or void.

3

Capture when you are ready to fulfill

Call capture_payment_session with a unique idempotency_key, the total_amount to capture, and the item_details being captured.

4

Fulfill after capture succeeds

The authorization webhook tells you the funds are held, not captured. Fulfill after your capture request succeeds for the amount you intend to charge.

5

Void if you will not fulfill

If the order should not be fulfilled, call void_payment_session to release the authorization hold.

If you need to capture more than the original authorization amount, void the authorization and create a new payment session. Capture amounts must be less than or equal to the original authorization.

Flow Diagram

Request Body

The create_payment_session endpoint can be invoked with the additional fields described here.

FieldTypeDescription
kindstringOne of: one_time_payment (default) or authorization

Kind Values

  • one_time_payment (DEFAULT): The charge is immediately captured. This is the default if this field is not set.
  • authorization: A one_time_payment authorization hold only. Must be manually captured or voided with a follow-up API call.

Response Body

The response is the same as described in the create_payment_session API reference, with additional error states.

Bad Request

HTTP Status: 400

If a field is missing or the request otherwise can’t be processed, we’ll return a 400.

Capture and Void Operations

Once an authorization hold has been created, you can either capture or void it:

Capture request

Use a unique idempotency_key for each capture attempt. Include the total amount being captured and the specific items included in the capture.

If you plan to capture by item, provide item_id on each order_items entry when creating the payment session so you can reference those same items in item_details.

$curl https://dev-api.truemed.com/payments/v1/payment_session/c51f5d44-9f8d-4e9f-bc5f-929a6f9f2f51/capture \
>  -X POST \
>  -H "Content-Type: application/json" \
>  -H "x-truemed-api-key: $TRUEMED_API_KEY" \
>  -d '{
>    "total_amount": 12500,
>    "idempotency_key": "capture_order_12345",
>    "final": true,
>    "item_details": [
>      {
>        "item_id": "line_item_1",
>        "quantity": 1,
>        "total": 12500
>      }
>    ]
>  }'

Set final to false only if you plan to make additional captures against the same authorization.

Void request

Void the authorization when the order should not be fulfilled.

$curl https://dev-api.truemed.com/payments/v1/payment_session/c51f5d44-9f8d-4e9f-bc5f-929a6f9f2f51/void \
>  -X POST \
>  -H "Content-Type: application/json" \
>  -H "x-truemed-api-key: $TRUEMED_API_KEY" \
>  -d '{
>    "idempotency_key": "void_order_12345"
>  }'