Payouts

Payouts are withdrawals or payments to customers, partners, etc.

List Payouts

This endpoint retrieves all payouts. Endpoint uses pagination and returns 25 payouts per page. Payouts are sorted by creation time in descending order.

HTTP Request

GET /v1/payouts/

Query Parameters

Parameter	Default	Description
p	None	Page number.
txid	None	Filter payouts by `txid`.
address	None	Filter payouts by recipient address.
reference_id	None	Filter payouts by `reference_id`.
profile_id	None	Filter payouts by Profile ID.

pythonjavascript

python

payouts = uniwire_api_request('/v1/payouts/')

javascript

uniwire_api_request('/v1/payouts/').then(function (response) {
    console.log(response);
}).catch(function (error) {
    console.log(error);
});

Get Payout

This endpoint retrieves a specific payout.

HTTP Request

GET /v1/payouts/<ID>/

URL Parameters

Parameter	Description
ID	The ID of the payout to retrieve.

pythonjavascript

python

payout = uniwire_api_request('/v1/payouts/42dbee1d-8659-44c3-aab2-6e414c5825a5/')

javascript

uniwire_api_request('/v1/payouts/42dbee1d-8659-44c3-aab2-6e414c5825a5/').then(function (response) {
    console.log(response);
}).catch(function (error) {
    console.log(error);
});

Create Payout

This endpoint creates a payout. Response is identical to Get Payout endpoint response.

HTTP Request

POST /v1/payouts/

Payload Parameters

Parameter	Description	Required
kind	Available Values Special kind values: `BTC_LIGHTNING_TO_BTC` – Lightning Network to On-Chain. `BTC_LIGHTNING_TO_LIGHTNING` – Lightning Network to Lightning Network payout.	Yes
profile_id	Profile ID for settings, callbacks and wallet selection if `wallet_id` not specified.	Yes
wallet_id	Wallet ID for funds selection. If not specified, default profile wallet is used.	No
passthrough	String. Meta-data you wish to store with the payout. If provided and no `reference_id` is specified, must be a unique value to avoid accidental duplicate payouts. Will be sent alongside all callbacks associated with the payout.	No
reference_id	String. Unique reference ID. Field is being indexed and is useful for lookups. If provided must be a unique value to avoid accidental duplicate payouts. Will be sent alongside all callbacks associated with the payout.	No
recipients	Array/list of recipient objects.	Yes
network_fee_pays	Who pays network fee. Available values: `merchant` (default) or `recipient`. In case of `recipient` value network fee will be deducted from first recipient.	No
network_fee_preset	Network fee preset. Available values: `high`, `normal` (default) , `economy`.	No
network_fee	Custom network fee in satoshi/byte. Integer.	No
estimate_only	Boolean. Will perform full checks and estimations, but without final execution.	No

Recipient Object Parameters

Parameter	Description	Required
amount	Quoted decimal payment amount. Optional for `BTC_LIGHTNING_TO_LIGHTNING` kind.	Yes
currency	Currency for the specified payment amount. Available values: BTC, LTC, ETH, TRX, SOL, POL, XRP, DOGE, TUSD, USDC, PAX, GUSD, BUSD, WBNB, SAND, DAI, SHIB, L-BTC, L-USDT, USD, EUR, GBP, AUD, CAD, CHF, ZAR, NOK, NZD, MXN, CLP, KRW, JPY, PLN, DKK, SEK, ARS, KES.	Yes
address	Address of the recipient. For `BTC_LIGHTNING_TO_LIGHTNING` this can be either a BOLT11 payment request (e.g. `lntb...`) or an LNURL (e.g. `LNURL1...`) optionally with `lightning:` prefix. Ripple X-address format is also supported as `address` field.	Yes
fee_amount	Custom fee amount that will be deducted from "received" amount.	No
fee_currency	Custom fee currency. Available values: Same values as for `currency` field.	No
destination_tag	Only for `XRP` and `TON` kind.	No
notes	Any internal notes. Use `memo:` prefix to send chain level message (ETH, BSC and TON only).	No
exchange_rate_limit	Object. Enables comparison and validation between provided exchange rates and Uniwire exchange rates. Rejects request if difference is greater than what is specified in `allowed_difference` field. Full specification of `exchange_rate_limit` object see here	No

pythonjavascript

python

import json

payload = {
  "profile_id": "e4e197bf-486d-4f57-a064-2d047c6cafae",
  "kind": "BTC",
  "passthrough": json.dumps({"user_id": 123}),
  "reference_id": "unique-payout-id-123",
  "recipients": [
    {
      "amount": "20",
      "currency": "USD",
      "address": "2N38koyyonVDAZJRV4GwnuFPxcGTymzn9HQ",
      "notes": "Notes 1"
    },
    {
      "amount": "10",
      "currency": "GBP",
      "address": "2MzCZNNDrmUB55LzdXnmdaXH2h2nJJ9EhrL",
      "notes": "Notes 2"
    },
    {
      "amount": "0.01",
      "currency": "BTC",
      "address": "2NC3zgngjjRWR7kbKzKYYPR2jpWh3QZHRML",
      "notes": "Notes 3"
    }
  ]
}
payout = uniwire_api_request('/v1/payouts/', payload, 'POST')
print(json.dumps(payout, indent=2))

javascript

var payload = {
  "profile_id": "e4e197bf-486d-4f57-a064-2d047c6cafae",
  "kind": "BTC",
  "passthrough": JSON.stringify({"user_id": 123}),
  "reference_id": "unique-payout-id-123",
  "recipients": [
    {
      "amount": "20",
      "currency": "USD",
      "address": "2N38koyyonVDAZJRV4GwnuFPxcGTymzn9HQ",
      "notes": "Notes 1"
    },
    {
      "amount": "10",
      "currency": "GBP",
      "address": "2MzCZNNDrmUB55LzdXnmdaXH2h2nJJ9EhrL",
      "notes": "Notes 2"
    },
    {
      "amount": "0.01",
      "currency": "BTC",
      "address": "2NC3zgngjjRWR7kbKzKYYPR2jpWh3QZHRML",
      "notes": "Notes 3"
    }
  ]
}

uniwire_api_request('/v1/payouts/', payload, 'POST').then(function (response) {
    console.log(response);
}).catch(function (error) {
    console.log(error);
});

JSON response for Create Payout endpoint:

json

{
  "result": {
    "id": "2f065e32-8b11-4081-b302-57f9f9dbd2e4",
    "kind": "BTC",
    "txid": "7efa4998d0b6d62c13154e53bed0b6c5283c73ac5412ce09c2ac437be031fb9d",
    "created_at": "2019-02-11T03:04:51.113794+00:00",
    "approved_at": "2019-02-11T03:05:15.110291+00:00",
    "executed_at": "2019-02-11T03:05:15.110291+00:00",
    "profile_id": "e4e197bf-486d-4f57-a064-2d047c6cafae",
    "wallet_id": "9ebdef36-71dd-4fdf-b02d-e5f836b4052f",
    "confirmations": 0,
    "status": "new",
    "network": "testnet",
    "amount": {
      "total": "0.01901596",
      "network_fee": "0.00001000"
    },
    "network_fee_pays": "merchant",
    "network_fee_preset": "normal",
    "network_fee": 5,
    "passthrough": "{\"user_id\": 123}",
    "reference_id": "unique-payout-id-123",
    "sub_kind": null,
    "error": null,
    "recipients": [
      {
        "id": "912c9225-eb7f-4697-a5ab-7d28acfb9168",
        "address": "2N38koyyonVDAZJRV4GwnuFPxcGTymzn9HQ",
        "amount": {
          "requested": {
            "amount": "20.00000000",
            "currency": "USD"
          },
          "received": {
            "amount": "0.00546744",
            "currency": "BTC"
          }
        },
        "custom_fee": null,
        "notes": "Notes 1"
      },
      {
        "id": "d49d2ef4-6613-4870-9fcf-6becce855761",
        "address": "2MzCZNNDrmUB55LzdXnmdaXH2h2nJJ9EhrL",
        "amount": {
          "requested": {
            "amount": "10.00000000",
            "currency": "GBP"
          },
          "received": {
            "amount": "0.00353852",
            "currency": "BTC"
          }
        },
        "custom_fee": null,
        "notes": "Notes 2"
      },
      {
        "id": "b827813f-389e-457e-81c5-13cd1cf49d27",
        "address": "2NC3zgngjjRWR7kbKzKYYPR2jpWh3QZHRML",
        "amount": {
          "requested": {
            "amount": "0.01000000",
            "currency": "BTC"
          },
          "received": {
            "amount": "0.01000000",
            "currency": "BTC"
          }
        },
        "custom_fee": null,
        "notes": "Notes 3"
      }
    ]
  }
}

Estimate Payout

To validate a payout and preview fees without executing it, use the estimate_only payload parameter. This feature should be used responsibly, as the payout process can be resource-intensive and may block real payout queue to prevent double-spending.

How to Use

When creating a payout, include "estimate_only": true in the payload. This triggers all standard checks, such as account balance and fee calculation, without processing the payout.

Response

The response includes estimated network fees. These fees are not guaranteed, as they fluctuate in real-time and may vary if larger UTXOs are spent concurrently. The estimate should be accurate if the actual payout is executed soon after.

Use Case

Use this feature to display estimated network fees at the final withdrawal stage, after the user enters the address and amount.

Approve or Reject Payout

This endpoint approves or rejects a payout draft. API key must have special "Approve" permissions. Response is identical to Get Payout endpoint response where the status field should be new now. If rejected status should be rejected.

API Keys with "Approve" permissions can only approve or reject payout drafts and can never create payouts. API Keys with limited "Max Payout" amount, can never approve payout drafts – separate keys are required for approving payout drafts.

HTTP Request

PUT https://api.uniwire.com/v1/payouts/<ID>/

Payload Parameters

Parameter	Description	Required
approve	Boolean. Allowed values: `true` or `false`	Yes

pythonjavascript

python

import json

payload = {
  "approve": True
}
payout = uniwire_api_request('/v1/payouts/42dbee1d-8659-44c3-aab2-6e414c5825a5', payload, 'PUT')
print(json.dumps(payout, indent=2))

javascript

var payload = {
  "approve": true
}

uniwire_api_request('/v1/payouts/42dbee1d-8659-44c3-aab2-6e414c5825a5', payload, 'PUT').then(function (response) {
    console.log(response);
}).catch(function (error) {
    console.log(error);
});

JSON response for Approve Payout endpoint:

json

{
  "result": {
    "id": "2f065e32-8b11-4081-b302-57f9f9dbd2e4",
    "status": "new",
    # ... [rest of the payout object]
  }
}

Payout Confirmations

This endpoint returns confirmations for specified payout ID(s).

HTTP Request

POST /v1/payouts/confirmations/

Payload Parameters

Parameter	Description	Required
id	Array/list of payout ID.	Yes

pythonjavascript

python

import json

payload = {
  "id": [
    "9094fefe-3ac2-49b3-99ec-9b719331316c",
    "47ad5fa7-0754-4ba8-bc2d-1cdd0dbcddaa"
  ]
}
confirmations = uniwire_api_request('/v1/payouts/confirmations/', payload, 'POST')
print(json.dumps(confirmations, indent=2))

javascript

var payload = {
  "id": [
    "9094fefe-3ac2-49b3-99ec-9b719331316c",
    "47ad5fa7-0754-4ba8-bc2d-1cdd0dbcddaa"
  ]
}

uniwire_api_request('/v1/payouts/confirmations/', payload, 'POST').then(function (response) {
    console.log(response);
}).catch(function (error) {
    console.log(error);
});

The above command returns JSON structured like this:

json

{
  "result": [
    {
      "id": "9094fefe-3ac2-49b3-99ec-9b719331316c",
      "confirmations": 2
    },
      {
        "id": "47ad5fa7-0754-4ba8-bc2d-1cdd0dbcddaa",
        "confirmations": 7
      }
  ]
}

Resend Payout Callback

This endpoint manually resends the last callback for a specific payout. Useful when the original callback failed or needs to be resent.

HTTP Request

POST /v1/payouts/<ID>/resend-callback/

URL Parameters

Parameter	Description
ID	The ID of the payout to resend callback for.

Response Fields

Parameter	Description
status	Callback status: `success`, `error`, or `pending`
message	Human-readable message describing the result
error	Error type if status is `error` (e.g., `no_profile_or_callback_url`, `callback_failed`, `exception_occurred`)
response	Callback response details if available (contains last HTTP response from callback URL)

pythonjavascript

python

callback_result = uniwire_api_request('/v1/payouts/42dbee1d-8659-44c3-aab2-6e414c5825a5/resend-callback/', {}, 'POST')

javascript

uniwire_api_request('/v1/payouts/42dbee1d-8659-44c3-aab2-6e414c5825a5/resend-callback/', {}, 'POST').then(function(response) {
  console.log(response);
}).catch(function(error) {
  console.log(error);
});

The above command returns JSON structured like this:

json

{
  "status": "success",
  "message": "Callback sent successfully",
  "response": {
    "status_code": 200,
    "url": "https://example.com/callback"
  }
}

Payout Statuses

Status	Description
draft	Either payout was created manually in the app and is not yet approved or payout was made by an API, but the payout amount was larger than "Max Payout" value for current API key - in such case requires manual approval in the app.
scheduled	Payout is scheduled to be executed at certain time.
queued	Payout is queued as part of a larger batch (TON network only).
new	Payout is just created and is awaiting further processing.
pending	Payout transaction is broadcast on the Bitcoin network (0 confirmations).
confirmed	Payout transaction is included in the first block (1 confirmation).
complete	Payout transaction has 6+ confirmations.
rejected	Payout draft requiring approval has been rejected through API.
unconfirmed	Payout have been unconfirmed for more that 24h.
awaiting_funds	Payout is using "reserve wallet" functionality and is awaiting for funds to be converted and added to wallet balance.
awaiting_policies	Payout is awaiting payout policies to be complete - for example extra signatures, etc.

Payout Callbacks

Callbacks provide same exact response format as in Get Payout API endpoint in result field plus three extra fields specified in Callbacks Documentation.

You can view history of callbacks (if any) in Uniwire in Payout detail view.

Payout Callback Statuses

Status	Description
payout_pending	Payment transaction is broadcast on the Bitcoin network (0 confirmations).
payout_confirmed	Payout transaction is included in the first block (1 confirmation).
payout_complete	Payout transaction has 6+ confirmations.
payout_failed	Payout has failed.
payout_rejected	Payout has been rejected manually or through API.

Important!

INFO

Note: Due to asynchronous nature of creating payouts, on certain chains final network fee can only be determined after broadcast, make sure to update fields like amount.network_fee from callback data.

Important

Never assume that a payout might have been processed successfully if the response error is nonspecific or if the request fails due to network issues like a Gateway Timeout. In such cases, it is risky to assume that the entire payout failed. Only return the deducted funds to the user when the error message explicitly indicates a failure.

Payouts ​

List Payouts ​

HTTP Request ​

Query Parameters ​

Get Payout ​

HTTP Request ​

URL Parameters ​

Create Payout ​

HTTP Request ​

Payload Parameters ​

Recipient Object Parameters ​

Estimate Payout ​

How to Use ​

Response ​

Use Case ​

Approve or Reject Payout ​

HTTP Request ​

Payload Parameters ​

Payout Confirmations ​

HTTP Request ​

Payload Parameters ​

Resend Payout Callback ​

HTTP Request ​

URL Parameters ​

Response Fields ​

Payout Statuses ​

Payout Callbacks ​

Payout Callback Statuses ​

Important! ​

Payouts

List Payouts

HTTP Request

Query Parameters

Get Payout

HTTP Request

URL Parameters

Create Payout

HTTP Request

Payload Parameters

Recipient Object Parameters

Estimate Payout

How to Use

Response

Use Case

Approve or Reject Payout

HTTP Request

Payload Parameters

Payout Confirmations

HTTP Request

Payload Parameters

Resend Payout Callback

HTTP Request

URL Parameters

Response Fields

Payout Statuses

Payout Callbacks

Payout Callback Statuses

Important!