Invoice to pay

Pay a supplier from a funded customer account using the same objects as any other payout — customers, counterparties, transfers, and webhooks — with an agent (agt_) bound to that customer, source account, spend limits, and a hard destination allowlist enforced on the agent key. This is the accounts payable path for an agent key. There is no separate “pay invoice” API. Compose the steps below.

Agents (customer pin, source-account pin, destination allowlist, spend limits) are early access — ask your account team to enable them (403 agents_not_enabled until then). Instruction-audit export is beta.

Flow

Step	What you do	Why
1. Intake	Capture vendor + bank details (and optional invoice document)	Evidence for screening and audit
2. Register payee	Create counterparty + external account	Destinations start `IN_REVIEW`
3. Wait for approval	Subscribe to `external_account.approved`	Unknown / rejected payees must not be paid
4. Open perimeter	Add the approved account id to the agent allowlist	Hard allowlist denies anything else
5. Pay	`POST /v1/transfers` with the agent key	Network enforces pins + allowlist
6. Reconcile	Webhooks, `GET /v1/transfers/{id}`, instruction-audit	Case file for every accepted payout

Prerequisites

Verified business customer in ACTIVE
Dedicated funded account for the agent (balance account, treasury wallet, or other payable source your corridor supports) — see Balance accounts
An agent in the default PAYMENT role (not PAYMENT_OPERATIONS, which is read-only and cannot create or submit transfers) created for that customer + source account with a non-null destination allowlist ([] until suppliers are approved), and an agent API key (sk_*_agent_*) issued from the console Agents page or POST /v1/agents/{id}/keys (see Credentials and scopes) — do not reuse broad org keys for payouts
Webhook endpoint subscribed to payee, agent, and transfer events (Webhooks)

Until agents are enabled for your org, you cannot use this playbook’s network perimeter — keep automation behind your own controls.

allowedDestinationAccountIds: null on the agent (the default when unset) still allows every valid destination owned by the pinned customer. Before issuing the agent key, set a non-null allowlist on the agent — start with [] (deny all) and add approved eba_… / ewa_… ids, or withhold the key secret until the allowlist is saved. Empty [] denies all destinations; only listed ids are payable.

Credentials and scopes

transfers:write alone is not enough for this playbook. Split operator / JWT work (open the perimeter, register payees, attach documents) from the restricted agent key (submit allowlisted payouts).

Phase	Credential	Permissions (minimum)
1. Document upload / confirm	Operator API key or JWT	`customers:write` (`transfers:write` only if you pass `transferId` on create)
2. Find / reuse payee (list counterparties + accounts)	Operator API key or JWT	`accounts:read` — write does not imply read
2. Create counterparty + external account	Operator API key or JWT	`accounts:write`
3. Poll payee / account status	Operator API key or JWT (preferred over agent key)	`accounts:read`
4. Read current allowlist	Agent key (own `agt_` only) or unconstrained org key / JWT	`apiKeys:read` (`GET /v1/agents/{id}`)
4. Update allowlist	Unconstrained organization API key or JWT — not the agent key	`apiKeys:write` (`PATCH /v1/agents/{id}` with `allowedDestinationAccountIds`; API-only today — see step 4)
5. Create / submit transfer	Agent API key on a `PAYMENT`-role agent	Fixed scopes include `transfers:write` on payment agents (`PAYMENT_OPERATIONS` agents are read-only)
6. Poll transfer / recovery list	Operator API key or JWT (preferred)	`transfers:read` — org-wide list on organization keys (see below)
6. Instruction-audit export	Operator API key or JWT	`transfers:read` (base). Full package sections may need `apiKeys:read` (legacy key-policy dump) and optionally `accounts:read` / `cases:read` / `members:read`

Agent pins and allowlists only gate transfer operations (create / confirm / submit / related money-movement). They do not filter reads on organization API keys.Agent keys use fixed scopes by MCP role on the agent:

Role	Scopes	Payout writes
`PAYMENT` (default)	`transfers:read`, `transfers:write`, `accounts:read`, `customers:read`, `apiKeys:read`	Allowed (subject to pins, allowlist, limits)
`PAYMENT_OPERATIONS`	`transfers:read`, `accounts:read`, `customers:read`, `apiKeys:read` — no `transfers:write`	Denied (`agent_read_only`)

Read scoping on agent keys: account list/get and customer get are limited to the agent’s principal customer. Transfer list/get is limited to that agent’s transfers (PAYMENT) or the pinned customer’s transfers (PAYMENT_OPERATIONS). GET /v1/counterparties without customerId is organization-wide even on agent keys — for payee reuse in this playbook, always list with customerId= (operator or agent). Agent keys cannot call PATCH /v1/agents/{id} or /v1/internal/api-keys/.../policy.Organization API keys and JWT sessions use normal scope grants. accounts:read and transfers:read on those credentials list organization-wide data — every customer in the org, not only the pinned customer. In multi-customer orgs, keep clientReferenceId recovery and cross-customer reconciliation on an operator credential with intentional scope, not on assumptions that agent pins hide other customers’ rows.

Least privilege

Agent key (PAYMENT role): inherits customer + source pins and allowlist from the agent; scopes are fixed (above). Do not hand out the key secret while the agent’s allowedDestinationAccountIds is still null.
Operator / organization key or JWT: human or trusted automation that registers suppliers, uploads invoice documents, updates the agent allowlist via GET / PATCH /v1/agents/{id} (apiKeys:read / apiKeys:write), and polls / recovers transfers with org-wide reads when needed. Payee reuse needs accounts:read and accounts:write.
Webhooks do not consume API scopes; they require a verified endpoint secret.

1. Invoice / vendor intake

Two valid starts: Known vendor — you already have legal name, bank (or wallet) details, and amount. You may skip document upload and go to Register the payee only when your payout corridor does not require supporting documents. Third-party SWIFT still needs at least one documentIds entry on transfer create (see step 5) — upload/confirm the invoice first even for a known vendor. Invoice evidence — upload supporting documents via the public Documents API, then attach them on the transfer with documentIds. Create the upload request with all of these fields (there is no category field):

Field	Example
`documentType`	`INVOICE`
`customerId`	`cus_abc123`
`fileName`	`invoice-2026-001.pdf`
`contentType`	`application/pdf`

POST /v1/documents — body as above; see Create document upload request
Upload bytes to the returned URL
POST /v1/documents/{id}/confirm — Confirm document upload
Keep the doc_ id for the transfer

Structured invoice parse (vendor / amount / bank prefill) is available in the console transfer-create flow and as an internal assist API. It does not create counterparties or move money. Agents and integrators should treat parse output as suggestions and still register payees through the counterparty + external-account path below.

Console invoice.* webhooks are accounts-receivable (you are collecting). They are not this supplier-payout playbook. Use transfer.* and external_account.* for accounts payable.

2. Register the payee

Do not always create a new counterparty. For repeat invoices to the same supplier, find and reuse the existing counterparty and external bank account or wallet first — list counterparties with customerId= (paying customer) and list accounts for that customer; match on bank or wallet identity. Do not rely on an unfiltered counterparty list on an agent key — it is organization-wide. This playbook covers bank accounts (eba_…) and external wallets (ewa_…) only. Do not use proxy destinations (epa_… / alias rails such as PIX, UPI, PromptPay) here — proxy create does not preserve the supplier counterpartyId binding this flow requires, and proxy rail reuse rules differ. Prefer a bank or wallet payee for AP payouts. External-bank / external-wallet create deduplicates by bank or wallet identity for that customer — not by requested rail, chain, or currency. If the same identifiers already exist:

The API returns the existing account with created: false (no new screening cycle)
Create does not merge capability fields from your request onto the reused row
For bank accounts and wallets, passing a different counterpartyId than the one already linked is rejected
Already-ACTIVE / approved reused accounts emit no new external_account.approved — do not wait forever for a webhook that will not fire; branch on the create response

On every create/reuse response, check created and status, then the fields that matter for this payout:

Destination	Check on reuse	If the payout capability is missing
Bank account (`eba_…`)	`paymentRails`	`PATCH /v1/external-bank-accounts/{id}` with the full compatible `paymentRails` list (existing plus any to add). A WIRE-only reused account fails ACH until ACH is added
External wallet (`ewa_…`)	`chains` and `currencies`	`PATCH /v1/external-wallets/{id}` with the full desired `chains` / `currencies` lists. Create reuse does not merge them — a BASE-only reused wallet fails an Ethereum payout until Ethereum is added

Do not rely on a second create to widen rails, chains, or currencies. When you do create, supplier destinations are third-party bank accounts or wallets. Create defaults isThirdParty to false and rejects counterpartyId unless isThirdParty is true — omitting these fields misclassifies the supplier destination as the customer’s own account. Set all of:

Field	Value
`customerId`	The paying customer (`cus_…`) — the principal whose funds move
`isThirdParty`	`true`
`counterpartyId`	The existing or newly created `cp_…` for that supplier

New rows (created: true) start IN_REVIEW and are not payable until screening finishes. On reuse (created: false), inspect status and the capability fields above (paymentRails, or chains / currencies) before waiting on webhooks or submitting a transfer. For crypto → fiat SWIFT supplier payouts, see SWIFT payouts for bank-account field shape.

3. Wait for destination approval

Subscribe to:

Event	Meaning
`external_account.in_review`	Destination entered screening
`external_account.approved`	Safe to allowlist and pay
`external_account.rejected`	Do not add to allowlist; do not pay
`counterparty.created` / `counterparty.updated`	Counterparty metadata only — not payability

Poll GET /v1/accounts/{id} (or list accounts for the customer) if you need authoritative status. On account-create reuse (created: false), use the returned status — do not block on a new approval webhook for an already-approved destination. Do not race the agent key against an unapproved destination: even if you omit allowlist updates, other validation may still reject the transfer.

4. Add the destination to the allowlist

Only after external_account.approved, add that account id (eba_… / ewa_…) to the agent (agt_…). Use an organization API key or JWT org session — not the agent key (sk_*_agent_* cannot update agents or legacy key policy). Do not allowlist proxy (epa_…) destinations for this playbook.

Console (read-only today): Agents → select the agent → Payees shows the current allowlist but has no editor — use the API below until console editing ships.
API: GET /v1/agents/{id} with the agent key (read own allowlist) or operator credential (apiKeys:read), then PATCH /v1/agents/{id} with an unconstrained org key or JWT (apiKeys:write) and the full allowedDestinationAccountIds array

allowedDestinationAccountIds on PATCH /v1/agents/{id} replaces the entire allowlist — it does not append. Read the agent first, then send the complete desired array including the new id. Sending only the new id drops every previously allowlisted destination.

Allowlist read-modify-PATCH has no version / CAS. Concurrent updates can stale-write and resurrect a supplier another operator just removed. Treat allowlist edits as a security perimeter: use a single serialized writer (one ops queue, lock, or equivalent concurrency control) per agent. Do not fan out parallel GET→PATCH jobs against the same agent.

Keep the allowlist small. Agents accept at most 50 destination IDs — larger supplier sets need pruning, multiple segmented agents/keys, or another perimeter design. An empty allowlist denies all destinations. PAUSED blocks new agent submit paths — POST /v1/transfers with confirm: true and POST /v1/transfers/{id}/submit (including submitting an existing DRAFT) — but does not stop in-flight processing of transfers already submitted, and does not block other transfer writes such as PATCH /v1/transfers/{id}/fund-from-balance on an existing pending crypto transfer (agent policy pins still apply). After credential compromise, revoke the agent key or agent — pausing alone leaves the key authenticated with scoped reads.

Changing a supplier’s bank details means a new external account (new id), a new approval, and an allowlist update. Treat bank swaps as a controlled perimeter change, not an in-place edit the agent can invent.

5. Create the transfer under the pinned key

Call POST /v1/transfers with the agent API key (not an organization key). Required discipline:

Field / header	Rule
`Authorization`	Agent key (`sk__agent_`) for the `agt_` with allowlist set
`Idempotency-Key`	Unique high-entropy value per logical payout — Idempotency
`clientReferenceId`	Organization-wide unique id for this logical payout (namespace by agent + customer + invoice/voucher, e.g. `ap:{agent}:{cus_…}:{voucher}`). Required for safe recovery after timeouts or cached 5xx — list filters the whole org by exact match and the API does not enforce uniqueness. Caller-local uniqueness is insufficient when two agents can collide
`onBehalfOf`	Pinned customer id
`source.accountId`	Pinned source account
`destination.accountId`	Allowlisted, approved external account
`counterpartyId`	Matching counterparty
`documentIds`	Required when `destination.paymentRail` is `SWIFT` for third-party / supplier payouts (API rejects without at least one supporting document). Optional but recommended for other rails when paying from invoice evidence
`confirm`	`true` to submit immediately, or omit / set false to leave a `DRAFT` you (or the same key) can later `POST /v1/transfers/{id}/submit`

For this playbook’s supplier SWIFT path, upload and confirm the invoice document first, then pass its doc_… in documentIds. See SWIFT payouts for rail-specific destination fields.

Example (USD balance → ACH supplier):

import requests

response = requests.post(
    'https://api.infinite.dev/v1/transfers',
    headers={
        'Authorization': 'Bearer sk_live_agent_...',
        'Content-Type': 'application/json',
        'Idempotency-Key': '9f3c2a1b-4d5e-6f70-8192-a3b4c5d6e7f8',
    },
    json={
        'onBehalfOf': 'cus_abc123',
        'clientReferenceId': 'ap:ops:cus_abc123:inv-2026-001',
        'amount': {
            'currency': 'USD',
            'rawValue': '12500',
        },
        'source': {
            'currency': 'USD',
            'paymentRail': 'BALANCE',
            'accountId': 'vba_agent_balance',
        },
        'destination': {
            'currency': 'USD',
            'paymentRail': 'ACH',
            'accountId': 'eba_vendor456',
        },
        'counterpartyId': 'cp_vendor456',
        'documentIds': ['doc_invoice789'],
        'paymentReason': 'PAYMENT_FOR_GOODS_AND_SERVICES',
        'confirm': True,
    },
)

const response = await fetch('https://api.infinite.dev/v1/transfers', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_live_agent_...',
    'Content-Type': 'application/json',
    'Idempotency-Key': '9f3c2a1b-4d5e-6f70-8192-a3b4c5d6e7f8',
  },
  body: JSON.stringify({
    onBehalfOf: 'cus_abc123',
    clientReferenceId: 'ap:ops:cus_abc123:inv-2026-001',
    amount: {
      currency: 'USD',
      rawValue: '12500',
    },
    source: {
      currency: 'USD',
      paymentRail: 'BALANCE',
      accountId: 'vba_agent_balance',
    },
    destination: {
      currency: 'USD',
      paymentRail: 'ACH',
      accountId: 'eba_vendor456',
    },
    counterpartyId: 'cp_vendor456',
    documentIds: ['doc_invoice789'],
    paymentReason: 'PAYMENT_FOR_GOODS_AND_SERVICES',
    confirm: true,
  }),
});

export INFINITE_API_KEY=sk_live_agent_...
infinite api POST /v1/transfers \
  --header 'Idempotency-Key: 9f3c2a1b-4d5e-6f70-8192-a3b4c5d6e7f8' \
  --body '{
  "onBehalfOf": "cus_abc123",
  "clientReferenceId": "ap:ops:cus_abc123:inv-2026-001",
  "amount": {
    "currency": "USD",
    "rawValue": "12500"
  },
  "source": {
    "currency": "USD",
    "paymentRail": "BALANCE",
    "accountId": "vba_agent_balance"
  },
  "destination": {
    "currency": "USD",
    "paymentRail": "ACH",
    "accountId": "eba_vendor456"
  },
  "counterpartyId": "cp_vendor456",
  "documentIds": ["doc_invoice789"],
  "paymentReason": "PAYMENT_FOR_GOODS_AND_SERVICES",
  "confirm": true
}'

# Agent MCP create_transfer does not send clientReferenceId or documentIds — use Python, TypeScript, CLI, or cURL for this playbook (SWIFT invoice evidence + org-unique clientReferenceId recovery). See /guides/mcp for simpler agent-key payouts.

curl -X POST "https://api.infinite.dev/v1/transfers" \
  -H "Authorization: Bearer sk_live_agent_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f3c2a1b-4d5e-6f70-8192-a3b4c5d6e7f8" \
  -d '{
    "onBehalfOf": "cus_abc123",
    "clientReferenceId": "ap:ops:cus_abc123:inv-2026-001",
    "amount": {
      "currency": "USD",
      "rawValue": "12500"
    },
    "source": {
      "currency": "USD",
      "paymentRail": "BALANCE",
      "accountId": "vba_agent_balance"
    },
    "destination": {
      "currency": "USD",
      "paymentRail": "ACH",
      "accountId": "eba_vendor456"
    },
    "counterpartyId": "cp_vendor456",
    "documentIds": ["doc_invoice789"],
    "paymentReason": "PAYMENT_FOR_GOODS_AND_SERVICES",
    "confirm": true
  }'

rawValue is minor units (cents for USD). For quotes, FX, and multi-rail patterns see Quotes and transfers. For crypto deposit → SWIFT fiat, see SWIFT payouts.

Policy deny paths (expected)

When the agent has pins and allowlist set, the network fail-closes:

Attempt	Typical result
Destination not on allowlist	Denied — destination not authorized
Wrong `source.accountId`	Denied — source pin
Wrong `onBehalfOf` / customer	Denied — customer pin
Empty allowlist	Denied — all destinations
Revoked agent / key	Auth failure

Denied creates do not produce a transfer id and are not in instruction-audit export. Capture your request id and error body for ops review.

POST /v1/transfers idempotency caches failed responses for about 24 hours — not only 4xx. Client errors (allowlist/pin denials), 5xx, and other recorded failures are returned again on the same Idempotency-Key. Reusing the key after a definitive cached failure only returns that cached error; it does not re-run create. After that window, the same key no longer short-circuits create.Always send an organization-wide unique clientReferenceId on the original create — namespace so two agents (or two customers) cannot collide (e.g. ap:{agentId}:{customerId}:{voucher}). Public transfer list supports exact clientReferenceId filter across the whole organization; optional customerId narrows the list, but you must still verify the returned transfer’s amount / destination / sourceCustomerId match the payout you intended (sourceCustomerId is the paying customer on list/get responses — the create body field is onBehalfOf). The API does not filter by amount and does not enforce uniqueness. Do not decide “no transfer exists” from customer/amount/time heuristics; that can miss a committed payout and a new idempotency key will duplicate the supplier payment.Serialize recovery per logical payout. An empty clientReferenceId list is not a distributed lock. Two operators recovering the same voucher concurrently can both see empty results and POST with different Idempotency-Key values — idempotency only dedupes identical keys, and clientReferenceId is not unique — so you get a double pay. Coordinate recovery (single writer, lease/lock, or queue) so only one writer runs list → decide → create for that payout at a time.On any ambiguous or delayed outcome (timeout, unknown whether create finished, or any non-immediate retry): list by exact clientReferenceId first before reusing or replacing the Idempotency-Key. A transfer can already exist even when replaying the key does not return a cached success. Prefer reusing the original key after an empty list while still within the ~24h failure-cache window; mint a new key only after another empty list when you must. Past that window, POST only after an empty list.

Outcome	What to do
Confirmed 4xx denial	Remediate policy (or request). `GET /v1/transfers?clientReferenceId=…` (operator credential; optionally `&customerId=…`) should be empty; then retry with a new `Idempotency-Key` (same org-unique `clientReferenceId` is fine)
Confirmed cached 5xx / recorded server failure	Do not keep replaying the same key. Under a single serialized recovery writer for this payout: exact-list `GET /v1/transfers?clientReferenceId=<id from original request>` (prefer also `customerId=`). If any transfer is returned, verify amount / destination / `sourceCustomerId`, then stop — reconcile that payout; do not create again. Only if the list is empty may you retry with a new `Idempotency-Key`
Ambiguous timeout / unknown whether create finished	Do not reuse the `Idempotency-Key` first. Under a single serialized recovery writer: exact-list `GET /v1/transfers?clientReferenceId=…` (operator; optionally `customerId`). If a transfer exists, verify amount / destination / `sourceCustomerId`, then stop and reconcile. Only if empty: within the ~24h failure-cache window prefer reusing the original key once; if that returns a definitive cached failure, mint a new key only after another empty list. Past ~24h, POST only after an empty list. Never run this path concurrently with another recoverer for the same voucher

Agent keys also cannot open other blast-radius surfaces (for example global payout batches, agent management, or fixed-route create). Use direct POST /v1/transfers for this playbook.

6. Reconcile and audit

Signal	Use
`transfer.created` / `transfer.processing` / `transfer.updated` / `transfer.completed` / `transfer.failed` / `transfer.cancelled` / `transfer.refund_initiated` / `transfer.refund_completed` / `transfer.reversed`	Push lifecycle — Webhooks. Settled bank returns that reverse a payout typically emit `transfer.reversed`. Some other refund flows emit cancelled and/or refund_* while status becomes `REVERSED`. Not every path to `REVERSED` emits a customer webhook (some operational status corrections are silent) — subscribe to `transfer.reversed` where applicable and keep periodic `GET` reconciliation.
`GET /v1/transfers/{id}`	Authoritative status (webhooks can lag or omit transitions, including silent operational corrections). Required after completion — do not infer terminal state from webhooks alone. A single post-completion GET (or polling only until the first terminal status) is not enough: status can later become `REVERSED` with no event. Schedule periodic re-fetches through your accounting reconciliation window (for example daily or at period close) for recently completed payouts until books are closed.
`GET /v1/internal/transfers/{id}/instruction-audit`	One beta case file: request context, policy checks (when attributable), screening/holds, route, settlement, events. Requires `transfers:read`; include `apiKeys:read` to see `apiKeyPolicy` (see Credentials and scopes).

When a transfer is in IN_REVIEW, poll until a terminal status on GET /v1/transfers/{id}: COMPLETED, REVERSED, FAILED, or CANCELLED. Some monitoring alerts do not hold funds — do not treat every compliance signal as a hard stop without checking transfer status. After first completion, keep re-checking status on your reconciliation schedule so a later silent REVERSED is not missed.

Operator checklist

Fund only the pinned source account
Human-vet suppliers; keep allowlist ≤ the set finance approved (max 50 destination IDs per key)
Agent: customer pin + source pin + non-null destination allowlist ([] until approved) — never allowlist-null on a multi-customer org
Prove deny paths before production volume (unknown dest, empty allowlist, wrong source, wrong customer, revoked key)
Export instruction-audit for sample completed payouts; schedule periodic GET /v1/transfers/{id} through the accounting reconciliation window (silent REVERSED has no webhook)
Revoke compromised agent keys (DELETE /v1/agents/{id}/keys/{keyId}) or the agent — do not rely on PAUSED alone after compromise (paused keys remain authenticated). Use PAUSED when you need to block new confirm: true creates and submit on drafts while existing submitted transfers keep processing; it is not a substitute for revocation after compromise

Out of scope for this playbook

Topic	Status
Proxy payees (`epa_…` / alias rails)	Out of scope — proxy create does not preserve supplier `counterpartyId` for this flow; use bank (`eba_…`) or wallet (`ewa_…`) payees
Self-serve supplier-change productization	Later Phase 1 suite work — today: new external account → approve → allowlist
Dual-control / amount thresholds	Optional later. A `DRAFT` transfer is only a procedural pause — a `PAYMENT`-role agent key with `transfers:write` can still `confirm: true` or submit its own draft; that is not a human-only auth boundary
Cards / scoped card credentials	Deferred
Marketplace seller settlement / dispute engine	Separate SKU
Public “pay this invoice” resource	Not offered — compose Documents + transfers

Next steps

Agents

Map wallet, pay, identity, and observability to live APIs

Webhooks

Signed events for payees and transfers

Quotes and transfers

Amounts, quotes, and execution patterns

SWIFT payouts

Crypto to fiat supplier wires

Idempotency

Safe retries for agent writers

Error handling

Read API errors without guessing

Get started

Core Concepts

Guides

Flow

Prerequisites

Credentials and scopes

1. Invoice / vendor intake

2. Register the payee

3. Wait for destination approval

4. Add the destination to the allowlist

5. Create the transfer under the pinned key

Policy deny paths (expected)

6. Reconcile and audit

Operator checklist

Out of scope for this playbook

Next steps

Agents

Webhooks

Quotes and transfers

SWIFT payouts

Idempotency

Error handling