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.

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.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. This is the amount that Txn debited from your account on the Txn platform.
data.attributes.currency	string	Payout amount currency code. This is effectively the currency account which Txn took the payout amount from.
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 Txn's processing fee.
data.attributes.payoutFeeCurrency	string	Payout fee currency.
data.attributes.exchangeRate	string	Exchange rate.

Response

HTTP 201

{
  "data": {
    "id": "c03bc7ec-8cf8-449c-9ba5-660364970682",
    "type": "payouts",
    "attributes": {
      "address": "TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe",
      "createdAt": "2024-07-30T15:32:15.287Z",
      "absorbFees": false,
      "reference": "e8fd9254-dba4-448e-a537-4a670d720855",
      "status": "processing",
      "amount": "50.00",
      "currency": "USD",
      "payCurrency": "TRX",
      "payAmount": "363.663665",
      "payNetwork": "ttrx",
      "payNetworkName": "Tron",
      "txid": null,
      "networkFee": "2.000000",
      "networkFeeCurrency": "TRX",
      "payoutFee": "0.50",
      "payoutFeeCurrency": "USD",
      "exchangeRate": "0.1353703"
    }
  },
  "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.