Skip to main content
POST
/
checkout_sessions
Create a checkout session
curl --request POST \
  --url https://api.lavapayments.com/v1/checkout_sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "checkout_mode": "onboarding",
  "origin_url": "https://your-app.example.com/",
  "reference_id": "customer_123456",
  "connection_id": "con_01K7QJT2YR0XPQQ5QZ6DWARNW1",
  "subscription_config_id": "sc_123"
}'
{
  "checkout_session_id": "cs_01K7QJT2YQ7W3NDZX5PY7ACZ0C",
  "checkout_session_token": "eyJzZWNyZXQiOiJjc3NfbGl2ZV9kTGlxakFGYktPZ3Bodms3N2o0b3ZZdmdSZEZHekNaTlpXRTZpbmdYRThPeWNHaFBza3JINWNoIiwiYmFzZSI6Imh0dHBzOi8vd3d3LmxhdmFwYXltZW50cy5jb20vIn0=",
  "checkout_mode": "onboarding",
  "origin_url": "https://your-app.example.com/",
  "connection_id": "con_01K7QJT2YRPFSVA0HNPTYC0ABT",
  "reference_id": "customer_123456",
  "subscription_config_id": "sc_123",
  "created_at": "2023-05-15T08:30:00Z",
  "completed_at": "2023-05-15T08:35:42Z"
}

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

Available options:
onboarding,
topup,
subscription
Example:

"onboarding"

​
origin_url
string<uri>
required

Origin url where the checkout will be opened

Example:

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

​
reference_id
string

Optional custom identifier to associate with this connection for easier lookup in your system

Example:

"customer_123456"

​
connection_id
string

Required when checkout_mode is 'topup' - identifies the existing connection to add funds to

Example:

"con_01K7QJT2YR0XPQQ5QZ6DWARNW1"

​
subscription_config_id
string

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

Example:

"sc_123"

Response

Checkout session created

​
checkout_session_id
string
required

Unique identifier for the checkout session

Example:

"cs_01K7QJT2YQ7W3NDZX5PY7ACZ0C"

​
checkout_session_token
string
required

Secure token used for authentication in the checkout process

Example:

"eyJzZWNyZXQiOiJjc3NfbGl2ZV9kTGlxakFGYktPZ3Bodms3N2o0b3ZZdmdSZEZHekNaTlpXRTZpbmdYRThPeWNHaFBza3JINWNoIiwiYmFzZSI6Imh0dHBzOi8vd3d3LmxhdmFwYXltZW50cy5jb20vIn0="

​
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
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_01K7QJT2YRPFSVA0HNPTYC0ABT"

​
reference_id
string

Your custom identifier for tracking this connection in your system

Example:

"customer_123456"

​
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"