Start a top-up through a payment gateway
Starts a top-up and returns an intent. It does not credit the wallet.
/v1/topupsStarts a top-up and returns an intent. It does not credit the wallet. The balance moves only when the processor's verified confirmation arrives, over the gateway webhook or a later refresh, so a 201 here means "the user may now pay", not "the user has paid". Follow next_action to complete the payment. Requires topups:write and an Idempotency-Key; an API key may top up any user, a user token only itself (forbidden, 403). Refuses user_not_found (404), tier_limit_exceeded (422), and idempotency_key_reuse (409) when the key comes back with a different body.
Authorization
bearerAuth A tenant API key (sk_{env}_{id}_{secret}), a wallet user token, or an IdP access token. Which principal the credential resolves to decides the scopes it carries; see the authentication guide.
In: header
Header Parameters
1 <= length <= 200Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
# Creating an intent does NOT credit the wallet. The balance moves when# the processor confirms, over a verified webhook or /refresh.curl -sS -X POST "$WALLETD_API/v1/topups" \ -H "Authorization: Bearer $WALLETD_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: topup-cart-8891" \ -d '{"user_id": "'$USER_ID'", "amount": 5000, "gateway": "stripe"}'{ "id": "0191c2d7-9e21-7f6b-a038-77d1c4b2e590", "user_id": "0191c2d4-8f3a-7c51-9b2e-4a6f8d310e27", "amount": 5000, "gateway": "stripe", "status": "created", "next_action": { "kind": "client_secret", "client_secret": "pi_3S1exampleIntent_secret_8kLmQ2" }, "client_secret": "pi_3S1exampleIntent_secret_8kLmQ2", "created_at": "2026-09-20T09:15:03Z"}