Prepare a payment to a saved payee
A payment to a payee already saved in Avvio, with no invoice.
Path parameters
orgIdstringRequiredThe opaque organization id issued to you, normally CUID-shaped (for example
cmsx…). It is not anorg_-prefixed alias. Pass it unchanged in every organization-scoped path.
Headers
Idempotency-KeystringRequiredA 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. A4xxreleases 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.
payeeIdstringRequiredA saved payee's
id.amountstringRequiredIn the payee's currency, above zero, e.g.
1200.50.currencystringOptionalNeeded only when the payee is paid in more than one currency.
methodIdstringOptionalOne of the payee's saved accounts (
paymentMethods[].id).referencestringOptionalWhat 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
idstringRequiredThe package id.
objectstringRequiredcreatedAtstring<date-time> | nullOptionalcreatedByobjectRequiredShow 2 properties
apiKeyIdstringOptionalnamestring | nullOptional
documentobjectOptionalShow 1 property
filenamestring | nullOptional
approveUrlstring<uri>RequiredWhere a person on your team reviews and approves it in Avvio. Send them here; this key cannot approve.
packageobjectRequiredThe prepared payment as Avvio shows it:
status(readyonce a person can approve it),bill,payee(account numbers masked to their last 4),checks,questions, andpayoutIdonce sent. New fields are added without a major version.
Errors
400A field that is not in the body schema (bank details included), or an amount that is not a decimal above zero.
401The 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.
403INSUFFICIENT_SCOPE(the key lacksassistant),LIVE_KEY_REQUIRED(a test key), orAPI_KEY_REQUIRED(a dashboard session).404No such saved payee in this organization, or
methodIdis not one of its accounts.409OPEN_PAYMENT_EXISTS: a payment to this payee is already open;packageIdis set only when this key prepared it. Or anIdempotency-Keyreused with a different body.422NO_ACCOUNT_IN_CURRENCY,CURRENCY_REQUIRED,NO_ACCOUNT,AMOUNT_PRECISION(cents on a currency without them) orWALLET_PAYMENTS_OFF.429TOO_MANY_OPEN(20 open packages for this key in the last 30 days), or rate limited.503ASSISTANT_API_DISABLED.
Error body · Error
typestringRequiredStable machine-readable code.
detailstringRequiredWhat went wrong, in a sentence. Always a string, so
detail.toLowerCase()is safe.More
This is the field to read on
BAD_REQUESTandPROVIDER_REJECTED, where the type alone does not name the condition.messagestringRequiredThe same text as
detail, kept for integrations written beforedetailexisted. Readdetail.resolutionstringOptionalWhat 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_CANCELABLEandDESTINATION_ACCOUNT_NOT_FOUND), so treat it as optional and fall back todetail.statusintegerRequiredHTTP status, repeated in the body.
statusCodeintegerRequiredThe same value as
status, kept for integrations written beforestatusexisted. Readstatus.requestIdstringRequiredQuote this to support and we can find the exact request. Also sent as the
x-request-idresponse header, which is the only place it appears on a successful response. Success bodies do not carry it. Send your ownx-request-idon the request and we use it, so your trace and ours share one identifier; otherwise we mint one.errorsarray of stringOptionalPresent on VALIDATION_ERROR; names each field that failed.
originalIdempotencyKeystringOptionalOn
DUPLICATE_REQUEST_DETECTEDonly. 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.originalPayoutIdstringOptionalOn
DUPLICATE_REQUEST_DETECTEDonly. The payout the first request created.originalBatchIdstringOptionalOn a batch
DUPLICATE_REQUEST_DETECTED. The run the first request created.originalRequestIdstringOptionalOn a
409 PAYOUT_OUTCOME_UNKNOWNreplay. TherequestIdof the call whose outcome is unknown; quote it to support.existingRecipientIdstringOptionalOn
BANK_ACCOUNT_ALREADY_LINKED. The recipient in your organization that already holds this account.existingMethodIdstringOptionalOn
BANK_ACCOUNT_ALREADY_LINKED. The payment method on that recipient.limitobjectOptionalOn
PAYOUT_LIMIT_EXCEEDEDfrom a payout. Which cap refused it and what is left of it.Show 8 properties
scopestringRequiredorganization: a cap on your whole organization (seelimitsonGET /policy).api_key: a cap on the key that made the call (apiKeyLimits).Allowed values:organizationapi_keywindowstringRequiredsingleis one payout;dailyandmonthlyare the UTC day and calendar month.Allowed values:singledailymonthlycapUsdstringRequiredusedUsdstring | nullRequiredWhat already counts in this window.
nullforsingle. On the per-end-user cap, that end user's own volume.remainingUsdstring | nullRequiredcapUsd - usedUsd, never below zero: the most a payout may be under this cap right now.nullforsingle.resetsAtstring<date-time> | nullRequiredWhen the window starts over.
nullforsingle.capstringOptionalThe cap's name as the message says it (
single-payout,daily,daily per-end-user,monthly). Prose; branch onscopeandwindow.valueUsdstringOptionalThe 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.
Was this page helpful?