List payment reasons

Lists the values purposeOfPayment accepts.

GETCopy URL: https://api.avvio.xyz/business/api/v1/payments/organizations/{orgId}/payment-reasons

GET/payments/organizations/{orgId}/payment-reasons

Open in explorer

curl

curl -s "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/payment-reasons?currency=MXN" \
  -H "x-api-key: $AVVIO_API_KEY"

Node

const res = await fetch(`${process.env.AVVIO_BASE_URL}/payments/organizations/${process.env.AVVIO_ORG_ID}/payment-reasons?currency=MXN`, {
  headers: {
    'x-api-key': process.env.AVVIO_API_KEY,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

res = requests.get(
    f"{os.environ['AVVIO_BASE_URL']}/payments/organizations/{os.environ['AVVIO_ORG_ID']}/payment-reasons",
    headers={
        "x-api-key": os.environ["AVVIO_API_KEY"],
    },
    params={
        "currency": "MXN"
    },
)
print(res.status_code, res.json())

Try it

200OKResponse status200 OK400 Bad Request401 Unauthorized403 Forbidden429 Too Many Requests

{
  "payment_reasons": [
    {
      "id": "FAMILY_SUPPORT",
      "label": "Family support"
    },
    {
      "id": "EDUCATION",
      "label": "Education fees"
    }
  ],
  "default": "FAMILY_SUPPORT"
}

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

  Destination currency, ISO 4217. Omit for the default catalog.

Behavior

Some corridors require a stated purpose for the payment. POST /payouts and quote-accept take it as purposeOfPayment, and this is the catalog they validate against. Read it rather than guessing, because a rejected value is a 400 on a payout you have already promised somebody. Pass currency to get the catalog of the network that would carry a payout in that currency. The ids differ between networks (for example FAMILY_SUPPORT on one, family_support on another), so send back exactly an id from this list.

Responses

200The accepted payment reasons

Body

• payment_reasonsarray of objectRequired
  Show 2 properties

  • idstringRequired

    The value to send as purposeOfPayment (or paymentReason).

  • labelstringRequired
• defaultstringOptional

  The value used when a corridor requires one and you send none.

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 listPaymentReasons

Try it: List payment reasons

GET https://api.avvio.xyz/business/api/v1/payments/organizations/{orgId}/payment-reasons

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

Send request