Skip to content

Returns your organization's caps, approval threshold, features and rate limits.

GET

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.

Behavior

Read this first. Everything a client needs to know about its own organization before it sends money, in one call: the payout caps (null means no cap), the approval threshold and how many approvers a held payout needs, which features are on (mass_payouts for batches, developer for webhook endpoints), the rate-limit buckets per minute, the idempotency windows, the currencies that require a purposeOfPayment, and where to read corridors, events and the ledger.

Every value is what the server enforces with, read from your organization at request time, not a published table. A test key reads the sandbox's caps and approval policy (they are set per environment), features from the live organization the sandbox belongs to, and mode: test. A read-only key may read this.

Responses

200The policy your organization is under right now.

Body · Policy

  • organizationIdstringRequired

    The id you addressed. A test key sends the live organization id; this echoes it.

  • modestringRequired

    test for a test key or a sandbox environment: nothing here reaches a payment network.

    Allowed values:testlive
  • featuresarray of stringRequired

    Effective feature names, sorted. mass_payouts enables batches; developer enables webhook endpoints. Both are on unless your organization opted out.

  • limitsobjectRequired

    USD caps enforced on POST /payouts, batch lines and payout links; over one is 422 PAYOUT_LIMIT_EXCEEDED. null is no cap.

    Show 5 properties
    • maxSinglePayoutUsdstring | nullRequired
    • maxDailyPayoutUsdstring | nullRequired
    • maxDailyPerEndUserUsdstring | nullRequired

      Counted against endUser.id; when set, a payout without an endUser is refused.

    • usedTodayUsdstring | nullOptional

      What already counts toward maxDailyPayoutUsd today (UTC), every rail.

    • remainingTodayUsdstring | nullOptional

      What is left of maxDailyPayoutUsd today, never below zero; null with no daily cap.

  • apiKeyLimitsobject | nullRequired

    The calling API key's own USD caps, set when the key was issued, and what is left of them. They apply on top of limits (the stricter one refuses) to every payout this key creates, including batch lines and payouts released by an approval. Today and this month are UTC. null for a dashboard session. A key with any cap here must send through POST /payouts: the two-step quote/accept path answers 403 USE_POST_PAYOUTS.

    Show 7 properties
    • maxSinglePayoutUsdstring | nullRequired
    • maxDailyPayoutUsdstring | nullRequired
    • maxMonthlyPayoutUsdstring | nullRequired
    • usedTodayUsdstringRequired

      Dollar payouts this key has created today that were not returned, including ones still awaiting your funding.

    • usedThisMonthUsdstringRequired
    • remainingTodayUsdstring | nullRequired

      maxDailyPayoutUsd - usedTodayUsd, never below zero. null when there is no daily cap.

    • remainingThisMonthUsdstring | nullRequired

      maxMonthlyPayoutUsd - usedThisMonthUsd, never below zero. null when there is no monthly cap.

  • approvalsobjectRequired

    When thresholdUsd is set, a send above it answers 202 with an approval that requiredApprovals humans must approve in the dashboard. null means approvals are off.

    Show 3 properties
    • thresholdUsdstring | nullRequired
    • requiredApprovalsinteger | nullRequired
    • appliesToarray of stringRequired
      Allowed values:payoutsbatchespayout_links
  • agentWalletobject | nullRequired

    Present when this business pays its AI connections from its agent wallet instead of Treasury. An AI connection's payment can never be more than availableUsd; over it the payout is refused with AGENT_WALLET_LOW. null means AI connections pay from the main balance. Values are null when the chain could not be read.

    Show 2 properties
    • balanceUsdstring | nullRequired
    • availableUsdstring | nullRequired

      The balance minus AI payouts and withdrawals still in flight from it.

  • purposeOfPaymentobjectRequired
    Show 1 property
    • requiredForCurrenciesarray of stringRequired

      Destination currencies for which purposeOfPayment is required on a payout; values come from GET .../payment-reasons?currency=.

  • feesobjectRequired

    What your routing can state about its fees before a quote exists, read from its configuration. null on a number means "not published before a quote", never zero. The binding figure is always fee on the quote and on the payout; this is what to plan with.

    Show 1 property
    • payoutobjectRequired

      The payout fee, deducted from the send before conversion.

      Show 4 properties
      • bpsinteger | nullRequired

        Basis points of the send for every corridor not listed in byCurrency.

      • fixedUsdstring | nullRequired

        Fixed component in USD. Null when the network's own fixed charge is only priced on a quote.

      • byCurrencyobjectRequired

        Corridors priced differently from the default, keyed by destination currency. Empty when none are.

      • notestringRequired

        What the numbers cover and where the binding figure is. Prose; do not branch on it.

  • rateLimitsobjectRequired

    Requests per minute per credential. payouts is POST /payouts; reads covers events, orders, balance_transactions and audit-events; batches is batch creation; everything else is default. A source-IP ceiling applies on top.

    Show 4 properties
    • defaultintegerRequired
    • payoutsintegerRequired
    • batchesintegerRequired
    • readsintegerRequired
  • idempotencyobjectRequired
    Show 3 properties
    • requiredbooleanRequired

      An API key must send Idempotency-Key on every route that moves money.

    • replayWindowDaysintegerRequired

      How long a key replays its original response.

    • nearDuplicateWindowMinutesintegerRequired

      A byte-identical body under a different key inside this window is 409 DUPLICATE_REQUEST_DETECTED.

  • linksobjectRequired

    Relative paths, with your organization id filled in, for the reads an integration needs next.

    Show 3 properties
    • corridorsstringRequired
    • eventsstringRequired
    • balanceTransactionsstringRequired

Errors

  • 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.

  • limitobjectOptional

    On PAYOUT_LIMIT_EXCEEDED from a payout. Which cap refused it and what is left of it.

    Show 8 properties
    • scopestringRequired

      organization: a cap on your whole organization (see limits on GET /policy). api_key: a cap on the key that made the call (apiKeyLimits).

      Allowed values:organizationapi_key
    • windowstringRequired

      single is one payout; daily and monthly are the UTC day and calendar month.

      Allowed values:singledailymonthly
    • capUsdstringRequired
    • usedUsdstring | nullRequired

      What already counts in this window. null for single. On the per-end-user cap, that end user's own volume.

    • remainingUsdstring | nullRequired

      capUsd - usedUsd, never below zero: the most a payout may be under this cap right now. null for single.

    • resetsAtstring<date-time> | nullRequired

      When the window starts over. null for single.

    • capstringOptional

      The cap's name as the message says it (single-payout, daily, daily per-end-user, monthly). Prose; branch on scope and window.

    • valueUsdstringOptional

      The same value as capUsd.

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

Avvio Partner Payouts · Policy · operation getPolicy

Try it: Get your policy

GET https://api.avvio.xyz/business/api/v1/payments/organizations/{orgId}/policy

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.

Was this page helpful?