Payment 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

Rejected payment flow

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.