Customer Refund Webhook

The merchant issues a refund: tokens are sent from a per-link order address back to the original payer (or a designated refund destination).

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 an order address to a destination that is not a master address. This signals the refund flow rather than a collection sweep.

Trigger condition	Notes
`fromAddress` ∈ PIK order pool	Refund originates from the per-link order address
`toAddress` ∉ PIK master addresses	Distinguishes refund from `ORDER_COLLECT_OUT`

Event identifiers

Field	Value
`eventType`	`CUSTOMER_REFUND`
`businessRefType`	`REFUND`
`direction`	`OUT`

State machine

  PENDING ──── on-chain confirmed ────► CONFIRMED  (refund delivered)
     │
     └──────── reverted ─────────────► FAILED

Status	When	Side effects
`PENDING`	Refund transaction submitted and detected on-chain	Internal refund record marked in-progress
`CONFIRMED`	Sufficient confirmations reached	Refund is final — funds have reached the customer
`FAILED`	Refund transaction reverted	Funds remain in the order address; ops may retry

Payload examples

`status = PENDING`

{
  "event": "transaction.created",
  "timestamp": 1738810800000,
  "data": {
    "fundEventCode": "FE20260206150000007",
    "paymentLinkName": null,
    "businessRefType": "REFUND",
    "chain": "Ethereum",
    "tokenSymbol": "USDC",
    "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "txHash": "0xeeee777788889999eeee777788889999eeee777788889999eeee777788889999",
    "fromAddress": "0xfedcba0987654321fedcba0987654321fedcba09",
    "toAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "amount": 99.00,
    "direction": "OUT",
    "eventType": "CUSTOMER_REFUND",
    "status": "PENDING",
    "createTimeUtc": "2026-02-06 15:00:00"
  }
}

`status = CONFIRMED`

{
  "event": "transaction.created",
  "timestamp": 1738810980000,
  "data": {
    "fundEventCode": "FE20260206150000007",
    "paymentLinkName": null,
    "businessRefType": "REFUND",
    "chain": "Ethereum",
    "tokenSymbol": "USDC",
    "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "txHash": "0xeeee777788889999eeee777788889999eeee777788889999eeee777788889999",
    "fromAddress": "0xfedcba0987654321fedcba0987654321fedcba09",
    "toAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "amount": 99.00,
    "direction": "OUT",
    "eventType": "CUSTOMER_REFUND",
    "status": "CONFIRMED",
    "createTimeUtc": "2026-02-06 15:00:00"
  }
}

`status = FAILED`

{
  "event": "transaction.created",
  "timestamp": 1738811040000,
  "data": {
    "fundEventCode": "FE20260206150000007",
    "paymentLinkName": null,
    "businessRefType": "REFUND",
    "chain": "Ethereum",
    "tokenSymbol": "USDC",
    "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "txHash": "0xeeee777788889999eeee777788889999eeee777788889999eeee777788889999",
    "fromAddress": "0xfedcba0987654321fedcba0987654321fedcba09",
    "toAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "amount": 99.00,
    "direction": "OUT",
    "eventType": "CUSTOMER_REFUND",
    "status": "FAILED",
    "createTimeUtc": "2026-02-06 15:00:00"
  }
}

Field notes specific to this event

Field	Notes
`paymentLinkName`	`null` in the payload, even though the refund originates from a payment-link order address. Reconcile via the order address (`fromAddress`) if needed
`fromAddress`	The order address that originally received the customer's payment
`toAddress`	The refund destination — typically the original payer's wallet
`amount`	Net amount sent back to the customer

Recommended handler logic

1. Verify signature.
2. Look up local refund record by fundEventCode.
3. Switch on status:
     PENDING   → mark "in flight". Notify customer "refund processing".
     CONFIRMED → mark "refunded". Notify customer "refund delivered".
     FAILED    → mark "failed". Alert ops; manual retry may be required.
4. Respond 200 within 5 seconds.

The refund only makes sense in relation to a prior CUSTOMER_PAYMENT on the same order address. The two events have different fundEventCode values — link them via the order address (fromAddress of the refund equals toAddress of the payment).

Customer Refund Webhook

When it fires#

Event identifiers#

State machine#

Payload examples#

status = PENDING#

status = CONFIRMED#

status = FAILED#

Field notes specific to this event#

Recommended handler logic#

Related events#