Platform SetupAPIPayment SessionsPayment Behavior

Payment lifecycle

A payment session moves through statuses as the customer completes checkout, Truemed reviews the payment, and funds are captured, rejected, authorized, voided, or refunded.

Most immediate-capture integrations only need to handle processing, captured, and rejected. Manual capture integrations also need authorized, authorization_voided, and authorization_expired.

Status reference

StatusWhat it meansWhat to do
pendingThe payment session exists, but the customer has not completed checkout.Wait for the customer to complete the hosted flow.
canceledThe payment session was canceled before payment information was entered.Keep the order unpaid or let the customer choose another payment method.
processingThe customer entered payment details and Truemed is reviewing the payment.Show an “order placed” confirmation. Do not fulfill yet.
authorizedAn authorization hold was placed for a manual capture payment.Capture or void the payment later.
authorization_voidedThe authorization hold was voided.Do not fulfill unless the order was paid another way.
authorization_expiredA capture was attempted, but the authorization hold could no longer be re-secured on the customer’s card, so it expired.Do not fulfill unless the order was paid another way.
capturedThe payment cleared review and funds are secured.Fulfill the order.
rejectedThe payment failed review.Cancel the order and notify the customer.

Successful immediate-capture flow

Click "Pay with HSA/FSA" POST /create_payment_session redirect_url Redirect to Truemed Complete health survey Enter HSA/FSA card details Process payment Redirect to success_url payment_session_complete (processing) payment_session_complete (captured) Show "order placed" message Fulfill order User Merchant Truemed

Rejected payment flow

alt [Ineligible or payment failed before completion] [Payment under review, then rejected] Click "Pay with HSA/FSA" POST /create_payment_session redirect_url Redirect to Truemed Complete health survey Redirect to failure_url Return to checkout Redirect to success_url payment_session_complete (processing) payment_session_complete (rejected) Cancel order and notify customer User Merchant Truemed

Manual capture flow

For manual capture, create the payment session with kind: authorization. Truemed sends status: authorized when the hold is ready. Capture or void the authorization later through the payment session APIs.

Read Manual/Delayed Capture for the full flow.