Payouts

A payout sends crypto from your Tender merchant balance to an external destination — either a raw wallet address or a saved payout account. Payouts are processed asynchronously and do not require an OTP or password. Every payout request needs an Idempotency-Key header so that a retry never sends funds twice. To pay out fiat to a bank account or through MoneyGram, see Fiat payouts.

How it works

Check the fee

Call GET /payout/fee/{chain}/{coin}/{amount} to see the fee and net amount before committing.

Submit the payout

Call POST /payout/crypto with an Idempotency-Key header, the coin, chain, amount, and either a wallet address or a saved payoutAccountId.

Poll for completion

Call GET /payout/{id} until status is completed or failed. There are no payout webhooks, so polling is the only way to track progress.

Prerequisites

Authentication guide

These endpoints use Signed (HMAC) authentication — an HMAC-SHA256 signature is required on every request. See the authentication guide for code examples.

const BASE = 'https://sandbox-api.tender.cash/v1/api';
// makeHeaders() → { 'x-access-id', 'x-request-id', 'x-timestamp', 'authorization', ... }

Step 1 — Check the fee

const feeRes = await fetch(
  `${BASE}/payout/fee/tron/usdt/50`,
  { headers: makeHeaders() }
);
const { data: fee } = await feeRes.json();
/*
{
  amount:            50,    // debited from your balance
  amountUSD:         50,
  fee:               0.5,
  feeUSD:            0.5,
  amountDeductedFee: 49.5,  // what the recipient receives
  amountAfterFee:    50.5,  // amount + fee (gross), not the amount delivered
  currency:          "usdt",
  chain:             "tron",
  estimatedArrival:  "1-3 minutes",
  ...
}
*/

fee_res = requests.get(
    f"{BASE}/payout/fee/tron/usdt/50",
    headers=make_headers(),
)
fee = fee_res.json()["data"]

Step 2 — Submit a payout to a wallet address

Generate a new Idempotency-Key for each payout, and store it with your own record before you send the request. If the request times out, retry with the same key and body: you get the original response back instead of a second payout. See Idempotency. The amount must be worth at least $20 USD. The fee is taken out of amount, so the recipient receives amount − fee.

const payoutRes = await fetch(`${BASE}/payout/crypto`, {
  method: 'POST',
  headers: { ...makeHeaders(), 'Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({
    coin:    'usdt',
    chain:   'tron',
    amount:  '50',
    address: 'TQn9Y2khDD9JHTfVE5oB2h8BKWWM4LxKLT',
  }),
});

const { data: payout } = await payoutRes.json();
const payoutId = payout._id;
console.log('Status:', payout.status); // "pending"

import uuid

payout_res = requests.post(
    f"{BASE}/payout/crypto",
    headers={**make_headers(), "Idempotency-Key": str(uuid.uuid4())},
    json={
        "coin":    "usdt",
        "chain":   "tron",
        "amount":  "50",
        "address": "TQn9Y2khDD9JHTfVE5oB2h8BKWWM4LxKLT",
    },
)
payout    = payout_res.json()["data"]
payout_id = payout["_id"]

Step 2 (alt) — Payout to a saved payout account

The saved account must be one of your active crypto payout accounts, on the same chain and coin as the payout. If you send both address and payoutAccountId, the saved account’s address is used.

const payoutRes = await fetch(`${BASE}/payout/crypto`, {
  method: 'POST',
  headers: { ...makeHeaders(), 'Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({
    coin:            'usdt',
    chain:           'tron',
    amount:          '50',
    payoutAccountId: '66aec7de809b7f45c42a49f9',
  }),
});

payout_res = requests.post(
    f"{BASE}/payout/crypto",
    headers={**make_headers(), "Idempotency-Key": str(uuid.uuid4())},
    json={
        "coin":            "usdt",
        "chain":           "tron",
        "amount":          "50",
        "payoutAccountId": "66aec7de809b7f45c42a49f9",
    },
)

Step 3 — Poll for completion

// Payout endpoints share 10 requests/minute, so poll every 10s or slower.
async function pollPayout(id, intervalMs = 15000) {
  while (true) {
    const res = await fetch(`${BASE}/payout/${id}`, { headers: makeHeaders() });
    const { data } = await res.json();

    console.log('Status:', data.status);

    if (data.status === 'completed') return data;
    if (data.status === 'failed') throw new Error('Payout failed');

    await new Promise(r => setTimeout(r, intervalMs));
  }
}

const result = await pollPayout(payoutId);

import time

# Payout endpoints share 10 requests/minute, so poll every 10s or slower.
def poll_payout(payout_id, interval_s=15):
    while True:
        res  = requests.get(f"{BASE}/payout/{payout_id}", headers=make_headers())
        data = res.json()["data"]

        print(f"Status: {data['status']}")

        if data["status"] == "completed":
            return data
        if data["status"] == "failed":
            raise RuntimeError("Payout failed")

        time.sleep(interval_s)

Tender doesn’t send webhooks for payouts. Poll GET /payout/{id} (or list recent payouts with GET /payout) to track status.

Payout status values

Status	Meaning
`pending`	Queued, not yet sent
`processing`	Handed to the network or payout provider
`completed`	Delivered; `txId` holds the on-chain transaction hash
`failed`	The payout did not go through

Error handling

Scenario	Action
Insufficient balance	Check your balance on that chain before submitting
`Minimum withdrawal amount is $20 USD`	Increase the amount; check `amountUSD` from the fee endpoint
Neither `address` nor `payoutAccountId` provided	Send at least one; omitting both returns 400
`Idempotency-Key header is required`	Add the header to every `POST /payout/crypto` request
HTTP 409 on retry	You reused a key with a different body, or the first request is still running. Retry the same body later, or use a new key for a new payout
HTTP 429	Payout endpoints share 10 requests/minute, and each `POST /payout/crypto` counts twice. See Rate limits
`status: "failed"`	Check your balance and the destination, then create a new payout with a new key, or contact support

Getting started

Online payments

Subwallets

Webhooks

How it works

Prerequisites

Authentication guide

Step 1 — Check the fee

Step 2 — Submit a payout to a wallet address

Step 2 (alt) — Payout to a saved payout account

Step 3 — Poll for completion

Payout status values

Error handling

​How it works

​Prerequisites

Authentication guide

​Step 1 — Check the fee

​Step 2 — Submit a payout to a wallet address

​Step 2 (alt) — Payout to a saved payout account

​Step 3 — Poll for completion

​Payout status values

​Error handling

How it works

Prerequisites

Step 1 — Check the fee

Step 2 — Submit a payout to a wallet address

Step 2 (alt) — Payout to a saved payout account

Step 3 — Poll for completion

Payout status values

Error handling