Skip to navigation
API ReferenceThe four calls

Create a checkout session

Creates a hosted payment page at your payment provider and returns its url. Redirect the customer there. top_up buys credits for a prepaid plan, subscription starts a plan, and payment_method saves a card for postpaid invoices. The provider is the customer’s own payment_provider if set, then the first matching routing rule, then the account default, unless the request names one. When payment succeeds, Runledger grants the credits or starts the subscription and sends checkout_session.completed. Top-up credits expire one year after payment completes unless the plan’s top_up.credits_expire_in or this request’s credits_expire_in sets another length. That holds whether the session comes from your API call or from the customer view.

Authentication

AuthorizationBearer

A secret key (rl_sk_test_..., rl_sk_live_...) or a restricted key with limited scopes (rl_rk_test_..., rl_rk_live_...). A restricted key can carry agent: true and an expires_at, and is what a coding agent should hold. Keys end in a checksum so secret scanners can recognize them. People create, roll and revoke keys in the dashboard; GET /v1/api_keys lists them, masked.

Request

This endpoint expects an object.
modeenumRequired

top_up buys credits, subscription starts a plan, payment_method saves a card for postpaid invoices.

Allowed values:
success_urlstringRequiredformat: "uri"
Where the customer goes after paying.
customer_idstringOptional
external_customer_idstringOptional
creditsstringOptional

top_up only: credits to buy, as a decimal string, within the plan’s top-up limits. The credits join the plan’s top-up pool.

credits_expire_instringOptional

top_up only: how long the purchased credits last, as an ISO 8601 duration. Overrides the plan’s top_up.credits_expire_in. Leave it out to use the plan’s, which is one year when the plan sets none.

planstringOptional

subscription only: the plan (ID or key) to start.

cancel_urlstringOptionalformat: "uri"
Where the customer goes if they leave without paying.
expires_instringOptional
How long the page stays open, as an ISO 8601 duration. Default PT1H, maximum PT24H.
payment_providerstringOptional

Use this connected provider (by name) for this session instead of the one routing picks. Fails if the customer already saved a method at another provider.

metadatamap from strings to stringsOptional
Up to 50 keys of your own, with keys up to 40 characters and values up to 500 characters.

Response

The open checkout session.
idstring
object"checkout_session"
customerstring
modeenum

top_up buys credits, subscription starts a plan, payment_method saves a card for postpaid invoices.

Allowed values:
statusenum
Allowed values:
urlstringformat: "uri"
The hosted page to send the customer to.
expires_atdatetime
payment_providerstring
The name of the provider hosting the page, chosen by routing unless the request named one.
livemodeboolean
created_atdatetime
success_urlstringOptionalformat: "uri"
cancel_urlstringOptionalformat: "uri"
creditsstringOptional
planstringOptional
amount_totalobjectOptional
An amount of money in the currency's minor unit.
resultobjectOptional
What completion produced.
provider_referencestringOptional
The provider's ID for the payment, for reconciliation.
paymentstringOptional

The provider-neutral payment record (pay_...), once the customer has paid.

metadatamap from strings to stringsOptional
Up to 50 keys of your own, with keys up to 40 characters and values up to 500 characters.
completed_atdatetimeOptional

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
424
Failed Dependency Error
429
Too Many Requests Error
500
Internal Server Error