@avvio/payments 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog and versioning
+
+## What we may change without warning
+
+These are safe for us to change, so **do not build on them**:
+
+- **Adding fields to a response.** Ignore what you do not recognise.
+- **Adding a new `failureCode`.** Treat an unrecognised one as
+  `execution_failed`.
+- **Adding a new `stage`.** Treat an unrecognised one as the status alone.
+- **Adding a new event type.** Return `2xx` for events you do not handle.
+- **Prose in `detail` and `message`.** Branch on `type`, never on the wording.
+- **Which payment network we route an organization to.** Corridor field names
+  and sets can change with it, which is why you must read
+  `GET /recipients/{orgId}/corridors` rather than hardcoding a form.
+- **Exact rates and fees**, obviously.
+
+## What we will not change without notice
+
+- Removing or renaming an endpoint.
+- Removing or renaming a field you receive today.
+- Changing the meaning of a `status` or an existing `failureCode`.
+- Making an optional request field required.
+- Narrowing a validation rule so a request that works today stops working.
+
+Anything in that second list gets a new API version and a deprecation period.
+The version is in the URL: `/api/v1`.
+
+## The two guarantees worth designing around
+
+**`completed` is not always final.** A receiving bank can return a settled
+payment days later, producing `failed` with `returned_by_bank`. This is not a
+breaking change we will version away — it is how payments work. Do not write a
+ledger that treats `completed` as immutable.
+
+**You may not see every state.** We publish a payout's state on a short cycle,
+so a fast payout can go straight to `completed` with no `pending` in between.
+Build on the state you are given, not on having observed a sequence.
+
+---
+
+## 0.1.0
+
+First release. Not yet published to npm — install from a tarball, see the
+README.
+
+- Node client, CLI, and MCP server, sharing one core. Zero dependencies.
+- Sandbox with deterministic outcomes chosen by the last four digits of the
+  beneficiary's account number, including `0003`, which completes and is then
+  returned by the bank.
+- `payout()` and `POST /payouts` price and send in one call, refusing to send
+  when the quote has drifted from what you promised the payer.
+- Idempotency on every mutation, generated for you if you do not supply one.
+- Webhook verification built in — no third-party library needed.
+
+### Known limits at 0.1.0
+
+Stated here rather than discovered by you:
+
+- **Cancellation does not exist.** `canceled` is in the status vocabulary
+  because we expect to need it; there is no endpoint today.
+- **Exact-output depends on your routing.** Check `capabilities.exactOutput` on
+  the corridors call before offering it in your UI.
+- **`GET /payouts` filters** are available; a cursor is returned but the
+  aggregate page size is capped.
+- **Sandbox rates are fixed** and settlement takes seconds, not days.

package/ERRORS.md

@@ -0,0 +1,252 @@
+# Errors
+
+Every failure has the same shape. **Branch on `type`** — it is stable across
+versions, where the HTTP status and the prose are not.
+
+```jsonc
+{
+  "type": "RATE_DRIFT_EXCEEDED",
+  "status": 400,
+  "detail": "Refusing to send: quoted 3384.65 but you expected ~9999 (6615 bps of drift, limit 200). Nothing was sent.",
+  "resolution": "Nothing was sent. Re-quote, show the payer the new amount, and send again.",
+  "requestId": "req-1c"
+}
+```
+
+`resolution` says what to do, when there is a specific answer. **It is not on
+every error** — treat it as optional and fall back to `detail`, which is always
+present. (An earlier version of this page listed exactly which types omit it;
+the list was incomplete, and an incomplete enumeration is worse than saying
+"optional".)
+
+`requestId` is in the **body of every error**, and on a SUCCESSFUL response it
+is the `x-request-id` **header** rather than a body field. Log the header and
+you have it for every request either way. (This previously claimed the body
+carried it on success; it does not.)
+
+Validation failures add `errors`, a list of the fields that failed. `detail`
+stays a string in every case, so `detail.toLowerCase()` is always safe.
+
+---
+
+## Request errors
+
+| `type` | Status | What happened | What to do |
+|---|---|---|---|
+| `VALIDATION_ERROR` | 400 | A field is missing or malformed | Fix the fields in `errors` and retry |
+| `UNAUTHORIZED` | 401 | Key missing, wrong, revoked, or used on an endpoint keys cannot reach | Check it was copied whole and is not revoked |
+| `FORBIDDEN` | 403 | Valid key, wrong organization | Check `AVVIO_ORG_ID` |
+| `NOT_FOUND` | 404 | No such payout or beneficiary | Check the id came from us |
+| `RATE_LIMITED` | 429 | Too many requests | Back off, then retry |
+| `BAD_REQUEST` | 400 | A request we understood but cannot carry out — an expired quote, an amount above the corridor maximum, a non-positive amount | Read `detail`; it names the specific condition. Never retryable unchanged |
+| `PROVIDER_REJECTED` | 400 | The payout network refused the request — most often an amount below that corridor's minimum. **Nothing was submitted** | Read `detail`; it carries the network's own wording, e.g. `the minimum amount for this payment is $10 USD`. Change the request. Retrying it unchanged fails identically |
+| `FUNDING_TRANSACTION_INVALID` | 400 | We read the chain and the transaction does not fund this payout — reverted, wrong token, wrong address, short, or from a wallet other than the registered one. **Nothing was recorded** | Read `detail`; it names which. The payout is still fundable, so send the correct transaction and confirm that |
+| `FUNDING_NOT_YET_VERIFIABLE` | 409 | We could not read the transaction yet — not mined, or we could not reach the chain. **Nothing was recorded** | Retry the same request once it is mined. If you already paid, your funds are unaffected |
+| `FUNDING_TRANSACTION_ALREADY_USED` | 409 | That transaction already funded a different payout. The deposit address is shared between payouts, so one transfer funds exactly one | Send a separate transfer for this payout. `detail` names the payout it already funded |
+| `PAYOUT_NOT_FUNDABLE` | 400 | The payout is cancelled or already finished, so it cannot be funded. **Nothing was recorded** | Do not retry. Read the payout; if you still owe the recipient, create a new one |
+| `BENEFICIARY_EXTERNAL_ID_CONFLICT` | 409 | That `externalId` already identifies a beneficiary with **different** account details. **Nothing was changed** | Use a new `externalId` for a different account. If this was a retry, read the existing beneficiary — an `externalId` identifies one account, and a second account is a second `externalId` |
+| `CONFLICT` | 409 | The payout's funding state changed under you — it is already funded with a different transaction, or a concurrent request won. **Nothing was recorded** | Re-read the payout before retrying. If it is already funded, you are done |
+| `ACCOUNT_BLOCKED` | 403 | This organization is suspended | Contact us; retrying will not help |
+| `INSUFFICIENT_BALANCE` | 400 | Your balance will not cover this payout. **Nothing was sent** | Top up, then retry. Branch on this type rather than parsing the message — it is the one condition a payroll run must handle |
+| `ORDERS_TEMPORARILY_UNAVAILABLE` | 503 | We could not read the full payout list, so we will not report a partial page as complete | Retry. If you passed a `cursor` we did not issue, that is the likeliest cause |
+| `CORRIDOR_UNAVAILABLE` | — | Raised by the **Node client**, not the API: the corridor you asked about is not offered on your routing | Read the corridors call and pick one it lists |
+| `TIMEOUT` | 504 | Raised by the **Node client**, not the API: no response within the client's timeout. **The outcome is unknown** — if this was a send, the payout may exist | Retry with the **same** `Idempotency-Key`; a replay returns the original. Never start over with a new key |
+| `NETWORK_ERROR` | 502 | Raised by the **Node client**, not the API: the request never got a response — DNS, TLS, a dropped connection. **The outcome is unknown** unless you know it never left | Retry with the **same** `Idempotency-Key`, then read the payout back |
+| `INTERNAL` | 500 | Ours | Retry with the same `Idempotency-Key`. Send us the `requestId` if it persists |
+
+`BAD_REQUEST` is the catch-all for a 400 that is not a field-validation failure.
+Because it covers several conditions, it is the one type where you should read
+`detail` — it names the specific condition. **None of them is retryable
+unchanged.**
+
+There is no `retryable` field on the wire. An earlier version of this page told
+you to branch on one; the Node client derives it for you, but over raw HTTP the
+`type` is what you branch on.
+
+## Idempotency
+
+| `type` | Status | Meaning | What to do |
+|---|---|---|---|
+| `IDEMPOTENCY_KEY_REQUIRED` | 400 | No header on a mutation | Add one, unique per operation |
+| `IDEMPOTENCY_KEY_INVALID` | 400 | Malformed | 1–255 chars of `A-Z a-z 0-9 _ . : -`. A UUID works |
+| `IDEMPOTENCY_KEY_CONFLICT` | 409 | Same key, **different body** | **Do not retry.** This is a bug on your side — a different request needs a different key |
+| `IDEMPOTENCY_KEY_REQUEST_IN_PROGRESS` | 409 | An identical request is still running | Back off, retry the **same** key |
+| `IDEMPOTENCY_UNAVAILABLE` | 503 | We could not record it. **Nothing executed** | Retry the same key |
+| `DUPLICATE_REQUEST_DETECTED` | 409 | An identical request arrived under a **different** key seconds ago. **Nothing executed** | See below |
+
+A `4xx` **releases** the key — a request that failed validation committed
+nothing, so you may correct the body and reuse it.
+
+### `DUPLICATE_REQUEST_DETECTED`
+
+The key protects you only if your retry sends the *same* key. Some HTTP clients
+generate one per attempt, which defeats it silently: every retry looks like a new
+request, and every retry pays. So we watch a second signal — same body, different
+key, within 15 minutes — and refuse.
+
+```jsonc
+{
+  "type": "DUPLICATE_REQUEST_DETECTED",
+  "originalIdempotencyKey": "zz_advance_88213",
+  "originalPayoutId": "pay_01J…",
+  "detail": "An identical request was received in the last 15 minutes under a different Idempotency-Key…"
+}
+```
+
+**This is not "already paid".** Nothing was executed. Reading it as a success and
+marking the wage settled is the one wrong move, and it leaves a worker unpaid
+with your ledger saying otherwise.
+
+Two ways forward, and you have to pick one — we will not guess:
+
+- **It was a retry.** Send it again with the **value** of
+  `originalIdempotencyKey` as your `Idempotency-Key` header. That is the key the
+  first attempt used, so this replays it: you get the original payout back and
+  nothing is sent twice.
+
+  ```bash
+  # the 409 gave you: "originalIdempotencyKey": "zz_advance_88213"
+  curl -s -X POST ".../payouts" \
+    -H "idempotency-key: zz_advance_88213" \   # <- that value, as the header
+    -H "content-type: application/json" \
+    -d '{ ...the same body... }'
+  ```
+
+  `originalIdempotencyKey` is a field we send **to** you, not one you send back.
+  Putting it in the request body is rejected — request bodies reject unknown
+  properties.
+
+- **You meant two payments.** Add `X-Allow-Duplicate: true` and send again.
+  **This sends a second real payment.** Only take this branch if you are certain
+  the first one was intended too.
+
+**The window is 15 minutes, and that is a real boundary.** It covers a crashed
+job that requeues on a backoff — the realistic incident. It is deliberately not
+the full 7-day retention: content matching cannot tell a retry from a genuine
+repeat, and two advances of the same amount to the same worker in one week are
+ordinary payroll. At 7 days every routine repeat would be refused and you would
+end up sending `X-Allow-Duplicate` unconditionally, which removes the protection
+while appearing to strengthen it.
+
+**Send a unique `reference` per logical payment and this can never false-positive
+at any window length** — a different reference is a different body. That, plus
+persisting your own idempotency key, is the durable protection. This guard is a
+net for the accidental case, not a substitute for either.
+
+We refuse rather than silently returning the first payout, because *both*
+readings are common. Two advances of the same amount to the same worker in one
+week is ordinary payroll; replaying there would mean the second one never goes
+out while your ledger records that it did. A 409 you have to answer is recoverable.
+A payment that quietly evaporates is not.
+
+### How long a key is remembered
+
+Seven days, and the window is about **storage, not correctness**. There is no
+"the key expired, so we ran it again" path: while we hold the record it is
+authoritative, and an old key retried against it replays rather than re-executes.
+A TTL that quietly re-arms a key is a double payment on a timer.
+
+Past seven days the record is deleted and the key is genuinely unknown to us — so
+treat seven days as the outer bound on retrying, not on caring. If you are
+reconciling something older, read the payout by id.
+
+## Sending
+
+| `type` | Status | Meaning |
+|---|---|---|
+| `DESTINATION_ACCOUNT_NOT_FOUND` | 404 | No payout account with that id belongs to your organization. **Nothing was sent** |
+| `RATE_DRIFT_EXCEEDED` | 400 | The quote moved further from `expectDestination` than you allowed. **Nothing was sent** |
+| `QUOTE_UNVERIFIABLE` | 400 | We could not compare the quote to your expectation. **Nothing was sent** |
+| `EXACT_OUTPUT_UNSUPPORTED` | 400 | This routing cannot lock the receiving amount. Check `capabilities.exactOutput` on the corridors call |
+| `PAYOUT_NOT_CANCELABLE` | 400 | Only a payout still awaiting your funds can be cancelled. **Do not retry** |
+| `INSUFFICIENT_SCOPE` | 403 | This key is read-only. Issue one with the `write` scope to move money |
+| `INDICATIVE_PRICING_UNAVAILABLE` | 400 | This routing publishes no price without a beneficiary. **Do not retry** — check `capabilities.indicativePricing` and price against a real beneficiary |
+
+`DESTINATION_ACCOUNT_NOT_FOUND` is the guard against paying an id you did not
+get from us. A stale, typo'd, or copied-from-elsewhere account id is refused
+before anything is priced — rather than being sent, settling, and reporting
+`completed` to a payroll run where nobody received the money.
+
+### `INDICATIVE_PRICING_UNAVAILABLE`
+
+`GET /rates` shows a price before a beneficiary exists — "you send $200, they get
+3,410 MXN" while your user is still typing. Not every routing publishes one.
+
+This is a permanent property of how your organization is routed, not an outage,
+so retrying will never succeed. Read `capabilities.indicativePricing` on the
+corridors call and, when it is `false`, skip straight to creating the beneficiary
+and pricing against it.
+
+It used to surface as a `501` typed `INTERNAL` advising "retry with the same
+Idempotency-Key" — retry advice for a `GET`, on a condition that never changes.
+
+## Payout links
+
+| `type` | Status | Meaning | What to do |
+|---|---|---|---|
+| `PAYOUT_LINK_UNUSABLE` | 400 | The link is expired, already spent, or failed at execution | Mint a new one. Links are single-use by design |
+
+A link that was already spent successfully is **not** an error: a repeat submit
+returns the original payout with `status: "already_submitted"`, so a recipient
+who double-taps gets what they already have.
+
+A `404` on a link route covers expired, spent, forged and never-existed alike —
+a stranger probing links learns nothing from the difference.
+
+---
+
+## When a payout fails
+
+A payout that was accepted and later failed is **not** an error response — it is
+a payout whose `status` is `failed`, carrying a `failureCode`.
+
+| `failureCode` | What happened | Is the money back? | What to do |
+|---|---|---|---|
+| `returned_by_bank` | It settled, then the receiving bank returned it | Yes | Tell your user. Reverse whatever you credited |
+| `account_invalid` | The account details are wrong | Yes | Ask for correct details, create a new beneficiary |
+| `account_cannot_receive` | The account cannot accept this payment | Yes | Try another account or corridor |
+| `compliance_rejected` | Refused by compliance screening | **Not automatically** | Contact us with the `payoutId`. Do not retry |
+| `limit_exceeded` | Above a corridor or account limit | Yes | Split it, or check `limits` on the corridors call |
+| `quote_expired` | Too long between quoting and sending | Yes | Re-quote and send again |
+| `authorization_not_completed` | An authorisation step was not finished | Yes | Start again |
+| `execution_failed` | It did not go through, cause not established | Check `fundsReturned` | Safe to retry with a **new** idempotency key |
+| `unknown` | We do not have a specific cause | Check `fundsReturned` | Contact us with the `payoutId` |
+
+**Read `fundsReturned`, not the code.** It is the only field that answers "is
+the money back in my balance?", and it is absent when we do not yet know — which
+is deliberately not the same as `false`. Do not re-credit a user on a code alone.
+
+**The one case where it stays absent: `compliance_rejected`.** Those funds are
+held pending a human review, so there is no automatic answer to give and we will
+not invent one. Absent here means "ask us", not "not yet" — contact us with the
+`payoutId`. Your ledger can still settle the question without waiting: the
+balance history shows the debit with **no** matching `reversal` entry, which is
+the positive statement that the money did not come back.
+
+New failure codes are added without a major version. Treat an unrecognised one
+as `execution_failed`.
+
+
+### What the sandbox can and cannot produce
+
+Only three failure codes are reachable in sandbox — `account_invalid` (`0001`),
+`compliance_rejected` (`0004`) and `returned_by_bank` (`0003`). The rest
+(`limit_exceeded`, `account_cannot_receive`, `authorization_not_completed`,
+`execution_failed`, `quote_expired`, `unknown`) come from live rails only.
+
+`stage` is likewise live-only and never appears on a sandbox payout.
+
+**So do not treat a sandbox run as proof your failure handling is complete.**
+Write the switch for every code in the table, and make the default branch behave
+like `execution_failed` — you cannot test the others before go-live.
+
+---
+
+## The one that surprises people
+
+`completed → failed` with `returned_by_bank` happens **after** you were told the
+payout succeeded, sometimes days later.
+
+Keep processing webhooks for a payout after it completes, and do not write a
+ledger that treats `completed` as immutable. Trigger it on demand in sandbox
+with an account number ending `0003`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Avvio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/QUICKSTART.md

@@ -0,0 +1,317 @@
+# Quickstart
+
+From an API key to a completed payout, in one page. Nothing here touches a real
+payment network, and no real money can move.
+
+You need a **test key** (`ak_test_…`) from Dashboard → Developers, and your
+organization id. Set both:
+
+```bash
+export AVVIO_API_KEY=ak_test_…
+export AVVIO_ORG_ID=cmsx…        # a cuid, not an org_ prefix
+export AVVIO_BASE_URL=https://api.avvio.xyz/business/api/v1
+```
+
+Every step below is shown as a CLI command, as curl, and as Node — pick a tab
+and it stays picked for the rest of the site. Nothing here depends on a
+language. If you use Node, `npx -y @avvio/payments doctor` does step 1 and tells
+you which credential is wrong.
+
+---
+
+## 1. Check the key works
+
+{{sample:listCorridors}}
+
+You get the currencies you can pay out to and the fields each one needs.
+
+**Read this rather than hardcoding a form.** Both the corridor list and the
+field *names* depend on how your organization is routed, and we may re-route
+you. Mexico is one field; India is two.
+
+---
+
+## 2. Give yourself a balance
+
+Sandbox only. Real balances are funded by wire.
+
+{{sample:fundSandbox}}
+
+It is an explicit call rather than a balance we hand you, so you can also test
+the underfunded path deliberately — `400` at quote time is a case your
+integration has to handle.
+
+---
+
+## 3. Show a price before anyone commits
+
+{{sample:getIndicativeQuote}}
+
+```jsonc
+{
+  "indicative": true,
+  "sourceAmount":      { "currency": "USD", "amount": "200.00" },
+  "destinationAmount": { "currency": "MXN", "amount": "3384.65" },
+  "fee":               { "currency": "USD", "amount": "1.02" },
+  "totalDebit":        { "currency": "USD", "amount": "200.00" },
+  "rate": "17.010001005126146",   # full precision — round it yourself for display
+  "limits": { "min": "5.00", "max": "5000.00" }
+}
+```
+
+No beneficiary needed — this is what you show while someone is still typing an
+amount. The fee comes **out of** the send, so
+`destinationAmount = (sourceAmount − fee) × rate`.
+
+On a **payout** the fee is already inside the two amounts, so the identity there
+is simply `destinationAmount = sourceAmount × rate`. `rate` on a payout always
+means destination units per one source unit, whichever network carried it — it is
+derived from the payout's own amounts rather than passed through, because the
+networks state it in different directions and on different bases.
+
+---
+
+## 4. Create the beneficiary
+
+{{sample:createBeneficiary}}
+
+Two ids, two jobs. `endUserId` is **your** id for the person *sending* — it
+scopes the beneficiary so one of your users never sees another's saved
+accounts. `externalId` is your id for the beneficiary, and makes a repeat
+create return the existing one instead of registering a second bank account.
+
+**An `externalId` identifies one account.** Re-sending it with the SAME account
+replays and returns the existing beneficiary. Re-sending it with a DIFFERENT
+account is refused with `BENEFICIARY_EXTERNAL_ID_CONFLICT` — a second account
+needs a second `externalId`. Nothing is silently substituted.
+
+`type`, `name`, `email` and `method` are always required, whatever the corridor.
+The corridors call describes the fields inside `recipientDetails`; these four sit
+outside it and apply everywhere.
+
+Keep `paymentMethods[0].destinationAccountId` from the response.
+
+---
+
+## 5. Send it
+
+{{sample:createPayout}}
+
+```jsonc
+{ "payoutId": "…", "status": "pending", "reference": "ZZ-2026-0042", … }
+```
+
+**`expectDestination` is the one field not to skip.** Between pricing and
+sending, a rate can move. Pass the number you showed your user and we refuse to
+send if it has drifted more than 2% — nothing goes, and you re-quote. Without
+it, you send at whatever the quote says.
+
+---
+
+## 6. Watch it settle
+
+{{sample:getPayout}}
+
+`pending → processing → completed`. This endpoint is always live and is
+authoritative — more so than a webhook you may have missed.
+
+---
+
+## 6b. Money in, money out, and stopping one
+
+Three endpoints you will need on day one.
+
+**Your balance, and why it is that number:**
+
+```bash
+curl -s "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/balance" \
+  -H "x-api-key: $AVVIO_API_KEY"
+
+curl -s "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/balance/history" \
+  -H "x-api-key: $AVVIO_API_KEY"
+```
+
+`balance/history` is the ledger behind the number: every funding, every payout
+debit, and every `reversal` when money comes back. Read it whenever the balance
+is not what you expect — it answers the question directly rather than making you
+infer it from payouts.
+
+**Stopping a payout that has not been funded yet:**
+
+{{sample:cancelPayout}}
+
+It reports `canceled`, the money returns to your balance with a `reversal` row,
+and the payout can no longer be funded. **Once a payout is funded it cannot be
+cancelled** — you get `PAYOUT_NOT_CANCELABLE`, and that is the honest answer
+rather than a cancellation that does not happen. So cancel is for "created by
+mistake", not for "stop one already in flight".
+
+---
+
+## A trap worth knowing now: there are two organization ids
+
+The id you authenticate with — the one in every URL — is **not** the
+`organizationId` that comes back inside response bodies. That second id is an
+internal one, and using it in a URL gives:
+
+```jsonc
+{ "type": "FORBIDDEN", "detail": "This API key cannot access that organization" }
+```
+
+which reads as a credentials problem when it is not. **Keep using the org id you
+were issued.** Ignore `organizationId` in response bodies.
+
+---
+
+## 7. The one to run before you go live
+
+Create a second beneficiary whose account number ends **`0003`**:
+
+```
+"clabeNumber": "012345678901230003"
+```
+
+Pay it, then keep polling past `completed`. It flips:
+
+```jsonc
+{ "status": "failed", "failureCode": "returned_by_bank", "fundsReturned": true }
+```
+
+**A completed payout is not always final.** A receiving bank can return one days
+later. If your ledger treats `completed` as immutable, this is the case that
+breaks it — and it is the reason this trigger exists rather than being described
+in a paragraph you would skim.
+
+Other triggers, and exactly what each does:
+
+| account ends | what happens |
+|---|---|
+| `0001` | fails at the rail with `failureCode: account_invalid`, funds returned |
+| `0002` | settles slowly — useful for testing a poll loop |
+| `0003` | completes, then flips to `failed` / `returned_by_bank` (above) |
+| `0004` | `compliance_rejected`, and the money does **not** come back |
+| `0005` | the quote expires — the payout is refused at **create** with `400 BAD_REQUEST`, so no payout exists to poll |
+| `0006` | waits for you to fund it from your own wallet |
+| anything else | completes |
+
+`0006` is worth running too. Some routings do not settle on acceptance — they
+price the payout and wait for your funds. It returns `requiresFunding: true`
+and does not move until you confirm.
+
+Read the deposit instructions from `GET /payments/organizations/{orgId}/payouts/{payoutId}/funding`
+— the address, the amount, the network and an expiry — then send the funds and
+report the transaction:
+
+```bash
+curl -s -X POST "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/payouts/$PAYOUT_ID/funding/confirm" \
+  -H "x-api-key: $AVVIO_API_KEY" \
+  -H "idempotency-key: $(uuidgen)" \
+  -H "content-type: application/json" \
+  -d '{"transactionHash":"0x…"}'
+```
+
+**We read the chain before recording it.** In production a hash matching no
+transfer, the wrong token, the wrong address, the wrong amount or a wallet other
+than the one registered is refused — nothing is recorded, and the payout stays
+fundable. One transfer funds exactly one payout.
+
+The sandbox has no chain to read, so the **last four digits of the hash** choose
+the outcome, the same way the account number does:
+
+| hash ends | you get |
+|---|---|
+| `0001` | `FUNDING_TRANSACTION_INVALID` — 400, we read the chain and it does not fund this payout |
+| `0002` | `FUNDING_NOT_YET_VERIFIABLE` — 409, not mined yet; retry the same request |
+| anything else | accepted, and the payout settles |
+| a hash already used | `FUNDING_TRANSACTION_ALREADY_USED` — 409, naming the payout it funded |
+
+Testing that branch here is the alternative to discovering it in production.
+
+---
+
+## 8. Webhooks, before you need them
+
+Poll-only integrations survive the sandbox and struggle in production. Issue a
+sandbox secret and prove your handler works now:
+
+```bash
+curl -s -X POST "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/sandbox/webhook-endpoints" \
+  -H "x-api-key: $AVVIO_API_KEY" \
+  -H "idempotency-key: $(uuidgen)" \
+  -H "content-type: application/json" \
+  -d '{"url":"http://localhost:4000/hooks"}'
+```
+
+```jsonc
+{ "id": "…", "url": "…", "secret": "whsec_…",
+  "warning": "Store this secret now — it is not retrievable." }
+```
+
+`http://localhost` works **in sandbox only**, so your first receiver can be a
+script rather than a tunnel. Live endpoints are https and are created from the
+dashboard by a human, because a credential able to repoint its own webhook URL
+could redirect every payout notification.
+
+Then check what we actually sent:
+
+```bash
+curl -s "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/sandbox/webhook-endpoints/$ID/deliveries" \
+  -H "x-api-key: $AVVIO_API_KEY"
+```
+
+---
+
+## Not on Node?
+
+Every example here is curl, and the OpenAPI spec generates a working client. This
+is tested, not asserted — a generated Python client runs the full flow above in
+our CI, which is how we found (and fixed) four places where the spec disagreed
+with the server.
+
+```bash
+npx @openapitools/openapi-generator-cli generate \
+  -i partner-payouts.openapi.yaml -g python -o ./avvio --package-name avvio_payouts
+pip install -e ./avvio
+```
+
+```python
+import avvio_payouts
+from avvio_payouts.api.payouts_api import PayoutsApi
+
+cfg = avvio_payouts.Configuration(host=BASE_URL)
+cfg.api_key["ApiKeyAuth"] = API_KEY
+
+with avvio_payouts.ApiClient(cfg) as api:
+    payout = PayoutsApi(api).create_payout(
+        ORG_ID, str(uuid.uuid4()),                 # the Idempotency-Key
+        create_payout_request={
+            "amount": "200.00",
+            "destinationAccountId": acct,
+            "expectDestination": quote.destination_amount.amount,
+        })
+```
+
+Swap `-g python` for `java`, `go`, `ruby`, `csharp`, `php` — the generator
+supports all of them off the same file.
+
+**One shape to watch:** on the REST surface `sourceAmount` is a `Money` object
+(`{currency, amount}`); inside a **webhook** it is a flat decimal string beside a
+separate `sourceCurrency`. They are two schemas in the spec — `Payout` and
+`WebhookPayout` — because they are genuinely different.
+
+---
+
+## Then
+
+- [Errors](./ERRORS.md) — every code, and what to do about each
+- [Webhooks](../PARTNER_PAYOUTS_API.md#webhooks) — verification and delivery
+- [Going live](./GOING_LIVE.md) — the checklist
+
+## Two rules worth internalising now
+
+**A timeout is an unknown outcome, not a failure.** If a send times out, the
+payout may exist. Retry with the *same* `Idempotency-Key` — a replay returns the
+original. Calling again without it is a second payment.
+
+**Webhooks are the fast path, not the guarantee.** Reconcile against the payout
+read; treat a webhook as the nudge to look.