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:

1. 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.
2. 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.
3. 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.
4. 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": "ana.lopez@example.com"
  }
}

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:

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:

1. 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).
2. Beneficiary Registration: Create a recipient with POST /recipients/{orgId}. Store the resulting destinationAccountId. Pass externalId for safe retries.
3. Payout Execution: Call POST /payments/organizations/{orgId}/payouts with an Idempotency-Key and expectDestination to lock the rate and debit your USD balance.
4. 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.

Architecture & Trust Boundaries

Execution, Retries & Recovery