# Creates a new payment session

<span class="api-endpoint">POST {{<a href="#urlbases">baseURL</a>}}/pay-int-api/payment-sessions</span>
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 [xxx](xxx) 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

Endpoint: POST /pay-int-api/payment-sessions
Version: V1
Security: Bearer

## Header parameters:

  - `x-api-version` (string)

## Request fields (application/json):

  - `amount` (number, required)
    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

  - `customerId` (string)
    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

  - `mode` (integer)
    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
    Example: 2

  - `skipAddressVerification` (boolean)
    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
    Example: true

  - `referenceId` (string)
    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

  - `tipAmount` (number)
    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
    Example: 14.5

  - `customerHandling` (any)
    Specifies the intent of the session.
| Name | Description |
|  --- | --- |
| CreateCustomer |  |
| TokenOnly |  |

Example: CreateCustomer
    Example: CreateCustomer

  - `returnUrl` (string)
    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}}

  - `paymentMethodTypes` (array)
    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

  - `afterCompletionMessage` (string)
    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.

  - `pageName` (string)
    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

  - `paymentNotes` (string)
    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.

  - `expiresAt` (string)
    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

## Response 200 fields (application/json):

  - `id` (string)
    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

  - `mode` (string)
    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
    Example: Payment

  - `returnUrl` (string)
    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

  - `CheckoutUrl` (string)
    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

  - `createdAt` (string)
    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

  - `expiresAt` (string)
    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

  - `amount` (number)
    For use with Flute Checkout only.

Indicates the payment amount.

Example: 129.99
    Example: 129.99

  - `currency` (string)
    For use with Flute Checkout only.

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

Example: USD
    Example: USD

  - `status` (string)
    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. |

Example: Created
    Example: Created

  - `paymentMethodTypes` (array)
    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"]

## Response 400 fields (application/json):

  - `details` (string)
    Indicates details about the error.

Example: Validation failed: -- Email: 'Email' is not a valid email address. Severity: Error
    Example: Validation failed: -- Email: 'Email' is not a valid email address. Severity: Error

  - `statusCode` (integer)
    Specifies the HTTP response status code.
This is the HTTP status code returned by the attempted delivery.
The following is a list of HTTP response status codes that include but are not limited to:
| HTTP Status | Meaning |
|  --- | --- |
| 200 | Delivery succeeded |
| 400 | Bad request |
| 401 | Unauthorized |
| 404 | Endpoint not found |
| 429 | Rate limited |

Example: 401
    Example: 401

  - `source` (string)
    Indicates the source of the error.
Example: <Service>
    Example: <Service>

  - `exceptionType` (string)
    Indicates the error's exception type.

Example: FluentValidation.ValidationException
    Example: FluentValidation.ValidationException

  - `correlationId` (string)
    Indicates the correlation identifier.

Example: aa6cfcd0-0295-4a4c-b074-8c901f114fef
    Example: aa6cfcd0-0295-4a4c-b074-8c901f114fef

  - `entityId` (string)
    Indicates the entity identifier.
Example:
null

  - `errorCode` (string)
    Indicates the error code.
Example:
null

## Response 500 fields (application/json):

  - `details` (string)

  - `statusCode` (integer)
    Specifies the HTTP response status code.
This is the HTTP status code returned by the attempted delivery.
The following is a list of HTTP response status codes that include but are not limited to:
| HTTP Status | Meaning |
|  --- | --- |
| 200 | Delivery succeeded |
| 400 | Bad request |
| 401 | Unauthorized |
| 404 | Endpoint not found |
| 429 | Rate limited |

Example: 401
    Example: 401

  - `source` (string)

  - `exceptionType` (string)

  - `correlationId` (string)

  - `entityId` (string)

  - `errorCode` (string)