Top-ups (on-ramp)

Bring money in from M-Pesa, card or bank transfer and follow it until it's in the balance.

A top-up turns local money into an AutoPayKe balance, held as USDC in the account's own wallet. Today that means M-Pesa in Kenya. Card and bank transfer are built and appear when they're switched on.

The JavaScript and Python samples use the call helper from Errors, with auth set to { Authorization: `Bearer ${token}` }.

1. See what's on

curl "https://api.autopayke.com/api/v1/funding/options" \
  -H "Authorization: Bearer $AUTOPAYKE_TOKEN"

2. Start the top-up

The customer gets an M-Pesa prompt on their phone and approves it with their PIN.

curl -X POST "https://api.autopayke.com/api/v1/funding/mobile-money" \
  -H "Authorization: Bearer $AUTOPAYKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1500",
    "phone": "+254712345678",
    "operator": "Safaricom",
    "idempotencyKey": "topup-2026-11-03-0001"
  }'

3. Follow it

Stream changes from /funding/{id}/live, or poll /funding/{id} every two seconds, until progress.terminal is true. See Real-time status.

Statuses

Status	Means
`pending`	Created; waiting for the customer (open the checkout, approve the prompt, make the transfer)
`processing`	The payment network is handling it
`succeeded`	The money arrived; crediting is next
`crediting`	USDC is on its way to the wallet
`credited`	In the balance. Final.
`requires_review`	Held for a manual check before it continues
`failed`	Didn't go through; `failureReason` says why. Final.
`expired`	Nobody paid in time. Final.
`cancelled`	Stopped before payment. Final.
`reversed`	Paid, then returned to the payer. Final.

Card and bank transfer

Card returns a checkoutUrl on a hosted page; card details never touch your servers or ours. Money from a new card can be held for a period before it can be withdrawn; holdUntil says until when.
Bank transfer returns a virtualAccount to transfer into, the exact amount, and when it expires. It's in Nigerian naira today.

Full parameters are in the Top-ups reference.