Add another way to pay an existing beneficiary

post

https://api.avvio.xyz/business/api/v1/recipients/{orgId}/{recipientId}/methods

Use this when the same person can be paid in more than one currency or
over more than one rail. Creating a second beneficiary instead
duplicates them in your book and in ours.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

orgId

string

required

length ≥ 1

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.

recipientId

string

required

length ≥ 1

Opaque beneficiary id returned by this API. Pass it unchanged.

Body Params

kind

const

enum

required

Allowed:

currency

string

required

^[A-Za-z]{3}$

ISO 4217 payout currency. Matching is case-insensitive.

recipientDetails

object

required

The selected corridor's fields, keyed exactly by field id.
Values are normally strings; nested objects are accepted where
the field definition represents a structured address.

Headers

Idempotency-Key

string

required

length between 1 and 255

^[A-Za-z0-9_.:-]+$

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, not a
correctness one — there is no path where an expired key is re-executed.

Responses

201The added payment method

400Validation failed, or a corridor field is missing

401Missing, invalid, or revoked key — or a key on a route that does not accept one.

403Valid key, wrong organization.

409Either the key was reused with a different body, or an identical request is still in flight. The second is safe to retry after a backoff; the first means you should use a new key.