> ## Documentation Index > Fetch the complete documentation index at: https://docs.recoupable.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create Credits Top-Up Session > Top up credits on the authenticated account. **One credit equals one US cent (\$0.01).** The customer is charged `credits` plus a Stripe processing fee (US card pricing: 2.9% + \$0.30) — e.g. `credits: 10000` charges \$103.30 total (\$100.00 credits + \$3.30 fee). **Two outcomes, distinguished by response shape:** - **Auto-charged** — if the account has a card on file (from a prior subscription or top-up), the card is charged immediately and the response is `{ paymentIntentId, creditsPurchased, totalCents }`. Credits land in the account's balance asynchronously via Stripe webhook (typically within seconds). No human interaction required. - **Checkout required** — if no card is on file, or the saved card requires 3-D Secure authentication, the response is `{ id, url }` with a hosted Stripe Checkout URL. Redirect to that URL; credits land on successful payment. Clients should discriminate on the presence of `url` (Checkout) vs `paymentIntentId` (auto-charged). Cards entered through the Checkout fallback are saved for future top-ups, so a customer's second top-up typically auto-charges. ## OpenAPI ````yaml api-reference/openapi/accounts.json POST /api/credits/sessions openapi: 3.1.0 info: title: Recoup API - Accounts description: >- API documentation for the Recoup platform - an AI agent platform for the music industry license: name: MIT version: 1.0.0 servers: - url: https://api.recoupable.dev security: [] paths: /api/credits/sessions: post: description: >- Top up credits on the authenticated account. **One credit equals one US cent (\$0.01).** The customer is charged `credits` plus a Stripe processing fee (US card pricing: 2.9% + \$0.30) — e.g. `credits: 10000` charges \$103.30 total (\$100.00 credits + \$3.30 fee). **Two outcomes, distinguished by response shape:** - **Auto-charged** — if the account has a card on file (from a prior subscription or top-up), the card is charged immediately and the response is `{ paymentIntentId, creditsPurchased, totalCents }`. Credits land in the account's balance asynchronously via Stripe webhook (typically within seconds). No human interaction required. - **Checkout required** — if no card is on file, or the saved card requires 3-D Secure authentication, the response is `{ id, url }` with a hosted Stripe Checkout URL. Redirect to that URL; credits land on successful payment. Clients should discriminate on the presence of `url` (Checkout) vs `paymentIntentId` (auto-charged). Cards entered through the Checkout fallback are saved for future top-ups, so a customer's second top-up typically auto-charges. requestBody: description: Top-up parameters required: true content: application/json: schema: $ref: '#/components/schemas/CreateCreditsSessionRequest' responses: '200': description: >- Top-up initiated successfully. Some fields are conditional on which path was taken — see each field's description. content: application/json: schema: $ref: '#/components/schemas/CreditsTopupResponse' '400': description: Bad request - missing or invalid parameters content: application/json: schema: $ref: '#/components/schemas/CreditsSessionErrorResponse' '401': description: Unauthorized - invalid or missing authentication content: application/json: schema: $ref: '#/components/schemas/CreditsSessionErrorResponse' security: - apiKeyAuth: [] - bearerAuth: [] components: schemas: CreateCreditsSessionRequest: type: object required: - credits properties: successUrl: type: string format: uri description: >- The URL to redirect the customer to after a successful Stripe Checkout payment. Only used when the response is a Checkout fallback (no card on file or 3-D Secure required) — ignored when the card on file is charged directly. Defaults to a generic Recoup success page if omitted. example: https://chat.recoupable.com?credits=success credits: type: integer minimum: 1 description: >- The number of credits to purchase. One credit equals one US cent (\$0.01), so the value of the credits in USD is `credits / 100`. Example: `250` is \$2.50 worth of credits (the customer is also charged a Stripe processing fee on top). example: 250 accountId: type: string format: uuid description: >- UUID of the account to create the session for. Only applicable when the authenticated account has admin access to multiple accounts. If not provided, creates a session for the API key's own account. example: 123e4567-e89b-12d3-a456-426614174000 CreditsTopupResponse: type: object description: >- Top-up response. Two paths share this shape — clients can discriminate on the presence of `url` (Checkout fallback) vs `paymentIntentId` (auto-charged). properties: paymentIntentId: type: string description: >- **Auto-charge path only.** The Stripe PaymentIntent ID for the off-session charge. Useful for reconciliation and support. Omitted on the Checkout fallback path. example: pi_3O1a2b3c4d5e6f7g_h8i9j0kL creditsPurchased: type: integer minimum: 1 description: >- **Auto-charge path only.** The number of credits purchased, matching the `credits` request field. These credits are added to the account's balance asynchronously via Stripe webhook (typically within seconds). Omitted on the Checkout fallback path. example: 250 totalCents: type: integer minimum: 1 description: >- **Auto-charge path only.** Total amount in cents charged to the saved card, equal to `creditsPurchased` plus the Stripe processing fee. Omitted on the Checkout fallback path. example: 289 id: type: string description: >- **Checkout fallback only.** The Stripe Checkout Session ID. Omitted on the auto-charge path. example: cs_test_a1b2c3d4e5f6g7h8i9j0 url: type: string format: uri description: >- **Checkout fallback only.** The hosted Stripe Checkout URL — redirect the customer here to enter card details and complete payment. Omitted on the auto-charge path. example: https://checkout.stripe.com/pay/cs_test_a1b2c3d4e5f6g7h8i9j0 CreditsSessionErrorResponse: type: object required: - error properties: error: type: string description: Human-readable error message. example: credits must be a positive integer securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: Your Recoup API key. [Learn more](/quickstart#api-keys). bearerAuth: type: http scheme: bearer ````