@pandait.tech/payment-nuvei 1.0.0 → 1.1.0

package/README.md

@@ -110,11 +110,17 @@ export const POST = createChargeHandler({
 
 Apply the same pattern to the remaining handlers — each one is documented inline with its own `XHandlerDeps` interface.
 
-### Securing the webhook (important)
+### The webhook is OPTIONAL — and if you expose it, secure it
 
-Paymentez/Nuvei DMNs (webhooks) are **not signed**, so the webhook endpoint must be protected with a shared secret — otherwise anyone who knows an `orderId` could POST a fake "paid" notification.
+First, set expectations correctly:
 
-1. Set a secret and pass it to the handler (or via `NUVEI_WEBHOOK_SECRET`):
+- **Payments are confirmed by the synchronous `/debit` response** (`createChargeHandler` reads `transaction.status === "success" && status_detail === 3`), plus the 3DS `term_url` callback + `verify` polling for challenged transactions. **That path fully confirms a payment without any webhook.**
+- Paymentez's transaction-notification **callback** (`developers.paymentez.com/api/#webhook`) is an **optional, redundant async channel** — Paymentez POSTs transaction status to a URL you register *with Paymentez during integration* (there is no documented self-serve dashboard; for many accounts it is simply never wired up). In a real production consumer we observed Paymentez never calling it at all.
+- So `createWebhookHandler` is a reconciliation backstop you can mount **if** your Paymentez account is configured to notify it. It is **not required** to take payments.
+
+Because the endpoint is nonetheless a **public POST** route, if you mount it you must authenticate it — otherwise anyone who knows an `orderId` could POST a fake "paid" notification (`status_detail: 3`) and mark an order paid. Paymentez callbacks are **not signed**, so use a shared secret:
+
+1. Pass a secret to the handler (or via `NUVEI_WEBHOOK_SECRET`):
 
    ```ts
    export const POST = createWebhookHandler({
@@ -125,7 +131,7 @@ Paymentez/Nuvei DMNs (webhooks) are **not signed**, so the webhook endpoint must
    });
    ```
 
-2. In the **Nuvei dashboard**, configure your DMN/callback URL with the secret as a query param:
+2. If/when you register the notification URL with Paymentez, append the secret as a query param:
 
    ```
    https://your-shop.com/api/webhooks/nuvei?key=YOUR_SECRET
@@ -133,9 +139,9 @@ Paymentez/Nuvei DMNs (webhooks) are **not signed**, so the webhook endpoint must
 
    (The secret is also accepted as the `x-webhook-key` header.)
 
-Requests without a matching key get `401` and are not processed (constant-time compared). If `webhookSecret` is **unset**, the handler still processes but logs a loud warning — treat that as not-production-ready.
+Requests without a matching key get `401` and are not processed (constant-time compared). If `webhookSecret` is **unset**, the handler still processes but logs a loud warning. If you never register the URL with Paymentez, setting the secret simply seals the endpoint (everything → 401), which is a safe default.
 
-> `onPaymentSucceeded` fires once, on the transition into `paid` (idempotent across Nuvei's webhook retries).
+> `onPaymentSucceeded` fires once, on the transition into `paid` (idempotent across retries).
 
 ## Hosting & deployment (3DS callback + Nuvei egress)