Skip to main content
POST
/
api
/
v1
/
checkout
/
sessions
Create a checkout session
curl --request POST \
  --url http://localhost:7701/api/v1/checkout/sessions \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "amount": 15000,
  "currency": "BRL",
  "merchant_order_id": "ORD-123",
  "payment_method": "card",
  "gateway_first_try": "pagarme",
  "expires_in": 1800,
  "metadata": {},
  "success_url": "https://mystore.com/order/success",
  "cancel_url": "https://mystore.com/order/failed"
}
'
{
  "token": "cs_live_a1b2c3d4e5f6...",
  "amount": 15000,
  "currency": "BRL",
  "merchant_order_id": "ORD-123",
  "payment_method": "card",
  "gateway_first_try": "pagarme",
  "metadata": {},
  "success_url": "https://mystore.com/order/success",
  "cancel_url": "https://mystore.com/order/failed",
  "expires_at": "2026-06-23T14:30:00+00:00"
}

Authorizations

​
X-API-Key
string
header
required

Company API key. Send in the X-API-Key header.

Body

application/json
​
amount
integer
required

Amount in cents

Example:

15000

​
currency
enum<string>
required
Available options:
BRL,
USD
Example:

"BRL"

​
merchant_order_id
string
required
Example:

"ORD-123"

​
payment_method
enum<string> | null

Restrict to a specific method. Omit to allow both.

Available options:
card,
pix
Example:

"card"

​
gateway_first_try
enum<string> | null

Gateway slug to attempt first. Falls back to routing rules if not set or if the gateway is not enabled for this company.

Available options:
pagarme,
picpay,
safe2pay,
pagbank,
stripe,
asaas,
erede
Example:

"pagarme"

​
expires_in
integer

Lifetime in seconds (60–86400). Default: 1800.

Example:

1800

​
metadata
object

Arbitrary data forwarded to your frontend.

​
success_url
string<uri> | null

Frontend redirect after successful payment.

Example:

"https://mystore.com/order/success"

​
cancel_url
string<uri> | null

Frontend redirect after failed or cancelled payment.

Example:

"https://mystore.com/order/failed"

Response

Checkout session created

​
token
string

Single-use session token to pass to your frontend.

Example:

"cs_live_a1b2c3d4e5f6..."

​
amount
integer

Amount in cents — immutable once session is created.

Example:

15000

​
currency
string
Example:

"BRL"

​
merchant_order_id
string
Example:

"ORD-123"

​
payment_method
enum<string> | null
Available options:
card,
pix
Example:

"card"

​
gateway_first_try
string | null
Example:

"pagarme"

​
metadata
object
​
success_url
string<uri> | null
Example:

"https://mystore.com/order/success"

​
cancel_url
string<uri> | null
Example:

"https://mystore.com/order/failed"

​
expires_at
string<date-time>

ISO 8601 UTC timestamp when the session expires.

Example:

"2026-06-23T14:30:00+00:00"