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.

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.

Operations

Creates a new payment session

Request

POST {{baseURL}}/pay-int-api/payment-sessions

This endpoint creates a payment session object.

The client, typically a frontend or checkout page, can use to securely collect payment details and process a transaction.

For Flute Checkout, use of this endpoint is required. To use Flute Checkout, see Flute Checkout for details.

For all other instances, use of this endpoint is not required. However, we encourage using it. Using a payment session:

protects payments from duplicating charges
manages complex flows, such as those with tips, surcharges, discounts, and authorization steps
offers fraud protection

See Also:
To retrieve payment session details by ID, see GET /pay-int-api/payment-sessions/{paymentSessionId}.
To cancel a payment session, see POST /pay-int-api/payment-sessions/{paymentSessionId}/cancel.

Security

Bearer

x-api-versionstring

Specifies the API version to use for the request.

Example: 1.0

Example:1.0

Bodyapplication/json

Payment session creation request.

amountnumber, (double), decimal places <= 2, >= 0.01required

For use with Flute Checkout also.

Specifies the base amount (in USD) to charge.

For payment sessions, this value must be greater than zero.
For vault-only sessions, this value must be zero. If null or omitted, this creates a flexible-amount session where the amount is set at checkout.

Examples:
64.99
0 null

Example:64.99

customerIdstring or null, (uuid)

For use with Flute Checkout also.

Specifies the customer identifier.

This is used when saving the payment method.
If this value is provided, the payment method is saved to the specified customer.
If this value is not provided, a new customer record is created.

Example: fd9198a4-eb6f-4620-9603-4f4638289de5

Example:"fd9198a4-eb6f-4620-9603-4f4638289de5"

modeinteger, (enum)

For use with Flute Checkout also.

Specifies the intent of the session.

Value	Name	Description
1	Payment	Standard payment session. Makes `skipAddressVerification` applicable. Default.
2	SaveMethod	Vault-only session to store a payment method.
3	PaymentAndSave	Charge the payment and save the method. Makes `skipAddressVerification` applicable.

Example: 2

Default:1

Example:2

skipAddressVerificationboolean

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, <= 50 characters

Specifies a reference identifier provided by the ISV.

This is included in the duplicate-check key. It allows the same card and amount combination to be charged multiple times when the reference identifies 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

customerHandlingany, (string)

Specifies the intent of the session.

Name	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

Default:"CreateCustomer"

Example:"CreateCustomer"

returnUrlstring, (URL)

For use with Flute Checkout only.

Specifies a target URL.

The customer is redirected to this Web page after payment is completed.

The request body field returnUrl value contains the literal string {{paymentSessionId}}. It is a placeholder. When this payment session endpoint successfully returned, Flute Checkout replaced the placeholder with the actual payment session identifier.

Example: https://isv.example.com/payments/returnUrl/{{paymentSessionId}}

Example:"https://isv.example.com/payments/returnUrl/{{paymentSessionId}}"

paymentMethodTypesArray of strings or null

For use with Flute Checkout also.

Specifies payment methods to be shown at checkout.

Valid values are:

Payment method	Type
Card	Credit or debit card payment
ACH	ACH (automated clearing house) payment

Example: Card

Example:"Card"

afterCompletionMessagestring or null

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."

pageNamestring or null

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

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."

expiresAtstring, (date-time)

For use with Flute Checkout only.

Specifies the expiration date and time (in an ISO 8601 date-time UTC format) of the transaction.

If null or omitted, this defaults to 30 minutes.

Example: 2026-01-19T14:27:02.767105Z

Example:"2026-01-19T14:27:02.767105Z"

taxRatenumber or null, (double), decimal places <= 3

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

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

taxRate and taxMode must be set together, or both omitted. When both are omitted, the payment session has no tax configured.

Example: 8.25 (for 8.25%)

Example:8.25

taxModeinteger or null, (enum)

Specifies whether the base amount already includes the tax or the tax is added on top of it.

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

taxRate and taxMode must be set together, or both omitted. When both are omitted, the payment session has no tax configured.

Example: 1

Example:1

metadataobject or null

For use with Flute Checkout only.

Specifies key-value pairings.

This is an optional collection of key-value pairings to provide additional information for the checkout process. They are arbitrary values, often specific to the transaction.

Content of the key-value pairs will be sanitized for security purposes. Maximum of 50 key-value pairings. Maximum 40 characters for the key name. Maximum 500 characters for the value. The maximum for the entire set of key-value pairings is 8 KB.

Example:
{ "orderId": "9921", "invoiceNumber": "INV-2026-001" }

Example:

{
  "orderId": "9921",
  "invoiceNumber": "INV-2026-001"
}

curl -i -X POST \
  https://developer.flute.com/_mock/api-reference/pay-int-api/payment-sessions \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-api-version: 1.0' \
  -d '{
    "amount": 64.99,
    "customerId": "fd9198a4-eb6f-4620-9603-4f4638289de5",
    "mode": 2,
    "skipAddressVerification": true,
    "referenceId": "10001",
    "tipAmount": 14.5,
    "customerHandling": "CreateCustomer",
    "returnUrl": "https://isv.example.com/payments/returnUrl/{{paymentSessionId}}",
    "paymentMethodTypes": "Card",
    "afterCompletionMessage": "Thank you for shopping with us.",
    "pageName": "Peppared Street Cafe'\''s Preferred Payment",
    "paymentNotes": "The client'\''s server is being repaired.",
    "expiresAt": "2026-01-19T14:27:02.767105Z",
    "taxRate": 8.25,
    "taxMode": 1,
    "metadata": {
      "orderId": "9921",
      "invoiceNumber": "INV-2026-001"
    }
  }'

Responses

Bodyapplication/json

idstring, (uuid)

Indicates the payment session identifier.

Use this value as the paymentSessionId. This value allows the customer to send the card information to complete the transaction.

Example: 16143c97-07bc-448c-9807-924189311a66

Example:"16143c97-07bc-448c-9807-924189311a66"

modestring

For use with Flute Checkout only.

Indicates the intent of the session.

Name	Description
Payment	Standard payment session. Makes `skipAddressVerification` applicable. Default.
SaveMethod	Vault-only session to store a payment method.
PaymentAndSave	Charge the payment and save the method. Makes `skipAddressVerification` applicable.

Example: Payment

Default:1

Example:"Payment"

returnUrlstring, (URL)

For use with Flute Checkout only.

Indicates a target URL.

The customer is redirected to this Web page after payment is completed.

The request body field returnUrl value contains the literal string {{paymentSessionId}}. It was a placeholder. When this payment session endpoint successfully returned, Flute Checkout replaced the placeholder with the actual payment session identifier.

Example: https://isv.example.com/payments/returnUrl/16143c97-07bc-448c-9807-924189311a66

Example:"https://isv.example.com/payments/returnUrl/16143c97-07bc-448c-9807-924189311a66"

CheckoutUrlstring, (URL)

For use with Flute Checkout only.

Indicates the checkout URL.

The checkout page is the URL of the Flute Checkout page.

Example: https://public.flute.com/checkout/16143c97-07bc-448c-9807-924189311a66

Example:"https://public.flute.com/checkout/16143c97-07bc-448c-9807-924189311a66"

createdAtstring, (date-time)

For use with Flute Checkout only.

Indicates the date and time (in an ISO 8601 date-time UTC format) the transaction was created.

Example: 2026-01-19T14:27:02.767105Z

Example:"2026-01-19T14:27:02.767105Z"

expiresAtstring, (date-time)

For use with Flute Checkout only.

Indicates the expiration date and time (in an ISO 8601 date-time UTC format) of the transaction.

Example: 2026-01-19T14:27:02.767105Z

Example:"2026-01-19T14:27:02.767105Z"

amountnumber, (double)

For use with Flute Checkout only.

Indicates the payment amount.

Example: 129.99

Example:129.99

currencystring or null

For use with Flute Checkout only.

Indicates the currency code (in ISO 4217 currency code).

Example: USD

Example:"USD"

statusstring

For use with Flute Checkout only.

Indicates the payment session status.

Possible values:

Status	Description
Created	Payment session was initialized but not yet processed.
Cancelled	Payment session was cancelled before completion.
Completed	Payment session was completed. Check transaction details to verify if the payment was approved or not.
Failed	Payment was attempted but did not succeed. A new session must be created for a new payment attempt.
Expired	Payment session expired before being completed.

Example: Created

Example:"Created"

paymentMethodTypesArray of strings

For use with Flute Checkout only.

Indicates the payment method type name.

Value values:

Name	Notes
Card	For credit or debit card
Ach

Example: [ "Card", "Ach" ]

Example:

[
  "Card",
  "Ach"
]

taxRatenumber or null, (double)

Indicates the tax rate percentage pinned on the session.

Omitted when the session has no tax configured. Always set and cleared together with taxMode.

Example: 8.25 (for 8.25%)

Example:8.25

taxModeinteger or null, (enum)

Indicates whether the amount already includes the tax or the tax was added on top of it.

Omitted when the session has no tax configured. Always set and cleared together with taxRate.

Value	Name	Description
1	Exclusive	The tax was added on top of `amount`. The payer was charged `amount` plus the tax.
2	Inclusive	The `amount` already included the tax. No extra amount was added.

Example: 1

Example:1

metadataobject or null

For use with Flute Checkout only.

Specifies key-value pairings.

This is an optional collection of key-value pairings to provide additional information for the checkout process. They are arbitrary values, often specific to the transaction.

Examples:
[ {"orderId": "9921"} ]
[ {"invoiceNumber": "INV-2026-001"} ]

Example:

[
  {
    "orderId": "9921"
  },
  {
    "invoiceNumber": "INV-2026-001"
  }
]

Response

{
  "id": "16143c97-07bc-448c-9807-924189311a66",
  "mode": "Payment",
  "returnUrl": "https://isv.example.com/payments/returnUrl/16143c97-07bc-448c-9807-924189311a66",
  "CheckoutUrl": "https://public.flute.com/checkout/16143c97-07bc-448c-9807-924189311a66",
  "createdAt": "2026-01-19T14:27:02.767105Z",
  "expiresAt": "2026-01-19T14:27:02.767105Z",
  "amount": 129.99,
  "currency": "USD",
  "status": "Created",
  "paymentMethodTypes": [
    "Card",
    "Ach"
  ],
  "taxRate": 8.25,
  "taxMode": 1,
  "metadata": [
    {
      "orderId": "9921"
    },
    {
      "invoiceNumber": "INV-2026-001"
    }
  ]
}