Payment Sessions

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.

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 selecting a payment method, applying discounts or promotions, 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 resumes 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 GET /v2/payment-sessions/{{paymentSessionId}}, the field status.
The transaction is canceled. The client chooses to not complete the transaction. If the client cannot later resume the transaction, a new payment session must be started.
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.

Operations

Creates a new payment session

Request

POST {{baseURL}}/v2/payment-sessions

This endpoint creates a new payment session.

This endpoint is Idempotent. See the idempotency-key header entry. For more information, see Idempotency.

This endpoint requires a merchant API token. A partner API token will result in a permissions error including possibly a 403 response.

See Also:
To retrieve a payment session by Id, see GET /v2/payment-sessions/{{paymentSessionId}}.
To cancel a payment session, see POST /v2/payment-sessions/{{paymentSessionId}}/cancel.

Security

Bearer

Headers

idempotency-keystring, (uuid), <= 255 characters

Specifies the client-generated idempotency-key.

This key is optional. We recommend using the key to prevent multiple invocations of the operation. This key makes this request safely retryable, or idempotent. If the idempotency key is not included, the call will not have idempotency protection.

A retry with the same key, made within the retention window, returns the original response verbatim. The operation is not repeated. The retention window, also called the TTL (time to live) is 1440 minutes (24 hours) by default but this setting may be changed.

A retry with the same key while the original request is still processing returns 409 Conflict (IdempotencyKeyInProgress). Retry again after a short delay.

Reusing the same key with a different request body returns 422 Unprocessable Content (IdempotencyKeyConflict). Generate a new key for each distinct operation.

A 500 series server error is not stored against the key. A retry with the same key after a 500 series response processes the request again.

Example:6a1f7e2c-4b3d-4e5a-8f9c-1d2e3f4a5b6c

Bodyapplication/json

amountnumber or null, (double), decimal places <= 2

Specifies the base amount (in USD) to charge.

For payment sessions (mode of either Payment or PaymentAndSave), this value must be greater than zero.

For vault-only payment sessions (mode of SaveMethod), this value must be zero.

A value of null creates a flexible-amount payment session where the amount is set at checkout.

Examples:
64.99
0
null

Example:64.99

modestring, (enum)

Indicates the intent of the session.

Name	Description
Payment	Standard payment session.
SaveMethod	Vault-only session to store a payment method. The amount must be zero. No payment is processed. This stores the customer's card details for future use. `vaultedPaymentMethodId` is returned on the session once confirmed.
PaymentAndSave	Charge the payment and store the customer's card details for future use. `vaultedPaymentMethodId` is returned on the session once confirmed.

Example: Payment

Default:"Payment"

Enum:"Payment""SaveMethod""PaymentAndSave"

Example:"Payment"

skipAddressVerificationboolean or null

Specifies to bypass the AVS (address verification service) in the payment gateway.

This value is applicable only to Payment and PaymentAndSave from mode.

If true, bypasses AVS in the payment gateway.
If false, does not bypass AVS in the payment gateway.

Example: true

Default:false

Example:true

referenceIdstring or null, <= 50 characters

Specifies a reference identifier provided by the merchant.

This is included in the duplicate-check key. It allows the same card and amount combination to be charged multiple times when the reference identifiers are different.

Example: 10001

Example:"10001"

tipAmountnumber or null, (double), decimal places <= 2

Specifies the absolute amount (in USD) of the tip to be added.

If this value is provided, it must be greater than zero.

This amount adds to the base amount of the original transaction. That transaction must be authorized first (POST /pay-api/v1/transactions/auth).

Example: 14.50 (for $14.50)

Example:14.5

customerIdstring or null, (uuid)

Identifies the customer to link this payment method to.

This value may be null when this payment method is an orphan owned by the merchant directly. An orphan payment method is a payment method in the merchant's vault but has no customer record associated with it.

Example: 8fa8e727-73c6-436e-b56f-6f55aabf3b1c

Example:"8fa8e727-73c6-436e-b56f-6f55aabf3b1c"

customerHandlingstring or null

Specifies how the payer's information is retained after the payment session completes.

Valid values are:

Value	Description
CreateCustomer	Creates or attaches a customer record from the session, in addition to any payment method vaulting.
TokenOnly	Vaults the payment method without creating or attaching a customer record.

Example: CreateCustomer

Enum:"CreateCustomer""TokenOnly"

Example:"CreateCustomer"

returnUrlstring or null, <= 2000 characters

Specifies the URL to redirect the payer to after a successful payment.

This value is not needed if using Flute Elements and Flute Checkout.

Example: https://api.payments.flute.com/xOut/sessions/session-complete.html

Example:"https://api.payments.flute.com/xOut/sessions/session-complete.html"

paymentMethodsobject

Identifies the payment methods a payment link accepts. It is keyed by method so each one carries only the configuration that applies to it.

At least one payment method must be enabled, card or ACH. Both may be specified.

taxModestring

Specifies how taxRate and taxAmount is applied to amount.

Name	Description
Exclusive	Adds the tax on top of `amount`. The payer is charged `amount` plus the tax.
Inclusive	Treats `amount` as already including the tax. No extra amount is added.

A taxMode value must be used with exactly one of taxRate or taxAmount, or none of the three. When all three are omitted, the payment session has no tax configured.

Example: Exclusive

Enum:"Exclusive""Inclusive"

Example:"Exclusive"

taxRatenumber or null, (double)

Specifies the tax rate percentage to apply to the base amount.

Valid values range from 0 to 100, with up to three decimal places.

A taxMode value must be used with exactly one of taxRate or taxAmount, or none of the three. When all three are omitted, the payment session has no tax configured.

Example: 8.25 (for 8.25%)

Example:8.25

taxAmountnumber or null, (double), decimal places <= 2, >= 0

Specifies a fixed tax amount (in USD) to apply to the base amount.

This value has up to two decimal places and cannot be negative. This value requires a fixed baseAmount.

A taxMode value must be used with exactly one of taxRate or taxAmount, or none of the three. When all three are omitted, the payment session has no tax configured.

A response carries this value only when the tax was configured as an amount. Otherwise, it is null.

Examples:
3.75 (for $3.75)
null

Example:3.75

metadataobject or null

Specifies arbitrary key-value pairs to attach to the payment session object.

These values are used to store supplemental information. They are not functionally used in this endpoint. Instead, they are included while retrieving the payment session. This allows additional notes to be passed along to the operator.

Pass null to clear all metadata.

Examples:
[ {"orderId": "9921"} ]
[ {"Guest notes": "Member of The World of Hyatt Credit Card."} ]
[{"orderId": "9921"}, {"Guest notes": "Member of The World of Hyatt Credit Card.}]

Example:

[
  {
    "orderId": "9921"
  },
  {
    "Guest notes": "Member of The World of Hyatt Credit Card."
  }
]

afterCompletionMessagestring or null, <= 500 characters

Specifies a message shown to the payer after the payment session completes.

This value is not needed if using Flute Elements and Flute Checkout.

Example: Thank you for shopping with us.

Example:"Thank you for shopping with us."

expiresAtstring or null, (date-time)

Specifies the date-time (in an ISO 8601 date-time format) expiration for the payment session.

The time must be in the future.

If this value is null or omitted, there is no expiration date.

Example: 2027-02-19T20:24:52.934Z

Default:null

Example:"2027-02-19T20:24:52.934Z"

pageNamestring or null, <= 200 characters

Specifies the display name shown on the checkout page.

This is a free-formed name that is convenient for the merchant to recognize.

Example: Peppared Street Cafe's Preferred Payment

Example:"Peppared Street Cafe's Preferred Payment"

paymentNotesstring or null, <= 500 characters

Specifies additional notes shown to the payer on the checkout page.

Example: The client's server is being repaired.

Example:"The client's server is being repaired."

curl -i -X POST \
  https://sandbox.api.flute.com/v2/payment-sessions \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'idempotency-key: 6a1f7e2c-4b3d-4e5a-8f9c-1d2e3f4a5b6c' \
  -d '{
    "amount": 64.99,
    "mode": "Payment",
    "skipAddressVerification": true,
    "referenceId": "10001",
    "tipAmount": 14.5,
    "customerId": "8fa8e727-73c6-436e-b56f-6f55aabf3b1c",
    "customerHandling": "CreateCustomer",
    "returnUrl": "https://api.payments.flute.com/xOut/sessions/session-complete.html",
    "paymentMethods": {
      "card": {
        "enabled": true,
        "processorId": "d529945e-8d10-4cb4-9dc3-718e57f3f14e"
      },
      "ach": {
        "enabled": true,
        "processorId": "d529945e-8d10-4cb4-9dc3-718e57f3f14e",
        "achAllowFasterProcessing": false
      }
    },
    "taxMode": "Exclusive",
    "taxRate": 8.25,
    "taxAmount": 3.75,
    "metadata": [
      {
        "orderId": "9921"
      },
      {
        "Guest notes": "Member of The World of Hyatt Credit Card."
      }
    ],
    "afterCompletionMessage": "Thank you for shopping with us.",
    "expiresAt": "2027-02-19T20:24:52.934Z",
    "pageName": "Peppared Street Cafe'\''s Preferred Payment",
    "paymentNotes": "The client'\''s server is being repaired."
  }'

Responses

Bodyapplication/json

idstring, (uuid)

Indicates the identifier of the created payment session.

This is also called the paymentSessionId.

If mode was SaveMethod, a payment session was successfully created but with an automatic Completed status. That payment session is not available for additional processing. The paymentSessionId may be used to retrieve the payment session information. For those details, see GET /v2/payment-sessions/{{paymentSessionId}}.

If the mode was PaymentAndSave, a payment session was successfully created. That payment session is available for additional processing.

Example: dce6a259-0a1b-4c2d-3e4f-5a6b7c8d9e25

Example:"dce6a259-0a1b-4c2d-3e4f-5a6b7c8d9e25"

paymentMethodsobject

Identifies the payment methods a payment link accepts. It is keyed by method so each one carries only the configuration that applies to it.

At least one payment method must be enabled, card or ACH. Both may be specified.

Response

{
  "id": "dce6a259-0a1b-4c2d-3e4f-5a6b7c8d9e25",
  "paymentMethods": {
    "card": {
      "enabled": true,
      "processorId": "d529945e-8d10-4cb4-9dc3-718e57f3f14e"
    },
    "ach": {
      "enabled": true,
      "processorId": "d529945e-8d10-4cb4-9dc3-718e57f3f14e",
      "achAllowFasterProcessing": false
    }
  }
}