---
title: "Create a Stripe checkout topup session when enabled"
method: POST
path: "/v1/billing/stripe/topup-sessions"
---

# Create a Stripe checkout topup session when enabled

`POST /v1/billing/stripe/topup-sessions`

## Request

- Base URL: `https://api.skysay.ai`
- URL: `https://api.skysay.ai/v1/billing/stripe/topup-sessions`
- Auth: none declared

Optional number_request_id must belong to the authenticated workspace/project and still be payment_required (requires numbers:read in addition to wallet:write). Return selection is rebuilt from this validated request and the configured website origin. Only a signed Stripe webhook credits funds. A still-payable or uncertain checkout with a different return context is refused; no second checkout is created.

## Request body

- union
  - object
    - `amount_cents` integer
    - `amount_minor` integer, required
    - `cancel_url` string, uri
    - `currency` string: Must match wallet settlement currency when provided.
    - `idempotency_key` string: Request-aware checkout uses the persisted claim even when a caller supplies a key.
    - `number_request_id` string: Optional exact request context; never confirms, purchases or reserves a number.
    - `organization_id` string, required
    - `project_id` string
    - `receipt_email` string, email
    - `success_url` string, uri
  - object
    - `amount_cents` integer, required
    - `amount_minor` integer
    - `cancel_url` string, uri
    - `currency` string: Must match wallet settlement currency when provided.
    - `idempotency_key` string: Request-aware checkout uses the persisted claim even when a caller supplies a key.
    - `number_request_id` string: Optional exact request context; never confirms, purchases or reserves a number.
    - `organization_id` string, required
    - `project_id` string
    - `receipt_email` string, email
    - `success_url` string, uri

## Response `201`

Stripe checkout session or disabled status

## Other responses

- `404`: Request not found in workspace project
- `409`: Stale request or conflicting open checkout (reason topup_context_conflict, known checkout_url when available)

---

[API](https://skmtc.dev/skysay/apis/skysay-api.md) · [All operations](https://skmtc.dev/skysay/apis/skysay-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skysay/apis/skysay-api/revisions/148c7e111260?raw)