Skip to main content
POST
/
api
/
v1
/
billing
/
checkout-session
Create a Stripe Checkout Session for self-service top-up
curl --request POST \
  --url http://localhost:3051/api/v1/billing/checkout-session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount_usd": "<unknown>",
  "save_payment_method": true
}
'

Documentation Index

Fetch the complete documentation index at: https://docs.omnifence.ai/llms.txt

Use this file to discover all available pages before exploring further.

Creates a Stripe Checkout Session and returns the URL to redirect your customer to. Two modes are supported:
  • payment (default) — a one-time top-up. The customer pays the amount_usd you supplied. Stripe credits your balance with the same USD amount once the checkout completes successfully, regardless of the presentment currency.
  • setup — a zero-dollar checkout that saves a card without charging it. Useful before enabling auto top-up. Omit amount_usd.
Requires the billing:write scope.

​
Amounts

FieldMinMaxNotes
amount_usd$5$5000Required for mode=payment, omitted for mode=setup.

​
Tax and currency

Checkout collects a billing address (required) so Stripe Tax can apply local tax. Customers in supported regions can pay in local currency via Adaptive Pricing; your USD balance is always credited the amount_usd you set.

​
After checkout

When the customer completes payment, Stripe sends a checkout.session.completed webhook to our server and we credit your balance. The success URL we set redirects them back to /billing?topup=success. If the payment fails or the customer cancels, no charge is made and the cancel URL redirects them back to /billing?topup=cancelled. The returned topup_intent_id is a durable handle to this top-up attempt — useful for correlating logs.

​
Webhook events to subscribe to

If you’re integrating directly (not via the dashboard), subscribe to the following Stripe events on your own Stripe account so you can react to top-up state changes:
  • checkout.session.completed
  • checkout.session.async_payment_succeeded
  • checkout.session.async_payment_failed
  • payment_intent.payment_failed

Authorizations

​
Authorization
string
header
required

API key from the Stars dashboard

Body

application/json
​
amount_usd
any
​
save_payment_method
boolean
​
mode
enum<string>
Available options:
payment,
setup

Response

200

Default Response