Drafting payout (Optional)

POST /api/public/v1/payouts/draft

Creates a payout draft and locks the exchange rate for 30 seconds. No funds move at this stage — the draft transitions to processing only after you call Confirming payout draft. If you do not confirm within 30 seconds, the draft expires and is automatically cancelled.

Use the draft flow when you want to show the user the exact amounts and rates before committing — for example, on a confirmation screen before the user clicks "Send".

Treat a confirmed draft as irreversible. Once you call the confirm endpoint, the payout is queued and cannot be recalled.

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 draft. If the recipient does not have a destination tag, pass 0:

rwCQVZLSMNY6DgMH61317qvH3nHYqm68PF?dt=0

Do not use dt=0 for wallets shared by multiple users such as exchange platforms or custodial wallets. Funds sent without a valid destination tag cannot be attributed to a specific account and may be permanently lost.

cURL

## Draft payout XRP

curl -X "POST" "https://api.sandbox.txn.io/api/public/v1/payouts/draft" \
     -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	No	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 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 (8–10 digits). Required for binance_pay payouts. Validate it first using the Validate Binance ID endpoint.

Response Body

Name	Type	Description
data.id	string	Payout draft ID.
data.type	string	Always payouts.
data.attributes.reference	string	Your internal correlation key, as set at creation.
data.attributes.status	string	Always draft. See Payout Status Flow.
data.attributes.address	string	Recipient's wallet address.
data.attributes.createdAt	string	ISO 8601 timestamp of when the draft was created.
data.attributes.expiresAt	string	ISO 8601 timestamp of when the draft expires. The rate lock is valid until this time — confirm within 30 seconds.
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. Always null for drafts — populated after the draft is confirmed and the transaction is sent.
data.attributes.payNetwork	string	Network code of the cryptocurrency sent. See Supported Currencies.
data.attributes.payNetworkName	string	Human-readable network name, e.g. Ripple.
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. 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": "6ecebf80-b210-413b-b396-df4760d142c5",
    "type": "payouts",
    "attributes": {
      "absorbFees": null,
      "absorbNetworkFee": false,
      "absorbPayoutFee": true,
      "address": "rLsBa2vWV2uuPx2UKbocAZG2WHXoaGyMPf?dt=61",
      "amount": "1000.00",
      "amountCharged": "22.70",
      "amountChargedCurrency": "USD",
      "approvalStatus": null,
      "binanceStatus": null,
      "createdAt": "2026-04-01T06:56:53.830Z",
      "currency": "TRY",
      "displayFee": "10.00",
      "displayFeeCurrency": "TRY",
      "exchangeRate": "62.3244527497791",
      "expiresAt": "2026-04-01T06:57:23.830Z",
      "networkFee": "1.000000",
      "networkFeeCurrency": "XRP",
      "payAmount": "15.045067",
      "payChargeRate": "1.4010781",
      "payChargeRateCurrency": "USD",
      "payCurrency": "XRP",
      "payNetwork": "txrp",
      "payNetworkName": "Ripple",
      "paymentMethod": "on_chain",
      "payoutFee": "0.22",
      "payoutFeeCurrency": "USD",
      "receiverBinanceId": null,
      "reference": "c533ca8f-63eb-4c0a-a784-4cdfc731ca31",
      "status": "draft",
      "txid": null
    },
    "relationships": {
      "accountCharged": {
        "data": {
          "id": "80b8dd61-35bc-49cc-9e04-f2c0f741a096",
          "type": "accounts"
        }
      },
      "author": {
        "data": {
          "id": "b56961f4-46cf-4e60-bb32-b36addb09f66",
          "type": "apiKeys"
        }
      }
    }
  },
  "included": [
    {
      "id": "80b8dd61-35bc-49cc-9e04-f2c0f741a096",
      "type": "accounts",
      "attributes": {
        "balance": "446.68",
        "bankDepositAvailable": true,
        "bankReference": "BDR3455470827278341",
        "bankWithdrawalAvailable": false,
        "currencyCode": "USD",
        "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

HTTP 422

HTTP 422

HTTP 422

HTTP 422

HTTP 422