Partner payouts · API version 2026-08-18.1

Pay your customers in their local currency, straight from your funded balance.

Server to server, one API key, 23 endpoints. Your end users never onboard with us. The money leaves your balance, and the person receiving it is your counterparty, not ours.

Move a real payout before you write any code

The package ships a client, a CLI and an MCP server together, with zero runtime dependencies. The CLI is the fastest honest path from nothing to a payout that moved — no signup form, no playground, no code.

export AVVIO_API_KEY=akid_test_…
export AVVIO_PRIVATE_KEY='-----BEGIN PRIVATE KEY-----…'
export AVVIO_ORG_ID=cmsx…

npx -y @avvio/payments doctor     # is the credential right?
npx -y @avvio/payments guide      # the whole flow, as commands

doctor names which of the four things is wrong — key, organization, base URL, or an account that cannot pay yet — because "it doesn't work" is otherwise four indistinguishable problems. Then guide prints this:

Nothing above touches a payment network while your key id starts akid_test_.

The sandbox is deterministic — you choose the outcome

The last four digits of the beneficiary account number select what the payout does. Same input, same outcome, every time: a partner writing tests needs that, and a flaky sandbox teaches integrators to wrap correct code in retries. The trigger travels with the beneficiary rather than living in a header you have to remember on every call.

Account ends	What happens	Status path	failureCode
`0001`	Fails at the rail. The money returns to your balance.	pending → processing → failed	`account_invalid`
`0002`	Settles slowly, so you can watch pending → processing → completed.	pending → processing → completed	—
`0003`	Completes, then the receiving bank RETURNS it. This is the case most integrations get wrong — a completed payout is not always final.	pending → processing → completed → failed	`returned_by_bank`
`0004`	Rejected by compliance. The money does NOT come back automatically.	pending → processing → failed	`compliance_rejected`
`0005`	The quote expires before it can be executed.	refused at create	—
`0006`	Waits for you to fund it from your own wallet. Returns requiresFunding, then instructions, then settles once you confirm. The other funding model.	pending → processing → completed (after you fund it)	—
`anything else`	Completes normally.	pending → processing → completed	—

0003 is the one to run before you go live. It completes and then fails — a receiving bank returning a settled payment days later is the case a ledger that treats completed as immutable gets wrong. The quickstart walks it through.