Webhook Events

Kyren Pay sends webhook notifications for the following event types.

Event Types

Event	Description	Trigger
`order.paid`	A payment has been confirmed	Customer completes checkout
`order.refunded`	A refund has been applied to an order	A refund succeeds

The current order integration does not emit an order.closed webhook. Query GET /v1/orders/{orderId} to reconcile unpaid terminal states such as FAILED, CLOSED, or REVOKED; see Orders.

Event Object Structure

All webhook events share the same top-level structure:

{
  "id": "evt_abc123",
  "type": "order.paid",
  "created_at": 1736932500000,
  "data": {
    // Event-specific data
  }
}

Field	Type	Description
`id`	string	Unique event identifier (use for deduplication)
`type`	string	The event type
`created_at`	integer	Unix timestamp in milliseconds
`data`	object	Event-specific payload

order.paid

Sent when a customer successfully completes a payment.

{
  "id": "evt_abc123",
  "type": "order.paid",
  "created_at": 1736932500000,
  "data": {
    "order_id": "order_def456",
    "product_id": "prod_abc123",
    "customer_email": "customer@example.com",
    "amount": "9.99",
    "currency": "USD",
    "net_amount": "9.29",
    "paid_at": 1736932500000,
    "metadata": { "user_id": "u_123" }
  }
}

Field	Type	Description
`order_id`	string	The order ID
`product_id`	string	The product that was purchased; may be empty for orders without a product
`customer_email`	string \| null	Customer’s email address, if available
`amount`	string	Original/base order amount; excludes an additional fee charged to the payer
`currency`	string	Three-letter currency code
`net_amount`	string	Amount after fees
`paid_at`	integer \| null	When the payment was confirmed (Unix timestamp in milliseconds), if available
`metadata`	object \| null	Merchant metadata from the checkout session; internal provider fields are filtered out

This is the most important event. Use it to fulfill orders — for example, adding credits to a user’s account.

order.refunded

Sent when a refund has been applied to an order. Use this event to update entitlement, balance, or reconciliation records in your system. See Order refunds for the dashboard refund request flow and refund status definitions.

{
  "id": "evt_refund123",
  "type": "order.refunded",
  "created_at": 1736932600000,
  "data": {
    "order_id": "order_def456",
    "refund_id": "refund_abc123",
    "refund_status": "PARTIAL",
    "amount": "2.50",
    "currency": "USD",
    "refunded_amount": "2.50",
    "original_amount": "9.99",
    "reason": "customer_request",
    "metadata": { "user_id": "u_123" }
  }
}

Field	Type	Description
`order_id`	string	The order ID
`refund_id`	string	The refund ID
`refund_status`	string	Order refund status, such as `PARTIAL` or `FULL`
`amount`	string	Amount refunded by this event
`currency`	string	Three-letter currency code
`refunded_amount`	string	Total refunded amount on the order after this refund
`original_amount`	string	Original/base order amount; excludes an additional fee charged to the payer
`reason`	string \| null	Refund reason
`metadata`	object \| null	Merchant metadata from the checkout session; internal provider fields are filtered out

Dispute Events (When Available)

If dispute processing is supported and enabled for your account, you may also receive these notifications. Availability depends on the provider and operational configuration; confirm it with Kyren support. See Disputes.

Event	Trigger
`dispute.created`	A dispute case is first matched to your order and becomes visible to you
`dispute.updated`	Merchant-visible case details or financial projection change

Both use the same event envelope. Their data contains the following case snapshot; nullable values may be unavailable:

Field	Type	Description
`id`	string	Dispute case ID, distinct from the top-level event ID
`provider`	string	Payment provider
`provider_dispute_id`	string \| null	Provider’s dispute ID
`order_id`	string \| null	Related order ID
`type`, `status`	string	Case type and normalized status
`provider_status`	string \| null	Provider status
`amount`, `currency`	string	Case amount and currency
`reason_code`, `reason`	string \| null	Dispute reason
`defendable`	boolean \| null	Whether defense is available, if known
`response_due_at`, `occurred_at`	integer \| null	Unix timestamps in milliseconds
`updated_at`	integer	Case update time in milliseconds
`financial_status`, `financial_allocation_status`	string	Case financial processing and allocation status
`settlement_currency`	string \| null	Currency of the financial amounts below
`allocated_merchant_principal`, `allocated_rolling_reserve`	string	Principal and reserve allocated to this case
`frozen_principal`, `charged_back_principal`	string	Principal frozen or charged back for this case
`offset_rolling_reserve`, `chargeback_fee`	string	Reserve offset and merchant chargeback fee for this case
`projection_state`	string \| null	State of the related order’s financial projection
`related_case_count`	integer	Number of cases sharing the order projection
`shared_order_projection`	boolean	Whether multiple cases share that projection

These are operational case notifications. A change to status alone does not prove a balance movement; use the financial fields and dashboard records for reconciliation. Financial amounts are scoped to the individual case, even when shared_order_projection is true.

Handling Events

Here’s how to handle webhook events in your endpoint:

app.post('/webhooks/kyren', async (req, res) => {
  // ... verify signature first ...

  const event = JSON.parse(req.body.toString());

  try {
    switch (event.type) {
      case 'order.paid':
        await handleOrderPaidIdempotently(event.id, event.data);
        break;
      case 'order.refunded':
        await handleOrderRefundedIdempotently(event.id, event.data);
        break;
      case 'dispute.created':
      case 'dispute.updated':
        await handleDisputeIdempotently(event.id, event.data);
        break;
      default:
        console.log(`Unhandled event: ${event.type}`);
    }
    res.status(200).send('OK');
  } catch (error) {
    res.status(500).send('Retry later');
  }
});

The handlers must durably complete their work before acknowledging the event. For longer processing, use the durable queue pattern and return 2xx only after persistence succeeds.

Start Here

Dashboard Guide

Webhooks

Troubleshooting

Epay Migration

System Integrations

FAQ

References

Event Types

Event Object Structure

order.paid

order.refunded

Dispute Events (When Available)

Handling Events

​Event Types

​Event Object Structure

​order.paid

​order.refunded

​Dispute Events (When Available)

​Handling Events

Event Types

Event Object Structure

order.paid

order.refunded

Dispute Events (When Available)

Handling Events