---
updatedAt: 2026-11-20T20:15:32.764Z
---

Fetch the complete documentation index at: https://docs.avvio.xyz/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# Prepare a payment to a saved payee

`POST https://api.avvio.xyz/business/api/v1/assistant/v1/{orgId}/packages`

A payment to a payee already saved in Avvio, with no invoice. Avvio
uses the payee's saved name and account; this request carries no bank
details (an unknown field is a 400). New payees or new bank details
come on an invoice (send it to `documents`) or from a person in Avvio.

**Nothing is paid from this API.** A person approves the package in
Avvio, at `approveUrl`.

Needs a live key with the
`assistant` scope. One open payment per payee, and at most 20 open
packages per key in the last 30 days. Another payment to the payee open
or paid in the last 30 days puts a question on the package that only a
person answers. `reference` is a plain ASCII bank memo (A-Z, 0-9,
spaces and . , ' / # ( ) & : -), never a link.

## Parameters

- `orgId` (path, required) — The opaque organization id issued to you, normally CUID-shaped (for example `cmsx…`). It is not an `org_`-prefixed alias. Pass it unchanged in every organization-scoped path.
- `Idempotency-Key` (header, required) — A unique value per logical operation, 1-255 chars of `A-Z a-z 0-9 _ . : -`. Reuse it to retry. Same key with the same body replays the stored response; same key with a *different* body is a `409`, because answering with the first call's result would hand you a receipt for a payout you did not request. A `4xx` releases the key, so you can fix the body and reuse it. **Reuse it; do not generate one per attempt.** A key minted per attempt defeats replay entirely: every retry looks like a new request, so every retry pays. We also watch for an identical body arriving under a *different* key within 15 minutes and refuse it with `DUPLICATE_REQUEST_DETECTED`. Records are kept for 7 days. That is a retention window only: there is no path where an expired key is re-executed.

## Example

```bash
IDEMPOTENCY_KEY=$(uuidgen)  # new key per call; reuse it only to retry this exact request
curl -s -X POST "$AVVIO_BASE_URL/assistant/v1/$AVVIO_ORG_ID/packages" \
  -H "x-api-key: $AVVIO_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "content-type: application/json" \
  -d '{
        "payeeId": "<payeeId>",
        "amount": "<amount>"
      }'
```

## Responses

- `201` — The package, waiting for a person to approve it at `approveUrl`.
- `400` — A field that is not in the body schema (bank details included), or an amount that is not a decimal above zero.
- `401` — The key was refused. Nothing ran. - `UNAUTHORIZED`: missing, invalid or revoked, or a key on a route that does not accept one. - `KEY_EXPIRED`: the key passed the expiry it was issued with. Issue a new one; an expired key cannot be rotated. - `KEY_IP_NOT_ALLOWED`: the key is pinned to source addresses and this request came from another.
- `403` — `INSUFFICIENT_SCOPE` (the key lacks `assistant`), `LIVE_KEY_REQUIRED` (a test key), or `API_KEY_REQUIRED` (a dashboard session).
- `404` — No such saved payee in this organization, or `methodId` is not one of its accounts.
- `409` — `OPEN_PAYMENT_EXISTS`: a payment to this payee is already open; `packageId` is set only when this key prepared it. Or an `Idempotency-Key` reused with a different body.
- `422` — `NO_ACCOUNT_IN_CURRENCY`, `CURRENCY_REQUIRED`, `NO_ACCOUNT`, `AMOUNT_PRECISION` (cents on a currency without them) or `WALLET_PAYMENTS_OFF`.
- `429` — `TOO_MANY_OPEN` (20 open packages for this key in the last 30 days), or rate limited.
- `503` — `ASSISTANT_API_DISABLED`.

Machine contract: [partner-payouts.openapi.yaml](/partner-payouts.openapi.yaml), operation `createAssistantPackage`.
