The merchant (or any third party) deposits tokens directly to the master address without going through a payment link. Typical use case: the merchant tops up their own PIK wallet from an exchange or external wallet.Read webhook-overview.md first for signature verification, retry policy, and the state machine common to all events.
When it fires#
PIK detects an incoming on-chain transfer to a master address, AND the transaction hash does not match any open payment link order (which is what distinguishes it from WEB3_DIRECT_PAYMENT).| Trigger condition | Notes |
|---|
toAddress ∈ PIK master addresses | |
fromAddress ∉ PIK order pool | Not a sweep |
txHash does not match any pre-recorded payment transaction | No payment link involved |
Event identifiers#
| Field | Value |
|---|
eventType | MASTER_RECHARGE |
businessRefType | PAYMENT |
direction | IN |
State machine#
PENDING ──── on-chain confirmed ────► CONFIRMED (balance credited)
│
└──────── reverted ─────────────► FAILED
| Status | When | Side effects |
|---|
PENDING | First on-chain detection of the inbound transfer | None visible to merchant balance yet |
CONFIRMED | Sufficient confirmations reached | Funds added to the master available balance |
FAILED | Transaction reverted | No balance change |
Payload examples#
status = PENDING#
{
"event": "transaction.created",
"timestamp": 1738800000000,
"data": {
"fundEventCode": "FE20260206120000003",
"paymentLinkName": null,
"businessRefType": "PAYMENT",
"chain": "Tron",
"tokenSymbol": "USDT",
"tokenAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"txHash": "trxabc123def456trxabc123def456trxabc123def456trxabc123def456abcd",
"fromAddress": "TPzZkjy6CqkSjUKjy7gw1AHQ4G7Wt8z1MyPay",
"toAddress": "TMasterAddressBBBBMasterAddressBBBBMasterB",
"amount": 5000.00,
"direction": "IN",
"eventType": "MASTER_RECHARGE",
"status": "PENDING",
"createTimeUtc": "2026-02-06 12:00:00"
}
}
status = CONFIRMED#
{
"event": "transaction.created",
"timestamp": 1738800180000,
"data": {
"fundEventCode": "FE20260206120000003",
"paymentLinkName": null,
"businessRefType": "PAYMENT",
"chain": "Tron",
"tokenSymbol": "USDT",
"tokenAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"txHash": "trxabc123def456trxabc123def456trxabc123def456trxabc123def456abcd",
"fromAddress": "TPzZkjy6CqkSjUKjy7gw1AHQ4G7Wt8z1MyPay",
"toAddress": "TMasterAddressBBBBMasterAddressBBBBMasterB",
"amount": 5000.00,
"direction": "IN",
"eventType": "MASTER_RECHARGE",
"status": "CONFIRMED",
"createTimeUtc": "2026-02-06 12:00:00"
}
}
status = FAILED#
{
"event": "transaction.created",
"timestamp": 1738800240000,
"data": {
"fundEventCode": "FE20260206120000003",
"paymentLinkName": null,
"businessRefType": "PAYMENT",
"chain": "Tron",
"tokenSymbol": "USDT",
"tokenAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"txHash": "trxabc123def456trxabc123def456trxabc123def456trxabc123def456abcd",
"fromAddress": "TPzZkjy6CqkSjUKjy7gw1AHQ4G7Wt8z1MyPay",
"toAddress": "TMasterAddressBBBBMasterAddressBBBBMasterB",
"amount": 5000.00,
"direction": "IN",
"eventType": "MASTER_RECHARGE",
"status": "FAILED",
"createTimeUtc": "2026-02-06 12:00:00"
}
}
Field notes specific to this event#
| Field | Notes |
|---|
paymentLinkName | Always null — no payment link involved |
toAddress | The merchant master address |
fromAddress | Whoever initiated the deposit (often the merchant's exchange withdrawal address) |
Recommended handler logic#
1. Verify signature.
2. Look up the deposit by fundEventCode (idempotency).
3. Switch on status:
PENDING → record the inbound deposit, optionally notify finance team.
CONFIRMED → reconcile balance, fire any internal "deposit available" hooks.
FAILED → mark as failed and investigate.
4. Respond 200 within 5 seconds.
MASTER_RECHARGE does not produce a follow-up ORDER_COLLECT_OUT event because the funds already landed in the master address. Modified at 2026-05-25 08:36:02
