Skip to main content
POST
Top up wallet (agent-paid)

Authorizations

X-API-Key
string
header
required

API key for authentication. Get your key from the API Keys page.

Body

application/json

A wallet top-up an agent pays for with the Machine Payments Protocol.

amount
string
required

Amount to add in USD, from 10.00 to 500.00. Charged over MPP once the agent presents a payment credential.

Pattern: ^(?=.*[1-9])(?:0|[1-9]\d{0,11})(?:\.\d{1,2})?$
Example:

"25.00"

Response

Payment settled and wallet credited

The settled top-up and the balance it produced.

status
enum<string>
required

settled: the wallet is credited. pending (HTTP 202): the card was charged and the credit lands shortly via webhook; do not pay again.

Available options:
settled,
pending
amount
string
required
Pattern: ^(?=.*[1-9])(?:0|[1-9]\d{0,11})(?:\.\d{1,6})?$
Example:

"25.00"

currency
enum<string>
required
Available options:
USD
Example:

"USD"

payment_reference
string
required

Stripe PaymentIntent that settled this top-up.

Example:

"pi_3QxYz2Ab"

ledger_entry_id
string | null
required
Example:

"wallet-grant:machine-payment:pi_3QxYz2Ab"

available_balance
string | null
required

Spendable balance after the credit landed; null when pending or unreadable.

Pattern: ^-?(?:0|[1-9]\d{0,11})(?:\.\d{1,6})?$
Example:

"31.44"

hint
string

On a 202: do not pay again.