How It Works

Avvio enables cross-border payouts for platforms that already manage their own end users and customers.

Core Principles

Four foundational principles shape how the API operates:

You hold the balance: You wire USD to a dedicated account we issue. That capital sits as your organization's funded balance. Each payout directly debits this balance.
Your users never onboard with us: We do not KYC your end users, and they never interact with our brand. Your organization completes business verification (KYB) once.
You are the sender of record: Your KYB business entity appears on the final payment transfer sent to the beneficiary's bank account, not your end user.
One integration, every corridor: Discover corridor requirements at runtime. The same three core calls work across every supported currency and destination country.

The End User Attribution Object

The endUser object you attach to payout requests is for internal attribution:

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

This object is echoed back on the payout record and in webhook payloads. The
event log carries the payoutId; fetch that payout when reconciliation needs
the attribution fields. It is never transmitted to the clearing house or
payment rail.

Integration Surfaces

Avvio exposes one organization-scoped payout core across four integration surfaces:

Surface	Runtime	Trust Boundary	Bank Details	Best Used For
Direct REST API	Partner Backend	`akid_*` + P-256 Request Signatures	Partner collected	Direct control over corridor discovery, quotes, and payouts
Node.js SDK (`@avvio/payments`)	Partner Backend	Signs REST requests under the hood	Partner collected	Typed methods, automated request signing, retry-safe clients
CLI / MCP Server	Operator or Agent	Environment-provided credentials	Partner input	Operational troubleshooting, automated testing, agent workflows
Hosted Payout Links	Partner Backend + User Browser	Single-use signed token URL	Avvio collected	Zero bank data touch; recipient enters details on a secure page

All surfaces interact with the exact same payout state machine, generate the same webhook events, and reconcile through the same event feed.

The Payout Lifecycle

Moving money follows a consistent four-step workflow:

Corridor Discovery: Query GET /recipients/{orgId}/corridors to dynamically retrieve the required bank fields for the target currency (e.g. clabeNumber for MXN, iban for EUR).
Beneficiary Registration: Create a recipient with POST /recipients/{orgId}. Store the resulting destinationAccountId. Pass externalId for safe retries.
Payout Execution: Call POST /payments/organizations/{orgId}/payouts with an Idempotency-Key and expectDestination to lock the rate and debit your USD balance.
Tracking & Reconciliation: Monitor state updates via signed webhooks or sequence-based event logs (GET /payments/organizations/{orgId}/events?since=).

Trust Boundaries & Security

Private Keys Never Leave Your Server: The private P-256 ECDSA key resides strictly on your server. It is never exposed in client-side bundles or web pages.
Organization Scoping: All API paths and credentials are bound to an organization ID (orgId). Credentials cannot access routes belonging to any other organization.
Idempotency on Partner Mutations: Every money-moving partner operation,
plus recipient, payout-link, and sandbox mutations, declares an
Idempotency-Key in the API reference. Persist it before sending and reuse it
for the same logical operation so network timeouts cannot double-charge.