# Payout from a Wallet

Turn a user's crypto into money on a bank account, paid from a wallet **they** control — Aurea never holds it and never sends it for them.

## Overview

This is the payout Fase 5 was built for, and it is not the [hosted one](https://docs.aureahub.com/docs/guide-fiat-payout.md). There, the bank ramp's own page takes the money out of Aurea's balance. Here the user's wallet sends the crypto, the bank ramp recognises the deposit **by the address it came from**, and pays the beneficiary. Nothing passes through Aurea.

The shape of it, in five calls:

1. Ask where the money may go — country, channel, and whatever that channel asks about the beneficiary.
2. Ask for a **quote**: the rate, the fees and the deadline, locked.
3. Bind that quote to a **payout**, saying which wallet will pay. The answer is the deposit: an address, an exact amount, and a deadline.
4. The user's wallet **sends that deposit**.
5. Follow the payout until it completes.

Two things decide everything that follows: **the deposit must come from the address you named**, and **it must arrive before its deadline**.

## Before You Start

- Your tenant banks with the bank ramp, has **payouts** switched on in the environment you use, and offers the pair you are paying with — [Tenant Settings](https://docs.aureahub.com/docs/bank-settings.md) says what you may show, and [Currencies & Networks](https://docs.aureahub.com/docs/bank-currencies.md) what Aurea enables.
- The **Aurea wallets** mode is on for your tenant. Paying from an address outside Aurea is the *standalone* mode and its own guide: [Standalone Pay-Out](https://docs.aureahub.com/docs/guide-standalone-payout.md).
- The user has a bank ramp profile in that environment, with onboarding completed and KYC approved — [Fiat Pay-In](https://docs.aureahub.com/docs/guide-fiat-payin.md) takes them there. A user who is not approved is refused at step 3 with `422` `NOAH_KYC_NOT_APPROVED`, not at the end.
- Choose the environment on **every** call with `isTestnet`: `true` is the bank ramp's sandbox, with its own profile, its own quotes and its own payouts. The examples below are the sandbox.

## Step 1: Where the Money Goes

[Countries](https://docs.aureahub.com/docs/payout-countries.md) lists where payouts may land; [Search Channels](https://docs.aureahub.com/docs/payout-channels.md) lists the ways to get there — a SEPA transfer, a local rail, a wallet — each with its limits and its fees. Then [Channel Form](https://docs.aureahub.com/docs/payout-channel-form.md) says what that channel needs to know about the beneficiary, field by field, in the order to ask.

A user who has been paid before has [saved beneficiaries](https://docs.aureahub.com/docs/payout-beneficiaries.md): offer those first, and ask for the form only for a new one.

## Step 2: The Quote

[Create a Quote](https://docs.aureahub.com/docs/payout-quote.md) is where the numbers are decided: how much fiat the beneficiary receives, at which rate, with which fees — your tenant's payout fee included — and **until when**. Show the user those numbers, not your own arithmetic on them.

- The bank ramp may ask for more before it can quote. The answer then carries a **form step**, and you send what it asks with [Answer a Form Step](https://docs.aureahub.com/docs/payout-quote-step.md) until the quote is `ready`. This is a conversation, not one call.
- `quote.expiresAt` is the rate's deadline. After it the quote locks nothing and step 3 refuses it.
- The signed quote the bank ramp returns stays inside Aurea. You never see it and never need it.

## Step 3: Pay It From the Wallet

[Pay Out a Quote from Your Wallet](https://docs.aureahub.com/docs/payout-wallet-pay.md) binds the quote to a payout. You send three things: the `quoteId`, the `network` the deposit will travel on, and `source.walletId` — one of the user's Aurea wallets.

**The key decides, not the wallet's label.** An EVM wallet is a valid source on every EVM network, because it is the same key: a wallet created on Ethereum can send the deposit on `PolygonTestAmoy`. A Solana wallet sends on Solana networks. What a wallet may *not* do is send a deposit it cannot sign: a watch-only wallet is refused (`400` `NOAH_SOURCE_NOT_ALLOWED`, `reason` `watch_only`), because Aurea has no proof the user controls its key.

Send an `Idempotency-Key`. The bank ramp's rule carries no reference of its own, so asking twice would make two rules; with the key, a retry answers with the first payout and the bank ramp is not asked again.

## Step 4: Send the Deposit

The answer *is* the instruction. Four fields matter to the wallet:

- `deposit.address` — where to send.
- `deposit.amountUnits` — **exactly** how much, in the token's smallest unit. It is the number a transfer takes. `deposit.amount` is the same figure written for a person.
- `deposit.expiresAt` — when the deposit must have arrived. A deposit later than this is matched by no rule: the money leaves the user's wallet and no payout follows it. Show this deadline, and do not let a user start a transfer that cannot arrive in time.
- `deposit.uri` — the same transfer written the way the chain family writes one: **EIP-681** on EVM, **Solana Pay** on Solana. Hand it to the wallet and nobody retypes an amount. Wallets honour these unevenly, so **check the amount before signing** and treat `amountUnits` as the truth.

The deposit must come **from the source you named**. The bank ramp has nothing else to go on: there is no memo and no reference in the request, by design.

## Step 5: Follow It

[Get a Wallet Payout](https://docs.aureahub.com/docs/payout-wallet-get.md) and [List Wallet Payouts](https://docs.aureahub.com/docs/payout-wallet-list.md) answer where it is. `pending` is waiting for the deposit; `processing`, the deposit arrived and the bank ramp is paying; `completed`, the beneficiary has the money; `failed`, the bank ramp refused the rule; `expired`, no deposit came in time.

Do not poll for it: [Events to Your Server](https://docs.aureahub.com/docs/guide-events.md) posts your own record to your server whenever it changes, signed, and the user's device is notified when the payout completes or fails.

## When It Does Not Work

| Answer | What happened | What to do |
| --- | --- | --- |
| `409` `NOAH_QUOTE_NOT_LOCKED` | The quote cannot be paid: The bank ramp still asks a form step (`not_ready`), or a locked rate has passed (`expired`). A quote that locks no rate is paid by a rule, not refused | Finish the form, or ask for a new quote. Nothing was stored |
| `400` `NOAH_PAYOUT_AMOUNT_TOO_SMALL` | The quote pays the beneficiary nothing: the amount is below the channel's `cryptoLimits.min`, so its fixed fee takes it all, and the bank ramp prices it at zero instead of refusing it | Read `cryptoLimits.min` from [Search Channels](https://docs.aureahub.com/docs/payout-channels.md) and ask for a quote above it. Nothing was stored |
| `409` `NOAH_QUOTE_USED` | That quote already pays a payout — whatever its status. A quote pays one payout | Use `details.payoutId` to show the one that exists; a new payout needs a new quote |
| `409` `NOAH_PAYOUT_SOURCE_BUSY` | That address already has a payout waiting for a deposit of that currency on that network — **anywhere in Aurea**, not only in your tenant. The bank ramp matches by address, so two rules on one address would be ambiguous | Wait for the deposit or for the hold to end, or use another wallet. The same address on another network, or another currency, does not collide |
| `400` `NOAH_PAIR_UNAVAILABLE` | The quote's currency on that network is not a payout pair Aurea enables and your tenant offers | `details.available` names what is offered; the currency comes from the quote, so only the network is yours to choose |
| `403` `NOAH_MODE_OFF`, `mode` `aureaWallets` | Your tenant does not have the Aurea wallets mode | Ask the Aurea operator to switch it on, or pay from a proven address instead |
| `422` `NOAH_KYC_NOT_APPROVED` | The user's KYC is not approved in that environment | Send them through onboarding; the check happens before anything is stored |
| `502` `NOAH_UNEXPECTED_RESPONSE` with `outcome: "unknown"` | the bank ramp was asked once and its answer never arrived. A rule may or may not exist | **Do not retry.** Read the payout: Aurea repairs it on its own from what the bank ramp has, and the source stays held meanwhile |

## What Never Happens

- **Aurea never holds the money and never sends the deposit.** The user's wallet signs the transfer; there is no path in which Aurea moves it for them.
- **Aurea's own balance at the bank ramp is never what pays this.** A payout paid by a rule must move it by nothing at all, and an Aurea operator is told if it ever does.
- **The bank ramp is asked for the rule once.** Its trigger carries no reference, so a second attempt would make a second rule; when Aurea cannot tell what happened it keeps the payout and repairs it from what the bank ramp has.
- **Nothing of the user reaches a log.** Not the source address, not the deposit address, not the bank ramp's form session, not the signed quote.

---

Web version: https://docs.aureahub.com/#guide-wallet-payout