Docs / Core Guides / Funded Payouts

Funded Payouts

While most payouts settle instantly against your pre-funded USD balance, certain cryptocurrency or dedicated settlement routings price the transfer and require you to fund the payout from your own non-custodial wallet.

Avvio holds no keys to these funds and cannot execute the transfer on your behalf. You will know a payout requires external funding because the creation response returns:

json

{
  "requiresFunding": true
}

1. Retrieve Funding Instructions#

Call GET /payments/organizations/{orgId}/payouts/{payoutId}/funding:

http

GET /payments/organizations/{orgId}/payouts/payout_98124b89/funding

Response:

json

{
  "payoutId": "payout_98124b89",
  "amount": "200.00",
  "currency": "USDC",
  "depositAddress": "0x71C...492",
  "network": "base",
  "expiresAt": "2026-08-17T09:15:00.000Z"
}

WARN

Respect expiresAt. The pricing and exchange rate lock expire strictly at expiresAt. Sending on-chain funds against expired deposit instructions can result in unmatchable transfers.

2. Confirm Funding#

Once you broadcast the transaction from your registered wallet, notify Avvio with the transaction hash:

http

POST /payments/organizations/{orgId}/payouts/payout_98124b89/funding/confirm
Idempotency-Key: 5a81e921-bc01-447a-9a11-0982716a5b42
Content-Type: application/json

{
  "transactionHash": "0x98a123...45f"
}

Avvio verifies the blockchain state before recording the deposit. The transaction must:

Exist on the designated network.
Have successfully confirmed.
Have transferred at least the required token amount to the exact depositAddress.

Confirmation Error Handling#

Response Code	Type	Meaning	Action
`400`	`FUNDING_TRANSACTION_INVALID`	Transaction reverted, went to wrong address, or sent insufficient amount.	Nothing is recorded. The payout remains open. Correct the transfer and submit the new transaction hash.
`409`	`FUNDING_NOT_YET_VERIFIABLE`	The transaction has not yet been mined or indexed by the node.	Your transfer is unaffected. Back off and retry confirming the same transaction hash.

Solana Funding Rail#

On Solana rails, confirmation signatures are validated on syntactic shape rather than real-time chain inspection. If a signature is submitted for a wrong transaction, the payout remains pending. Treat any Solana payout still pending after its expiresAt as unfunded.