Checkout Types

CheckoutSession — the response shape returned by every Checkout Sessions API endpoint.

Schemas returned by the Checkout Sessions API and embedded inside Webhook payloads.

CheckoutSession

Field	Type	Description
`id`	CheckoutSessionId	Unique session identifier.
`url`	string	Hosted checkout page URL. Redirect your customer here.
`status`	CheckoutSessionStatus	The session's lifecycle state. See CheckoutSessionStatus.
`active`	boolean	Deprecated — prefer `status`. `true` if the session has not expired.
`customerId`	CustomerId / null	Decal customer ID if one is attached.
`order`	Order	The full order object.
`failedAttempts`	integer	Number of times a payment-processor failed to capture the payment on this session.
`requireFromCustomer`	CheckoutRequireFromCustomer / null	Inputs the customer must provide before payment, or `null` if none were required.
`successUrl`	string/null	Where the customer is sent after a successful payment.
`callbackUrl`	string/null	Webhook URL for payment events.
`expiresAt`	DateTime	When the session expires.
`createdAt`	DateTime	When the session was created.
`updatedAt`	DateTime	When the session was last modified.

failedAttempts only counts payment-processor rejections — card declined, insufficient funds, on-chain transaction failure, or processor API error. It does not count validation errors (e.g. malformed card details) or user-cancelled flows. Per-attempt detail (reason, timestamp, method) is not currently exposed via the public API.

CheckoutSessionStatus

The lifecycle state of a checkout session, returned as the status field on every CheckoutSession. It is a string union:

type CheckoutSessionStatus =
  | "pending"
  | "processing"
  | "completed"
  | "failed"
  | "expired"
  | "completed_externally";

Value	Terminal	Description
`pending`	No	Session created and awaiting payment. This is the initial state.
`processing`	No	A payment has been submitted and is being confirmed (e.g. awaiting on-chain settlement).
`completed`	Yes	Payment was received through Decal and the order is paid.
`failed`	Yes	A payment attempt failed and the session was not completed.
`expired`	Yes	The session passed its `expiresAt` window without a completed payment.
`completed_externally`	Yes	The order was paid outside Decal (e.g. at the register via a connected POS) and the session was reconciled as such.

Terminal states are final — a session in completed, failed, expired, or completed_externally will not transition again. The deprecated active boolean is true only while status is pending or processing and the session has not yet expired.

CheckoutRequireFromCustomer

Declares which inputs the hosted checkout page must collect from the customer before it will accept payment. Set the flags you need to true when creating a session via the requireFromCustomer request field; the same object is echoed back on the CheckoutSession response, or null if no inputs were required. Every field is optional and defaults to false.

interface CheckoutRequireFromCustomer {
  phone?: boolean;
  shippingAddress?: boolean;
  location?: boolean;
}

Field	Type	When `true`, the customer must provide
`phone`	boolean	A phone number. Returned on the paid order as `order.customer.phone`.
`shippingAddress`	boolean	A full shipping address. Returned on the order as `order.shippingAddress`.
`location`	boolean	Minimal location data — country and postal code — used for compliance and jurisdiction screening. Returned on the order as `order.customer.location`.

A value you already supply at session creation pre-satisfies the matching requirement, so the customer is not prompted for it again — e.g. passing customer.phone satisfies phone, and passing a shippingAddress satisfies both shippingAddress and location. When a flag is omitted or false, that input is simply optional on the checkout page.

Checkout Types

CheckoutSession

CheckoutSessionStatus

CheckoutRequireFromCustomer

On this page