Billing

Charge the saved card to top up prepaid balance

Changed on

Charges the org's default saved card off-session for amountCents and returns the PaymentIntent id and status, which tells the client what to do next. The balance credit is applied by the payment_intent.succeeded webhook (the authoritative money signal), not this response: poll the balance after success.

Requires the billing.manage permission. See Permissions for the roles and API key permissions that include it.

post/v1/orgs/{orgId}/billing/deposit

Request

  • Base URL
    https://api.openrelay.inc
  • URL
    https://api.openrelay.inc/v1/orgs/{orgId}/billing/deposit
  • Auth
    HTTP bearer

Path parameters

orgIdstring required

Request body

amountCentsinteger required

Amount to charge the saved card, in cents. The flat floor is $25 and the default per-deposit cap is $500 (raised to an approved monthly spend limit). While the org has usage running the endpoint requires at least one hour of the current burn; read the exact figure from Balance.minDepositCents rather than re-deriving it.

deviceEventIdstring

Optional Fingerprint event id (see DeviceSignals).

deviceFingerprintstring

Optional Fingerprint visitor id (see DeviceSignals). Recorded and clustered. A device that puts the account on a verification hold gets 403 ACCOUNT_PENDING_VERIFICATION, or 403 VERIFICATION_UNAVAILABLE when the hold could not be recorded; every other verdict is observe-only.

idempotencyKeystring

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).

Response

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

clientSecretstring

Set only when status is requires_action (on-session SCA).

declineCodestring

Why the card was declined, set when status is requires_payment_method and Stripe gave a reason: a Stripe decline code (https://docs.stripe.com/declines/codes) such as insufficient_funds, expired_card, incorrect_cvc or card_velocity_exceeded. A decline Stripe asks merchants not to explain (fraudulent, lost_card, stolen_card, merchant_blacklist) is reported as generic_decline. New codes can appear, so treat an unknown one as a generic decline.

paymentIntentIdstring required
publishableKeystring

Set with clientSecret: the Stripe publishable key Stripe.js needs to confirm the PaymentIntent on-session.

statusstring required

Stripe PaymentIntent status. "succeeded" → credit lands via webhook; "requires_action" → complete SCA on-session with clientSecret; "requires_payment_method" → the card was declined.

Example response

{
  "declineCode": "insufficient_funds"
}

Changes

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status