Skip to main content
POST
/
checkout_sessions
Create checkout session
curl --request POST \
  --url https://api.lava.so/v1/checkout_sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "checkout_mode": "onboarding",
  "origin_url": "https://your-app.example.com/",
  "connection_id": "con_test_01KJHF4SFJ90Y0PKK3VJ9HF6WN",
  "subscription_config_id": "sc_123",
  "credit_bundle_id": "cb_abc123"
}
'
{ "checkout_session_id": "cs_test_01KJHF4SFHW93DY4BVF227F33V", "checkout_session_token": "eyJzZWNyZXQiOiJjc3NfdGVzdF9CSy1rYUVPbWlTcWdaTHRZdmszQXV3dXcta3UzdXl0WndEb0NBZmtXV193QnVnUmNKVXl6eDNXIiwiYmFzZSI6Imh0dHA6Ly9sb2NhbGhvc3Q6MzAwMC8ifQ==", "checkout_mode": "onboarding", "origin_url": "https://your-app.example.com/", "created_at": "2023-05-15T08:30:00Z", "connection_id": "con_test_01KJHF4SFJFP3GJYD74W240T5E", "subscription_config_id": "sc_123", "completed_at": "2023-05-15T08:35:42Z" }
For checkout_mode: "subscription", connection_id is optional:
  • Omit it for logged-out/new customers (checkout collects identity and creates a connection)
  • Include it for logged-in/returning customers (checkout reuses the existing connection)
// New customer subscription checkout
{
  "checkout_mode": "subscription",
  "origin_url": "https://yourapp.com",
  "subscription_config_id": "sub_plan_id"
}

// Returning customer subscription checkout
{
  "checkout_mode": "subscription",
  "origin_url": "https://yourapp.com",
  "subscription_config_id": "sub_plan_id",
  "connection_id": "conn_existing_customer_id"
}

Authorizations

​
Authorization
string
header
required

Bearer token authentication used for standard API calls. Format: 'Bearer YOUR_API_KEY'

Body

application/json
​
checkout_mode
enum<string>
required

Checkout mode: 'onboarding' creates a new wallet connection, 'topup' adds funds to an existing connection, 'subscription' creates a subscription checkout, 'credit_bundle' purchases a credit pack for an existing subscriber

Available options:
onboarding,
topup,
subscription,
credit_bundle
Example:

"onboarding"

​
origin_url
string<uri>
required

Origin url where the checkout will be opened

Example:

"https://your-app.example.com/"

​
connection_id
string

Required when checkout_mode is 'topup' or 'credit_bundle' - identifies the existing connection

Example:

"con_test_01KJHF4SFJ90Y0PKK3VJ9HF6WN"

​
subscription_config_id
string

Required when checkout_mode is 'subscription' - identifies the subscription configuration to use

Example:

"sc_123"

​
credit_bundle_id
string

Required when checkout_mode is 'credit_bundle' - identifies the credit bundle to purchase

Example:

"cb_abc123"

Response

Checkout session created

​
checkout_session_id
string
required

Unique identifier for the checkout session

Example:

"cs_test_01KJHF4SFHW93DY4BVF227F33V"

​
checkout_session_token
string
required

Secure token used for authentication in the checkout process

Example:

"eyJzZWNyZXQiOiJjc3NfdGVzdF9CSy1rYUVPbWlTcWdaTHRZdmszQXV3dXcta3UzdXl0WndEb0NBZmtXV193QnVnUmNKVXl6eDNXIiwiYmFzZSI6Imh0dHA6Ly9sb2NhbGhvc3Q6MzAwMC8ifQ=="

​
checkout_mode
enum<string>
required

Checkout mode: 'onboarding' creates a new wallet connection, 'topup' adds funds to an existing connection, 'subscription' creates a subscription checkout

Available options:
onboarding,
topup,
subscription,
credit_bundle
Example:

"onboarding"

​
origin_url
string
required

Origin url where the checkout will be opened

Example:

"https://your-app.example.com/"

​
created_at
string<date-time>
required

ISO 8601 timestamp when the checkout session was created

Example:

"2023-05-15T08:30:00Z"

​
connection_id
string

Identifier for the connection (only available after checkout completion)

Example:

"con_test_01KJHF4SFJFP3GJYD74W240T5E"

​
subscription_config_id
string

Identifier for the subscription configuration (only available for subscription mode)

Example:

"sc_123"

​
completed_at
string<date-time>

If completed, ISO 8601 timestamp when the checkout was completed

Example:

"2023-05-15T08:35:42Z"