StripeKit - Create Payment

`kit.payments.create()`

Starts a one-off payment. What actually happens depends on the resolved flow, see Choosing a mode.

api flow: creates a Stripe-hosted Checkout Session in payment mode and returns hostedUrl to redirect the customer to.

elements flow: creates a PaymentIntent and returns clientSecret for your frontend to confirm with Stripe Elements.

Signature

Parameters

Field	Type	Required	Description
`amount`	`number`	Yes	Amount in minor currency units. Must be at least 50 (for example, $0.50), or a `ValidationError` is thrown. See Money and currency.
`currency`	`string`	No	3-letter ISO code. Defaults to the `currency` configured on init.
`customerId`	`string`	No	An existing Stripe customer to bill.
`email`	`string`	No	Used as `customer_email` on the Checkout Session (`api` flow) or as `receipt_email` (`elements` flow) when `customerId` is not given.
`userId`	`string\|number`	No	Your own internal user ID, stamped on the persisted record. Only used in the `elements` flow, where a `KitPaymentRecord` is saved.
`description`	`string`	No	Shown on the Checkout Session's line item, or set as the PaymentIntent's description.
`metadata`	`Record<string,string>`	No	Merged with StripeKit's own `source: "stripekit"` entry.
`paymentMethodId`	`string`	Only for `elements` flow	An existing payment method to charge directly instead of collecting a new one.
`receiptEmail`	`string`	Only for `elements` flow	Overrides `email` for the receipt address specifically.
`offSession`	`boolean`	Only for `elements` flow	Marks the PaymentIntent as off-session.
`confirm`	`boolean`	Only for `elements` flow	Forces immediate confirmation. Defaults to `true` automatically when both `paymentMethodId` and `offSession` are set.
`captureMethod`	`'automatic'\|'manual'`	Only for `elements` flow	Defaults to `'automatic'`.
`statementDescriptor`	`string`	Only for `elements` flow	Shown on the customer's card statement.
`applicationFeeAmount`	`number`	Only for `elements` flow	For Stripe Connect platforms taking a fee.
`returnUrl`	`string`	No	Unused by `create()` itself; kept for parity with other payment calls.
`mode`	`'api'\|'elements'`	Only when global `mode` is `'both'`	Overrides the resolved flow for this call.

Example request — `api` flow

Example response

Redirect the customer to hostedUrl.

Example request — `elements` flow

Example response

Pass clientSecret to your frontend. See Stripe Elements.

Errors

Exception	When
`ValidationError`	`amount` is below 50 minor units, or `currency` is not a valid 3-letter code.
`ConfigurationError`	The resolved flow is neither `'api'` nor `'elements'`, which normally only happens with a misconfigured `mode`.
`StripeOperationError`	Stripe rejects the request.

Notes

In the api flow, success_url and cancel_url fall back to the values configured on StripeKit.init(). If neither is set, StripeKit falls back to placeholder https://example.com/... URLs, which you almost certainly want to override, either globally on init or by configuring successUrl / cancelUrl.

Only the elements flow persists a KitPaymentRecord via savePayment(). The api flow does not persist anything until the customer completes checkout and, if configured, your webhook handler syncs the resulting payment. See Webhooks.

Create

kit.payments.create()#

Signature#

Parameters#

Example request — api flow#

Example response#

Example request — elements flow#

Example response#

Errors#

Notes#

`kit.payments.create()`

Signature

Parameters

Example request — `api` flow

Example response

Example request — `elements` flow

Example response

Errors

Notes