---
updatedAt: 2026-09-30T15:54:20.000Z
---

Fetch the complete documentation index at: https://docs.avvio.xyz/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# 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:

```text
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](/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](/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](/webhooks/) covers signing and delivery, and
[Reconcile your ledger](/reconciliation/) the feed.

Every error carries a `type` to branch on, and [Errors](/errors/) says for
each one whether money moved and whether a retry is safe.
[Environments & sandbox](/environments/) 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.

```json
{
  "endUser": {
    "id": "user_9481a",
    "name": "Ana López",
    "email": "ana.lopez@example.com"
  }
}
```

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

![The payout lifecycle: authenticate, discover the corridor, register the recipient, execute the payout, reconcile](/partner-assets/diagrams/payout-lifecycle.svg)

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](/idempotency) has the list).

## Getting access

1. Create an organization at [business.avvio.xyz](https://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](/quickstart/).

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