Payments

Tender generates a unique deposit address for each payment request. Your customer sends the exact crypto amount to that address, Tender detects the on-chain transfer, and marks the transaction complete. No custodial account or key management is required on your side.

How it works

Initiate a payment

Call POST /payment/initiate with the fiat amount, the chain and the crypto currency. Tender returns a deposit walletAddress, the all-in crypto amount to collect, and a txId to track the payment.

Customer sends crypto

Display the walletAddress and exact amount to your customer. They send from their own wallet — any compatible wallet on that chain works.

Tender detects the transfer

Tender checks the address on-chain automatically and sends webhook events as the payment progresses.

Validate the payment

Call POST /payment/validate/{id} to check the payment on demand and read its current status.

Prerequisites

Authentication guide

Payment endpoints use Basic (Access ID) authentication — only your x-access-id header is required. See the authentication guide for details on both auth methods.

const BASE = 'https://sandbox-api.tender.cash/v1/api';
// makeHeaders() → { 'x-access-id': ACCESS_ID, 'Content-Type': 'application/json' }

Pricing: what `amount` means

amount is a fiat price, not a crypto amount:

On POST /payment/initiate, it is in your outlet’s default fiat currency (USD if none is set).
On POST /payment/initiate/{currency}, it is in the fiat currency named in the path, such as ngn.

Tender converts it to the chosen cryptocurrency and adds every fee on top (the receive fee, any activation fee, any auto-payout fees and, on Tron, the gasless network service fee). The response’s amount is the all-in crypto total the customer must send. To show the customer that total before creating a payment, call POST /payment/quote/{currency}. Its totalPayable matches what initiation charges.

Step 1 — Initiate a payment

const res = await fetch(`${BASE}/payment/initiate`, {
  method: 'POST',
  headers: makeHeaders(),
  body: JSON.stringify({
    amount:    '10.00',      // fiat, in the outlet's default currency
    chain:     'tron',
    currency:  'usdt',
    reference: 'ORDER-9821', // your own order ID, optional
    meta: { customerEmail: 'customer@example.com' }, // optional
  }),
});

const { data: payment } = await res.json();
/*
{
  txId:            "66aec7de809b7f45c42a49f9",
  walletAddress:   "TQn9Y2khDD9JHTfVE5oB2h8BKWWM4LxKLT",
  amount:          "10.15",      // all-in USDT the customer must send
  requestedAmount: "10.00",      // the fiat amount you asked for
  usdAmount:       "10.15",
  fee:             0.1,
  chain:           "tron",
  referenceId:     "ORDER-9821",
  ...
}
*/

const { txId, walletAddress, amount } = payment;

res = requests.post(
    f"{BASE}/payment/initiate",
    headers=make_headers(),
    json={
        "amount":    "10.00",   # fiat, in the outlet's default currency
        "chain":     "tron",
        "currency":  "usdt",
        "reference": "ORDER-9821",
        "meta":      {"customerEmail": "customer@example.com"},  # optional
    },
)
payment = res.json()["data"]
tx_id          = payment["txId"]
wallet_address = payment["walletAddress"]
amount         = payment["amount"]

A reference can be used by only one payment at a time. Reusing the reference of a payment that isn’t cancelled returns 409. See Initiate Payment for the full response and error list.

Step 2 — Show payment details to your customer

Display the deposit address, the network and the exact amount from the response.

Please send:

  10.15 USDT
  Network: Tron (TRC-20)
  To:      TQn9Y2khDD9JHTfVE5oB2h8BKWWM4LxKLT

  Do not send from an exchange. Use a self-custody wallet.

The walletAddress is unique to this transaction. Never reuse addresses across payments.

Step 3 — Poll for payment status

POST /payment/validate/{id} returns HTTP 202 with the payment once funds have arrived. Until then it returns HTTP 406 with the message Payment Not made yet. A 406 is not a failure: keep polling until your own checkout deadline.

async function pollPayment(txId, { intervalMs = 8000, timeoutMs = 30 * 60 * 1000 } = {}) {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/payment/validate/${txId}`, {
      method: 'POST',
      headers: makeHeaders(),
    });
    const body = await res.json();

    if (res.status === 202) {
      const { status, amountReceived, balanceRequired } = body.data;
      console.log('Status:', status, '| Received:', amountReceived);

      if (status === 'completed' || status === 'overpayment') return body.data;
      if (status === 'partial-payment') {
        console.log('Still owed:', balanceRequired); // keep polling for a top-up
      }
    } else if (res.status !== 406) {
      throw new Error(`Validate failed: ${res.status} ${body.message}`);
    }
    // 406 (e.g. "Payment Not made yet") → keep polling

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

  // Customer didn't pay in time: cancel the request
  await fetch(`${BASE}/payment/cancel/${txId}`, { method: 'POST', headers: makeHeaders() });
  return null;
}

const result = await pollPayment(txId);

import time

def poll_payment(tx_id, interval_s=8, timeout_s=30 * 60):
    deadline = time.time() + timeout_s

    while time.time() < deadline:
        res  = requests.post(f"{BASE}/payment/validate/{tx_id}", headers=make_headers())
        body = res.json()

        if res.status_code == 202:
            data = body["data"]
            print(f"Status: {data['status']} | Received: {data['amountReceived']}")

            if data["status"] in ("completed", "overpayment"):
                return data
            if data["status"] == "partial-payment":
                print(f"Still owed: {data['balanceRequired']}")  # keep polling for a top-up
        elif res.status_code != 406:
            raise RuntimeError(f"Validate failed: {res.status_code} {body['message']}")
        # 406 (e.g. "Payment Not made yet") → keep polling

        time.sleep(interval_s)

    # Customer didn't pay in time: cancel the request
    requests.post(f"{BASE}/payment/cancel/{tx_id}", headers=make_headers())
    return None

Use webhooks instead of polling for production. Register a webhook and Tender pushes transaction_completed, transaction_partially_paid, transaction_overpayment and the other payment events as they happen. See Webhooks.

Payment status values

Status	Meaning
`pending`	Address generated; awaiting the customer’s transfer
`reserved`	No payment arrived within about 2 hours. Tender keeps checking the address, less often; a payment that arrives still completes.
`partial-payment`	Some funds arrived, but less than the full amount
`completed`	The full amount arrived
`overpayment`	The customer paid more than the amount (by about $3 or more)
`cancelled`	The request was cancelled, by you or automatically after it went unpaid

completed and overpayment are final. A payment can only be cancelled through the API while it is pending.

Internal transactions

Some payments are settled in more than one step. A payment can be bridged to another chain, or converted as it settles, and each step is its own on-chain transaction. These transactions don’t appear in your payment list, because they belong to a payment you already see. To get them, with hashes and explorer links, call List Payment Internal Transactions with the payment’s txId:

`role`	Meaning
`bridge_deposit`	Funds sent into a bridge to move the payment to another chain
`bridge_settlement`	Funds received on the destination chain when the bridge completes
`conversion_send`	The on-chain send that funds a conversion
`conversion_settlement`	The transaction that credits the result of a conversion

Most payments have none and return an empty list.

Unpaid payments

Payments don’t fail. A request with no funds received moves from pending to reserved after about 2 hours, and Tender cancels it automatically once it has been unpaid for at least a day. The automatic cancellation doesn’t send a webhook. If your checkout has its own time limit, cancel the request yourself when it passes with POST /payment/cancel/{id}. Cancelling sends the transaction_cancelled webhook and frees the payment’s reference for reuse.

Partial payments and overpayments

If the customer sends less than the required amount (by $0.10 or more), the payment moves to partial-payment. A smaller shortfall is treated as completed. While a payment is partial-payment:

balanceRequired shows what is still owed. The customer can send the rest to the same address.
Tender keeps checking for 24 hours from the first partial payment. After that it accepts the partial amount as final: isFulfilled becomes true, fulfilledBy is expiry, and Tender sends the transaction_partial_fulfilled webhook. The status stays partial-payment.

If the customer sends noticeably more than required (about $3 or more over), the payment moves to overpayment.

Error handling

Scenario	Action
Validate returns 406 `Payment Not made yet`	Keep polling; no funds have arrived yet
Customer sends too little	Status is `partial-payment`; ask for `balanceRequired`, or wait for the partial to be accepted as final
Customer never pays	Cancel the request when your checkout times out, then initiate a new one if needed
Wrong network	Funds sent on the wrong chain can’t be recovered automatically — always display the network clearly
Initiate returns 409	A payment with the same `reference` already exists; validate or cancel it instead

Getting started

Online payments

Subwallets

Webhooks

How it works

Prerequisites

Authentication guide

Pricing: what `amount` means

Step 1 — Initiate a payment

Step 2 — Show payment details to your customer

Step 3 — Poll for payment status

Payment status values

Internal transactions

Unpaid payments

Partial payments and overpayments

Error handling

​How it works

​Prerequisites

Authentication guide

​Pricing: what amount means

​Step 1 — Initiate a payment

​Step 2 — Show payment details to your customer

​Step 3 — Poll for payment status

​Payment status values

​Internal transactions

​Unpaid payments

​Partial payments and overpayments

​Error handling

How it works

Prerequisites

Pricing: what `amount` means

Step 1 — Initiate a payment

Step 2 — Show payment details to your customer

Step 3 — Poll for payment status

Payment status values

Internal transactions

Unpaid payments

Partial payments and overpayments

Error handling