Payout links

Create a payout link

Mint a one-time link for the person being paid.

POST

POST/payments/organizations/{orgId}/payout-links

IDEMPOTENCY_KEY=$(uuidgen)  # new key per call; reuse it only to retry this exact request
curl -s -X POST "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/payout-links" \
  -H "x-api-key: $AVVIO_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "content-type: application/json" \
  -d '{
        "amount": "75.00",
        "destinationCurrency": "MXN",
        "endUserId": "<endUserId>"
      }'

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}/payments/organizations/${process.env.AVVIO_ORG_ID}/payout-links`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.AVVIO_API_KEY,
    'Idempotency-Key': idempotencyKey,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    "amount": "75.00",
    "destinationCurrency": "MXN",
    "endUserId": "<endUserId>"
  }),
});
console.log(res.status, await res.json());

import os
import uuid
import requests

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']}/payments/organizations/{os.environ['AVVIO_ORG_ID']}/payout-links",
    headers={
        "x-api-key": os.environ["AVVIO_API_KEY"],
        "Idempotency-Key": idempotency_key,
    },
    json={
        "amount": "75.00",
        "destinationCurrency": "MXN",
        "endUserId": "<endUserId>"
    },
)
print(res.status_code, res.json())

201Created

{
  "payoutLinkId": "cmf3k2xh10010q8b7a3c5e7gj",
  "url": "https://pay.avvio.xyz/l/eyJhbGciOiJIUzI1NiJ9.ZXhhbXBsZQ",
  "expiresAt": "2026-08-20T15:03:11.000Z",
  "status": "pending"
}

{
  "type": "VALIDATION_ERROR",
  "status": 400,
  "detail": "MXN payouts start at 1.00 USD.",
  "resolution": "Correct the fields listed in `errors` and retry.",
  "errors": [
    "amount: minimum 1.00 USD for MXN"
  ],
  "requestId": "req-a9y",
  "message": "MXN payouts start at 1.00 USD.",
  "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": "USE_POST_PAYOUTS",
  "status": 403,
  "detail": "This organization has payout controls (approvals or limits) that are enforced on POST /payouts only. Create the payout there instead. Nothing was sent.",
  "resolution": "Nothing was sent. This organization has payout controls that only POST /payouts enforces; send the payout through it (you may receive 202 pending_approval).",
  "requestId": "req-9k7",
  "message": "This organization has payout controls (approvals or limits) that are enforced on POST /payouts only. Create the payout there instead. Nothing was sent.",
  "statusCode": 403
}

{
  "type": "IDEMPOTENCY_KEY_CONFLICT",
  "status": 409,
  "detail": "This Idempotency-Key was already used with a different request body. Use a new key for a different request.",
  "resolution": "This key was used with a different body. Do not retry — use a new key for a new request.",
  "requestId": "req-9g3",
  "message": "This Idempotency-Key was already used with a different request body. Use a new key for a different request.",
  "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_LINKS_UNAVAILABLE",
  "status": 503,
  "detail": "Hosted payout links are not configured on this environment: receipt provider contacts are missing.",
  "resolution": "Hosted payout links are not configured on this environment. Nothing was sent; contact support.",
  "requestId": "req-a9x",
  "message": "Hosted payout links are not configured on this environment: receipt provider contacts are missing.",
  "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.

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.

amountstringRequired
USD debit amount as a decimal string with at most two fractional digits.
destinationCurrencystringRequired
ISO 4217 payout currency; normalized to uppercase.
endUserIdstringRequired
Your id for the person being paid.
referencestringOptional
Your payment reference. Echoed back and searchable.
expiresInMinutesintegerOptionalDefaults to 60
Whole minutes. Defaults to 60 and is capped at 7 days (10,080 minutes).
endUserobjectOptional
The sender, your own end user; the same shape POST /payouts takes.
Show 2 properties
- namestringOptional
- emailstring<email>Optional
  Where the Reg E receipt goes when the link holder supplies no senderEmail.

Behavior

The alternative to collecting bank details yourself. You send the amount and who it is for on your side; we return a URL. The recipient enters their own account details, so you never hold them.

Your Idempotency-Key is carried onto the link, so the payout it eventually creates deduplicates against your retry, not only against ours. Minting the same link twice cannot become two payments even though a stranger spends them minutes apart.

Responses

201The link.

Body

payoutLinkIdstringRequired
urlstring<uri>Required
expiresAtstring<date-time>Required
statusstringRequired

Errors

400
VALIDATION_ERROR: a field is malformed, or the amount is outside the corridor's minimum or maximum (errors names the figure). IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_INVALID: the header is missing or malformed.
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
USE_POST_PAYOUTS: this organization has an approval threshold or a velocity cap, and only POST /payouts enforces them. Nothing was sent; send the payout through POST /payouts, which may answer 202 pending_approval. Also the refusals every write can answer: FORBIDDEN (a key for a different organization), ACCOUNT_BLOCKED, LIVE_KEY_ORG_NOT_APPROVED and INSUFFICIENT_SCOPE.
409
Either the key was reused with a different body (IDEMPOTENCY_KEY_CONFLICT: use a new key), or the first request with this key is still running (IDEMPOTENCY_KEY_REQUEST_IN_PROGRESS: back off and retry the same key).
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
PAYOUT_LINKS_UNAVAILABLE: hosted payout links are not configured on this environment. Nothing was sent; contact support.

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 · Payout links · operation createPayoutLink

Try it: Create a payout link

POST https://api.avvio.xyz/business/api/v1/payments/organizations/{orgId}/payout-links

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

Idempotency-Key headerRequired

Body JSON

Was this page helpful?