Add credit
POST
/v1/wallet/top-up
Add credit to the signed-in account — the single credit-purchase endpoint. Choose how to pay with method: card returns a secure Stripe checkout link to open (or, with a savedCardId, charges a card you saved earlier — instantly, no browser needed); crypto (with an optional coin) returns a hosted crypto checkout link. Saving a NEW card needs the browser once (Stripe's hosted page, for PCI) — after that, charging it is pure API. The response is either confirmed (credit landed immediately) or pending with a checkoutUrl to complete, then poll GET /wallet/top-up/{reference}. Retries are safe automatically — a double-submit within a short window won't charge twice. manual (instant credit) works only on development deployments.
Authorizations
Bearer
JWT bearer token from POST /v1/auth/login.
Type
HTTP (bearer)
or
ApiKey
Scoped API key for non-interactive clients (issued by PBI #1426).
Type
API Key (header: X-Api-Key)
Request Body
application/json
The unified credit-purchase payload (POST /v1/wallet/top-up, #2114) — the single way to add credit. An
amount plus the payment method, with the crypto coin and saved-card selectors each method needs.
The amount to add to the wallet, in USD.
Format
"double"Pattern
"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$"The crypto coin ticker to pay with (e.g. BTC); only used when Method is crypto.
The payment method — card, crypto, or manual (dev-only). Omit for the default manual.
A saved card to charge in-app; only used when Method is card (omit to open a hosted checkout for a new card).
Format
"uuid"Responses
OK
application/json
An agent-facing view of a single top-up / redeem (#1429): the reference to poll, its lifecycle status,
and — once confirmed — how much landed and the resulting balance. A string? WalletTopUpView.CheckoutUrl is present
only when a payment provider needs the human to complete a hosted checkout (the manual / redeem paths
credit immediately, returning a confirmed view with no URL).
The amount the top-up/redeem is for, in USD.
Format
"double"Pattern
"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$"The wallet balance to show alongside (post-credit once confirmed).
Format
"double"Pattern
"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$"A hosted checkout link to hand to the human, or null when credit is immediate.
How much was credited once confirmed; null while pending/failed.
Format
"double"Pattern
"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$"For a pending crypto checkout, the deposit address the invoice resolved; otherwise null.
For a pending crypto checkout, the exact coin amount to send to string? WalletTopUpView.CryptoAddress; otherwise null.
For a pending crypto checkout, the coin the invoice resolved (e.g. BTC); otherwise null.
Currency code (always USD for now).
Default
"USD"A human-readable result the agent can surface.
Lowercase payment method: manual | card | crypto.
Opaque reference to poll this transaction via GET /v1/wallet/top-up/{reference}.
Lowercase lifecycle: confirmed | pending | failed | cancelled | expired.