# Payouts concept

## General

Payouts let you send cryptocurrency from your Txn account to an external wallet. Each payout request is processed immediately — Txn broadcasts the transaction to the relevant blockchain network as soon as the request is accepted, rather than batching multiple requests together.

{% hint style="danger" %}
**Treat every successfully submitted payout request as irreversible.** Once the API accepts your request, the transaction is queued for broadcast and cannot be recalled. Validate recipient addresses before submitting, especially in production.
{% endhint %}

You can fund payouts from either a fiat or cryptocurrency account balance. Each payout requires the amount, currency, payment network, and recipient wallet address.

### Reference

Every payout accepts a `reference` field — your internal correlation key. Set it to your order ID, user ID, or any value that lets you match the payout back to a record in your system. The `reference` is returned on every read response and webhook event, making it the primary hook for reconciliation.

## Fees

Two fees apply when sending a payout:

* The **payout fee** is the platform fee Txn charges for the service.
* The **network fee** covers blockchain transaction costs. Txn does not control miner fees; network fee settings are updated periodically to track the average fee required for next-block inclusion. Expect network fees to change without prior notice.

Use the `absorbPayoutFee` and `absorbNetworkFee` boolean parameters in your payout request to control how each fee is handled:

* **Absorbed by the merchant** — deducted from your account balance.
* **Deducted from the payout amount** — reduces the cryptocurrency amount the recipient receives.

### Examples

In the formulas below, variable names map to API response fields as follows: `payoutAmount` → `amount`, `paidAmount` → `payAmount`, `rate` → `exchangeRate`.

#### Case 1

`absorbPayoutFee = true` and `absorbNetworkFee = true`

Both fees are absorbed by the merchant. The recipient receives the full intended amount.

Formula:

```ini
amountCharged = payoutAmount + payoutFee + networkFee * rate
paidAmount = payoutAmount / rate
```

#### Case 2

`absorbPayoutFee = false` and `absorbNetworkFee = false`

Both fees are deducted from the payout amount. The recipient receives less cryptocurrency.

Formula:

```ini
amountCharged = payoutAmount
paidAmount = (payoutAmount - payoutFee) / rate - networkFee
```

#### Case 3

`absorbPayoutFee = true` and `absorbNetworkFee = false`

The merchant absorbs the payout fee. The network fee is deducted from the recipient's amount.

Formula:

```ini
amountCharged = payoutAmount + payoutFee
paidAmount = payoutAmount / rate - networkFee
```

#### Case 4

`absorbPayoutFee = false` and `absorbNetworkFee = true`

The payout fee is deducted from the recipient's amount. The merchant absorbs the network fee.

Formula:

```ini
amountCharged = payoutAmount + networkFee * rate
paidAmount = (payoutAmount - payoutFee) / rate
```

Test your fee configuration in the Sandbox environment before going live. Cross-check `amountCharged`, `payAmount`, `payoutFee`, and `networkFee` in the response against your expected values to ensure your reconciliation flows handle all cases correctly.

The table below summarises all four combinations:

<table data-header-hidden data-full-width="true"><thead><tr><th></th><th></th><th></th><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>absorbPayoutFee</strong></td><td><strong>absorbNetworkFee</strong></td><td><strong>Who pays payout fee</strong></td><td><strong>Who pays network fee</strong></td><td><strong>amountCharged</strong></td><td><strong>paidAmount</strong></td></tr><tr><td><strong>true</strong></td><td><strong>true</strong></td><td>Merchant (account balance)</td><td>Merchant (account balance)</td><td><code>payoutAmount + payoutFee + networkFee * rate</code></td><td><code>payoutAmount / rate</code></td></tr><tr><td><strong>false</strong></td><td><strong>false</strong></td><td>Recipient (deducted from payout)</td><td>Recipient (deducted from crypto)</td><td><code>payoutAmount</code></td><td><code>(payoutAmount - payoutFee) / rate - networkFee</code></td></tr><tr><td><strong>true</strong></td><td><strong>false</strong></td><td>Merchant (account balance)</td><td>Recipient (deducted from crypto)</td><td><code>payoutAmount + payoutFee</code></td><td><code>payoutAmount / rate - networkFee</code></td></tr><tr><td><strong>false</strong></td><td><strong>true</strong></td><td>Recipient (deducted from payout)</td><td>Merchant (account balance)</td><td><code>payoutAmount + networkFee * rate</code></td><td><code>(payoutAmount - payoutFee) / rate</code></td></tr></tbody></table>

## Display currency and charge currency

By default, `currency` also determines which of your Txn account balances is debited. A 100 EUR payout debits your EUR account.

Setting `chargeCurrency` decouples these: you can denominate the payout in one currency while funding it from a different account. This is common when paying recipients who expect amounts quoted in a local currency — such as CNY — while your Txn account holds EUR or another tradable currency.

When `chargeCurrency` is set, three distinct currencies can appear in the response:

* **`currency`** — the display currency the payout is denominated in (e.g. CNY)
* **`amountChargedCurrency`** — the currency debited from your account (e.g. EUR, always matches `chargeCurrency`)
* **`payCurrency`** — the cryptocurrency sent to the recipient (e.g. USDT)

**Example:** 500 CNY display amount, EUR account debited, USDT sent via Tron — both fees absorbed by the merchant:

| Field           | Value      | Currency     |
| --------------- | ---------- | ------------ |
| `amount`        | 500.00     | CNY          |
| `payAmount`     | 71.297671  | USDT         |
| `amountCharged` | 64.84      | EUR          |
| `payoutFee`     | 0.63       | EUR          |
| `networkFee`    | 1.000000   | USDT         |
| `displayFee`    | 5.00       | CNY          |
| `exchangeRate`  | 7.01285182 | CNY per USDT |
| `payChargeRate` | 0.8881381  | EUR per USDT |

`displayFee` is the payout fee re-expressed in `currency` for display to the recipient. `exchangeRate` converts between `currency` and `payCurrency`; `payChargeRate` converts between `payCurrency` and `amountChargedCurrency`.

## Payout status

Payouts move through the following statuses: **processing** → **completed** (or **cancelled**). When using the optional draft flow, a **draft** status precedes processing.

A payout in **processing** has been accepted and is in flight — the transaction is being prepared and broadcast, or has been broadcast and is awaiting its first blockchain confirmation. **completed** means the transaction has received at least one on-chain confirmation. See [Payout Status Flow](/payouts/payout-status-flow.md) for the full reference.

## Payout limits

Contact Txn support for the minimum and maximum payout amounts per currency.

## Payment methods

Payouts support two payment methods, set via the `paymentMethod` parameter:

* **`on_chain`** (default) — sends cryptocurrency directly to the recipient's wallet address on-chain.
* **`binance_pay`** — routes the payment off-chain through Binance Pay. Requires the recipient's Binance ID instead of a wallet address. Validate the Binance ID using the [Validate Binance ID](/payouts/validating-recipients-binance-id.md) endpoint before submitting the payout request.

## Address validation

Txn automatically validates the recipient wallet address format and screens it against sanctions and high-risk wallet lists on every payout request. An invalid or flagged address causes the request to be rejected immediately.

For production integrations, validate addresses before submitting a payout request using the [Validate Address](/payouts/validating-addresses.md) endpoint:

1. Collect the wallet address from your user.
2. Call [Validate Address](/payouts/validating-addresses.md) to confirm it is correctly formatted and not flagged.
3. Call [Create Payout](/payouts/creating-payout.md) with the validated address.

This approach catches problems before they reach the payout itself, giving you a clean error surface and avoiding failed payout attempts.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.txn.io/payouts/payouts-concept.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.