CLI

Installed by npx, or as a dependency. Every command takes --json for machine-readable output, and reads AVVIO_API_KEY, AVVIO_ORG_ID and AVVIO_BASE_URL from the environment. This page is generated from the CLI's own --help, so it cannot list a command the binary does not have.

npx -y @avvio/payments doctor

Setup#

Command	What it does
`guide`	The whole flow, as commands you can paste
`doctor`	Check your credentials, connectivity and balance
`mcp`	Run as an MCP server over stdio (for agents)

Discovery#

Command	What it does
`corridors`	Currencies you can pay out to
`requirements <CCY>`	Fields a beneficiary in that currency needs

Pricing#

Command	What it does
`quote`	What the recipient gets, and the fee

Beneficiaries#

Command	What it does
`beneficiary create`	external-id makes a repeat create return the existing beneficiary instead of registering a second account
`beneficiary list`	see the help text below

Sandbox#

Command	What it does
`fund`	Credit your test balance
`balance`	What you can send; --history explains every change

Paying#

Command	What it does
`pay`	see the help text below
`cancel <payoutId>`	stop a payout that has not been funded yet
`status <payoutId>`	--watch polls until it stops moving
`payouts`	Recent payouts

Reconciliation#

Command	What it does
`events`	Every transition, in order. Carry the returned nextSince back as --since; --follow polls and prints new rows as they land (--interval SECONDS)

Funding#

Command	What it does
`funding`	Where to wire money to top up your balance
`funding <payoutId>`	Deposit instructions for a payout you fund yourself (requiresFunding: true)
`funding confirm <payoutId>`	Report the transfer you already sent

Payout links#

Command	What it does
`link create`	Mint a one-time link; the recipient enters their own bank details (--reference, --expires MINUTES)

Webhooks (sandbox)#

Command	What it does
`webhook create`	Register an endpoint, print its signing secret (--events a,b to filter; localhost ok in sandbox)
`webhook deliveries <id>`	What we sent, what came back, what we retried

Configuration (environment)#

Command	What it does
`AVVIO_API_KEY`	required Server-side only. Never ship it to a browser or a phone.
`AVVIO_ORG_ID`	required
`AVVIO_BASE_URL`	optional

A first payout, end to end#

The same three calls in whichever language you are actually in:

getIndicativeQuote

avvio-payments quote --amount 200.00 --to MXN

curl -s "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/rates?from=USD&to=MXN&amount=200.00" \
  -H "x-api-key: $AVVIO_API_KEY"

const quote = await avvio.quote({
  amount: '200.00',
  to: 'MXN',
});
// → { sourceAmount, destinationAmount, fee, rate, limits, indicative: true }

createBeneficiary

avvio-payments beneficiary create \
  --name "María González" --email maria@example.com \
  --currency MXN --country MX \
  --end-user employee_42 --external-id emp42_maria \
  --field clabeNumber=012345678901234567

curl -s -X POST "$AVVIO_BASE_URL/recipients/$AVVIO_ORG_ID" \
  -H "x-api-key: $AVVIO_API_KEY" \
  -H "idempotency-key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
        "type": "individual",
        "name": "María González",
        "email": "maria@example.com",
        "country": "MX",
        "endUserId": "employee_42",
        "method": {
          "kind": "fiat",
          "currency": "MXN",
          "recipientDetails": {
            "clabeNumber": "012345678901234567"
          }
        }
      }'

const beneficiary = await avvio.createBeneficiary({
  name: 'María González',
  email: 'maria@example.com',
  country: 'MX',
  currency: 'MXN',
  endUserId: 'employee_42',        // YOUR id for the person sending
  externalId: 'emp42_maria',       // makes a repeat create safe
  details: { clabeNumber: '012345678901234567' },
});

createPayout

avvio-payments pay --amount 200.00 \
  --to <destinationAccountId> \
  --expect 3384.65 \
  --end-user employee_42 --reference ZZ-2026-0042

curl -s -X POST "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/payouts" \
  -H "x-api-key: $AVVIO_API_KEY" \
  -H "idempotency-key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
        "amount": "200.00",
        "destinationAccountId": "<destinationAccountId>",
        "expectDestination": "3384.65",
        "maxDriftBps": 200,
        "endUser": {
          "id": "employee_42"
        }
      }'

const payout = await avvio.payout({
  amount: '200.00',
  destinationAccountId: acct,
  expectDestination: quote.destinationAmount.amount,  // 3384.65
  endUser: { id: 'employee_42' },
  reference: 'ZZ-2026-0042',
});

The full help text#

avvio-payments — pay out to your customers from your balance

  Setup
    guide                       The whole flow, as commands you can paste
    doctor                      Check your credentials, connectivity and balance
    mcp                         Run as an MCP server over stdio (for agents)

  Discovery
    corridors                   Currencies you can pay out to
    requirements <CCY>          Fields a beneficiary in that currency needs

  Pricing
    quote --amount 200 --to MXN         What the recipient gets, and the fee

  Beneficiaries
    beneficiary create --name "Maria Gonzalez" --email maria@example.com \\
      --currency MXN --end-user emp_42 \\
      --external-id emp42_maria \\
      --field clabeNumber=012345678901234567
      [--country MX] [--external-id <your id>]   external-id makes a repeat
                                                 create return the existing
                                                 beneficiary instead of
                                                 registering a second account
    beneficiary list [--end-user emp_42] [--limit 50] [--cursor <id>]

  Sandbox
    fund [--amount 5000]        Credit your test balance
    balance [--history]         What you can send; --history explains every change

  Paying
    pay --amount 200 --to <destinationAccountId> --end-user emp_42 \\
        [--expect <destinationAmount from quote>] [--end-user-name "Ana Lopez"] \\
        [--reference ZZ-1] [--idempotency-key k1] [--max-drift-bps 200]
    cancel <payoutId>      stop a payout that has not been funded yet
  status <payoutId> [--watch]   --watch polls until it stops moving
    payouts                     Recent payouts

  Reconciliation
    events [--since <sequence>] [--limit N] [--payout-id ID] [--follow]
                                Every transition, in order. Carry the returned
                                nextSince back as --since; --follow polls and
                                prints new rows as they land (--interval SECONDS)

  Funding
    funding                     Where to wire money to top up your balance
    funding <payoutId>          Deposit instructions for a payout you fund
                                yourself (requiresFunding: true)
    funding confirm <payoutId> --tx <hash>
                                Report the transfer you already sent

  Payout links
    link create --amount --to --end-user
                                Mint a one-time link; the recipient enters their
                                own bank details (--reference, --expires MINUTES)

  Webhooks (sandbox)
    webhook create --url <url>  Register an endpoint, print its signing secret
                                (--events a,b to filter; localhost ok in sandbox)
    webhook deliveries <id>     What we sent, what came back, what we retried

  Configuration (environment)
    AVVIO_API_KEY   required    Server-side only. Never ship it to a browser or a phone.
    AVVIO_ORG_ID    required
    AVVIO_BASE_URL  optional

  Every command takes --json for machine-readable output.