Corridors

List corridors

Currencies you can pay out to, and the fields each needs.

GET

GET/recipients/{orgId}/corridors

curl -s "$AVVIO_BASE_URL/recipients/$AVVIO_ORG_ID/corridors" \
  -H "x-api-key: $AVVIO_API_KEY"

const res = await fetch(`${process.env.AVVIO_BASE_URL}/recipients/${process.env.AVVIO_ORG_ID}/corridors`, {
  headers: {
    'x-api-key': process.env.AVVIO_API_KEY,
  },
});
console.log(res.status, await res.json());

import os
import requests

res = requests.get(
    f"{os.environ['AVVIO_BASE_URL']}/recipients/{os.environ['AVVIO_ORG_ID']}/corridors",
    headers={
        "x-api-key": os.environ["AVVIO_API_KEY"],
    },
)
print(res.status_code, res.json())

200OK

{
  "corridors": [
    {
      "currency": "MXN",
      "fields": [
        {
          "id": "clabeNumber",
          "title": "CLABE",
          "description": "18-digit CLABE issued by the recipient's Mexican bank.",
          "type": "string",
          "pattern": "^[0-9]{18}$",
          "checksum": "clabe",
          "required": true
        }
      ],
      "limits": {
        "min": "1.00",
        "max": "5000.00"
      },
      "settlement": null
    }
  ],
  "capabilities": {
    "exactOutput": true,
    "indicativePricing": true
  }
}

{
  "type": "BAD_REQUEST",
  "status": 400,
  "detail": "No approved payments provider is available for this request",
  "requestId": "req-9uh",
  "message": "No approved payments provider is available for this request",
  "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": "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

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.

Query parameters

currencystringOptional
ISO-4217 destination currency used for provider routing.

Behavior

Render your recipient form from this response. Do not hardcode fields: both the set of corridors and the field names within a corridor depend on how your organization is routed. A form built against one routing fails against another with a missing-field error naming a field you have never seen. When you know the destination currency, pass it so discovery and recipient creation use the same approved provider decision.

Responses

200Available corridors

Body

corridorsarray of objectRequired
Show 6 properties
- currencystringRequired
  ISO 4217 payout currency.
- countrystringOptional
  ISO 3166-1 alpha-2 country; XX means an international corridor. Present only when the routing publishes one; the sandbox does not. Key on currency, never on this.
- fieldsarray of objectRequired
  Render these, in order. Names and count vary by routing.
  Show 8 properties
  - idstringRequired
  - titlestringRequired
  - descriptionstringOptional
  - typestringRequired
  - patternstringOptional
    Regex the value must match.
  - checksumstringOptional
    A check the server applies beyond pattern, named so you can run the same one client-side. Present only on fields that have one; a value matching pattern but failing this check is refused with 400 VALIDATION_ERROR and an errors[] entry naming the check digit. clabe: digit 18 of a Mexican CLABE checks digits 1-17 with weights 3,7,1 repeating, each product taken mod 10 before summing, then (10 - sum mod 10) mod 10 (Banxico's algorithm). See Register recipients.
    Allowed values:clabe
  - requiredbooleanRequired
  - optionsarray of objectOptional
    Present for select fields; submit the chosen value.
    Show 2 properties
    valueanyRequired
    labelstringRequired
- limitsobjectOptional
  Present when the routing publishes a floor or ceiling. Denominated in the destination currency (currency), not the source.
  Show 2 properties
  - minstringOptional
  - maxstringOptional
- settlement | nullRequired
  Settlement windows, cutoffs and name-matching rules are not published per corridor yet, and this field says so explicitly rather than a docs page saying "ask us". It stays null until the networks confirm figures we can stand behind. What is known lands on each payout as expectedSettlementAt when the network reports it.
- minimumSourceAmountobjectOptional
  The floor for this corridor, stated by the routing in USD on the source side. Distinct from limits, which is denominated in the destination currency when a routing publishes one. Absent when no floor is known.
  Show 2 properties
  - currencystringRequired
  - amountstringRequired
capabilitiesobjectRequired
What this routing can do. Read exactOutput here before offering an exact receiving amount in your UI. The alternative is discovering it from a 400 on a payout you have already promised somebody.
Show 2 properties
- exactOutputbooleanRequired
- indicativePricingbooleanRequired

Errors

400
BAD_REQUEST: your organization has no approved way to carry this request (for a currency you passed, or at all). Nothing ran. Check the currency against your corridors, or contact us.
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 call. Nothing ran.
- FORBIDDEN: the key belongs to a different organization.
- ACCOUNT_BLOCKED: API access for your organization is suspended, and every key is refused until we lift it. Contact support.
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 · Corridors · operation listCorridors

Try it: List corridors

GET https://api.avvio.xyz/business/api/v1/recipients/{orgId}/corridors

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

currency queryOptional

Was this page helpful?