Skip to content

Top up the wallet

Get a card payment page to add money to your wallet. Approved accounts can request a bank transfer invoice with invoice: true. The first card top-up saves the card and enables automatic $20 top-ups by default. Set auto_top_up to change the amount or no_auto_top_up: true to decline them.

Parameters

#
amountstring
Wallet top-up, in whole dollars from 5 to 1000. Maximum $250 during the account's first 30 days.
auto_top_upstring
Automatic wallet top-up amount in whole dollars. The first card top-up enables $20 top-ups by default.
no_auto_top_upboolean
Decline automatic wallet top-ups for this checkout.
invoiceboolean
Request a bank transfer invoice. Available for accounts approved for bank transfer. The wallet is credited after payment.
organizationstring
Organization name or ID. A credential, named resource or sole membership can select the organization for you.

Returns

#
dataobjectAlways present
A billing outcome and its payment page.
Show 2 attributesHide attributes
purposestringAlways present
Payment outcome or required next action.
urlstringAlways present
Billing task or payment page.

Errors

#
CodeStatusWhat happened
invalid400An input is missing or invalid.
unauthenticated401The credential is missing, invalid, expired or revoked.
denied403The caller lacks permission for this action.
not_found404The resource is absent or inaccessible to this caller.
conflict409The request conflicts with the current resource state or an earlier request.
over_capacity409The request exceeds a resource or credential allowance.
access_list_full409The change would exceed the access-list allowance.
payment_required402Payment or credit is required.
rate_limited429The caller's request rate exceeds its limit.
busy429Too much work is in progress to accept this request.
unknown503The outcome is unconfirmed; a change may have happened.
unavailable503The service or requested feature is unavailable.

Notes

#
  • CLI: heaven login with HEAVEN_API_KEY unset. MCP: Heaven sign-in. cURL: HEAVEN_SIGN_IN_KEY from approved device sign-in (POST /v1/auth/create).
  • A key limited to a command list cannot run this command.