Creating payout

POST /api/public/v1/payouts

This endpoint creates payouts.

It takes a few seconds to build and broadcast a transaction, so please expect some delay before a txId value appears. We advise polling the GET /api/public/v1/payouts/:id endpoint to monitor both the payout status and the txId.

Destination Tag Requirement for XRP Addresses:

XRP addresses require an additional parameter: a destination tag.

A destination tag functions similarly to a reference number in bank transfers, helping to identify the intended beneficiary of a transaction.

Important Notes:

• A destination tag cannot be left blank. Collect this tag from your customers before submitting a payout request to Txn

• If end-users do not specify a destination tag, use "0" by formatting the address as follows:

  rwCQVZLSMNY6DgMH61317qvH3nHYqm68PF?dt=0

Warning: If you enter "0" as the destination tag for a wallet shared by multiple users, e.g. online wallets or exchange platforms, the funds may be permanently lost.

cURL

## Create payout XRP

curl -X "POST" "https://api.sandbox.txn.pro/api/public/v1/payouts" \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Authorization: Bearer ' \
     -d $'{
  "data": {
    "type": "payouts",
    "attributes": {
      "reference": "b8ad764b-7951-4cbc-9a15-efa91d47fe4e",
      "amount": "2000",
      "currency": "TRY",
      "chargeCurrency": "EUR",
      "absorbFees": true,
      "address": "rLsBa2vWV2uuPx2UKbocAZG2WHXoaGyMPf?dt=61",
      "payNetwork": "txrp"
    }
  }
}'

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	The custom reference ID to tie the payout to end-user who gets paid. This can be anything you choose. Must be a unique value for each pyout you create.
data.attributes.amount	number	Yes	Payout amount. This is the amount that Txn will debit from your account on the Txn platform. Refer to Payout Limitations.
data.attributes.currency	string	Yes	Payout amount currency code. This is effectively the currency account which Txn will take the payout amount from. Refer to Supported Currencies.
data.attributes.chargeCurrency	string	No	Determines from which merchant's currency account the payout amount and fees should be taken. Refer to Supported Currencies. If omitted, the money will be taken from the data.attributes.currency account.
data.attributes.payNetwork	string	Yes	Refer to Supported Currencies.
data.attributes.address	string	Yes	Wallet address of a payout recipient.
absorbFees	boolean	No	If false or omitted, both service and network fees are deducted from the transaction amount. If true, both fees are deducted from your account balance.

Response Body

Name	Type	Description
data.id	string	Payout ID.
data.type	string	Aways payouts.
data.attributes.reference	string	The custom reference ID to tie the payout to end-user who gets paid. This can be anything you choose.
data.attributes.status	string	Payout status. Refer to Payout Status Flow.
data.attributes.address	string	Wallet address of a payout recipient.
data.attributes.createdAt	string	Payout creation timestamp.
data.attributes.absorbFees	boolean	If false or omitted, both service and network fees are deducted from the transaction amount. If true, both fees are deducted from your account balance.
data.attributes.amount	number	Payout amount.
data.attributes.currency	string	Payout amount currency code.
data.attributes.payCurrency	string	The code of a token or cryptocurrency transferred to the receiving address.
data.attributes.payAmount	string	The amount of tokens or cryptocurrency transferred to the receiving address.
data.attributes.txid	string	The token or cryptocurrency transaction hash. This is effectively a unique identifier of a transaction on a relevant blockchain. You can share it with the receipient as a proof of payment.
data.attributes.payNetwork	string	Refer to Supported Currencies.
data.attributes.networkName	string	Network name. E.g. Tron (TRC20).
data.attributes.networkFee	string	The network fee amount Txn took to cover blockchain fees.
data.attributes.networkFeeCurrency	string	Network fee currency.
data.attributes.payoutFee	string	Payout fee amount. This is the processing fee amount taken from the merchant's account.
data.attributes.payoutFeeCurrency	string	Payout fee currency.
data.attributes.displayFee	string	Fee associated with the payout represented in data.attributes.currency. For example, if the payout currency is TRY, the fee is also expressed in TRY.
data.attributes.displayFeeCurrency	string	Fee associated with the payout represented in data.attributes.currency. For example, if the payout currency is TRY, the fee is also expressed in TRY.
data.attributes.amountCharged	string	The amount deducted from the merchant's account.
data.attributes.amountChargedCurrency	string	The amount deducted from the merchant's account.
data.attributes.payChargeRate	string	Pay currency to charge currency exchange rate applied by Txn. E.g., XRP/EUR.
data.attributes.payChargeRateCurrency	string	Pay currency to charge currency exchange rate applied by Txn.
data.attributes.exchangeRate	string	Pay currency to currency exchange rate applied by Txn. E.g., XRP/TRY.

Response

HTTP 201

{
  "data": {
    "id": "9b4317e2-f369-4e00-9e65-6ee7d59667a4",
    "type": "payouts",
    "attributes": {
      "address": "rLsBa2vWV2uuPx2UKbocAZG2WHXoaGyMPf?dt=61",
      "expiresAt": "2025-01-31T09:48:01.580Z",
      "createdAt": "2025-01-31T09:47:31.580Z",
      "absorbFees": true,
      "reference": "c2b091dc-d140-44fc-a9de-58c405a67af3",
      "status": "processing",
      "amount": "2000.00",
      "currency": "TRY",
      "payCurrency": "XRP",
      "payAmount": "17.901661",
      "payNetwork": "txrp",
      "payNetworkName": "Ripple",
      "txid": null,
      "networkFee": "1.000000",
      "networkFeeCurrency": "XRP",
      "payoutFee": "0.54",
      "payoutFeeCurrency": "EUR",
      "displayFee": "20.00",
      "displayFeeCurrency": "TRY",
      "exchangeRate": "111.72147825",
      "amountCharged": "57.16",
      "amountChargedCurrency": "EUR",
      "payChargeRate": "2.99537619",
      "payChargeRateCurrency": "EUR"
    }
  },
  "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"
    }
  ]
}

// Invalid address format.

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.