A payment session is an in-progress payment transaction. It is a temporary, time-limited context created when a client initiates a payment flow.

It becomes a secure, stateful environment for completing a payment transaction. Instead of passing sensitive payment data on every request, the payment session persists transaction details. This includes the amount, currency, payment method, and status. It exposes only the payment session identifier to the client. This reduces the risk of data exposure.

The use of a payment session is applicable only to Flute Elements and Flute Checkout. Some fields may include a note about their use, and specifically for Elements and Checkout.

Conceptually, the following is a common workflow for using a payment session.

• Create the payment session.
• Connect through Flute Elements or Flute Checkout. This may include collect shipping information, selecting a payment method, applying discounts or promotions, reviewing and confirming the order, authorizing the payment, and capturing the funds. Many of these individual steps will be transparent to the client when using Flute Elements or Flute Checkout.

At each step, the payment session holds the transaction state. This means each step can update the session without resubmitting the full transaction data. If the client navigates away but later returns or does not complete the transaction immediately, the session can be retrieved by its identifier. The flow resumed from where it left off.

The payment session can end in one of the following ways:

• The transaction is completed. Check the status of the transaction for its success. See POST /v2/payment-sessions/{{paymentSessionId}}, the field status.
• The transaction is canceled. The client chooses to not complete the transaction. The state of the transaction is saved. The client may retrieve the payment session later and continue the transaction.
• The payment session expires or times out. When creating a payment session, an expiration date and time can be assigned. If the transaction is neither completed nor explicitly canceled, the payment session cancels itself. Like the cancel operation, the state of the transaction is saved. The client may retrieve the payment session later and continue the transaction.