Skip to content

A payment to a payee already saved in Avvio, with no invoice.

POST

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.

  • payeeIdstringRequired

    A saved payee's id.

  • amountstringRequired

    In the payee's currency, above zero, e.g. 1200.50.

  • currencystringOptional

    Needed only when the payee is paid in more than one currency.

  • methodIdstringOptional

    One of the payee's saved accounts (paymentMethods[].id).

  • referencestringOptional

    What it is for.

Behavior

Avvio uses the payee's saved name and account; this request carries no bank details (an unknown field is a 400). New payees or new bank details come on an invoice (send it to documents) or from a person in Avvio.

Nothing is paid from this API. A person approves the package in Avvio, at approveUrl.

Needs a live key with the assistant scope. One open payment per payee, and at most 20 open packages per key in the last 30 days. Another payment to the payee open or paid in the last 30 days puts a question on the package that only a person answers. reference is a plain ASCII bank memo (A-Z, 0-9, spaces and . , ' / # ( ) & : -), never a link.

Responses

201The package, waiting for a person to approve it at approveUrl.

Body · AssistantPackage

  • idstringRequired

    The package id.

  • objectstringRequired
  • createdAtstring<date-time> | nullOptional
  • createdByobjectRequired
    Show 2 properties
    • apiKeyIdstringOptional
    • namestring | nullOptional
  • documentobjectOptional
    Show 1 property
    • filenamestring | nullOptional
  • approveUrlstring<uri>Required

    Where a person on your team reviews and approves it in Avvio. Send them here; this key cannot approve.

  • packageobjectRequired

    The prepared payment as Avvio shows it: status (ready once a person can approve it), bill, payee (account numbers masked to their last 4), checks, questions, and payoutId once sent. New fields are added without a major version.

Errors

  • 400

    A field that is not in the body schema (bank details included), or an amount that is not a decimal above zero.

  • 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

    INSUFFICIENT_SCOPE (the key lacks assistant), LIVE_KEY_REQUIRED (a test key), or API_KEY_REQUIRED (a dashboard session).

  • 404

    No such saved payee in this organization, or methodId is not one of its accounts.

  • 409

    OPEN_PAYMENT_EXISTS: a payment to this payee is already open; packageId is set only when this key prepared it. Or an Idempotency-Key reused with a different body.

  • 422

    NO_ACCOUNT_IN_CURRENCY, CURRENCY_REQUIRED, NO_ACCOUNT, AMOUNT_PRECISION (cents on a currency without them) or WALLET_PAYMENTS_OFF.

  • 429

    TOO_MANY_OPEN (20 open packages for this key in the last 30 days), or rate limited.

  • 503

    ASSISTANT_API_DISABLED.

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 · Assistant · operation createAssistantPackage

Try it: Prepare a payment to a saved payee

POST https://api.avvio.xyz/business/api/v1/assistant/v1/{orgId}/packages

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?