payment-router-sdk

TypeScript SDK for payment-router: register webhook routes so a gateway that only accepts one notification URL can still reach the right app.

Install

npm install payment-router-sdk

Usage

import { PaymentRouterClient } from "payment-router-sdk";

const router = new PaymentRouterClient();

// Register the real webhook URL, get back the id to send the gateway plus its callback URLs.
const route = await router.createRoute({
    webhookUrl: "https://shop.example.com/webhooks/payu",
    expiresAt: "2026-07-12T10:00:00Z", // optional, defaults to 12h out
});

route.externalId; // send this to the gateway as its external payment id
route.callbackUrls; // { payu: "https://router.example.com/webhooks/payu" }

Point the gateway's notification URL at the matching entry in route.callbackUrls, and send route.externalId as the gateway's external payment id. That is the whole setup - there is nothing to verify on the SDK side.

externalId is a UUID generated by the server. Keep it alongside your own order id so you can correlate the callback when it lands.

Failed requests throw a PaymentRouterError carrying status and the parsed body - route creation is rate-limited per IP, so expect a 429 if you hammer it.

Verifying the forwarded webhook

The router replays the gateway's request verbatim - same method, same body byte for byte, same headers - and adds nothing of its own. So verify it exactly as you would if the gateway had called you directly: check the gateway's own signature (PayU's OpenPayU-Signature, PayNow's Signature, ...) against the raw body. Your externalId is inside that payload, where the gateway put it.

Development

pnpm install
pnpm type-check
pnpm build        # tsup -> dist/ (esm + cjs + d.ts)