Withdraw Out Webhook

The merchant initiates a withdrawal: tokens move from the master address to an external destination address chosen by the merchant.

Read webhook-overview.md first for signature verification, retry policy, and the state machine common to all events.

When it fires

PIK detects an outbound on-chain transfer from a master address. Each merchant-initiated withdrawal request produces a fund event tied to a CustomerWithdrawal record.

Trigger condition	Notes
`fromAddress` ∈ PIK master addresses	Withdrawal source
Matching `CustomerWithdrawal` record exists	Identifies the withdrawal request

Event identifiers

Field	Value
`eventType`	`WITHDRAW_OUT`
`businessRefType`	`WITHDRAW`
`direction`	`OUT`

State machine

  PENDING ──── on-chain confirmed ────► CONFIRMED  (withdrawal complete)
     │
     └──────── reverted / rejected ──► FAILED

Status	When	Side effects
`PENDING`	Withdrawal transaction submitted to chain; balance has already been frozen/deducted when the request was placed	The internal `CustomerWithdrawal` record is in `SUCCESS` state (submitted), but on-chain confirmation pending
`CONFIRMED`	Sufficient confirmations	Withdrawal is final — funds have left the master
`FAILED`	Transaction reverted or pre-flight validation rejected the withdrawal	Frozen balance is returned to the merchant's available balance

Note: a withdrawal may also start in FAILED if the request was rejected synchronously (e.g., insufficient balance, validation error). In that case you receive a single FAILED webhook with no preceding PENDING.

Payload examples

`status = PENDING`

{
  "event": "transaction.created",
  "timestamp": 1738807200000,
  "data": {
    "fundEventCode": "FE20260206140000005",
    "paymentLinkName": null,
    "businessRefType": "WITHDRAW",
    "chain": "Ethereum",
    "tokenSymbol": "USDC",
    "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "txHash": "0xdddd444455556666dddd444455556666dddd444455556666dddd444455556666",
    "fromAddress": "0xMasterAddressAAAAMasterAddressAAAAMasterAA",
    "toAddress": "0xExternalDest1234567890ExternalDest1234567",
    "amount": 500.00,
    "direction": "OUT",
    "eventType": "WITHDRAW_OUT",
    "status": "PENDING",
    "createTimeUtc": "2026-02-06 14:00:00"
  }
}

`status = CONFIRMED`

{
  "event": "transaction.created",
  "timestamp": 1738807380000,
  "data": {
    "fundEventCode": "FE20260206140000005",
    "paymentLinkName": null,
    "businessRefType": "WITHDRAW",
    "chain": "Ethereum",
    "tokenSymbol": "USDC",
    "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "txHash": "0xdddd444455556666dddd444455556666dddd444455556666dddd444455556666",
    "fromAddress": "0xMasterAddressAAAAMasterAddressAAAAMasterAA",
    "toAddress": "0xExternalDest1234567890ExternalDest1234567",
    "amount": 500.00,
    "direction": "OUT",
    "eventType": "WITHDRAW_OUT",
    "status": "CONFIRMED",
    "createTimeUtc": "2026-02-06 14:00:00"
  }
}

`status = FAILED`

Note: when a withdrawal fails synchronously (rejected before chain submission), txHash may be absent or empty.

{
  "event": "transaction.created",
  "timestamp": 1738807440000,
  "data": {
    "fundEventCode": "FE20260206140000006",
    "paymentLinkName": null,
    "businessRefType": "WITHDRAW",
    "chain": "Ethereum",
    "tokenSymbol": "USDC",
    "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "txHash": "",
    "fromAddress": "0xMasterAddressAAAAMasterAddressAAAAMasterAA",
    "toAddress": "0xExternalDest1234567890ExternalDest1234567",
    "amount": 500.00,
    "direction": "OUT",
    "eventType": "WITHDRAW_OUT",
    "status": "FAILED",
    "createTimeUtc": "2026-02-06 14:01:00"
  }
}

Field notes specific to this event

Field	Notes
`paymentLinkName`	`null` — withdrawals are not tied to payment links
`fromAddress`	Merchant master address
`toAddress`	The external destination chosen by the merchant when initiating the withdrawal
`amount`	The net amount sent to the destination (post-gas-fee deduction)

Gas fee

For each withdrawal you may also receive a separate fund event with businessRefType = "GAS FEE" representing the gas-fee deduction. That event has its own fundEventCode and is delivered through the same webhook channel.

Recommended handler logic

1. Verify signature.
2. Look up local withdrawal record by fundEventCode.
3. Switch on status:
     PENDING   → mark "in flight". Show user "processing".
     CONFIRMED → mark "completed". Notify user.
     FAILED    → mark "failed". Frozen balance is auto-refunded by PIK;
                 reconcile your internal ledger.
4. Respond 200 within 5 seconds.

Funds withdrawn here must have first arrived in the master via MASTER_RECHARGE, WEB3_DIRECT_PAYMENT, or ORDER_COLLECT_OUT.

Withdraw Out Webhook

When it fires#

Event identifiers#

State machine#

Payload examples#

status = PENDING#

status = CONFIRMED#

status = FAILED#

Field notes specific to this event#

Gas fee#

Recommended handler logic#

Related events#