Webhook Events

Every webhook uses the envelope {"eventId": "...", "event": "...", "data": {...}}. This page describes data for each event. See Webhooks for registration, delivery and security.

Payloads list a stable public subset of fields. Additional fields may be present; ignore fields you don’t recognise. Monetary amounts are strings unless stated otherwise.

Supported events

Subscribe using these exact names (lowercase, case-sensitive). You can also fetch them from GET /v1/api/webhook/events.

Event	When it fires
`transaction_requested`	A payment was initiated.
`transaction_completed`	A payment was paid in full.
`transaction_overpayment`	A payment received more than the amount due.
`transaction_partially_paid`	A payment received less than the amount due. May repeat.
`transaction_partial_fulfilled`	A partially paid payment was accepted as final.
`transaction_cancelled`	A pending payment was cancelled.
`sub_user_wallet_transaction_detected`	A deposit to a subwallet address was detected. Repeats as confirmations rise.
`sub_user_wallet_transfer_confirmed`	An outgoing subwallet transfer was confirmed.
`sub_user_wallet_transfer_failed`	An outgoing gasless subwallet transfer failed.
`offramp_order_completed`	A dashboard off-ramp order completed.
`offramp_order_cancelled`	A dashboard off-ramp order was cancelled, declined or expired.
`offramp_order_failed`	A dashboard off-ramp order failed.

There are no webhooks for payouts, conversions or on-ramp orders created through the API. Poll GET /v1/api/payout/{id}, GET /v1/api/conversions/{id} and GET /v1/api/onramp/{reference} instead.

Payment events

transaction_requested

Fires when a payment is initiated through initiate payment or initiate payment by currency. data matches the initiate response, with IDs as strings.

Field	Description
`txId`	The payment ID. Use it to validate or cancel the payment.
`type`	Always `receive`.
`chain`	Chain ID, for example `tron`.
`chainId`, `currency`	IDs of the chain and currency records.
`amount`, `coinAmount`	Total the payer must send, in the payment currency, including fees.
`usdAmount`	`amount` in USD.
`requestedAmount`, `agentAmount`, `agentCurrency`	The amount you asked for, and its currency.
`fee`, `feeUSD`, `activationFee`, `activationFeeUSD`	Fees included in `amount`.
`rate`	USD price of one unit of the payment currency used for this payment.
`walletAddress`	The wallet’s controlling address.
`gasFreeAddress`	Present on gasless chains. When present, this is the address the payer must pay.
`contractAddress`	Token contract address, or empty for native coins.
`balanceRequired`, `balanceRequiredUSD`	Amount still outstanding (the full amount at this point).
`referenceId`	The reference you sent at initiation.
`agentId`, `merchantId`	IDs of the outlet and merchant.

{
  "eventId": "0d9c6a52-3f1e-4b7a-8a6e-2c5f9b1d7e40",
  "event": "transaction_requested",
  "data": {
    "txId": "66aec7de809b7f45c42a49f9",
    "type": "receive",
    "chain": "tron",
    "chainId": "6538e1b2bdec6d1a21978a10",
    "currency": "6538e1c4bdec6d1a21978a22",
    "amount": "10.15",
    "coinAmount": "10.15",
    "usdAmount": "10.15",
    "requestedAmount": "10",
    "agentAmount": "10",
    "agentCurrency": "USD",
    "fee": "0.15",
    "feeUSD": "0.15",
    "activationFee": "0",
    "activationFeeUSD": "0",
    "rate": 1,
    "walletAddress": "TQ5NmAqXwBvnDgC9bYVh7f3S9oYr4kJx2M",
    "gasFreeAddress": "TGx8kP3m9ZqLhW2vYcR7nB5tD1sF6aJ4uE",
    "contractAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "balanceRequired": "10.15",
    "balanceRequiredUSD": "10.15",
    "referenceId": "order-123",
    "agentId": "6538eaaebdec6d1a21978e6a",
    "merchantId": "6538e8f9bdec6d1a21978a64"
  }
}

Payment status events

transaction_completed, transaction_overpayment, transaction_partially_paid and transaction_partial_fulfilled all carry the same payment object, which is also what validate payment returns.

transaction_completed

Fires once, when the amount received reaches the amount due. status is completed.

transaction_overpayment

Fires once, when the payer sends more than the amount due. status is overpayment. Compare amountReceived with amount to find the excess.

transaction_partially_paid

Fires when a payment receives less than the amount due. status is partial-payment. The payment is re-checked periodically, so this event may repeat while the payment stays partially paid, with updated amountReceived and balanceRequired. If the balance arrives, you’ll receive transaction_completed or transaction_overpayment.

transaction_partial_fulfilled

Fires once, when a partially paid payment is accepted as final and no further funds are expected. This happens automatically 24 hours after the payment became partially paid, or earlier if Tender accepts it at your request. status stays partial-payment; isFulfilled is true, and fulfilledAt and fulfilledBy (expiry, merchant or admin) are set.

Payment object fields

Field	Description
`txId` (also `_id`)	The payment ID.
`type`	Always `receive`.
`status`	`completed`, `overpayment` or `partial-payment`.
`chain`	Chain ID, for example `ethereum`.
`chainId`	Chain object: `_id`, `id`, `name`, `coin`, `icon`, `explorer`, `chainType`.
`currency`	Currency object: `_id`, `id`, `name`, `symbol`, `icon`, `isContract`.
`walletAddress`	The address the payer paid (the gasless address on gasless chains).
`contractAddress`	Token contract address, or empty for native coins.
`amount`, `coinAmount`, `usdAmount`	The amount due, in the payment currency and in USD.
`amountReceived`, `amountReceivedUSD`	What has been received so far.
`balanceRequired`, `balanceRequiredUSD`	What is still outstanding. `"0"` once paid in full.
`agentAmount`, `agentCurrency`, `agentRate`, `amountReceivedAgent`, `balanceRequiredAgent`	The same amounts in the outlet’s currency.
`fee`, `feeUSD`, `activationFee`, `activationFeeUSD`	Fees charged on this payment.
`feeBreakdown`	`{ settlement, charged: { receive, activation, autoPayoutSwap, autoPayoutWithdrawal, gasFreeService, totalCoin, totalUSD } }`. Each charged leg is `{ coin, usd }`.
`rate`	USD price of one unit of the payment currency.
`isPartialPayment`, `partialPaymentAt`	Whether the payment was ever partially paid, and when.
`isFulfilled`, `fulfilledAt`, `fulfilledBy`	Whether the payment is final (fully paid or a partial accepted as final).
`referenceId`	The reference you sent at initiation.
`agentId`	Outlet object: `_id`, `name`, `email`, `phoneNumber`, `country`.
`merchantId`	Merchant object: `_id`, `merchantName`, `email`.
`createdAt`, `updatedAt`	ISO 8601 timestamps.

{
  "eventId": "b3c1f7a2-5d4e-4f8a-9c2b-6e1d0a7f3b94",
  "event": "transaction_completed",
  "data": {
    "_id": "66aec7de809b7f45c42a49f9",
    "txId": "66aec7de809b7f45c42a49f9",
    "type": "receive",
    "status": "completed",
    "chain": "ethereum",
    "chainId": {
      "_id": "6538e1b2bdec6d1a21978a11",
      "id": "ethereum",
      "name": "Ethereum",
      "coin": "ETH",
      "icon": "https://assets.tender.cash/chains/ethereum.png",
      "explorer": "https://etherscan.io",
      "chainType": "EVM"
    },
    "currency": {
      "_id": "6538e1c4bdec6d1a21978a23",
      "id": "usdt",
      "name": "Tether USD",
      "symbol": "USDT",
      "icon": "https://assets.tender.cash/coins/usdt.png",
      "isContract": true
    },
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
    "contractAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
    "amount": "10.15",
    "coinAmount": "10.15",
    "usdAmount": "10.15",
    "amountReceived": "10.15",
    "amountReceivedUSD": "10.15",
    "balanceRequired": "0",
    "balanceRequiredUSD": "0",
    "agentAmount": "10",
    "agentCurrency": "USD",
    "agentRate": "1",
    "amountReceivedAgent": "10",
    "balanceRequiredAgent": "0",
    "fee": "0.15",
    "feeUSD": "0.15",
    "activationFee": "0",
    "activationFeeUSD": "0",
    "feeBreakdown": {
      "settlement": "pending",
      "charged": {
        "receive": { "coin": "0.15", "usd": 0.15 },
        "activation": { "coin": "0", "usd": 0 },
        "autoPayoutSwap": { "coin": "0", "usd": 0 },
        "autoPayoutWithdrawal": { "coin": "0", "usd": 0 },
        "gasFreeService": { "coin": "0", "usd": 0 },
        "totalCoin": "0.15",
        "totalUSD": 0.15
      }
    },
    "rate": "1",
    "isPartialPayment": false,
    "partialPaymentAt": null,
    "isFulfilled": true,
    "fulfilledAt": null,
    "fulfilledBy": null,
    "referenceId": "order-123",
    "agentId": {
      "_id": "6538eaaebdec6d1a21978e6a",
      "name": "Lagos Store",
      "email": "store@example.com",
      "phoneNumber": "+2348012345678",
      "country": "Nigeria"
    },
    "merchantId": {
      "_id": "6538e8f9bdec6d1a21978a64",
      "merchantName": "Example Ltd",
      "email": "owner@example.com"
    },
    "createdAt": "2026-10-15T09:00:00.000Z",
    "updatedAt": "2026-10-15T09:04:12.000Z"
  }
}

A transaction_partially_paid payload has the same shape, for example with "status": "partial-payment", "isPartialPayment": true, "amountReceived": "5" and "balanceRequired": "5.15".

transaction_cancelled

Fires when a pending payment is cancelled, for example with cancel payment. Cancelling an already-cancelled payment doesn’t send it again.

Field	Description
`txId`	The payment ID.
`status`	Always `cancelled`.
`referenceId`	The reference you sent at initiation, or `""`.
`amount`, `usdAmount`	The amount that was due.
`chain`	Chain ID.
`walletAddress`	The wallet’s controlling address.
`cancelledAt`	ISO 8601 timestamp.

{
  "eventId": "6f2e9d14-8c3b-4a57-b0e1-9d4c2a7f5e31",
  "event": "transaction_cancelled",
  "data": {
    "txId": "66aec7de809b7f45c42a49f9",
    "status": "cancelled",
    "referenceId": "order-123",
    "amount": "10.15",
    "usdAmount": "10.15",
    "chain": "ethereum",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
    "cancelledAt": "2026-10-15T09:00:00.000Z"
  }
}

Subwallet events

sub_user_wallet_transaction_detected

Fires when a deposit to one of your subwallet addresses is detected on-chain, and again each time its confirmation count changes. Deduplicate on depositKey, and credit the deposit only once confirmed is true.

Field	Description
`depositKey`	Unique ID of the deposit: `<chainId>:<txHash>:<index>`.
`transactionId`	Tender’s ID for the deposit record.
`walletReference`, `addressReference`	The references you gave the wallet and address. `addressReference` may be `null`.
`addressId`	ID of the receiving address record.
`chainId`	Chain the deposit arrived on.
`network`	Network family of the address, for example `EVM`.
`symbol`	Asset symbol, for example `USDT`.
`address`	The receiving address.
`txHash`, `index`	Transaction hash, and the transfer’s index within it.
`amount`	Amount in the asset’s smallest unit, as a string. Divide by 10^`decimals`.
`decimals`	Decimals for `amount`.
`confirmed`	`true` once the deposit has `confirmationsRequired` confirmations.
`blockNumber`, `confirmations`, `confirmationsRequired`	Confirmation progress.
`occurredAt`	ISO 8601 timestamp.

{
  "eventId": "a51c3e07-92d4-4b6f-8e1a-7c0d5f2b9e68",
  "event": "sub_user_wallet_transaction_detected",
  "data": {
    "depositKey": "ethereum:0xabc123…def:0",
    "transactionId": "671e0f2a9b3c4d5e6f708192",
    "walletReference": "user-8821",
    "addressReference": "slot-2",
    "addressId": "671e0a119b3c4d5e6f708150",
    "chainId": "ethereum",
    "network": "EVM",
    "symbol": "USDT",
    "address": "0x5aE1c2b3D4e5F60718293A4b5C6d7E8f90a1B2c3",
    "txHash": "0xabc123…def",
    "index": 0,
    "amount": "1000000",
    "decimals": 6,
    "confirmed": false,
    "blockNumber": 21034567,
    "confirmations": 1,
    "confirmationsRequired": 12,
    "occurredAt": "2026-10-15T09:00:00Z"
  }
}

sub_user_wallet_transfer_confirmed

Fires once when an outgoing subwallet transfer is confirmed.

Field	Description
`transactionId`	Tender’s ID for the outgoing transfer.
`transferKey`	The transaction hash for on-chain transfers, or the operation ID for gasless transfers.
`txHash`	Transaction hash. On gasless transfers it may be empty if the hash isn’t known.
`walletReference`, `addressReference`	References of the sending wallet and address.
`network`	Network family, for example `EVM`.
`type`	`coin` (native coin) or `asset` (token).
`sender`, `receiver`	Sending and receiving addresses.
`amount`	Amount sent, as given in the transfer request.
`asset`	Asset symbol, or `null`.
`paymentReference`	The `payment_reference` you sent with the transfer.
`blockNumber`	On-chain transfers only.
`operationId`, `status`	Gasless transfers only. `status` is the final operation status, for example `succeeded`.

On-chain transfer:

{
  "eventId": "3e7b1c90-4f2a-4d8e-a6b5-1c9f0e2d7a43",
  "event": "sub_user_wallet_transfer_confirmed",
  "data": {
    "transactionId": "671e1b4c9b3c4d5e6f7081a0",
    "txHash": "0x9f8e7d…c2b1",
    "transferKey": "0x9f8e7d…c2b1",
    "walletReference": "user-8821",
    "addressReference": "slot-2",
    "network": "EVM",
    "type": "asset",
    "sender": "0x5aE1c2b3D4e5F60718293A4b5C6d7E8f90a1B2c3",
    "receiver": "0x8bC9d0E1f2A3b4C5d6E7f8091a2B3c4D5e6F7a8B",
    "amount": "10",
    "asset": "USDT",
    "paymentReference": "withdrawal-5521",
    "blockNumber": 21034890
  }
}

Gasless transfer:

{
  "eventId": "c8a2f0e5-1b7d-4e39-9a64-5d3b2c1e0f87",
  "event": "sub_user_wallet_transfer_confirmed",
  "data": {
    "transactionId": "671e1b4c9b3c4d5e6f7081a1",
    "txHash": "a1b2c3…e9f0",
    "transferKey": "op_01J9Z6Q4V7XK3M2N8P5R",
    "operationId": "op_01J9Z6Q4V7XK3M2N8P5R",
    "status": "succeeded",
    "walletReference": "user-8821",
    "addressReference": "slot-1",
    "network": "TRON",
    "type": "asset",
    "sender": "TGx8kP3m9ZqLhW2vYcR7nB5tD1sF6aJ4uE",
    "receiver": "TQ5NmAqXwBvnDgC9bYVh7f3S9oYr4kJx2M",
    "amount": "25",
    "asset": "USDT",
    "paymentReference": "withdrawal-5522"
  }
}

sub_user_wallet_transfer_failed

Fires once when an outgoing gasless subwallet transfer ends in failure. The payload matches the gasless sub_user_wallet_transfer_confirmed payload, with "status": "failed". txHash is usually empty.

{
  "eventId": "e1f4a7b2-6c3d-4e58-8b90-2a1d7c6e5f34",
  "event": "sub_user_wallet_transfer_failed",
  "data": {
    "transactionId": "671e1b4c9b3c4d5e6f7081a2",
    "txHash": "",
    "transferKey": "op_01J9Z7B2C4D6E8F0G1H3",
    "operationId": "op_01J9Z7B2C4D6E8F0G1H3",
    "status": "failed",
    "walletReference": "user-8821",
    "addressReference": "slot-1",
    "network": "TRON",
    "type": "asset",
    "sender": "TGx8kP3m9ZqLhW2vYcR7nB5tD1sF6aJ4uE",
    "receiver": "TQ5NmAqXwBvnDgC9bYVh7f3S9oYr4kJx2M",
    "amount": "25",
    "asset": "USDT",
    "paymentReference": "withdrawal-5523"
  }
}

Off-ramp order events

offramp_order_completed, offramp_order_cancelled and offramp_order_failed are sent for off-ramp orders created in the Tender merchant dashboard (selling crypto to a bank account through Tender’s off-ramp partner). They aren’t sent for API payouts.

Event	When it fires	`status`
`offramp_order_completed`	The order completed and the fiat was paid out.	`complete`
`offramp_order_cancelled`	The order was cancelled, declined or expired.	`cancelled`, `declined` or `expired`
`offramp_order_failed`	The order failed.	`failed`

Field	Description
`banxaOrderId`	The off-ramp partner’s order ID.
`status`	The order’s new status (see the table above).
`order`	The order record as it was before this update. Its `status`, `txHash` and fee fields can be out of date; use the top-level `status`.
`order._id`, `order.banxaOrderId`, `order.orderType`	Order identifiers. `orderType` is `SELL`.
`order.crypto`, `order.blockchain`, `order.cryptoAmount`	The crypto sold.
`order.fiat`, `order.fiatAmount`	The fiat paid out.
`order.txHash`	Hash of the crypto transfer, once known.
`order.processingFee`, `order.networkFee`	Fees, once known.
`order.withdrawalId`	The related withdrawal record, if any.
`order.createdAt`, `order.updatedAt`	ISO 8601 timestamps.

{
  "eventId": "9b0d2e4f-7a1c-4f63-8e25-c4b6a8d0f1e2",
  "event": "offramp_order_completed",
  "data": {
    "banxaOrderId": "a7c3e9f1b2d4",
    "status": "complete",
    "order": {
      "_id": "671e2c5d9b3c4d5e6f7081b3",
      "banxaOrderId": "a7c3e9f1b2d4",
      "orderType": "SELL",
      "status": "inProgress",
      "crypto": "USDT",
      "blockchain": "TRON",
      "cryptoAmount": "500",
      "fiat": "USD",
      "fiatAmount": "492.50",
      "txHash": "b4c5d6…a9f0",
      "processingFee": "5.00",
      "networkFee": "2.50",
      "withdrawalId": "671e2c4a9b3c4d5e6f7081b2",
      "createdAt": "2026-10-15T08:30:00.000Z",
      "updatedAt": "2026-10-15T08:52:10.000Z"
    }
  }
}

Reserved event names

GET /v1/api/webhook/events also returns transaction_reserved. It is reserved and not currently sent; subscribing to it has no effect.

Getting started

Online payments

Subwallets

Webhooks

Supported events

Payment events

transaction_requested

Payment status events

transaction_completed

transaction_overpayment

transaction_partially_paid

transaction_partial_fulfilled

Payment object fields

transaction_cancelled

Subwallet events

sub_user_wallet_transaction_detected

sub_user_wallet_transfer_confirmed

sub_user_wallet_transfer_failed

Off-ramp order events

Reserved event names

​Supported events

​Payment events

​transaction_requested

​Payment status events

​transaction_completed

​transaction_overpayment

​transaction_partially_paid

​transaction_partial_fulfilled

​Payment object fields

​transaction_cancelled

​Subwallet events

​sub_user_wallet_transaction_detected

​sub_user_wallet_transfer_confirmed

​sub_user_wallet_transfer_failed

​Off-ramp order events

​Reserved event names

Supported events

Payment events

transaction_requested

Payment status events

transaction_completed

transaction_overpayment

transaction_partially_paid

transaction_partial_fulfilled

Payment object fields

transaction_cancelled

Subwallet events

sub_user_wallet_transaction_detected

sub_user_wallet_transfer_confirmed

sub_user_wallet_transfer_failed

Off-ramp order events

Reserved event names