Creates a new payment session

Request

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

This endpoint creates a new payment session.

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

Bodyapplication/json

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

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

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

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.

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

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

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

curl -i -X POST \
  https://sandbox.api.flute.com/v2/payment-sessions \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -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"
      }
    },
    "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.

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