Creating payout

POST /api/public/v1/payouts

Creates a payout and immediately queues it for broadcast on the specified network. The response always returns status: processing. The txid field is null on creation and is populated once the transaction is sent — poll Read Payout to track progress.

Treat a successful response as irreversible. Once the API accepts the request, the payout is queued and cannot be recalled.

Address and network must match

address must be the recipient's address for the network in payNetwork, exactly as shown in their wallet or exchange. The API checks that the address is well-formed for the network, but it cannot tell whether the recipient's wallet actually issued that address for that network.

This matters most for Tron and EVM networks (Ethereum, BNB Smart Chain, Polygon), which share the same key material. A 0x Ethereum-style address is also a valid encoding of a Tron address, so a 0x address submitted with trx:usdt is accepted and the funds are sent to the Tron form of that address (T...). The recipient's Ethereum wallet or exchange does not monitor that Tron address, and Txn cannot recall the funds.

Never convert an address between network formats. Check the prefix before you submit: Tron addresses start with T, EVM addresses start with 0x. If the prefix does not match payNetwork, ask the recipient for the correct address. Run Validate Address first and see Expected address format by network for the full list.

XRP destination tag

XRP payouts require a destination tag appended to the wallet address as address?dt=tag. The destination tag identifies the specific recipient within a shared XRP wallet — without it, the funds cannot be attributed to the correct account.

Collect the destination tag from your recipient before creating the payout. If the recipient does not have a destination tag, pass 0:

rwCQVZLSMNY6DgMH61317qvH3nHYqm68PF?dt=0

Funds sent without a valid destination tag cannot be attributed to a specific account and may be permanently lost.

cURL

## Create payout XRP

curl -X "POST" "https://api.sandbox.txn.io/api/public/v1/payouts" \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Authorization: Bearer <api_key>' \
     -d $'{
  "data": {
    "type": "payouts",
    "attributes": {
      "reference": "b8ad764b-7951-4cbc-9a15-efa91d47fe4e",
      "amount": "1000",
      "currency": "TRY",
      "chargeCurrency": "EUR",
      "accountChargedId": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "absorbPayoutFee": true,
      "absorbNetworkFee": false,
      "address": "rLsBa2vWV2uuPx2UKbocAZG2WHXoaGyMPf?dt=61",
      "payNetwork": "txrp",
      "paymentMethod": "on_chain",
    }
  }
}'

Headers

Name	Value
Content-Type	application/vnd.api+json
Authorization	Bearer <api_key>

Request Body

Name	Type	Required	Description
data.type	string	Yes	Can only be payouts.
data.attributes.reference	string	No	Your internal correlation key for this payout — use your order ID, user ID, or any value that lets you match this payout to a record in your system. Must be unique per payout.
data.attributes.amount	number	Yes	Payout amount in currency. Contact Txn support for minimum and maximum values per currency.
data.attributes.currency	string	Yes	Currency of the payout amount. When chargeCurrency is omitted, also determines which of your Txn account balances is debited. See Supported Currencies.
data.attributes.chargeCurrency	string	No	Specifies from which merchant's currency account the payout amount and fees should be taken. Can be any tradable fiat or cryptocurrency listed on the Supported currencies page — display fiat currencies are not accepted. If omitted, defaults to the data.attributes.currency account; in that case currency must itself be a tradable fiat or cryptocurrency, otherwise chargeCurrency must be supplied.
data.attributes.accountChargedId	string		ID of the account to debit the payout from. Can be a master or subaccount ID. Defaults to your master account. Requires chargeCurrency.
data.attributes.payNetwork	string	Yes	Network code for the cryptocurrency to send. See Supported Currencies.
data.attributes.address	string	Yes	Recipient's wallet address for payNetwork, exactly as shown in the recipient's wallet or exchange for that network. Do not convert between formats: a 0x address is not rejected on Tron but the funds will not reach the recipient. See Address and network must match. For XRP, include the destination tag as address?dt=tag.
data.attributes.absorbFees	boolean	No	Deprecated. Use absorbPayoutFee and absorbNetworkFee instead.
data.attributes.absorbPayoutFee	boolean	No	If false or omitted, the payout fee is deducted from the amount the recipient receives. If true, the fee is charged to your account balance instead.
data.attributes.absorbNetworkFee	boolean	No	If false or omitted, the network fee is deducted from the amount the recipient receives. If true, the fee is charged to your account balance instead.
data.attributes.paymentMethod	string	No	on_chain sends cryptocurrency directly to the recipient's wallet. binance_pay routes the payment off-chain through Binance Pay and requires receiverBinanceId. Defaults to on_chain.
data.attributes.receiverBinanceId	string	No	Recipient's Binance ID (7 or more digits). Required for binance_pay payouts. Validate it first using the Validate Binance ID endpoint.

Response Body

Name	Type	Description
data.id	string	Payout ID.
data.type	string	Always payouts.
data.attributes.reference	string	Your internal correlation key, as set at creation.
data.attributes.status	string	Payout status. Refer to Payout Status Flow.
data.attributes.address	string	Recipient's wallet address.
data.attributes.createdAt	string	ISO 8601 timestamp of when the payout was created.
data.attributes.expiresAt	string	ISO 8601 timestamp of when the exchange rate lock expires.
data.attributes.absorbFees	boolean	Deprecated. Use absorbPayoutFee and absorbNetworkFee instead.
data.attributes.absorbPayoutFee	boolean	If false, the payout fee was deducted from the amount the recipient received. If true, the fee was charged to your account balance.
data.attributes.absorbNetworkFee	boolean	If false, the network fee was deducted from the amount the recipient received. If true, the fee was charged to your account balance.
data.attributes.amount	number	Payout amount in currency.
data.attributes.currency	string	Payout amount currency code.
data.attributes.payCurrency	string	Currency code of the cryptocurrency sent to the recipient.
data.attributes.payAmount	string	Amount of cryptocurrency sent to the recipient.
data.attributes.txid	string	On-chain transaction hash. Share with the recipient as proof of payment.
data.attributes.payNetwork	string	Network code of the cryptocurrency sent. See Supported Currencies.
data.attributes.payNetworkName	string	Human-readable network name, e.g. Tron.
data.attributes.networkFee	string	Network fee amount in networkFeeCurrency.
data.attributes.networkFeeCurrency	string	Currency of the network fee.
data.attributes.payoutFee	string	Txn service fee amount in payoutFeeCurrency.
data.attributes.payoutFeeCurrency	string	Currency of the Txn service fee.
data.attributes.displayFee	string	Payout fee expressed in currency.
data.attributes.displayFeeCurrency	string	Currency of displayFee. Always matches currency.
data.attributes.amountCharged	string	Total amount debited from your account, including all fees, in amountChargedCurrency.
data.attributes.amountChargedCurrency	string	Currency of amountCharged. Matches chargeCurrency.
data.attributes.payChargeRate	string	Exchange rate between payCurrency and amountChargedCurrency applied by Txn.
data.attributes.payChargeRateCurrency	string	Quote currency of payChargeRate.
data.attributes.exchangeRate	string	Exchange rate between payCurrency and currency applied by Txn.
data.attributes.paymentMethod	string	Payment method used: on_chain or binance_pay.
data.attributes.receiverBinanceId	string	Recipient's Binance ID. Present only for binance_pay payouts.
data.attributes.approvalStatus	string	Approval workflow status. Present only for dashboard-initiated payouts subject to an approval rule. Always null for API-created payouts.
data.attributes.binanceStatus	string	Binance Pay processing status. Present only for binance_pay payouts.

Response

HTTP 201

{
  "data": {
    "id": "20d3a6a7-e3ed-402b-b786-19d50a9b607a",
    "type": "payouts",
    "attributes": {
      "absorbFees": null,
      "absorbNetworkFee": true,
      "absorbPayoutFee": true,
      "address": "TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe",
      "amount": "50.00",
      "amountCharged": "51.39",
      "amountChargedCurrency": "EUR",
      "approvalStatus": null,
      "binanceStatus": null,
      "createdAt": "2026-05-15T18:45:39.275Z",
      "currency": "EUR",
      "displayFee": "0.50",
      "displayFeeCurrency": "EUR",
      "exchangeRate": "0.8866755",
      "expiresAt": "2026-05-15T18:46:09.275Z",
      "networkFee": "1.000000",
      "networkFeeCurrency": "USDT",
      "payAmount": "56.390416",
      "payChargeRate": "0.8866755",
      "payChargeRateCurrency": "EUR",
      "payCurrency": "USDT",
      "payNetwork": "ttrx:usdt",
      "payNetworkName": "Tron (TRC20)",
      "paymentMethod": "on_chain",
      "payoutFee": "0.50",
      "payoutFeeCurrency": "EUR",
      "receiverBinanceId": null,
      "reference": "70327e5f-9a3e-4720-b2e4-e899fcbbb956",
      "status": "processing",
      "txid": null
    },
    "relationships": {
      "accountCharged": {
        "data": {
          "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
          "type": "accounts"
        }
      },
      "author": {
        "data": {
          "id": "3cd066e3-94f7-4182-a242-bf3b4e8ea2da",
          "type": "apiKeys"
        }
      }
    }
  },
  "included": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "balance": "39207.72",
        "bankDepositAvailable": true,
        "bankReference": "BDR6421088115176062",
        "bankWithdrawalAvailable": true,
        "currencyCode": "EUR",
        "currencyType": "fiat",
        "label": "master",
        "master": true,
        "totalBalance": null,
        "transferAvailable": true
      },
      "relationships": {
        "company": { "meta": { "included": false } },
        "networks": { "meta": { "included": false } },
        "txnBankCredentials": { "meta": { "included": false } }
      }
    },
    {
      "id": "3cd066e3-94f7-4182-a242-bf3b4e8ea2da",
      "type": "apiKeys",
      "attributes": {
        "createdAt": "2026-05-07T10:39:48.046Z",
        "name": "My API Key"
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}

HTTP 201 (with chargeCurrency)

500 CNY display amount, EUR account debited, USDT sent via Tron. currency, amountChargedCurrency, and payCurrency are all different.

{
  "data": {
    "id": "9d12fe2c-c8ac-44c7-b2f0-b9d11aa62f53",
    "type": "payouts",
    "attributes": {
      "absorbFees": null,
      "absorbNetworkFee": true,
      "absorbPayoutFee": true,
      "address": "TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe",
      "amount": "500.00",
      "amountCharged": "64.84",
      "amountChargedCurrency": "EUR",
      "approvalStatus": null,
      "binanceStatus": null,
      "createdAt": "2026-05-19T15:40:37.788Z",
      "currency": "CNY",
      "displayFee": "5.00",
      "displayFeeCurrency": "CNY",
      "exchangeRate": "7.01285182",
      "expiresAt": "2026-05-19T15:41:07.788Z",
      "networkFee": "1.000000",
      "networkFeeCurrency": "USDT",
      "payAmount": "71.297671",
      "payChargeRate": "0.8881381",
      "payChargeRateCurrency": "EUR",
      "payCurrency": "USDT",
      "paymentMethod": "on_chain",
      "payNetwork": "ttrx:usdt",
      "payNetworkName": "Tron (TRC20)",
      "payoutFee": "0.63",
      "payoutFeeCurrency": "EUR",
      "receiverBinanceId": null,
      "reference": "docs-cny-eur-example-001",
      "status": "processing",
      "txid": null
    },
    "relationships": {
      "accountCharged": {
        "data": {
          "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
          "type": "accounts"
        }
      },
      "author": {
        "data": {
          "id": "b56961f4-46cf-4e60-bb32-b36addb09f66",
          "type": "apiKeys"
        }
      }
    }
  },
  "included": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "balance": "38968.92",
        "bankDepositAvailable": true,
        "bankReference": "BDR6421088115176062",
        "bankWithdrawalAvailable": true,
        "currencyCode": "EUR",
        "currencyType": "fiat",
        "label": "master",
        "master": true,
        "totalBalance": null,
        "transferAvailable": true
      },
      "relationships": {
        "company": { "meta": { "included": false } },
        "networks": { "meta": { "included": false } },
        "txnBankCredentials": { "meta": { "included": false } }
      }
    },
    {
      "id": "b56961f4-46cf-4e60-bb32-b36addb09f66",
      "type": "apiKeys",
      "attributes": {
        "createdAt": "2024-06-17T19:41:33.398Z",
        "name": "Test API key"
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}

HTTP 422

{
  "errors": [
    {
      "status": 422,
      "title": "amount is below minimum",
      "detail": "amount: 10.0, minimum: 50.00",
      "code": "amount_below_minimum"
    }
  ]
}

Amount too low.

HTTP 422

{
  "errors": [
    {
      "status": 422,
      "title": "amount is above maximum",
      "detail": "amount: 500000.0, maximum: 100000.00",
      "code": "amount_above_maximum"
    }
  ]
}

Amount too high.

HTTP 422

{
  "errors": [
    {
      "status": 422,
      "title": "Invalid address",
      "code": "invalid_address"
    }
  ]
}

Address is not a valid address on payNetwork. Not every mismatch is caught: an address in another network's format is only rejected when that format is not also valid on payNetwork. See Address and network must match.

HTTP 422

{
  "errors": [
    {
      "status": 422,
      "title": "Invalid attribute",
      "detail": "Reference has already been taken",
      "code": "payout_invalid",
      "source": {
        "pointer": "/data/attributes/externalId"
      }
    }
  ]
}

Duplicate reference.

HTTP 422

{
  "errors": [
    {
      "status": 422,
      "title": "account has insufficient balance",
      "code": "account_has_insufficient_balance"
    }
  ]
}

Your source account has insufficient funds.

HTTP 422

{
  "errors": [
    {
      "status": 422,
      "title": "We couldn’t send funds to this address, please try another address",
      "code": "address_has_high_risk_score"
    }
  ]
}

Destination wallet address risk profile is too high.