Create
$kit->checkout->create()
mode (or flowOverride).Signature
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
mode | 'payment'|'subscription' | Yes | What kind of checkout this is. |
amount | int | Required for payment mode; required for subscription mode in the elements flow | Minor currency units, minimum 50. |
currency | string | No | Defaults to the currency configured on init. |
priceId | string | Required for subscription mode | An existing Stripe Price ID. |
email | string | No | Used to look up or create a customer if userId doesn't resolve one. |
userId | string|int | No | Looked up via your storage adapter's findUserById() to resolve an existing Stripe customer. |
description | string | No | Line item name (payment mode, api flow) or PaymentIntent description. |
metadata | array<string,string> | No | Merged with StripeKit's own tracking metadata, including a generated checkout_id. |
customFields | list<array> | No | key, label, required?, pattern?, patternHint? per field. See Custom fields below. |
fieldValues | array<string,string> | No | Pre-filled values for customFields, validated immediately if both are given together. |
successUrl / cancelUrl | string | No | Override the values configured on init, for this call only. |
couponCode | string | No | Applied to the session if valid. |
flowOverride | 'api'|'elements' | No | Overrides the resolved flow for this call, equivalent to mode on $kit->payments->create(). |
Custom fields
customFields describes a small form your frontend should render before the customer can pay, for example to collect a company name or a VAT number:fieldValues and they are validated and stored immediately. Otherwise, leave fieldValues empty and collect them afterwards with submitFields().Example request — subscription, api flow
Example response
amount is always 0 for a subscription checkout in the api flow, the price itself is defined by priceId on Stripe's side, and subscriptionId is only populated once the customer completes checkout (typically observed via your webhook handler).Example request — one-off payment with custom fields, elements flow
Example response
requiresFields is true here because customFields were defined but no fieldValues were submitted yet. Render the form described by fieldSchema, then call submitFields().Errors
| Exception | When |
|---|---|
ValidationError | mode is neither 'payment' nor 'subscription'; amount is missing or too low for a payment checkout; priceId is missing for a subscription checkout; the email is invalid; or submitted fieldValues fail schema validation (fieldErrors is set). |
ConfigurationError | A couponCode was passed but the coupons module isn't attached, which should never happen in normal use since StripeKit::init() wires this automatically. |
StripeOperationError | Stripe rejects the underlying Checkout Session or PaymentIntent creation. |
Notes
expiresAtUtc). This is fixed and not currently configurable.checkout_id written into Stripe's metadata, so you can trace a Stripe object back to the checkout session that created it even without your own storage adapter.