---
title: "Create a checkout session for a one-time payment (recommended)"
method: POST
path: "/api/checkout/sessions/one-time-payment"
tags: ["Checkout Sessions"]
---

# Create a checkout session for a one-time payment (recommended)

`POST /api/checkout/sessions/one-time-payment`

Recommended way to start a hosted one-time payment. Replaces the deprecated `POST /api/checkout/payment`.

Returns `{ sessionId, checkoutUrl }` — redirect the buyer to `checkoutUrl` to pay. The `paymentId` is created once the buyer submits a payment method during the session. Subscribe to `checkout_session.*` merchant webhooks — the `paymentId` is included in the payload once the session is completed (e.g. `checkout_session.completed`).

## Request body

- CreateApiOneTimePaymentSessionDto
  - `currency` 'EUR' | 'USD', required — The currency of the checkout session, this currency will refer to product list prices
  - `successUrl` string — The url to redirect to after a successful payment, we will append the id of the payment in the query parameters as "?paymentId={{PAYMENT_ID}}"
  - `cancelUrl` string, nullable — The url to redirect to after the user failed to pay, we will append the paymentId in the query parameters
  - `products` ApiSessionProductDto[], required — The list of products to purchase, the total amount is the sum of price * quantity for each product.
    - `name` string, required — The name of the product to purchase
    - `price` number, required — The price of the product to purchase in cents (1000 = 10.00)
    - `quantity` number, required — The quantity of the product to purchase
    - `imageUrl` string — Product image URL shown in the checkout summary
  - `customerEmail` string — Default customer email pre-filled in the checkout session. @deprecated Prefer `customer.email`.
  - `sessionCustomization` ApiSessionCustomizationDto
    - `bgColor` string — The background color of the checkout session
    - `fontColor` string — The font color of the checkout session
    - `logoUrl` string — The logo url of the checkout session
    - `merchantName` string — The merchant name of the checkout session, the default merchant name will be used if not provided
    - `backgroundColor` string — The background color of the checkout session
  - `statementDescriptor` string — Optional statement descriptor (max 11 characters) shown on the customer's bank statement as 'INFLOWPAY* <descriptor>'. Falls back to the account-level statement descriptor if omitted.
  - `metadatas` object — Custom metadata for the session/payment, key/value pairs (supports nested objects and arrays)
  - `expiresIn` number — Duration in hours before the session expires. 0.75 = 45 minutes, 24 = 1 day. Minimum 0.25 (15 minutes). If not provided, the session will not have an automatic expiration.
  - `isVatIncluded` boolean — Whether the VAT is included in the product prices
  - `billingCountry` string — Optional default billing country (ISO 3166-1 alpha-2). When set, the checkout session is pre-filled with this country and VAT is recomputed accordingly. Ignored silently if the country is not supported for tax. @deprecated Prefer `customer.billingCountry`.
  - `customer` ApiSessionCustomerInfoDto
    - `id` string — Existing Inflow customer id (cus_...). When provided, the payment — and any saved payment method — is always attached to this customer, even if the buyer edits the pre-filled info on the checkout (the buyer's email is then kept on the payment only; no other customer is created or looked up). The customer's stored info pre-fills the checkout fields, which stay editable unless `locked` is set. The customer must belong to the merchant and have an email.
    - `email` string, email — Customer email pre-filled in the checkout session.
    - `billingCountry` string — Default billing country (ISO 3166-1 alpha-2). When set, the checkout session is pre-filled with this country and VAT is recomputed accordingly. Ignored silently if the country is not supported for tax.
    - `purchasingAsBusiness` boolean — Whether the buyer purchases as a business. Determines which identity set is used: when false/omitted the individual set (firstName/lastName), when true the business set (businessName/taxId).
    - `firstName` string — Customer first name (individual purchase set, used when purchasingAsBusiness is false/omitted).
    - `lastName` string — Customer last name (individual purchase set, used when purchasingAsBusiness is false/omitted).
    - `businessName` string — Business name (business purchase set, used when purchasingAsBusiness is true).
    - `taxId` string — Business tax identification number (business purchase set, used when purchasingAsBusiness is true).
    - `locked` boolean — When true, all customer info pre-filled here is locked on the checkout: the buyer sees the fields but cannot edit them.
  - `captureMode` 'AUTOMATIC' | 'MANUAL' — Set to MANUAL to authorize the payment at checkout and capture it later via `POST /api/payment/:paymentId/capture`. Defaults to AUTOMATIC (immediate capture). Card and wallet payments only.
  - `marketplaceFeeInCents` number — Marketplaces only: fixed fee to collect on this payment, in cents. Can only be set by the parent marketplace acting on behalf of a sub-merchant. Defaults to the marketplace's configured fee.
  - `savePaymentMethod` boolean — When true, the checkout offers the buyer the option to save their payment method (card / wallet) for future payments. The saved payment method is attached to the merchant's customer matching the buyer's email (created if needed). Pass `customer.id` to instead anchor it to a specific existing customer, regardless of the email the buyer enters. The buyer must still opt in via a checkbox for a reusable payment method to be stored.

## Response `201`

Checkout session created

- CheckoutSessionResponseDto
  - `sessionId` string, required — Checkout session unique identifier
  - `checkoutUrl` string, required — Hosted Checkout V2 URL. Redirect the buyer here to complete the checkout.

---

[API](https://skmtc.dev/inflowpay/apis/inflow-api.md) · [All operations](https://skmtc.dev/inflowpay/apis/inflow-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/inflowpay/inflow-api/revisions/3012dd3dd14a/schema)