Skip to main content
POST
Open a top-up for self (end-user)

Authorizations

Authorization
string
header
required

60-3600 second end-user JWT minted via /credits/end-users/{id}/token. If the JWT has sid, send the original session value in X-Locus-Session-Id; sid contains only its SHA-256 fingerprint. Bearer tokens are replayable until expiry; use short TTLs, optional session binding, and Idempotency-Key on operations.

Headers

X-Locus-Session-Id
string

Required only when the end-user JWT carries sid. Send the original high-entropy session value; sid is its SHA-256 fingerprint. Ignored for secret-key authentication.

Required string length: 16 - 128
Pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{15,127}$

Body

application/json
usd
string
required

Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.

Pattern: ^\d+(?:\.\d{1,6})?$
successUrl
string<uri>
required
Maximum string length: 2048
cancelUrl
string<uri>
required
Maximum string length: 2048
credits
string

Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.

Pattern: ^\d+(?:\.\d{1,6})?$
metadata
object

Serialized object is limited to 500 characters.

Response

Checkout session

success
boolean
required
sessionId
string
required
Pattern: ^cs_
url
string<uri>
required
externalUserId
string | null
required
quote
object
required
bonus
object

Present only when this checkout session will mint a volume bonus on completion (tenant pool top-up reaching a tier).