Checkout

Create Stripe checkout sessions for customer wallet top-ups. The payment goes to the operator's Stripe account, and the workspace balance is credited automatically after payment.

Auth: Session token or platform key. When using a platform key, pass workspace_id in the request body.

Create a Checkout Session

POST /v1/platform/wallet/checkout

Generates a Stripe checkout URL. The customer pays total_amount which includes the base amount plus any configured markup and platform fees.

Body Parameters

Name	Type	Required	Description
`amount`	number	Yes	Top-up amount in USD
`success_url`	string	Yes	URL to redirect after payment
`cancel_url`	string	Yes	URL to redirect on cancellation
`workspace_id`	string	No	Target workspace (platform key only)

const checkout = await billing.checkout.create({
  amount: 25,
  successUrl: 'https://app.example.com/billing?status=success',
  cancelUrl: 'https://app.example.com/billing?status=cancelled',
})
// Redirect user to checkout.url

Response

{
  "url": "https://checkout.stripe.com/c/pay/cs_live_a1b2c3...",
  "base_amount": "25.000000",
  "platform_fee": "1.250000",
  "markup": "2.500000",
  "total_amount": "28.750000"
}

Response Fields

Field	Type	Required	Description
`url`	string	Always	Stripe checkout URL -- redirect the user here
`base_amount`	string	Always	The requested top-up amount
`platform_fee`	string	Always	Fee charged by Assistant Billing
`markup`	string	Always	Operator markup
`total_amount`	string	Always	Total charged to customer

Fee Calculation

The total is calculated as:

total = base_amount + (base_amount x markup%) + (base_amount x platform_fee%)

For a project with 10% markup and 5% platform fee, a $25 top-up:

Component	Amount
Base amount (credited to balance)	$25.00
Markup (10%)	$2.50
Platform fee (5%)	$1.25
Total charged	$28.75

After payment, the checkout.session.completed webhook credits the base amount ($25) to the workspace wallet.

Errors

Status	Cause
400	Invalid `amount` (< 1), missing URLs, or Stripe not configured
404	Project not found