# Creates a new payment session

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

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

## Security:

  - `Bearer` (unknown)
    http bearer JWT

## Header parameters:

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

## Request fields (application/json):

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

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

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

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

  - `paymentMethods` (object)
    Identifies the payment methods a payment link accepts.
It is keyed by method so each one carries only the configuration that applies to it.

  - `paymentMethods.card` (object)
    Identifies the card configuration on a payable resource.

  - `paymentMethods.card.enabled` (boolean)
    Identifies whether card payments are accepted.

Naming the payment method without a body offers it with no further configuration.

Example: true
    Example: true

  - `paymentMethods.card.processorId` (string)
    Identifies the processor that charges this resource's card payments.
This must be an active card processor of the merchant.
Omit this value to pin the merchant's current default active card processor.
A response carries the pinned processor, or `null` for a resource created before pinning was introduced.
Example: d529945e-8d10-4cb4-9dc3-718e57f3f14e
    Example: d529945e-8d10-4cb4-9dc3-718e57f3f14e

  - `paymentMethods.ach` (object)
    Identifies the ACH configuration on a payable resource.

This is typed separately from the card configuration so that ACH-only settings are enforced by the contract rather than by validation.

  - `paymentMethods.ach.enabled` (boolean)
    Identifies whether ACH payments are accepted.

Naming the payment method without a body offers it with no further configuration.

Example: true
    Example: true

  - `paymentMethods.ach.processorId` (string)
    Identifies the processor that charges this resource's ACH payments.
This must be an active ACH processor of the merchant.
Omit this value to pin the merchant's current default active ACH processor.
A response carries the pinned processor, or `null` for a resource created before pinning was introduced.
Example: d529945e-8d10-4cb4-9dc3-718e57f3f14e
    Example: d529945e-8d10-4cb4-9dc3-718e57f3f14e

  - `paymentMethods.ach.achAllowFasterProcessing` (boolean)
    Identifies ACH (automated clearing house) payments made through this resource use same-day processing.
If `true`, a submitted ACH payment is processed the same day.
If `false`, a submitted ACH payment uses standard processing timing.
Example: false
    Example: false

  - `taxRate` (number)
    Identifies the tax rate percentage to apply to the base amount.
Valid values range from 0 to 100, with up to three decimal places.
`taxMode` and `taxRate` must be set together, or both omitted.
When both are omitted, there is no tax configured.
Example: 8.25 (for 8.25%)
    Example: 8.25

  - `taxMode` (string)
    Indicates how `taxRate` 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. |

`taxMode` and `taxRate` must be set together, or both omitted.
When both are omitted, the payment session has no tax configured.
Example: Exclusive
    Enum: "Exclusive", "Inclusive"

  - `metadata` (object)
    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."}]

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

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

  - `200` (unknown)
    OK

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

  - `paymentMethods` (object)
    Identifies the payment methods a payment link accepts.
It is keyed by method so each one carries only the configuration that applies to it.

  - `paymentMethods.card` (object)
    Identifies the card configuration on a payable resource.

  - `paymentMethods.card.enabled` (boolean)
    Identifies whether card payments are accepted.

Naming the payment method without a body offers it with no further configuration.

Example: true
    Example: true

  - `paymentMethods.card.processorId` (string)
    Identifies the processor that charges this resource's card payments.
This must be an active card processor of the merchant.
Omit this value to pin the merchant's current default active card processor.
A response carries the pinned processor, or `null` for a resource created before pinning was introduced.
Example: d529945e-8d10-4cb4-9dc3-718e57f3f14e
    Example: d529945e-8d10-4cb4-9dc3-718e57f3f14e

  - `paymentMethods.ach` (object)
    Identifies the ACH configuration on a payable resource.

This is typed separately from the card configuration so that ACH-only settings are enforced by the contract rather than by validation.

  - `paymentMethods.ach.enabled` (boolean)
    Identifies whether ACH payments are accepted.

Naming the payment method without a body offers it with no further configuration.

Example: true
    Example: true

  - `paymentMethods.ach.processorId` (string)
    Identifies the processor that charges this resource's ACH payments.
This must be an active ACH processor of the merchant.
Omit this value to pin the merchant's current default active ACH processor.
A response carries the pinned processor, or `null` for a resource created before pinning was introduced.
Example: d529945e-8d10-4cb4-9dc3-718e57f3f14e
    Example: d529945e-8d10-4cb4-9dc3-718e57f3f14e

  - `paymentMethods.ach.achAllowFasterProcessing` (boolean)
    Identifies ACH (automated clearing house) payments made through this resource use same-day processing.
If `true`, a submitted ACH payment is processed the same day.
If `false`, a submitted ACH payment uses standard processing timing.
Example: false
    Example: false

## Response 400:

  - `400` (unknown)
    Bad Request

## Response 400 fields (application/json):

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

Example: Unauthorized
    Example: Unauthorized

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

This is a unique identifier, a trace identifier, Flute attaches to a request/response pair so a single transaction can be traced end-to-end across systems and logs. 

Its intent is to support troubleshooting.
We recommend including this value when contacting support.

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

  - `entityId` (string)
    Indicates the entity identifier.
This is a field on Flute's standard error response object, alongside values such as `correlationId`, `errorCode`, or `statusCode`.
It's the identifier of the specific resource the failed request was about.
Error messages may specify "Entity with ID b31fbe9f-eebb-45ce-9cae-92265389f47f does not exist or has been deleted."
When a 404 (or similar entity-specific error, like a conflict) comes back,
check `entityId` to get the exact identifier of the record that couldn't be found or matched.
This is useful for confirming which resource reference was wrong, especially if the request touched multiple identifiers at once.
Example: null

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

  - `title` (string)
    Indicates a short, human-readable summary of the error category.

Example: Resource not found
    Example: Resource not found

  - `cause` (string)
    Indicates the reason the error occurred.

Example: The requested resource does not exist or has been deleted.
    Example: The requested resource does not exist or has been deleted.

  - `resolution` (string)
    Indicates the recommended action for resolving the error.

Example: Verify the resource ID is correct or retrieve a list of available resources.
    Example: Verify the resource ID is correct or retrieve a list of available resources.

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

## Response 500:

  - `500` (unknown)
    Internal Server Error

## Response 500 fields (application/json):

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

Example: Unauthorized
    Example: Unauthorized

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

This is a unique identifier, a trace identifier, Flute attaches to a request/response pair so a single transaction can be traced end-to-end across systems and logs. 

Its intent is to support troubleshooting.
We recommend including this value when contacting support.

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

  - `entityId` (string)
    Indicates the entity identifier.
This is a field on Flute's standard error response object, alongside values such as `correlationId`, `errorCode`, or `statusCode`.
It's the identifier of the specific resource the failed request was about.
Error messages may specify "Entity with ID b31fbe9f-eebb-45ce-9cae-92265389f47f does not exist or has been deleted."
When a 404 (or similar entity-specific error, like a conflict) comes back,
check `entityId` to get the exact identifier of the record that couldn't be found or matched.
This is useful for confirming which resource reference was wrong, especially if the request touched multiple identifiers at once.
Example: null

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

  - `title` (string)
    Indicates a short, human-readable summary of the error category.

Example: Resource not found
    Example: Resource not found

  - `cause` (string)
    Indicates the reason the error occurred.

Example: The requested resource does not exist or has been deleted.
    Example: The requested resource does not exist or has been deleted.

  - `resolution` (string)
    Indicates the recommended action for resolving the error.

Example: Verify the resource ID is correct or retrieve a list of available resources.
    Example: Verify the resource ID is correct or retrieve a list of available resources.

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