For agents

This page is for a coding agent integrating this API, and for the human pointing one at it. Everything here is machine-readable on purpose.

The short version#

https://docs.avvio.xyz/llms.txt        index of everything, with links
https://docs.avvio.xyz/llms-full.txt   the entire corpus in one fetch
https://docs.avvio.xyz/partner-payouts.openapi.yaml   the contract

llms-full.txt is the whole of the quickstart, the error reference and the going-live checklist concatenated, with every code sample expanded into all three languages. One fetch, no HTML to strip, no pagination. Start there rather than crawling the site.

Drive the API directly with MCP#

The npm package ships an MCP server over stdio, so an agent can price and send payouts without anyone writing an HTTP client first.

claude mcp add avvio-payments -- npx -y @avvio/payments mcp

{
  "mcpServers": {
    "avvio-payments": {
      "command": "npx",
      "args": ["-y", "@avvio/payments", "mcp"],
      "env": { "AVVIO_API_KEY": "ak_test_…", "AVVIO_ORG_ID": "cmsx…" }
    }
  }
}

The tool list is on the MCP server page, generated from the server itself. Two properties matter more than the list:

• Money-moving tools require confirm: true as a separate argument. An agent told "pay Maria" has to state the intent to move money explicitly, so a half-parsed instruction cannot become a payment. It costs one field and removes a category of accident.

• Give an agent a test key. A key starting ak_test_ cannot move real money, and every tool reports which mode it is in.

If you are writing the integration instead#

Read these in this order. They are short and each one is answering a question the next one assumes.

1. Quickstart — the whole flow, with curl for every step.
2. Errors — every error type, marked with whether the request

executed and whether retrying is safe. This is the page to internalise before writing any retry logic.

1. Going live — reconciliation, webhooks, and what changes when

the money is real.

Then generate a client from the OpenAPI spec rather than hand-rolling HTTP:

npx @openapitools/openapi-generator-cli generate \
  -i partner-payouts.openapi.yaml -g python -o ./avvio --package-name avvio_payouts

The four things agents get wrong here#

Retrying without the same Idempotency-Key. Every mutation takes one, and a retry that generates a fresh key is a second payment rather than a retry. Persist the key before sending, reuse it on every attempt. This is the single most expensive mistake available on this API.

Treating a timeout as a failure. It is an unknown outcome: the payout may exist. Retry with the same key — a replay returns the original. Starting over is how one wage advance becomes two.

Treating completed as final. A receiving bank can return a settled payment days later, and the payout flips to failed with returned_by_bank. Reconcile from GET /events and keep processing a payout after it completes.

Inventing corridor fields. The fields a beneficiary needs depend on how the organization is routed and can change. Read GET /recipients/{orgId}/corridors and build the request from the response. Mexico is one field; India is two. Hardcoding either is a bug waiting for a re-route.

There is no browser playground#

x-api-key is deliberately absent from the CORS allowlist, so a browser cannot call this API at all. Do not generate front-end code that calls it directly, and do not suggest putting the key in a client-side environment variable — it is a bearer credential for the partner's money. The API is server-to-server, and the interactive surface is the CLI.

Verify before you assert#

Everything on this site is generated from source: the command list from the CLI's own help text, the tool list from the MCP server, the endpoint table and every code sample from the OpenAPI spec, the sandbox triggers from the scenario table the sandbox runs. If a page and the API disagree, the API is right and the page is a bug — tell us, with the requestId.