Skip to navigation

Create a wallet top-up link

Creates a hosted payment page (Stripe Checkout or a Razorpay Payment Link) that adds amount_minor to the API token’s organization wallet once the customer pays. Open checkout_url in a browser; nothing is charged until the customer pays there, and the wallet is credited only after the payment succeeds (poll GET /billing/wallet to confirm). The gateway and currency follow the organization’s billing profile. Billing applies its minimums and refuses a frozen or closed wallet, an organization that is not billed, or (first top-up) an amount below the first top-up minimum: 422 topup_rejected with Billing’s message. An organization without a wallet gets 404 wallet_not_found; no wallet is created. The token’s principal also needs permission to manage the organization’s billing; a restricted or suspended organization can still top up. Requires scope: billing.topup.

# Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first).
curl -X POST "https://api.ibee.ai/v1/billing/topups?workspace_id=$WORKSPACE_ID" \
-H "Authorization: Bearer $IBEE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"amount_minor": 100000}'

Authentication

AuthorizationBearer

IBEE platform API token. Production tokens start with ibee_prod_key_; development tokens start with ibee_dev_key_. Use a token only with its matching gateway environment.

Headers

Idempotency-KeystringOptionalformat: "^[!-~]{8,128}$"8-128 characters

Retry key for this top-up, scoped to the organization’s wallet. A repeated key returns the payment link (and amount) it first created. Without a key, every call creates a new payment link.

Query parameters

workspace_idstringRequiredformat: "^[1-9][0-9]*$">=1 character

The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected.

Request

This endpoint expects an object.
amount_minorlongRequired>=1

Amount to add, an integer in the wallet currency’s minor unit (paise for INR, cents for USD). Billing applies its minimum.

Response headers

Cache-ControlstringOptional

Always no-store.

Response

Payment link created. Repeating the same Idempotency-Key returns the same link.

checkout_urlstringformat: "uri"
The https payment page to open in a browser.
gatewayenum
The payment gateway serving the page.
Allowed values:
amount_minorlong
Amount the page charges, in the currency's minor unit.
currencystring

ISO 4217 currency of the amount, such as INR or USD.

expires_atdatetime or null
When the page stops accepting payment, if it expires.
payment_attempt_idstring
Billing's id for this payment attempt.
organization_idstring
The API token's organization, whose wallet is credited.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
413
Content Too Large Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
502
Bad Gateway Error
503
Service Unavailable Error
504
Gateway Timeout Error