Add a payment method

Add another way to pay an existing recipient.

POST

POST/recipients/{orgId}/{recipientId}/methods

IDEMPOTENCY_KEY=$(uuidgen)  # new key per call; reuse it only to retry this exact request
curl -s -X POST "$AVVIO_BASE_URL/recipients/$AVVIO_ORG_ID/$recipientId/methods" \
  -H "x-api-key: $AVVIO_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "content-type: application/json" \
  -d '{
        "kind": "fiat",
        "currency": "MXN",
        "recipientDetails": {
          "clabeNumber": "012180000080004471"
        }
      }'

const recipientId = '<recipientId>';
const idempotencyKey = crypto.randomUUID(); // new key per call; reuse it only to retry this exact request

const res = await fetch(`${process.env.AVVIO_BASE_URL}/recipients/${process.env.AVVIO_ORG_ID}/${recipientId}/methods`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.AVVIO_API_KEY,
    'Idempotency-Key': idempotencyKey,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    "kind": "fiat",
    "currency": "MXN",
    "recipientDetails": {
      "clabeNumber": "012180000080004471"
    }
  }),
});
console.log(res.status, await res.json());

import os
import uuid
import requests

recipientId = "<recipientId>"
idempotency_key = str(uuid.uuid4())  # new key per call; reuse it only to retry this exact request

res = requests.post(
    f"{os.environ['AVVIO_BASE_URL']}/recipients/{os.environ['AVVIO_ORG_ID']}/{recipientId}/methods",
    headers={
        "x-api-key": os.environ["AVVIO_API_KEY"],
        "Idempotency-Key": idempotency_key,
    },
    json={
        "kind": "fiat",
        "currency": "MXN",
        "recipientDetails": {
            "clabeNumber": "012180000080004471"
        }
    },
)
print(res.status_code, res.json())

201Created

{
  "id": "cmf3k2xa10004q8b7r5t8u1vw",
  "name": "Ana Ruiz",
  "email": "[email protected]",
  "country": "MX",
  "externalId": "payroll-4471",
  "endUserId": "customer_42",
  "type": "individual",
  "phone": "+525512345678",
  "createdAt": "2026-08-20T13:58:02.000Z",
  "updatedAt": "2026-08-20T13:58:02.000Z",
  "organizationId": "cmsx0h2k900a1n11ib3qz9v42",
  "paymentMethods": [
    {
      "id": "cmf3k2xa10005q8b7w9x2y3za",
      "kind": "fiat",
      "currency": "MXN",
      "last4": "4471",
      "status": "active",
      "destinationAccountId": "sbx_acct_MXN_4471_ae66cbc5"
    }
  ]
}

{
  "type": "VALIDATION_ERROR",
  "status": 400,
  "detail": "1 field(s) failed validation for MXN.",
  "resolution": "Correct the fields listed in `errors` and retry.",
  "errors": [
    "clabeNumber: CLABE does not match the required format (^[0-9]{18}$)"
  ],
  "requestId": "req-9pc",
  "message": "1 field(s) failed validation for MXN.",
  "statusCode": 400
}

{
  "type": "UNAUTHORIZED",
  "status": 401,
  "detail": "Invalid API key",
  "resolution": "Check the API key was copied whole and has not been revoked.",
  "requestId": "req-9bz",
  "message": "Invalid API key",
  "statusCode": 401
}

{
  "type": "FORBIDDEN",
  "status": 403,
  "detail": "This API key cannot access that organization",
  "resolution": "This key is scoped to a different organization.",
  "requestId": "req-9d0",
  "message": "This API key cannot access that organization",
  "statusCode": 403
}

{
  "type": "BANK_ACCOUNT_ALREADY_LINKED",
  "status": 409,
  "detail": "This bank account is already saved on María González.",
  "existingRecipientId": "cmf3k2xe80004q8b7a1c2d3e4",
  "existingMethodId": "cmf3k2xe80005q8b7f5g6h7i8",
  "requestId": "req-9vi",
  "message": "This bank account is already saved on María González.",
  "statusCode": 409
}

{
  "type": "RATE_LIMITED",
  "status": 429,
  "detail": "ThrottlerException: Too Many Requests",
  "resolution": "Back off and retry after the Retry-After interval.",
  "requestId": "req-9e1",
  "message": "ThrottlerException: Too Many Requests",
  "statusCode": 429
}

{
  "type": "PAYOUT_ACCOUNT_PROVIDER_UNAVAILABLE",
  "status": 503,
  "detail": "Payout account registration is temporarily unavailable. Please retry.",
  "resolution": "No beneficiary account was saved locally. Retry the same request and Idempotency-Key.",
  "requestId": "req-9ob",
  "message": "Payout account registration is temporarily unavailable. Please retry.",
  "statusCode": 503
}

Path parameters

orgIdstringRequired
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.
recipientIdstringRequired
Opaque recipient id returned by this API. Pass it unchanged.

Headers

Idempotency-KeystringRequired
A unique value per logical operation, 1-255 chars of A-Z a-z 0-9 _ . : -.
More
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.

Body

This endpoint expects a JSON object.

Fiat bank destination

kindstringRequired
Send the literal string fiat for a bank destination.
currencystringRequired
ISO 4217 payout currency. Matching is case-insensitive.
railstringOptional
Optional. The corridor's payout rail. Omit it and the corridor's default rail is used, which is what almost every integration wants. It has no example, so a generated request does not carry one.
recipientDetailsobjectRequired
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. Fields in the bank_address group (the recipient's own postal address, on corridors that require one) may be sent flat or nested under bank_address.

Cryptocurrency destination

kindstringRequired
Send the literal string crypto for a wallet destination.
addressstringRequired
Valid EVM, Solana, or Bitcoin address. Leading and trailing whitespace is ignored.

Behavior

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

The response is the whole recipient, with method naming the one this call added.

Responses

201The recipient, with method set to the payment method just added

Body · BeneficiaryRegistration

idstringOptional
namestringOptional
emailstring | nullOptional
The contact address you supplied, or null when none was sent.
countrystring | nullOptional
ISO 3166-1 alpha-2. Null when none was stored (crypto recipients).
externalIdstring | nullOptional
Your id for the recipient, or null when none was sent.
endUserIdstring | nullOptional
typestringOptional
Allowed values:individualbusiness
phonestring | nullOptional
screeningStatusstring | nullOptional
Internal compliance state. Returned today but not part of the contract, and it will be removed. Do not read it.
screeningReasonstring | nullOptional
Internal compliance state. Returned today but not part of the contract, and it will be removed. Do not read it.
screenedAtstring<date-time> | nullOptional
Internal compliance state. Returned today but not part of the contract, and it will be removed. Do not read it.
deletedAtstring<date-time> | nullOptional
Always null on a read (deleted recipients are not returned). It will be removed.
createdAtstring<date-time>Optional
updatedAtstring<date-time>Optional
organizationIdstringOptional
The organization id you authenticate with, the same one you put in the URL, for test and live keys alike.
paymentMethodsarray of objectOptional
Show 10 properties
- idstringOptional
- kindstringOptional
  Allowed values:fiatcrypto
- currencystring | nullOptional
- last4string | nullOptional
- statusstringOptional
  Allowed values:activependingfailed
- destinationAccountIdstring | nullOptional
  Pass this as destinationAccountId when pricing a payout.
- addressstring | nullOptional
  Crypto methods only. The destination wallet address.
- chainstring | nullOptional
  Crypto methods only. The network the address is on.
- labelstring | nullOptional
- railstring | nullOptional
  An internal routing label. Returned today but not part of the contract, and it will be removed. Do not read it.
methodobjectOptional
The payment method this call registered, or on a repeat the one it matched. Keep method.destinationAccountId. Absent only if the call could not name a single method; then read the recipient again rather than choosing one.
Show 6 properties
- idstringOptional
- kindstringOptional
- currencystring | nullOptional
- last4string | nullOptional
- statusstringOptional
- destinationAccountIdstring | nullOptional

Errors

400
Validation failed, or a corridor field is missing
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
A valid key that may not make this write. Nothing was changed.
- FORBIDDEN: the key belongs to a different organization.
- ACCOUNT_BLOCKED: API access for your organization is suspended.
- LIVE_KEY_ORG_NOT_APPROVED: a live key, before we have approved your business verification. Use a test key until then.
- INSUFFICIENT_SCOPE: a read-only key. Issue one with the write scope.
404
Unknown or deleted recipient
409
BANK_ACCOUNT_ALREADY_LINKED: this bank account is already saved on a recipient (existingRecipientId, existingMethodId). Or an idempotency conflict (IDEMPOTENCY_KEY_CONFLICT, IDEMPOTENCY_KEY_REQUEST_IN_PROGRESS).
429
Too many requests. The default ceiling is 100 requests per minute per API credential on a 60-second window. High-volume payout and reconciliation routes declare a 600/minute override, and batch submission a 30/minute ceiling. A separate 2,000/minute per-source-IP abuse ceiling always applies.

Obey Retry-After; it is in seconds and is authoritative. A 429 means the request was refused before the handler ran. Retry reads normally; retry an idempotent mutation with its same Idempotency-Key.
503
Provider registration is temporarily unavailable; retry safely.

Error body · Error

typestringRequired
Stable machine-readable code.
detailstringRequired
What went wrong, in a sentence. Always a string, so detail.toLowerCase() is safe.
More
This is the field to read on BAD_REQUEST and PROVIDER_REJECTED, where the type alone does not name the condition.
messagestringRequired
The same text as detail, kept for integrations written before detail existed. Read detail.
resolutionstringOptional
What to do about it, when there is a specific answer. It is not on every error (it is absent on BAD_REQUEST, NOT_FOUND, PAYOUT_NOT_CANCELABLE and DESTINATION_ACCOUNT_NOT_FOUND), so treat it as optional and fall back to detail.
statusintegerRequired
HTTP status, repeated in the body.
statusCodeintegerRequired
The same value as status, kept for integrations written before status existed. Read status.
requestIdstringRequired
Quote this to support and we can find the exact request. Also sent as the x-request-id response header, which is the only place it appears on a successful response. Success bodies do not carry it. Send your own x-request-id on the request and we use it, so your trace and ours share one identifier; otherwise we mint one.
errorsarray of stringOptional
Present on VALIDATION_ERROR; names each field that failed.
originalIdempotencyKeystringOptional
On DUPLICATE_REQUEST_DETECTED only. Send the request again with this to receive the original payout instead of making a second one. Without it there is no way to recover except by risking a double payment.
originalPayoutIdstringOptional
On DUPLICATE_REQUEST_DETECTED only. The payout the first request created.
originalBatchIdstringOptional
On a batch DUPLICATE_REQUEST_DETECTED. The run the first request created.
originalRequestIdstringOptional
On a 409 PAYOUT_OUTCOME_UNKNOWN replay. The requestId of the call whose outcome is unknown; quote it to support.
existingRecipientIdstringOptional
On BANK_ACCOUNT_ALREADY_LINKED. The recipient in your organization that already holds this account.
existingMethodIdstringOptional
On BANK_ACCOUNT_ALREADY_LINKED. The payment method on that recipient.

Branch on type, never on the status or the message. Every error type is listed with what to do about it.

Avvio Partner Payouts · Recipients · operation addBeneficiaryMethod

Try it: Add a payment method

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

API key Required

Test keys only. Sent as x-api-key through this site's proxy to the Avvio API, never saved, and cleared when you close this dialog.

orgId pathRequired

recipientId pathRequired

Idempotency-Key headerRequired

Body JSON

Was this page helpful?