Get a payout link

Returns what the recipient's page renders.

GET

GET/payout-links/{token}

curl -s "$AVVIO_BASE_URL/payout-links/$token"

const token = '<token>';

const res = await fetch(`${process.env.AVVIO_BASE_URL}/payout-links/${token}`);
console.log(res.status, await res.json());

import os
import requests

token = "<token>"

res = requests.get(
    f"{os.environ['AVVIO_BASE_URL']}/payout-links/{token}",
)
print(res.status_code, res.json())

200OK

{
  "sender": {
    "name": "Northstar Logistics"
  },
  "amount": {
    "currency": "USD",
    "amount": "75.00"
  },
  "destinationCurrency": "MXN",
  "reference": "ZZ-WAGE-1",
  "expiresAt": "2026-08-20T15:03:11.000Z",
  "status": "pending",
  "requirements": [
    {
      "id": "clabeNumber",
      "title": "CLABE",
      "pattern": "^[0-9]{18}$",
      "required": true
    }
  ],
  "savedDestinations": [
    {
      "destinationAccountId": "sbx_acct_MXN_4471_ae66cbc5",
      "name": "Ana Ruiz",
      "label": "BBVA México",
      "last4": "4471"
    }
  ],
  "paymentReasons": [
    {
      "id": "FAMILY_SUPPORT",
      "label": "Family support"
    },
    {
      "id": "SALARY_PAYMENT",
      "label": "Salary"
    }
  ],
  "defaultPaymentReason": "FAMILY_SUPPORT",
  "preview": {
    "indicative": true,
    "sourceAmount": {
      "currency": "USD",
      "amount": "75.00"
    },
    "destinationAmount": {
      "currency": "MXN",
      "amount": "1275.75"
    },
    "fee": {
      "currency": "USD",
      "amount": "0.38"
    },
    "totalDebit": {
      "currency": "USD",
      "amount": "75.38"
    },
    "rate": "17.010050924685068"
  },
  "disclosure": {
    "kind": "prepayment",
    "estimated": true,
    "lines": [
      {
        "label": "Transfer Amount",
        "value": "75.00 USD"
      },
      {
        "label": "Transfer Fees",
        "value": "0.38 USD",
        "sign": "+"
      },
      {
        "label": "Total",
        "value": "75.38 USD"
      },
      {
        "label": "Exchange Rate",
        "value": "USD 1.00 = 17.0101 MXN"
      },
      {
        "label": "Total to Recipient",
        "value": "1275.75 MXN"
      }
    ],
    "otherFeesDisclaimer": "Recipient may receive less due to fees charged by the recipient’s bank and foreign taxes."
  }
}

{
  "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
}

Path parameters

tokenstringRequired
Opaque signed bearer token from the link URL. It is JWT-shaped but its claims are not a public contract; do not decode, construct, log, or store it beyond the recipient session.

Behavior

Takes no credential. The signed token in the URL is the credential, which is why it is short-lived and single-use.

Returns the amount, the fields that corridor needs, and saved destinations masked to name, label, and last four digits. It returns no organization id, no endUserId, and never full bank details. A public route that echoes back what was typed turns a forwarded link into a disclosure of someone's account number.

Expired, spent, forged and tampered tokens are all a flat 404. A stranger probing links learns nothing from the difference.

Responses

200What to render.

Body

senderobjectOptional
Who is paying: your organization's display name, so the recipient can recognize the payment. The name only; the organization id is never exposed here.
Show 1 property
- namestringRequired
amountobjectRequired
Always a decimal string, never a float and never base units. Floats lose cents at scale; base units mean every integrator re-derives the exponent.
Show 2 properties
- currencystringRequired
- amountstringRequired
destinationCurrencystringRequired
referencestringOptional
expiresAtstring<date-time>Required
statusstringRequired
consumed and expired links return 404 and are never exposed here.
Allowed values:pendingconsumingfailed
requirementsarray of objectRequired
Show 6 properties
- idstringRequired
- titlestringOptional
- typestringOptional
- descriptionstringOptional
- patternstringOptional
- requiredbooleanOptional
savedDestinationsarray of objectRequired
Masked destinations scoped to this link's end user and currency.
Show 4 properties
- destinationAccountIdstringRequired
- namestringRequired
- labelstringOptional
- last4stringOptional
paymentReasonsarray of objectOptional
The corridor's payment purposes, for the page's picker; send one id as paymentReason on submit. Omitted when the corridor asks for none.
Show 2 properties
- idstringRequired
- labelstringRequired
defaultPaymentReasonstringOptional
The purpose used when none is chosen. Present only with paymentReasons, and only when the corridor names one.
previewobjectOptional
What the page shows above the form: the rate, the fee, and roughly what lands in the recipient's account. The same shape as GET /rates, and indicative for the same reason: the binding quote is priced at submit, against the bank details this page collects. Omitted when the corridor cannot be priced in advance; the page still renders and the link is still payable.
More
A link converts its whole amount and adds the fee on top, unlike GET /rates: destinationAmount = amount x rate, and totalDebit = amount + fee (not equal to sourceAmount here).
Show 7 properties
- indicativebooleanOptional
  Always true here. This is an estimate, not a locked rate.
- sourceAmountobjectOptional
  Always a decimal string, never a float and never base units. Floats lose cents at scale; base units mean every integrator re-derives the exponent.
  Show 2 properties
  - currencystringRequired
  - amountstringRequired
- destinationAmountobjectOptional
  Always a decimal string, never a float and never base units. Floats lose cents at scale; base units mean every integrator re-derives the exponent.
  Show 2 properties
  - currencystringRequired
  - amountstringRequired
- feeobjectOptional
  Charged on the send side and deducted before conversion.
  Show 2 properties
  - currencystringRequired
  - amountstringRequired
- totalDebitobjectOptional
  What leaves your balance. On GET /rates the fee is deducted from the send rather than added on top, so this equals sourceAmount. A payout link's preview adds the fee on top, so there it is sourceAmount + fee. Read this field rather than assuming either.
  Show 2 properties
  - currencystringRequired
  - amountstringRequired
- ratestringOptional
  The indicative mid-rate, before the fee: destination units per source unit converted, "1 USD = 17.01 MXN". destinationAmount = (sourceAmount - fee) x rate. This is a different number from Payout.rate, which is the effective rate with the fee inside (destination over source), so it reads lower by the fee share for the same conversion. The rate did not move.
- limitsobjectOptional
  The corridor's floor and ceiling, in the source currency.
  Show 2 properties
  - minstringOptional
  - maxstringOptional
disclosureobjectOptional
The US Regulation E remittance disclosure, as the hosted page renders it: prepayment on the resolve (estimated, omitted when the corridor cannot be priced), receipt on the submit. Render lines in order.
Show 4 properties
- kindstringRequired
  Allowed values:prepaymentreceipt
- estimatedbooleanRequired
- linesarray of objectRequired
  Show 3 properties
  - labelstringRequired
  - valuestringRequired
  - signstringOptional
    Allowed values:+-
- otherFeesDisclaimerstringRequired

Errors

404
Not valid (expired, already spent, or never existed).
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.

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 resolvePayoutLink

Was this page helpful?

Ask AI

Get a payout link

Path parameters

Behavior

Responses

Errors

Try it: Get a payout link