How it works

You keep a US dollar balance with Avvio. To pay someone, you tell us who they are and how much to send, and we deliver it to their bank account in their own currency. The people you pay never sign up with Avvio; the payment comes from your business.

API basics

Every path below is relative to one base URL, the same in the sandbox and in production:

https://api.avvio.xyz/business/api/v1

Authentication is one header. Send the complete avvio_live_… or avvio_test_… key as x-api-key on every request; there is nothing to sign, and the key’s prefix decides whether real money moves. Authentication covers issuing, limiting and rotating keys.

Every write that moves money or creates a recipient, payout, batch or link takes an Idempotency-Key. Retrying with the same key returns the original result instead of a second payment. Idempotency lists the routes and the replay rules.

State changes arrive as signed webhooks and are recorded in an ordered event feed you can replay. Webhooks covers signing and delivery, and Reconcile your ledger the feed.

Every error carries a type to branch on, and Errors says for each one whether money moved and whether a retry is safe. Environments & sandbox covers the test key, versioning and rate limits.

Core principles

You hold a USD balance, funded by wire to a dedicated account we issue or with USDC, and every payout is paid from it. Your users never onboard with us: we do not KYC them and they never see our brand. Your organization completes business verification (KYB) once, and your verified business is the sender of record on every transfer the recipient’s bank receives. The same three calls work for every corridor, because you read each corridor’s fields at runtime.

The end user attribution object

The endUser object on a payout request is for your own attribution. It names your customer the money is sent for, never the recipient. In payroll the employer is the end user and the worker is the recipient. The per-end-user daily cap keys on endUser.id. If you are the sender yourself, omit the object.

{
  "endUser": {
    "id": "user_9481a",
    "name": "Ana López",
    "email": "[email protected]"
  }
}

It is echoed back on the payout record, in webhook payloads and in the event feed (endUser and endUserId in each row’s data). It is never sent to the clearing house or payment rail.

Integration surfaces

Every surface creates the same payouts, with the same statuses, webhooks and event feed.

When you collect the bank details:

• The REST API, called from your backend with the avvio_* API key, or from the API reference console with a test key.
• The Node SDK (@avvio/payments): the same key, with typed methods and retry-safe defaults.
• The CLI and MCP server, run by an operator or an AI agent with credentials from the environment, for troubleshooting, automated tests and agent workflows.

When we collect the bank details:

• Hosted payout links. Your backend creates a link with a single-use signed token, and the recipient enters their details on a page we host. Their account number never touches your systems.

The payout lifecycle

Every payout takes the same three calls, then tracking:

1. Discover the corridor. GET /recipients/{orgId}/corridors returns the bank fields each currency requires, such as clabeNumber for MXN or iban for EUR.
2. Register the recipient. POST /recipients/{orgId} returns the destinationAccountId to store. Persist and send an Idempotency-Key; an optional externalId gives the recipient a stable identity in your system.
3. Send the payout. POST /payments/organizations/{orgId}/payouts, with an Idempotency-Key, prices, sends and debits your USD balance in one call. If the rate has drifted more than maxDriftBps from expectDestination (the amount you told the recipient), it is refused and nothing is sent.
4. Track and reconcile. Follow state changes through signed webhooks and the event feed (GET /payments/organizations/{orgId}/events?since=).

Trust boundaries and security

• Keep the complete API key in server-side secret storage. Use only a test key in the API reference’s Try It console, and never embed a key in a client-side bundle.
• Every path and credential is bound to an organization id (orgId) and cannot reach another organization’s routes.
• Send a new Idempotency-Key on every write that moves money or creates a recipient, payout, batch or link. Reuse a key only to retry that same request (Idempotency has the list).

Getting access

1. Create an organization at business.avvio.xyz.
2. Issue a test key on the Developer page. It works against the sandbox immediately.
3. Complete business verification (KYB) with company details and documents. Live keys are issued once your organization is verified.
4. Give your engineering team the test key, the organization id and the Quickstart.

The sandbox needs no call with us, and nothing in it touches a payment network.

Architecture and trust boundaries

The API key never enters the browser. Hosted links shift bank collection to Avvio; direct clients keep it in the partner's server boundary.

Execution, retries and recovery

Persist the idempotency key before dispatch. A timeout is an unknown outcome; replay the exact same operation with the same key.