Partner payouts · API version 2026-08-18

Pay your own customers, in their own currency, from your own 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=ak_test_…
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 starts ak_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.

Start here#

QuickstartAPI key to a completed payout, in one page.CLI24 commands, including the whole first-payout flow.ErrorsEvery type, whether it executed, and whether retrying is safe.Node SDK25 methods, no dependencies.MCP server15 tools, so an agent can drive payouts.Going liveWhat changes when the money is real.

There is no try-it playground, and there cannot be one#

The API key is a bearer credential for your money, and x-api-key is deliberately absent from the CORS allowlist — a browser cannot send one, including this one. A playground would have to teach you to paste a live key into a web page, so instead the CLI is the interactive surface: it runs where the credential belongs, on your machine or your server.