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.
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.
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:
Case 2
absorbPayoutFee = false and absorbNetworkFee = false
Both fees are deducted from the payout amount. The recipient receives less cryptocurrency.
Formula:
Case 3
absorbPayoutFee = true and absorbNetworkFee = false
The merchant absorbs the payout fee. The network fee is deducted from the recipient's amount.
Formula:
Case 4
absorbPayoutFee = false and absorbNetworkFee = true
The payout fee is deducted from the recipient's amount. The merchant absorbs the network fee.
Formula:
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:
absorbPayoutFee
absorbNetworkFee
Who pays payout fee
Who pays network fee
amountCharged
paidAmount
true
true
Merchant (account balance)
Merchant (account balance)
payoutAmount + payoutFee + networkFee * rate
payoutAmount / rate
false
false
Recipient (deducted from payout)
Recipient (deducted from crypto)
payoutAmount
(payoutAmount - payoutFee) / rate - networkFee
true
false
Merchant (account balance)
Recipient (deducted from crypto)
payoutAmount + payoutFee
payoutAmount / rate - networkFee
false
true
Recipient (deducted from payout)
Merchant (account balance)
payoutAmount + networkFee * rate
(payoutAmount - payoutFee) / rate
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 matcheschargeCurrency)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:
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 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 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 endpoint:
Collect the wallet address from your user.
Call Validate Address to confirm it is correctly formatted and not flagged.
Call Create Payout 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.
Last updated