---
title: "Charge the saved card to top up prepaid balance"
method: POST
path: "/v1/orgs/{orgId}/billing/deposit"
tags: ["Billing"]
---

# Charge the saved card to top up prepaid balance

`POST /v1/orgs/{orgId}/billing/deposit`

Charges the org's default saved card off-session. The balance credit is applied by the payment_intent.succeeded webhook (the authoritative money signal), not this response — poll the balance after success.

## Path parameters

- `orgId` string, required

## Request body

- DepositRequest
  - `amountCents` integer, required — Amount to charge the saved card, in cents (bounds $10–$500).
  - `idempotencyKey` string — Client-generated id for this logical deposit; reused verbatim on retry so a network/client retry can't double-charge. Optional — the server generates one if absent (then retries won't dedupe).
  - `promoCode` string — Optional first-deposit promo code. When valid on the org's first deposit, amountCents is the deposit the customer wants credited and the saved card is charged the DISCOUNTED amount; the discount is credited as free (usage-only) credit by the webhook. Invalid / already-used codes are rejected (400) before any charge.

## Response `200`

Charge outcome (status drives the dashboard's next step)

- DepositResult
  - `clientSecret` string — Set only when status is requires_action (on-session SCA).
  - `paymentIntentId` string, required
  - `status` string, required — Stripe PaymentIntent status. "succeeded" → credit lands via webhook; "requires_action" → complete SCA on-session with clientSecret; "requires_payment_method" → the card was declined.

## Other responses

- `400` — The request is invalid
- `401` — Missing or invalid API key
- `403` — API key lacks the required scope
- `503` — A required integration (e.g. payments) is not configured

---

[API](https://skmtc.net/openrelay/apis/openrelay-api.md) · [All operations](https://skmtc.net/openrelay/apis/openrelay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openrelay/openrelay-api/versions/32905b8f44f8/schema)