Webhook Payloads

Canonical Structure

interface WebhookPayload {
  id: string;
  type: string;
  timestamp: string;
  data: {
    order: CheckoutOrder | null;
    payment: CheckoutPayment | null;
    refund: Record<string, unknown> | null;
    paymentBridge: Record<string, unknown> | null;
  };
}

data.order

CheckoutOrder is present for order lifecycle events and usually includes:

• id
• merchantId
• status
• requestedUsdcAmount
• remainingUsdcAmount
• destinationAddress
• destinationToken
• destinationChainId
• metadata

data.payment

CheckoutPayment may be present for fulfillment/payout-related events.

Useful fields:

• id
• orderId
• rail
• paymentAmount
• netSettledUsdcAmount
• fulfillTransaction

Example

{
  "id": "evt_abc123",
  "type": "PAYMENT_SETTLED",
  "timestamp": "2026-04-03T10:00:00.000Z",
  "data": {
    "order": {
      "id": "ord_123",
      "merchantId": "merchant_123",
      "status": "FULFILLED",
      "requestedUsdcAmount": "50.00",
      "remainingUsdcAmount": "0.00",
      "destinationAddress": "0x742d...",
      "destinationToken": "USDC",
      "destinationChainId": "8453"
    },
    "payment": {
      "id": "pay_123",
      "orderId": "ord_123",
      "rail": "venmo",
      "paymentAmount": "50.00",
      "netSettledUsdcAmount": "49.50",
      "fulfillTransaction": "0xabc..."
    },
    "refund": null,
    "paymentBridge": null
  }
}

Bridge Event Payloads

For PAYMENT_BRIDGE_PENDING, PAYMENT_BRIDGE_SUBMITTED, PAYMENT_BRIDGE_COMPLETED, and PAYMENT_BRIDGE_FAILED, data.paymentBridge includes bridge state and destination transfer metadata.

Refund Event Payloads

For REFUND_PENDING and REFUND_COMPLETED, data.refund carries refund metadata when the emitter provides it. data.order, data.payment, and data.paymentBridge may be null until refund records are backed by a dedicated backend refund model.

ORDER_RESIZED Payloads

For ORDER_RESIZED, the event carries post-resize order amounts in data.order, with data.payment, data.refund, and data.paymentBridge all null. The data.resize field contains the previous and new amounts:

{
  "id": "evt_resize123",
  "type": "ORDER_RESIZED",
  "timestamp": "2026-04-03T10:15:00.000Z",
  "data": {
    "order": {
      "id": "ord_456",
      "merchantId": "merchant_123",
      "status": "CREATED",
      "requestedUsdcAmount": "45.500000",
      "remainingUsdcAmount": "45.500000",
      "destinationAddress": "0x742d...",
      "destinationToken": "USDC",
      "destinationChainId": "8453"
    },
    "payment": null,
    "refund": null,
    "paymentBridge": null,
    "resize": {
      "previousAmountUsdc": "50.000000",
      "newAmountUsdc": "45.500000"
    }
  }
}