# Creates a new payment session

<a id="flute-v2-post-payment-sessions"></a>
<span class="api-endpoint">POST {{<a href="#urlbases">baseURL</a>}}/v2/payment-sessions</span>
This endpoint creates a new payment session.
<span class="api-seealso">See Also:</span><br>
To retrieve a payment session by Id, see `GET /v2/payment-sessions/{{paymentSessionId}}`.<br>
To cancel a payment session, see `POST /v2/payment-sessions/{{paymentSessionId}}/cancel`.

Endpoint: POST /v2/payment-sessions
Version: V2 Beta
Security: Bearer

## Request fields (application/json):

  - `amount` (number, required)
    Specifies the base amount (in USD) to charge.
For payment sessions (mode of either `SaveMethod` 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

  - `mode` (string)
    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
    Enum: "Payment", "SaveMethod", "PaymentAndSave"

  - `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 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

  - `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 (for $14.50)
    Example: 14.5

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

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

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

  - `isMultiUse` (boolean)
    Specifies the checkout URL can be used for multiple payments.
This value is applied only if using Flute Elements or Flute Checkout.
If `true`, the checkout URL can be used for multiple payments.
If `false`, the checkout URL cannot be used for multiple payments.
Example: true
    Example: true

  - `expiresAt` (string)
    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
    Example: 2027-02-19T20:24:52.934Z

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

## Response 200 fields (application/json):

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

  - `checkoutUrl` (string)
    Indicates full URL of the hosted checkout page for this payment session.

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

  - `checkoutUrlShort` (string)
    Indicates the shortened URL of the hosted checkout page for this payment session.

Example: https://smallurl.com/4kxm9p2
    Example: https://smallurl.com/4kxm9p2

## 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

  - `title` (string)

  - `cause` (string)

  - `resolution` (string)

  - `documentationUrl` (string)
    https://developer.flute.com/

## Response 500 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

  - `title` (string)

  - `cause` (string)

  - `resolution` (string)

  - `documentationUrl` (string)
    https://developer.flute.com/