Accept a quote

Send the money.

POST

POST/payments/organizations/{orgId}/quotes/accept

IDEMPOTENCY_KEY=$(uuidgen)  # new key per call; reuse it only to retry this exact request
curl -s -X POST "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/quotes/accept" \
  -H "x-api-key: $AVVIO_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "content-type: application/json" \
  -d '{
        "snapshotId": "<snapshotId>",
        "type": "OFFRAMP",
        "endUser": {
          "id": "customer_42"
        },
        "paymentReason": "FAMILY_SUPPORT"
      }'

const idempotencyKey = crypto.randomUUID(); // new key per call; reuse it only to retry this exact request

const res = await fetch(`${process.env.AVVIO_BASE_URL}/payments/organizations/${process.env.AVVIO_ORG_ID}/quotes/accept`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.AVVIO_API_KEY,
    'Idempotency-Key': idempotencyKey,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    "snapshotId": "<snapshotId>",
    "type": "OFFRAMP",
    "endUser": {
      "id": "customer_42"
    },
    "paymentReason": "FAMILY_SUPPORT"
  }),
});
console.log(res.status, await res.json());

import os
import uuid
import requests

idempotency_key = str(uuid.uuid4())  # new key per call; reuse it only to retry this exact request

res = requests.post(
    f"{os.environ['AVVIO_BASE_URL']}/payments/organizations/{os.environ['AVVIO_ORG_ID']}/quotes/accept",
    headers={
        "x-api-key": os.environ["AVVIO_API_KEY"],
        "Idempotency-Key": idempotency_key,
    },
    json={
        "snapshotId": "<snapshotId>",
        "type": "OFFRAMP",
        "endUser": {
            "id": "customer_42"
        },
        "paymentReason": "FAMILY_SUPPORT"
    },
)
print(res.status_code, res.json())

200OK

{
  "payoutId": "sbx_pay_7c1c0f2e-6d9b-4a3e-9d1a-2f4b8c9e0a11",
  "status": "processing",
  "stage": "settling",
  "sourceAmount": {
    "currency": "USD",
    "amount": "200.00"
  },
  "destinationAmount": {
    "currency": "MXN",
    "amount": "3384.65"
  },
  "destinationAccountId": "sbx_acct_MXN_4471_ae66cbc5",
  "fee": {
    "currency": "USD",
    "amount": "1.02"
  },
  "rate": "16.923250",
  "reference": "ZZ-WAGE-1",
  "endUser": {
    "id": "customer_42",
    "name": "Northwind Payroll LLC",
    "email": "payroll@northwind.example"
  },
  "createdAt": "2026-08-20T14:03:11.000Z",
  "updatedAt": "2026-08-20T14:03:12.480Z",
  "completedAt": null
}

{
  "type": "INSUFFICIENT_BALANCE",
  "status": 400,
  "detail": "Insufficient USD balance for this payout. Balance 150.00 USD, needed 200.00 USD. Nothing was sent. Top up by wiring to the account on GET /payments/organizations/{orgId}/payin-accounts.",
  "requestId": "req-9xk",
  "message": "Insufficient USD balance for this payout. Balance 150.00 USD, needed 200.00 USD. Nothing was sent. Top up by wiring to the account on GET /payments/organizations/{orgId}/payin-accounts.",
  "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": "USE_POST_PAYOUTS",
  "status": 403,
  "detail": "This organization has payout controls (approvals or limits) that are enforced on POST /payouts only. Create the payout there instead. Nothing was sent.",
  "resolution": "Nothing was sent. This organization has payout controls that only POST /payouts enforces; send the payout through it (you may receive 202 pending_approval).",
  "requestId": "req-9k7",
  "message": "This organization has payout controls (approvals or limits) that are enforced on POST /payouts only. Create the payout there instead. Nothing was sent.",
  "statusCode": 403
}

{
  "type": "IDEMPOTENCY_KEY_CONFLICT",
  "status": 409,
  "detail": "This Idempotency-Key was already used with a different request body. Use a new key for a different request.",
  "resolution": "This key was used with a different body. Do not retry — use a new key for a new request.",
  "requestId": "req-9g3",
  "message": "This Idempotency-Key was already used with a different request body. Use a new key for a different request.",
  "statusCode": 409
}

{
  "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
}

{
  "type": "PAYOUT_OUTCOME_UNKNOWN",
  "status": 500,
  "detail": "The outcome of this request is unknown: the payout may have been created. Do not send a new Idempotency-Key. Poll GET /orders?reference=<your reference>, or replay this key, which answers 409 until we resolve it. Contact support with the requestId.",
  "resolution": "The payout may have been created. Do not send a new Idempotency-Key. Poll GET /orders?reference=<your reference> (or replay the same key, which answers 409 until we resolve it) and contact support with the requestId.",
  "requestId": "req-2k9f",
  "message": "The outcome of this request is unknown: the payout may have been created. Do not send a new Idempotency-Key. Poll GET /orders?reference=<your reference>, or replay this key, which answers 409 until we resolve it. Contact support with the requestId.",
  "statusCode": 500
}

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.
X-Allow-DuplicatestringOptional
Set to true to send a request that is byte-identical to one you sent within the last 15 minutes under a different key. true is the only accepted value. It switches off the guard that catches a retry arriving under a fresh key, so send it only when you mean to pay twice.

Body

This endpoint expects a JSON object.

snapshotIdstringRequired
The snapshot's id from the pricing step.
quoteIdstringOptional
The snapshot's best_quote_id.
typestringRequired
Fixed payout quote type. Send the literal string OFFRAMP.
referencestringOptional
Your payment reference. Echoed back and searchable.
endUserobjectOptional
Your own customer this payout is sent for: the party sending through your platform, never the recipient. In payroll the employer is the end user and the worker is the recipient; omit the object when you are the sender yourself. Attribution and the per-end-user daily cap key on id; it is not forwarded to the payment network and does not change the sender of record, which stays your organization. Echoed on the payout and in every webhook, so a support question is answerable without your own id map.
Show 3 properties
- idstringOptional
  Your stable identifier for the sending customer (not the recipient).
- namestringOptional
  Person's display or legal name.
- emailstring<email>Optional
  Person's email address in standard email format.
filesarray of stringOptional
Compliance attachments as data URIs. Each item is data:<mime>;base64,<contents>; use PDF, JPEG, or PNG, up to 5 MB each. Some regulated corridors require an invoice. When both files and attachment are sent, files wins.
attachmentstringOptional
Single-attachment convenience using the same data-URI format as files.
paymentReasonstringOptional
Payment purpose, from GET /payment-reasons (its id). The vocabulary depends on how your organization is routed, so read it rather than hardcoding values.
commentstringOptional
Free-text note forwarded to compliance.
attestedAtstring<date-time>Optional
When the supporting document was attested as genuine.
signerNamestringOptional
Name of the person who made the attestation.

Behavior

This is the step that moves money. It debits your balance and returns the payout. A balance-funded payout needs nothing else. A payout you fund yourself comes back with requiresFunding: true: read GET /payouts/{payoutId}/funding, send the money, and confirm it with POST /payouts/{payoutId}/funding/confirm.

If this times out, the outcome is unknown: the payout may have been accepted. Retry with the same Idempotency-Key. A replay returns the original payout; re-quoting sends a second payment. A 500 PAYOUT_OUTCOME_UNKNOWN means the same thing: do not re-quote or mint a new key; look for the payout with GET /orders?reference=<your reference> first.

Responses

200The payout. A replayed idempotent request returns the original and sets the Idempotency-Replayed response header.

Headers

Idempotency-Replayedboolean
Present and true when this response was replayed.

Body · Payout

payoutIdstringOptional
statusstringOptional
A payout moves only along these transitions:
More
```
pending    -> processing | completed | failed | canceled
processing -> completed | failed
completed  -> failed                  (returned by the recipient's bank)
```
- pending: accepted, reserved, not sent. The only cancelable state.
- processing: handed to the payment network. Committed.
- completed: the recipient was paid. Not absolutely final.
- failed: not paid, or paid and then returned. Branch on failureCode.
- canceled: you ended it before it was sent. It is not a failure, so it carries no failureCode; fundsReturned is true because the money never left.
completed can still become failed. A receiving bank can return a payment days after settlement, giving failureCode: returned_by_bank and fundsReturned: true. Do not write a ledger that treats completed as immutable, and keep processing webhooks for a payout after it completes.
Allowed values:pendingprocessingcompletedfailed
Show 1 more value
canceled
stagestringOptional
Informational sub-state on a slow payout, so your support team can answer "where is it?". Non-authoritative: never branch integration behavior on it, and treat an unrecognized value as the status alone.
Allowed values:awaiting_detailsunder_reviewsettling
failureCodestringOptional
New codes may be added; treat an unknown one as execution_failed.
Allowed values:quote_expiredinsufficient_fundslimit_exceededaccount_invalid
Show 6 more values
account_cannot_receivecompliance_rejectedauthorization_not_completedreturned_by_bankexecution_failedunknown
requiresFundingbooleanOptional
Present and true when this payout is waiting on you to fund it from your own wallet. Absent on routings that settle on acceptance, so its presence is the signal.
fundsReturnedbooleanOptional
Whether the money is back in your balance. Separate from failureCode, because the same cause can go either way depending on how far the payment got.
sourceAmountobject | nullOptional
Always a decimal string, never a float and never base units. Floats lose cents at scale; base units mean every integrator re-derives the exponent.
Show 2 properties
- currencystringRequired
- amountstringRequired
destinationAmountobject | nullOptional
Always a decimal string, never a float and never base units. Floats lose cents at scale; base units mean every integrator re-derives the exponent.
Show 2 properties
- currencystringRequired
- amountstringRequired
destinationAccountIdstring | nullOptional
feeobject | nullOptional
The fee, already inside sourceAmount, deducted from the send not added on top, so destinationAmount = sourceAmount x rate still holds. The same value the event data and the payout row on /balance_transactions report. Null when the rail has not disclosed it, which is "not known", not zero.
Show 2 properties
- currencystringRequired
- amountstringRequired
ratestring | nullOptional
The effective rate: destinationAmount / sourceAmount, derived from this payout's own amounts with the fee inside, so destinationAmount = sourceAmount x rate always holds. Lower than the indicative mid-rate GET /rates showed for the same conversion by exactly the fee share; that is not the rate moving. Compare it to PreviewQuote.rate only after netting the fee. Always six decimal places, rounded half-up ("16.923250"). Null until the amounts are known.
referencestring | nullOptional
endUserobject | nullOptional
Your own customer this payout is sent for: the party sending through your platform, never the recipient. In payroll the employer is the end user and the worker is the recipient; omit the object when you are the sender yourself. Attribution and the per-end-user daily cap key on id; it is not forwarded to the payment network and does not change the sender of record, which stays your organization. Echoed on the payout and in every webhook, so a support question is answerable without your own id map.
Show 3 properties
- idstringOptional
  Your stable identifier for the sending customer (not the recipient).
- namestringOptional
  Person's display or legal name.
- emailstring<email>Optional
  Person's email address in standard email format.
createdAtstring<date-time> | nullOptional
updatedAtstring<date-time> | nullOptional
When this payout last changed. Carry the highest value you have seen as your updatedSince watermark. Without it in the payload the change feed cannot be paged.
completedAtstring<date-time> | nullOptional
expectedSettlementAtstring<date-time>Optional
When the funds are expected to be available to the recipient, where the routing states a settlement timeline. Present only when known; an estimate, not a promise.

Errors

400
Nothing was sent.
- BAD_REQUEST: the quote expired or is not one we issued (price again), or a field this route does not take (provider, billId, fundingId); detail says which.
- INSUFFICIENT_BALANCE: your balance does not cover the payout. Top up and quote again.
- VALIDATION_ERROR: a field is malformed; errors names it.
- IDEMPOTENCY_KEY_REQUIRED or IDEMPOTENCY_KEY_INVALID: the header is missing or malformed.
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
USE_POST_PAYOUTS: this organization has an approval threshold or a velocity cap, and only POST /payouts enforces them. Nothing was sent; send the payout through POST /payouts, which may answer 202 pending_approval. Also the refusals every write can answer: FORBIDDEN (a key for a different organization), ACCOUNT_BLOCKED, LIVE_KEY_ORG_NOT_APPROVED and INSUFFICIENT_SCOPE.
409
On a route that moves money:
- IDEMPOTENCY_KEY_CONFLICT: the key was reused with a different body. Use a new key for a new request.
- IDEMPOTENCY_KEY_REQUEST_IN_PROGRESS: the first request with this key is still running. Back off and retry the same key.
- PAYOUT_OUTCOME_UNKNOWN: a replay of a key whose first call answered 500 PAYOUT_OUTCOME_UNKNOWN. Money may have moved. Do not send a new key; look the outcome up first. originalRequestId names the first call.
- DUPLICATE_REQUEST_DETECTED: an identical body under a different key within 15 minutes. Nothing was executed. Retry with originalIdempotencyKey, or send X-Allow-Duplicate: true if you mean to pay twice.
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.
500
PAYOUT_OUTCOME_UNKNOWN: the call failed after the money may have moved, and we cannot yet say whether it did. Do not retry with a new Idempotency-Key; that is how a payment goes out twice. Look the outcome up first (the operation says where), or replay the same key, which answers 409 PAYOUT_OUTCOME_UNKNOWN until we resolve it. Send support the requestId.

Every other 500 is INTERNAL: nothing was recorded under the key, and retrying with the same key is safe.

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 · Quotes & rates · operation sendPayout

Try it: Accept a quote

POST https://api.avvio.xyz/business/api/v1/payments/organizations/{orgId}/quotes/accept

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

Idempotency-Key headerRequired

X-Allow-Duplicate headerOptional

Body JSON

Was this page helpful?