Kount ENS (Event Notification Service) Webhook

The Kount ENS webhook receives post-transaction notifications from Kount — enabling WordPress to automatically capture or void payments when Kount's fraud team completes a manual review of an order.

---

Webhook Endpoint

POST /wp-json/kount/v1/ens

Authentication: Validated using Kount's webhook signature / IP allowlist

Handler: \Suma\Endpoints\KountEns (in inc/endpoints/class-kount-ens.php)

---

What ENS Events Are Received

Kount sends ENS events for the following scenarios:

Event Name	When Sent	Action
APPROVE	Fraud team manually approves a reviewed order	Auto-capture payment; advance order to wc-processing
DECLINE	Fraud team manually declines a reviewed order	Void/refund payment; advance order to wc-cancelled
TIMEOUT	Review time limit expired without decision	Configurable: auto-decline or notify admin
CHARGEBACK	Chargeback received on a previously approved order	Flag order; notify admin; log to Wonolog

---

Webhook Payload

Kount sends a query-string formatted or JSON POST body:

MERC=MERCHANT_ID
SESS=kount_session_id_abc123
ORDR=12345
UNIQ=WC-ORDER-12345
EVNT=APPROVE
TRAN=kount_transaction_id

---

Processing Logic

On APPROVE event:

1. Find WooCommerce order by ORDR (order ID from Kount's UNIQ field)
2. Verify order is currently wc-on-hold
3. Verify payment gateway supports deferred capture
4. Call payment gateway's capture method
5. Update order status: wc-on-hold → wc-processing
6. Add order note: "Kount reviewed and approved. Payment captured."
7. Log event to Wonolog

On DECLINE event:

1. Find WooCommerce order by order ID
2. Verify order is currently wc-on-hold
3. Call payment gateway's void/refund method
4. Update order status: wc-on-hold → wc-cancelled
5. Add order note: "Kount reviewed and declined. Payment voided."
6. Send cancellation email to customer
7. Log event to Wonolog

On CHARGEBACK event:

1. Find WooCommerce order by order ID
2. Add order note: "Chargeback received from Kount ENS."
3. Flag order with meta: _kount_chargeback = 1
4. Send admin notification email
5. Log to Wonolog at warning level

---

Auto-Capture Logic

For deferred-capture gateways (primarily PayPal PPCP), the order is authorized but not captured at checkout for reviewed transactions. The ENS webhook triggers the actual capture.

This means:

• Authorization is placed at checkout
• Settlement is deferred until Kount decision
• If APPROVE: capture is triggered
• If DECLINE: authorization is voided (no money movement)

---

Webhook Security

The ENS endpoint validates incoming requests in two ways:

1. IP Allowlist: Only Kount's known IP ranges are accepted. Other IPs receive a 403 Forbidden response immediately.
2. Signature Validation: Kount signs the payload with a shared secret; the endpoint verifies the HMAC before processing.

// In class-kount-ens.php
private function verify_signature( WP_REST_Request $request ): bool {
    $signature = $request->get_header( 'X-Kount-Sig' );
    $payload   = $request->get_body();
    $expected  = hash_hmac( 'sha256', $payload, KOUNT_WEBHOOK_SECRET );
    return hash_equals( $expected, $signature );
}

---

Kount ENS Configuration

In the Kount AWC admin:

1. Navigate to Settings → Event Notification Service
2. Add the WordPress ENS endpoint URL: https://scottsdalemint.com/wp-json/kount/v1/ens
3. Configure SSL certificate verification
4. Select events to send (APPROVE, DECLINE, CHARGEBACK, TIMEOUT)
5. Test the webhook using Kount's test event tool

---

Logging

All ENS events are logged to Wonolog:

[INFO] Kount ENS received: APPROVE for order 12345, session abc123
[INFO] Order 12345 auto-captured after Kount approval
[WARNING] Chargeback received for order 12345

Check logs in CloudWatch → /aws/lambda/scottsdale-[env] or via YMIR's logging interface.