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

post

https://api.inflowpay.com/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).

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

currency

string

enum

required

The currency of the checkout session, this currency will refer to product list prices

Allowed:

successUrl

string

The url to redirect to after a successful payment. We append sessionId and, when the flow produced one, paymentId as query parameters, preserving any query string you already set. sessionId is the identifier that resolves everywhere — it exists from session creation and GET /api/checkout/sessions/:id answers for one-time, subscription and free-trial flows alike, whereas the free-trial path has no payment. Both are pointers, not proof of payment: grant access from the webhook or from a server-side session read. Required by returnMode: APP_RETURN, whose button and automatic redirect both aim at it.

cancelUrl

object | null

The url to redirect to after a failed or cancelled payment. Same identifiers appended as on successUrl.

returnMode

string

enum

Which success screen the buyer sees after paying. DEFAULT (default) keeps the current confirmation page. APP_RETURN is for a buyer who came from your app — a 'Back to the app' button plus an automatic redirect to successUrl. APP_INSTALL is for a buyer who came from the web and does not have the app yet — the App Store and Google Play badges plus the email they must sign in with. APP_RETURN falls back to the plain confirmation on a mouse-driven device, where its button would point at an app that cannot be there; APP_INSTALL is shown on every device, including desktop, since its whole premise is a buyer who does not have the app yet. APP_RETURN needs a successUrl, APP_INSTALL needs appStoreUrl or playStoreUrl — taken from this request, or inherited from the link / subscription offer. A mode you set in THIS request is validated: an incomplete one is rejected with 400, so you never get a silent DEFAULT for a screen you asked for. A mode inherited from the link or the subscription offer is not — it falls back to DEFAULT rather than blocking a buyer over a configuration they cannot fix.

Allowed:

appStoreUrl

string

App Store listing shown on the APP_INSTALL success screen. Ignored on the other screens. APP_INSTALL needs this or playStoreUrl — one of the two is enough, taken from this request or inherited from the link / offer.

playStoreUrl

string

Google Play listing shown on the APP_INSTALL success screen. Ignored on the other screens. APP_INSTALL needs this or appStoreUrl — one of the two is enough, taken from this request or inherited from the link / offer.

products

array of objects

required

The list of products to purchase, the total amount is the sum of price * quantity for each product.

products*

customerEmail

string

deprecated

Default customer email pre-filled in the checkout session. @deprecated Prefer customer.email.

sessionCustomization

object

The customization of the checkout session

statementDescriptor

string

Optional statement descriptor (max 11 characters) shown on the customer's bank statement as 'INFLOWPAY* '. 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

deprecated

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

object

Customer information pre-filled in the checkout session (email, identity or business, billing country) with an optional locked flag to make those fields read-only for the buyer. Takes priority over the deprecated top-level customerEmail / billingCountry.

captureMode

string

enum

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.

Allowed:

marketplaceFeeInCents

number

≥ 0

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

Defaults to false

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 (unless consent-less save is enabled by Inflow admin).

Response

201Checkout session created