Skip to main content
POST
Create a checkout session

Authorizations

Authorization
string
header
required

Your secret key, e.g. sk_live_... or sk_sandbox_....

Headers

X-Idempotency-Key
string

Optional key, 8 to 128 characters, that makes this request safe to retry. The first response is stored for 24 hours; a repeat returns it unchanged with X-Idempotent-Replayed: true.

Required string length: 8 - 128

Body

application/json
amount
number
required

Amount in major units. 50 means 50.00.

Required range: x >= 1
Example:

50

currency
string
required

Uppercase ISO 4217 code.

Required string length: 3
Example:

"USD"

description
string
required
Maximum string length: 500
Example:

"Order #1042"

return_url
string<uri>
required

Where the payer lands after the hosted page. Arrival there is not proof of payment.

Maximum string length: 2048
customer
object
required
expires_in_minutes
integer
Required range: 30 <= x <= 1440
webhook_url
string<uri>

Deliveries to this URL are not signed.

Maximum string length: 2048
statement_descriptor
string
Maximum string length: 22
Pattern: ^[A-Za-z0-9\s.,\-]+$
receipt_email
string<email>
Maximum string length: 255
entity_id
string
Maximum string length: 191
entity_created_at
string<date-time>
gateway_options
object

Optional processor-specific parameters, keyed by gateway code. Only gateways that declare options accept a section, and each section is validated against that gateway's own schema; an unknown code or an unsupported option is rejected. The codes and options available to your project are listed in your dashboard.

Example:
metadata
object

Up to 10 key/value pairs of your own, returned unchanged.

Example:
restriction
object

Lock the session to one country or one phone number. The two are mutually exclusive.

appearance
object

Per-session overrides on top of your project's checkout appearance.

Response

Checkout session created.

message
string
data
object