@wtfalch/payments 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Tallis Falch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# @wtfalch/payments
+
+One `PaymentProvider` interface -- create a payment, capture, refund, set up
+and charge a recurring agreement -- over Stripe and Vipps MobilePay, plus a
+`verify*Webhook` function per provider that turns a signed webhook request
+into one normalized event shape. Holds no card data: plain HTTP to each
+provider's REST API, zero runtime dependencies.
+
+## Install
+
+```sh
+pnpm add @wtfalch/payments
+```
+
+## Use
+
+Both adapters implement the same `PaymentProvider` interface. The caller
+resolves each provider's credential (from `@wtfalch/keys`, in the estate's
+case) and passes it in; this package never fetches or stores one.
+
+```ts
+import { createStripeProvider, createVippsProvider } from '@wtfalch/payments';
+
+const stripe = createStripeProvider({ secretKey }); // sk_...
+const vipps = createVippsProvider({ subscriptionKey, merchantSerialNumber, accessToken });
+
+const payment = await stripe.createPayment({
+  reference: 'order-123',
+  amount: { value: 1000, currency: 'NOK' }, // minor units: 1000 = 10.00 NOK
+  returnUrl: 'https://example.com/orders/123/return',
+});
+// payment.providerReference -- pass to capturePayment/refundPayment
+// payment.raw.client_secret -- Stripe: confirm with Stripe.js/Elements
+// payment.redirectUrl -- Vipps: send the payer here
+```
+
+```ts
+await stripe.capturePayment(payment.providerReference); // full capture
+await stripe.refundPayment(payment.providerReference, { reason: 'requested_by_customer' });
+```
+
+### Recurring agreements
+
+Thin provider mechanics only -- prices, plans and dunning are
+`@wtfalch/billing`'s job, not this package's:
+
+```ts
+const agreement = await vipps.createRecurringAgreement({
+  reference: 'agreement-123',
+  amount: { value: 29900, currency: 'NOK' },
+  productName: 'Pro plan',
+  returnUrl: 'https://example.com/agreements/123/return',
+  managementUrl: 'https://example.com/account/subscription',
+});
+// agreement.confirmationUrl -- send the payer here to approve it
+
+await vipps.chargeRecurringAgreement(agreement.agreementReference, {
+  amount: { value: 29900, currency: 'NOK' },
+  description: 'March invoice',
+});
+```
+
+For Stripe, `createRecurringAgreement` creates a SetupIntent
+(`agreement.clientSecret` -- confirm with Stripe.js) and
+`chargeRecurringAgreement` looks up the payment method it saved and charges
+it off-session.
+
+### Webhooks
+
+```ts
+import { verifyStripeWebhook, verifyVippsWebhook } from '@wtfalch/payments';
+
+// Stripe: the raw request body and the Stripe-Signature header, unparsed.
+const event = verifyStripeWebhook(rawBody, req.headers['stripe-signature'], webhookSecret);
+
+// Vipps: the raw body plus the four headers the Azure-APIM HMAC scheme signs,
+// and the request's own method + path (see the module doc comment in
+// src/vipps.ts for the exact algorithm and its primary sources).
+const event = verifyVippsWebhook(
+  rawBody,
+  { authorization: req.headers.authorization, xMsDate: req.headers['x-ms-date'], xMsContentSha256: req.headers['x-ms-content-sha256'], host: req.headers.host },
+  webhookSecret,
+  req.method,
+  req.url,
+);
+```
+
+Both throw `WebhookVerificationError` on a bad signature, a tampered
+payload, or a timestamp outside the replay tolerance (default 5 minutes) --
+never return a partially-trusted event. `event.type` is one of a closed set
+(`payment.created | authorized | captured | refunded | cancelled | failed |
+expired | unknown`); an event type this package does not yet recognise
+normalizes to `unknown` rather than throwing, so a new provider event is
+forward-compatible.
+
+## Errors
+
+- `PaymentProviderError` -- a provider API call failed (HTTP error, network
+  error, or an unparsable response). Never thrown for "the payment was
+  declined"; that is a normal `PaymentResult`/`RefundResult` with a `failed`
+  status.
+- `WebhookVerificationError` -- a webhook failed to verify. The caller must
+  reject the request, never act on the event.
+
+## Tests
+
+From `packages/payments`:
+
+```sh
+pnpm test
+```
+
+Every test runs against recorded/fake fixtures (`src/fixtures/{stripe,vipps}`)
+and a fake `fetch` (`src/test/fake-fetch.ts`) -- never a live provider call,
+never a real key. Webhook verification tests build their own valid signature
+independently of the code under test (see `*-webhook.test.ts`), then check
+that a tampered payload, a tampered signature, a wrong secret, a wrong
+request path (Vipps), and a stale timestamp are all rejected.
+
+## Known gap
+
+The exact `state` enum on a Vipps ePayment response was not confirmed from
+primary docs at build time (see `src/vipps.ts`'s module doc comment).
+`derivePaymentStatus` falls back to the documented `aggregate.*Amount`
+fields when `state` is absent or unrecognised, but this adapter has not been
+exercised against a real Vipps sandbox response. Do that before relying on
+it for anything that pays out money.

package/dist/http.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The minimal shape this package calls on `fetch`: a request in, a response
+ * with `ok`, `status`, `json()` and `text()` out. The real global `fetch`
+ * satisfies this structurally, and so does a fake with no network access,
+ * which is what every adapter test injects (never a real key, never a real
+ * call -- see each adapter's `*.test.ts`).
+ */
+export type FetchLike = (input: string, init?: FetchInit) => Promise<FetchResponseLike>;
+export interface FetchInit {
+    readonly method?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: string;
+}
+export interface FetchResponseLike {
+    readonly ok: boolean;
+    readonly status: number;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}
+/** `globalThis.fetch`, present on Node >=18 and required by this package's
+ * `engines.node` (>=22). Read lazily so importing this module never fails in
+ * an environment without a global `fetch` unless a call is actually made. */
+export declare function defaultFetch(): FetchLike;

package/dist/http.js

@@ -0,0 +1,9 @@
+/** `globalThis.fetch`, present on Node >=18 and required by this package's
+ * `engines.node` (>=22). Read lazily so importing this module never fails in
+ * an environment without a global `fetch` unless a call is actually made. */
+export function defaultFetch() {
+    if (typeof globalThis.fetch !== 'function') {
+        throw new Error('payments: no global fetch available; pass { fetch } explicitly to the provider constructor.');
+    }
+    return globalThis.fetch.bind(globalThis);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { CapturePaymentInput, ChargeRecurringAgreementInput, CreatePaymentInput, CreateRecurringAgreementInput, Money, NormalizedWebhookEvent, NormalizedWebhookEventType, PaymentResult, PaymentStatus, RecurringAgreementResult, RecurringAgreementStatus, RefundInput, RefundResult, } from './types.js';
+export { PaymentProviderError, WebhookVerificationError } from './types.js';
+export type { PaymentProvider } from './provider.js';
+export type { FetchInit, FetchLike, FetchResponseLike } from './http.js';
+export type { StripeProviderOptions, StripeWebhookOptions } from './stripe.js';
+export { createStripeProvider, verifyStripeWebhook } from './stripe.js';
+export type { VippsProviderOptions, VippsWebhookHeaders, VippsWebhookOptions, } from './vipps.js';
+export { createVippsProvider, verifyVippsWebhook } from './vipps.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { PaymentProviderError, WebhookVerificationError } from './types.js';
+export { createStripeProvider, verifyStripeWebhook } from './stripe.js';
+export { createVippsProvider, verifyVippsWebhook } from './vipps.js';

package/dist/provider.d.ts

@@ -0,0 +1,17 @@
+import type { CapturePaymentInput, ChargeRecurringAgreementInput, CreatePaymentInput, CreateRecurringAgreementInput, PaymentResult, RecurringAgreementResult, RefundInput, RefundResult } from './types.js';
+/**
+ * One shape, two adapters (`createStripeProvider`, `createVippsProvider`).
+ * Webhook verification is deliberately not a method here: it needs no
+ * provider instance (no credential is required to check a signature besides
+ * the webhook secret itself), so it is two standalone functions,
+ * `verifyStripeWebhook` and `verifyVippsWebhook`, each typed to that
+ * provider's own header shape rather than forced through one loose type.
+ */
+export interface PaymentProvider {
+    readonly name: 'stripe' | 'vipps';
+    createPayment(input: CreatePaymentInput): Promise<PaymentResult>;
+    capturePayment(providerReference: string, input?: CapturePaymentInput): Promise<PaymentResult>;
+    refundPayment(providerReference: string, input?: RefundInput): Promise<RefundResult>;
+    createRecurringAgreement(input: CreateRecurringAgreementInput): Promise<RecurringAgreementResult>;
+    chargeRecurringAgreement(agreementReference: string, input: ChargeRecurringAgreementInput): Promise<PaymentResult>;
+}

package/dist/provider.js

@@ -0,0 +1 @@
+export {};

package/dist/stripe.d.ts

@@ -0,0 +1,43 @@
+import { type FetchLike } from './http.js';
+import type { PaymentProvider } from './provider.js';
+import { type NormalizedWebhookEvent } from './types.js';
+export interface StripeProviderOptions {
+    /** The Stripe secret key (`sk_...` or a restricted key). The caller
+     * resolves this (from `@wtfalch/keys`, in the estate's case); this
+     * package never fetches or stores it beyond the call it is passed to. */
+    readonly secretKey: string;
+    /** Alternative to the real network for tests. Defaults to `globalThis.fetch`. */
+    readonly fetch?: FetchLike;
+    /** Override for testing. Defaults to `https://api.stripe.com/v1`. */
+    readonly baseUrl?: string;
+}
+/**
+ * A Stripe adapter. `createPayment` creates a PaymentIntent for the caller's
+ * frontend to confirm with Stripe.js/Elements using `clientSecret`
+ * (`raw.client_secret`); this package never touches card data itself.
+ */
+export declare function createStripeProvider(options: StripeProviderOptions): PaymentProvider;
+export interface StripeWebhookOptions {
+    /** Seconds of clock skew to tolerate between the event's timestamp and
+     * now, guarding against replay of an old, otherwise-valid signature.
+     * Default matches Stripe's own official-library default: 300 (5 minutes). */
+    readonly toleranceSeconds?: number;
+    /** Injectable for tests. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * Verifies a Stripe webhook's `Stripe-Signature` header against the raw
+ * request body, by hand -- the manual algorithm from
+ * https://docs.stripe.com/webhooks#verify-manually (no `stripe` SDK):
+ *
+ *   1. Parse `t=` (timestamp) and `v1=` (signature) out of the header.
+ *   2. Build `signedPayload = "${t}.${rawBody}"`.
+ *   3. HMAC-SHA256(webhookSecret, signedPayload), hex-encoded.
+ *   4. Constant-time compare to `v1`; reject if the timestamp is outside
+ *      `toleranceSeconds` of now (replay protection).
+ *
+ * `rawBody` must be the exact, unparsed request body -- Stripe's own
+ * warning applies here too: any framework reformatting of the body before
+ * this call breaks verification.
+ */
+export declare function verifyStripeWebhook(rawBody: string, signatureHeader: string, webhookSecret: string, options?: StripeWebhookOptions): NormalizedWebhookEvent;

package/dist/stripe.js

@@ -0,0 +1,275 @@
+import { defaultFetch } from './http.js';
+import { PaymentProviderError, WebhookVerificationError, } from './types.js';
+/**
+ * The Stripe adapter. Plain HTTP against Stripe's REST API (`/v1/*`,
+ * `application/x-www-form-urlencoded`, bearer auth with the secret key) --
+ * no `stripe` npm package. See docs/adr/0003-plain-http-no-provider-sdks.md.
+ *
+ * Sources (fetched 2026-09-23, primary docs, no live calls):
+ *   - https://docs.stripe.com/api/payment_intents
+ *   - https://docs.stripe.com/api/refunds/create
+ *   - https://docs.stripe.com/api/setup_intents
+ *   - https://docs.stripe.com/webhooks (manual signature verification)
+ */
+import { hmacSha256Hex, safeEqual } from './webhook-crypto.js';
+/** Form-urlencodes Stripe's `/v1` request bodies, including one level of
+ * bracket-notation nesting (`metadata[key]=value`) -- the only nesting this
+ * adapter sends. */
+function toFormBody(params) {
+    const pairs = [];
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined)
+            continue;
+        // Stripe's own examples send bracket-notation keys with the brackets
+        // literal (`metadata[order_id]=...`), not percent-encoded -- only the
+        // key's other characters and the value are encoded.
+        const encodedKey = encodeURIComponent(key).replace(/%5B/g, '[').replace(/%5D/g, ']');
+        pairs.push(`${encodedKey}=${encodeURIComponent(String(value))}`);
+    }
+    return pairs.join('&');
+}
+function metadataParams(metadata) {
+    const params = {};
+    if (!metadata)
+        return params;
+    for (const [key, value] of Object.entries(metadata)) {
+        params[`metadata[${key}]`] = value;
+    }
+    return params;
+}
+const PAYMENT_INTENT_STATUS = {
+    requires_payment_method: 'pending',
+    requires_confirmation: 'pending',
+    processing: 'pending',
+    requires_action: 'requires_action',
+    requires_capture: 'authorized',
+    succeeded: 'captured',
+    canceled: 'canceled',
+};
+const SETUP_INTENT_STATUS = {
+    requires_payment_method: 'pending',
+    requires_confirmation: 'pending',
+    requires_action: 'pending',
+    processing: 'pending',
+    succeeded: 'active',
+    canceled: 'stopped',
+};
+const REFUND_STATUS = {
+    pending: 'pending',
+    requires_action: 'pending',
+    succeeded: 'succeeded',
+    failed: 'failed',
+    canceled: 'failed',
+};
+function toPaymentResult(pi) {
+    return {
+        provider: 'stripe',
+        providerReference: pi.id,
+        status: PAYMENT_INTENT_STATUS[pi.status] ?? 'pending',
+        amount: { value: pi.amount, currency: pi.currency.toUpperCase() },
+        redirectUrl: pi.next_action?.redirect_to_url?.url,
+        raw: pi,
+    };
+}
+/**
+ * A Stripe adapter. `createPayment` creates a PaymentIntent for the caller's
+ * frontend to confirm with Stripe.js/Elements using `clientSecret`
+ * (`raw.client_secret`); this package never touches card data itself.
+ */
+export function createStripeProvider(options) {
+    const fetchImpl = options.fetch ?? defaultFetch();
+    const baseUrl = options.baseUrl ?? 'https://api.stripe.com/v1';
+    async function call(path, params, idempotencyKey) {
+        const headers = {
+            Authorization: `Bearer ${options.secretKey}`,
+            'Content-Type': 'application/x-www-form-urlencoded',
+        };
+        if (idempotencyKey)
+            headers['Idempotency-Key'] = idempotencyKey;
+        const response = await fetchImpl(`${baseUrl}${path}`, {
+            method: 'POST',
+            headers,
+            body: toFormBody(params),
+        });
+        const body = await response.json();
+        if (!response.ok) {
+            const message = typeof body === 'object' && body !== null && 'error' in body
+                ? String(body.error?.message ?? response.status)
+                : `HTTP ${response.status}`;
+            throw new PaymentProviderError('stripe', message, { status: response.status, raw: body });
+        }
+        return body;
+    }
+    async function get(path) {
+        const response = await fetchImpl(`${baseUrl}${path}`, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${options.secretKey}` },
+        });
+        const body = await response.json();
+        if (!response.ok) {
+            throw new PaymentProviderError('stripe', `HTTP ${response.status}`, {
+                status: response.status,
+                raw: body,
+            });
+        }
+        return body;
+    }
+    return {
+        name: 'stripe',
+        async createPayment(input) {
+            const pi = await call('/payment_intents', {
+                amount: input.amount.value,
+                currency: input.amount.currency.toLowerCase(),
+                description: input.description,
+                'automatic_payment_methods[enabled]': true,
+                'metadata[reference]': input.reference,
+                ...metadataParams(input.metadata),
+            }, input.idempotencyKey);
+            return toPaymentResult(pi);
+        },
+        async capturePayment(providerReference, input = {}) {
+            const pi = await call(`/payment_intents/${providerReference}/capture`, { amount_to_capture: input.amount?.value }, input.idempotencyKey);
+            // Defence in depth: the response is trusted as Stripe's, but a result
+            // that names a *different* PaymentIntent than the one just captured
+            // must never be silently returned as if it were this call's result --
+            // caught here rather than only up at the caller, which has no way to
+            // know this response was ever supposed to be about `providerReference`.
+            if (pi.id !== providerReference) {
+                throw new PaymentProviderError('stripe', `capture response id "${pi.id}" does not match the requested payment "${providerReference}"`, { raw: pi });
+            }
+            return toPaymentResult(pi);
+        },
+        async refundPayment(providerReference, input = {}) {
+            const refund = await call('/refunds', {
+                payment_intent: providerReference,
+                amount: input.amount?.value,
+                reason: input.reason,
+            }, input.idempotencyKey);
+            // Same integrity check as capturePayment: never attribute a refund to
+            // a payment_intent other than the one this call actually requested.
+            if (refund.payment_intent !== providerReference) {
+                throw new PaymentProviderError('stripe', `refund response payment_intent "${refund.payment_intent}" does not match the requested payment "${providerReference}"`, { raw: refund });
+            }
+            return {
+                provider: 'stripe',
+                refundReference: refund.id,
+                paymentReference: refund.payment_intent,
+                status: REFUND_STATUS[refund.status] ?? 'pending',
+                amount: { value: refund.amount, currency: refund.currency.toUpperCase() },
+                raw: refund,
+            };
+        },
+        async createRecurringAgreement(input) {
+            const si = await call('/setup_intents', {
+                usage: 'off_session',
+                'metadata[reference]': input.reference,
+                'metadata[productName]': input.productName,
+                'metadata[amount]': input.amount.value,
+                'metadata[currency]': input.amount.currency.toUpperCase(),
+            }, input.idempotencyKey);
+            return {
+                provider: 'stripe',
+                agreementReference: si.id,
+                status: SETUP_INTENT_STATUS[si.status] ?? 'pending',
+                clientSecret: si.client_secret,
+                raw: si,
+            };
+        },
+        async chargeRecurringAgreement(agreementReference, input) {
+            // A SetupIntent only saves a payment method; charging it off-session
+            // is a separate PaymentIntent against the customer + payment method
+            // it saved. Two calls, not one -- Stripe has no single "charge this
+            // agreement" endpoint the way Vipps does.
+            const si = await get(`/setup_intents/${agreementReference}`);
+            if (!si.customer || !si.payment_method) {
+                throw new PaymentProviderError('stripe', `setup_intent ${agreementReference} has no saved customer/payment_method yet -- the payer has not completed it`, { raw: si });
+            }
+            const pi = await call('/payment_intents', {
+                amount: input.amount.value,
+                currency: input.amount.currency.toLowerCase(),
+                customer: si.customer,
+                payment_method: si.payment_method,
+                off_session: true,
+                confirm: true,
+                description: input.description,
+            }, input.idempotencyKey);
+            return toPaymentResult(pi);
+        },
+    };
+}
+const WEBHOOK_EVENT_TYPE = {
+    'payment_intent.created': 'payment.created',
+    'payment_intent.requires_action': 'payment.authorized',
+    'payment_intent.amount_capturable_updated': 'payment.authorized',
+    'payment_intent.succeeded': 'payment.captured',
+    'payment_intent.canceled': 'payment.cancelled',
+    'payment_intent.payment_failed': 'payment.failed',
+    'charge.refunded': 'payment.refunded',
+    'charge.refund.updated': 'payment.refunded',
+};
+/**
+ * Verifies a Stripe webhook's `Stripe-Signature` header against the raw
+ * request body, by hand -- the manual algorithm from
+ * https://docs.stripe.com/webhooks#verify-manually (no `stripe` SDK):
+ *
+ *   1. Parse `t=` (timestamp) and `v1=` (signature) out of the header.
+ *   2. Build `signedPayload = "${t}.${rawBody}"`.
+ *   3. HMAC-SHA256(webhookSecret, signedPayload), hex-encoded.
+ *   4. Constant-time compare to `v1`; reject if the timestamp is outside
+ *      `toleranceSeconds` of now (replay protection).
+ *
+ * `rawBody` must be the exact, unparsed request body -- Stripe's own
+ * warning applies here too: any framework reformatting of the body before
+ * this call breaks verification.
+ */
+export function verifyStripeWebhook(rawBody, signatureHeader, webhookSecret, options = {}) {
+    const toleranceSeconds = options.toleranceSeconds ?? 300;
+    const now = options.now ?? Date.now;
+    const parts = signatureHeader.split(',').map((part) => part.trim());
+    let timestamp;
+    const v1Signatures = [];
+    for (const part of parts) {
+        const eq = part.indexOf('=');
+        if (eq === -1)
+            continue;
+        const key = part.slice(0, eq);
+        const value = part.slice(eq + 1);
+        if (key === 't')
+            timestamp = value;
+        else if (key === 'v1')
+            v1Signatures.push(value);
+    }
+    if (!timestamp || v1Signatures.length === 0) {
+        throw new WebhookVerificationError('stripe', 'Stripe-Signature header is missing "t=" or "v1="');
+    }
+    const signedPayload = `${timestamp}.${rawBody}`;
+    const expected = hmacSha256Hex(webhookSecret, signedPayload);
+    const matches = v1Signatures.some((sig) => safeEqual(sig, expected));
+    if (!matches) {
+        throw new WebhookVerificationError('stripe', 'signature does not match the payload');
+    }
+    const ageSeconds = Math.abs(now() / 1000 - Number(timestamp));
+    if (!Number.isFinite(ageSeconds) || ageSeconds > toleranceSeconds) {
+        throw new WebhookVerificationError('stripe', `timestamp is ${Math.round(ageSeconds)}s old, outside the ${toleranceSeconds}s tolerance (possible replay)`);
+    }
+    let event;
+    try {
+        event = JSON.parse(rawBody);
+    }
+    catch {
+        throw new WebhookVerificationError('stripe', 'payload is not valid JSON');
+    }
+    const object = event.data?.object;
+    const paymentReference = object?.payment_intent ?? object?.id ?? '';
+    const amount = typeof object?.amount === 'number' && object.currency
+        ? { value: object.amount, currency: object.currency.toUpperCase() }
+        : undefined;
+    return {
+        provider: 'stripe',
+        type: WEBHOOK_EVENT_TYPE[event.type ?? ''] ?? 'unknown',
+        eventId: event.id ?? '',
+        paymentReference,
+        amount,
+        raw: event,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Shared vocabulary for both adapters. Nothing here is provider-specific;
+ * `stripe.ts` and `vipps.ts` each translate their provider's own wire shape
+ * into these types and back.
+ */
+/** An amount in the smallest unit of its currency (cents, øre, ...). Both
+ * Stripe and Vipps already speak this way on the wire, so there is no
+ * conversion to get wrong at the boundary. */
+export interface Money {
+    /** Integer, minor units. Never a float. */
+    readonly value: number;
+    /** ISO 4217, upper case, e.g. "NOK", "EUR", "USD". */
+    readonly currency: string;
+}
+export type PaymentStatus = 'pending' | 'requires_action' | 'authorized' | 'captured' | 'partially_refunded' | 'refunded' | 'canceled' | 'failed';
+export type RecurringAgreementStatus = 'pending' | 'active' | 'stopped' | 'expired';
+export interface CreatePaymentInput {
+    /** The merchant's own reference for this payment. Must be unique per attempt. */
+    readonly reference: string;
+    readonly amount: Money;
+    readonly description?: string;
+    /** Where the payer returns to after completing the payment. */
+    readonly returnUrl: string;
+    /** Passed through to the provider as its idempotency key, so a retried
+     * `createPayment` call with the same key never double-charges. */
+    readonly idempotencyKey?: string;
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+export interface CapturePaymentInput {
+    /** Omit for a full capture of whatever was authorized. */
+    readonly amount?: Money;
+    readonly idempotencyKey?: string;
+}
+export interface RefundInput {
+    /** Omit for a full refund of the remaining captured amount. */
+    readonly amount?: Money;
+    readonly reason?: 'duplicate' | 'fraudulent' | 'requested_by_customer';
+    readonly idempotencyKey?: string;
+}
+export interface PaymentResult {
+    readonly provider: 'stripe' | 'vipps';
+    /** The provider's own identifier for this payment (Stripe: PaymentIntent
+     * id; Vipps: the `reference` echoed back). Pass this to `capturePayment`,
+     * `refundPayment`, and to match a webhook event to the payment it is about. */
+    readonly providerReference: string;
+    readonly status: PaymentStatus;
+    readonly amount: Money;
+    /** Where to send the payer to complete the payment, when the provider
+     * needs a redirect (Vipps always; Stripe only for some payment methods). */
+    readonly redirectUrl?: string;
+    /** The provider's own response body, for anything this shape does not
+     * carry. Never relied on by this package itself. */
+    readonly raw: unknown;
+}
+export interface RefundResult {
+    readonly provider: 'stripe' | 'vipps';
+    readonly refundReference: string;
+    readonly paymentReference: string;
+    readonly status: 'pending' | 'succeeded' | 'failed';
+    readonly amount: Money;
+    readonly raw: unknown;
+}
+export interface CreateRecurringAgreementInput {
+    readonly reference: string;
+    /** The periodic charge amount. Stripe's SetupIntent does not itself need
+     * one, but it is required here for symmetry with Vipps and because a
+     * caller building the agreement already knows it. */
+    readonly amount: Money;
+    readonly productName: string;
+    /** Where the payer returns after approving the agreement. */
+    readonly returnUrl: string;
+    /** Vipps' `merchantAgreementUrl`: the page where the payer manages this
+     * agreement. Required by Vipps for Norwegian merchants; ignored by Stripe. */
+    readonly managementUrl?: string;
+    readonly interval?: {
+        readonly unit: 'day' | 'week' | 'month';
+        readonly count: number;
+    };
+    readonly idempotencyKey?: string;
+}
+export interface RecurringAgreementResult {
+    readonly provider: 'stripe' | 'vipps';
+    readonly agreementReference: string;
+    readonly status: RecurringAgreementStatus;
+    /** Where the payer approves the agreement (Vipps: `vippsConfirmationUrl`). */
+    readonly confirmationUrl?: string;
+    /** Stripe's SetupIntent client secret, for the caller's frontend to
+     * confirm with Stripe.js. Absent for Vipps. */
+    readonly clientSecret?: string;
+    readonly raw: unknown;
+}
+export interface ChargeRecurringAgreementInput {
+    readonly amount: Money;
+    readonly description: string;
+    /** ISO date (YYYY-MM-DD). Vipps requires this at least one day ahead; Stripe ignores it. */
+    readonly dueDate?: string;
+    readonly idempotencyKey?: string;
+}
+/** A closed set, plus `unknown`. A provider event type this package does not
+ * yet recognise normalizes to `unknown` rather than throwing, so a new
+ * Stripe or Vipps event is forward-compatible, not a crash. */
+export type NormalizedWebhookEventType = 'payment.created' | 'payment.authorized' | 'payment.captured' | 'payment.refunded' | 'payment.cancelled' | 'payment.failed' | 'payment.expired' | 'unknown';
+export interface NormalizedWebhookEvent {
+    readonly provider: 'stripe' | 'vipps';
+    readonly type: NormalizedWebhookEventType;
+    /** The provider's own event id, for de-duplicating retried deliveries. */
+    readonly eventId: string;
+    /** Matches `PaymentResult.providerReference` / the payment this event is about. */
+    readonly paymentReference: string;
+    readonly amount?: Money;
+    /** The provider's own event payload, for anything this shape does not carry. */
+    readonly raw: unknown;
+}
+/** A provider API call failed -- HTTP error, network error, or a response
+ * this adapter could not parse. Never thrown for "the payment was declined";
+ * that is a normal `PaymentResult`/`RefundResult` with a `failed` status. */
+export declare class PaymentProviderError extends Error {
+    readonly provider: 'stripe' | 'vipps';
+    readonly status?: number;
+    readonly raw?: unknown;
+    constructor(provider: 'stripe' | 'vipps', message: string, options?: {
+        status?: number;
+        raw?: unknown;
+    });
+}
+/** A webhook payload failed to verify: missing/malformed signature header,
+ * a signature that does not match the payload, or a timestamp outside the
+ * replay tolerance. Callers must reject the request (400/401), never act on
+ * the event. */
+export declare class WebhookVerificationError extends Error {
+    readonly provider: 'stripe' | 'vipps';
+    constructor(provider: 'stripe' | 'vipps', message: string);
+}

package/dist/types.js

@@ -0,0 +1,32 @@
+/**
+ * Shared vocabulary for both adapters. Nothing here is provider-specific;
+ * `stripe.ts` and `vipps.ts` each translate their provider's own wire shape
+ * into these types and back.
+ */
+/** A provider API call failed -- HTTP error, network error, or a response
+ * this adapter could not parse. Never thrown for "the payment was declined";
+ * that is a normal `PaymentResult`/`RefundResult` with a `failed` status. */
+export class PaymentProviderError extends Error {
+    provider;
+    status;
+    raw;
+    constructor(provider, message, options = {}) {
+        super(`payments(${provider}): ${message}`);
+        this.name = 'PaymentProviderError';
+        this.provider = provider;
+        this.status = options.status;
+        this.raw = options.raw;
+    }
+}
+/** A webhook payload failed to verify: missing/malformed signature header,
+ * a signature that does not match the payload, or a timestamp outside the
+ * replay tolerance. Callers must reject the request (400/401), never act on
+ * the event. */
+export class WebhookVerificationError extends Error {
+    provider;
+    constructor(provider, message) {
+        super(`payments(${provider}) webhook verification failed: ${message}`);
+        this.name = 'WebhookVerificationError';
+        this.provider = provider;
+    }
+}

package/dist/vipps.d.ts

@@ -0,0 +1,55 @@
+import { type FetchLike } from './http.js';
+import type { PaymentProvider } from './provider.js';
+import { type NormalizedWebhookEvent } from './types.js';
+export interface VippsProviderOptions {
+    /** `Ocp-Apim-Subscription-Key`: the sales unit's subscription key. */
+    readonly subscriptionKey: string;
+    /** `Merchant-Serial-Number`: the sales unit's MSN. */
+    readonly merchantSerialNumber: string;
+    /** A valid OAuth access token. The caller obtains and refreshes this
+     * (`POST /accesstoken/get`); this package never does, the same as it
+     * never resolves a Stripe secret key on its own -- see the module doc
+     * comment. */
+    readonly accessToken: string;
+    readonly fetch?: FetchLike;
+    /** Override for testing. Defaults to `https://api.vipps.no`. */
+    readonly baseUrl?: string;
+}
+export declare function createVippsProvider(options: VippsProviderOptions): PaymentProvider;
+export interface VippsWebhookHeaders {
+    /** `Authorization`, e.g. `"HMAC-SHA256 SignedHeaders=x-ms-date;host;x-ms-content-sha256&Signature=..."`. */
+    readonly authorization: string;
+    readonly xMsDate: string;
+    readonly xMsContentSha256: string;
+    readonly host: string;
+}
+export interface VippsWebhookOptions {
+    /** Seconds of clock skew to tolerate between `x-ms-date` and now.
+     * Default: 300 (5 minutes), matching the tolerance this package also uses
+     * for Stripe. */
+    readonly toleranceSeconds?: number;
+    readonly now?: () => number;
+}
+/**
+ * Verifies a Vipps MobilePay webhook request, by hand, against the
+ * Azure-API-Management-style HMAC scheme documented at
+ * https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/request-authentication/
+ * (Vipps' webhook infrastructure runs on Azure APIM; there is no `v1=`/`t=`
+ * header the way Stripe has):
+ *
+ *   1. Recompute `sha256(rawBody)`, base64-encoded; it must match
+ *      `x-ms-content-sha256` (this also authenticates the body, not just
+ *      the headers).
+ *   2. Build the string-to-sign:
+ *      `"${method}\n${pathAndQuery}\n${xMsDate};${host};${xMsContentSha256}"`.
+ *   3. HMAC-SHA256(base64-decoded webhook secret, string-to-sign),
+ *      base64-encoded.
+ *   4. Constant-time compare to the `Signature=` value inside
+ *      `Authorization`; reject if `x-ms-date` is outside `toleranceSeconds`
+ *      of now.
+ *
+ * `method` and `pathAndQuery` must be exactly what Vipps signed: the HTTP
+ * method of the webhook request, and the request path plus query string
+ * (e.g. `"/webhooks/order-123"`), not a normalized or re-routed form of it.
+ */
+export declare function verifyVippsWebhook(rawBody: string, requestHeaders: VippsWebhookHeaders, webhookSecret: string, method: string, pathAndQuery: string, options?: VippsWebhookOptions): NormalizedWebhookEvent;

package/dist/vipps.js

@@ -0,0 +1,314 @@
+import { defaultFetch } from './http.js';
+import { PaymentProviderError, WebhookVerificationError, } from './types.js';
+/**
+ * The Vipps MobilePay adapter. Plain HTTP against the ePayment and Recurring
+ * REST APIs -- no Vipps SDK (there is no single official Node one). See
+ * docs/adr/0003-plain-http-no-provider-sdks.md.
+ *
+ * Sources (fetched 2026-09-23, primary docs, no live calls):
+ *   - https://developer.vippsmobilepay.com/api/epayment/ (create, capture, cancel, refund)
+ *   - https://developer.vippsmobilepay.com/api/recurring/ (agreements, charges)
+ *   - https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/request-authentication/
+ *
+ * Two things v1 deliberately leaves to the caller, recorded here and in the
+ * ledger's Fog rather than guessed at:
+ *   - the OAuth access token (`POST /accesstoken/get`): this adapter takes
+ *     an already-valid `accessToken` and never fetches or refreshes one
+ *     itself, the same "caller resolves the credential" shape as `stripe.ts`.
+ *   - the exact `state` enum on a payment/capture/refund response: the
+ *     fetched docs were not fully explicit about it, so `derivePaymentStatus`
+ *     below falls back to the `aggregate.*Amount` fields, which the docs did
+ *     confirm, whenever `state` is absent or unrecognised.
+ */
+import { hmacSha256Base64, safeEqual, sha256Base64 } from './webhook-crypto.js';
+const PAYMENT_STATE = {
+    CREATED: 'pending',
+    AUTHORIZED: 'authorized',
+    CAPTURED: 'captured',
+    CANCELLED: 'canceled',
+    TERMINATED: 'canceled',
+    REFUNDED: 'refunded',
+    EXPIRED: 'failed',
+    ABORTED: 'canceled',
+};
+/** Best-known `state` first; falls back to the documented `aggregate.*Amount`
+ * fields when `state` is missing or not one of the values above (see the
+ * module doc comment -- the exact enum was not confirmed from primary
+ * docs). Never throws on an unrecognised shape: worst case is `'pending'`. */
+function derivePaymentStatus(payment) {
+    const known = payment.state ? PAYMENT_STATE[payment.state] : undefined;
+    if (known)
+        return known;
+    const aggregate = payment.aggregate;
+    if (!aggregate)
+        return 'pending';
+    const captured = aggregate.capturedAmount?.value ?? 0;
+    const refunded = aggregate.refundedAmount?.value ?? 0;
+    const cancelled = aggregate.cancelledAmount?.value ?? 0;
+    const authorized = aggregate.authorizedAmount?.value ?? 0;
+    if (refunded > 0 && refunded >= captured && captured > 0)
+        return 'refunded';
+    if (refunded > 0)
+        return 'partially_refunded';
+    if (cancelled > 0)
+        return 'canceled';
+    if (captured > 0)
+        return 'captured';
+    if (authorized > 0)
+        return 'authorized';
+    return 'pending';
+}
+function toMoney(amount, fallback) {
+    if (!amount)
+        return fallback;
+    return { value: amount.value, currency: amount.currency.toUpperCase() };
+}
+function toPaymentResult(payment, fallbackAmount) {
+    return {
+        provider: 'vipps',
+        providerReference: payment.reference,
+        status: derivePaymentStatus(payment),
+        amount: toMoney(payment.aggregate?.authorizedAmount ?? payment.amount, fallbackAmount),
+        redirectUrl: payment.redirectUrl,
+        raw: payment,
+    };
+}
+/** `due` for a Recurring charge must be at least one day ahead (Vipps
+ * Recurring API). Tomorrow, in the caller's local calendar, as `YYYY-MM-DD`. */
+function tomorrowIsoDate() {
+    const d = new Date(Date.now() + 24 * 60 * 60 * 1000);
+    return d.toISOString().slice(0, 10);
+}
+export function createVippsProvider(options) {
+    const fetchImpl = options.fetch ?? defaultFetch();
+    const baseUrl = options.baseUrl ?? 'https://api.vipps.no';
+    function headers(idempotencyKey) {
+        const h = {
+            'Content-Type': 'application/json',
+            'Ocp-Apim-Subscription-Key': options.subscriptionKey,
+            'Merchant-Serial-Number': options.merchantSerialNumber,
+            Authorization: `Bearer ${options.accessToken}`,
+        };
+        if (idempotencyKey)
+            h['Idempotency-Key'] = idempotencyKey;
+        return h;
+    }
+    async function post(path, body, idempotencyKey) {
+        const response = await fetchImpl(`${baseUrl}${path}`, {
+            method: 'POST',
+            headers: headers(idempotencyKey),
+            body: JSON.stringify(body),
+        });
+        const parsed = await response.json();
+        if (!response.ok) {
+            throw new PaymentProviderError('vipps', `HTTP ${response.status}`, {
+                status: response.status,
+                raw: parsed,
+            });
+        }
+        return parsed;
+    }
+    async function get(path) {
+        const response = await fetchImpl(`${baseUrl}${path}`, {
+            method: 'GET',
+            headers: headers(undefined),
+        });
+        const parsed = await response.json();
+        if (!response.ok) {
+            throw new PaymentProviderError('vipps', `HTTP ${response.status}`, {
+                status: response.status,
+                raw: parsed,
+            });
+        }
+        return parsed;
+    }
+    return {
+        name: 'vipps',
+        async createPayment(input) {
+            const payment = await post('/epayment/v1/payments', {
+                reference: input.reference,
+                amount: { value: input.amount.value, currency: input.amount.currency.toUpperCase() },
+                paymentMethod: { type: 'WALLET' },
+                userFlow: 'WEB_REDIRECT',
+                returnUrl: input.returnUrl,
+                paymentDescription: input.description,
+            }, input.idempotencyKey ?? input.reference);
+            return toPaymentResult(payment, input.amount);
+        },
+        async capturePayment(providerReference, input = {}) {
+            // Unlike Stripe, Vipps requires an explicit modification amount -- it
+            // has no "capture whatever was authorized" shortcut. A missing
+            // `input.amount` (v1's "full capture" convention) needs one extra
+            // lookup to find out what that amount is.
+            const amount = input.amount ??
+                (await get(`/epayment/v1/payments/${providerReference}`)).aggregate
+                    ?.authorizedAmount;
+            if (!amount) {
+                throw new PaymentProviderError('vipps', `payment ${providerReference} has no authorized amount to capture`);
+            }
+            const payment = await post(`/epayment/v1/payments/${providerReference}/capture`, { modificationAmount: { value: amount.value, currency: amount.currency.toUpperCase() } }, input.idempotencyKey);
+            // Defence in depth: never attribute the result to a different payment
+            // than the one this call actually captured, even if the response body
+            // claims otherwise.
+            if (payment.reference !== providerReference) {
+                throw new PaymentProviderError('vipps', `capture response reference "${payment.reference}" does not match the requested payment "${providerReference}"`, { raw: payment });
+            }
+            return toPaymentResult(payment, { value: amount.value, currency: amount.currency });
+        },
+        async refundPayment(providerReference, input = {}) {
+            const amount = input.amount ??
+                (await get(`/epayment/v1/payments/${providerReference}`)).aggregate
+                    ?.capturedAmount;
+            if (!amount) {
+                throw new PaymentProviderError('vipps', `payment ${providerReference} has no captured amount to refund`);
+            }
+            const payment = await post(`/epayment/v1/payments/${providerReference}/refund`, { modificationAmount: { value: amount.value, currency: amount.currency.toUpperCase() } }, input.idempotencyKey);
+            // Same integrity check as capturePayment, even though this method
+            // does not read `payment.reference` for its own output below --
+            // a mismatch here still means the response is not about the payment
+            // this call requested, which is worth failing loudly on.
+            if (payment.reference !== providerReference) {
+                throw new PaymentProviderError('vipps', `refund response reference "${payment.reference}" does not match the requested payment "${providerReference}"`, { raw: payment });
+            }
+            const status = derivePaymentStatus(payment);
+            return {
+                provider: 'vipps',
+                // Vipps' ePayment API returns the mutated payment resource, not a
+                // separate refund id -- there is nothing else to use as the refund's
+                // own reference. See the module doc comment.
+                refundReference: providerReference,
+                paymentReference: providerReference,
+                status: status === 'refunded' || status === 'partially_refunded' ? 'succeeded' : 'pending',
+                amount: toMoney(payment.aggregate?.refundedAmount, {
+                    value: amount.value,
+                    currency: amount.currency,
+                }),
+                raw: payment,
+            };
+        },
+        async createRecurringAgreement(input) {
+            const agreement = await post('/recurring/v3/agreements', {
+                pricing: {
+                    type: 'LEGACY',
+                    amount: input.amount.value,
+                    currency: input.amount.currency.toUpperCase(),
+                },
+                interval: {
+                    unit: (input.interval?.unit ?? 'month').toUpperCase(),
+                    count: input.interval?.count ?? 1,
+                },
+                productName: input.productName,
+                merchantRedirectUrl: input.returnUrl,
+                merchantAgreementUrl: input.managementUrl ?? input.returnUrl,
+            }, input.idempotencyKey ?? input.reference);
+            return {
+                provider: 'vipps',
+                agreementReference: agreement.agreementId,
+                // A freshly created agreement always starts unapproved: the payer
+                // has not yet confirmed it at `vippsConfirmationUrl`.
+                status: 'pending',
+                confirmationUrl: agreement.vippsConfirmationUrl,
+                raw: agreement,
+            };
+        },
+        async chargeRecurringAgreement(agreementReference, input) {
+            const charge = await post(`/recurring/v3/agreements/${agreementReference}/charges`, {
+                amount: input.amount.value,
+                currency: input.amount.currency.toUpperCase(),
+                transactionType: 'DIRECT_CAPTURE',
+                due: input.dueDate ?? tomorrowIsoDate(),
+                retryDays: 0,
+                description: input.description,
+            }, input.idempotencyKey);
+            return {
+                provider: 'vipps',
+                providerReference: charge.chargeId,
+                // Recurring charges are created, then processed asynchronously by
+                // Vipps -- there is no synchronous "it went through" in this
+                // response. The caller learns the outcome from a webhook or a GET.
+                status: 'pending',
+                amount: input.amount,
+                raw: charge,
+            };
+        },
+    };
+}
+const WEBHOOK_EVENT_NAME = {
+    CREATED: 'payment.created',
+    AUTHORIZED: 'payment.authorized',
+    CAPTURED: 'payment.captured',
+    CANCELLED: 'payment.cancelled',
+    TERMINATED: 'payment.cancelled',
+    REFUNDED: 'payment.refunded',
+    EXPIRED: 'payment.expired',
+    ABORTED: 'payment.cancelled',
+};
+/**
+ * Verifies a Vipps MobilePay webhook request, by hand, against the
+ * Azure-API-Management-style HMAC scheme documented at
+ * https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/request-authentication/
+ * (Vipps' webhook infrastructure runs on Azure APIM; there is no `v1=`/`t=`
+ * header the way Stripe has):
+ *
+ *   1. Recompute `sha256(rawBody)`, base64-encoded; it must match
+ *      `x-ms-content-sha256` (this also authenticates the body, not just
+ *      the headers).
+ *   2. Build the string-to-sign:
+ *      `"${method}\n${pathAndQuery}\n${xMsDate};${host};${xMsContentSha256}"`.
+ *   3. HMAC-SHA256(base64-decoded webhook secret, string-to-sign),
+ *      base64-encoded.
+ *   4. Constant-time compare to the `Signature=` value inside
+ *      `Authorization`; reject if `x-ms-date` is outside `toleranceSeconds`
+ *      of now.
+ *
+ * `method` and `pathAndQuery` must be exactly what Vipps signed: the HTTP
+ * method of the webhook request, and the request path plus query string
+ * (e.g. `"/webhooks/order-123"`), not a normalized or re-routed form of it.
+ */
+export function verifyVippsWebhook(rawBody, requestHeaders, webhookSecret, method, pathAndQuery, options = {}) {
+    const toleranceSeconds = options.toleranceSeconds ?? 300;
+    const now = options.now ?? Date.now;
+    const actualContentHash = sha256Base64(rawBody);
+    if (!safeEqual(actualContentHash, requestHeaders.xMsContentSha256)) {
+        throw new WebhookVerificationError('vipps', 'x-ms-content-sha256 does not match the request body');
+    }
+    const signatureMatch = /Signature=([^&]+)$/.exec(requestHeaders.authorization);
+    if (!signatureMatch) {
+        throw new WebhookVerificationError('vipps', 'Authorization header is missing a "Signature=" value');
+    }
+    const providedSignature = signatureMatch[1];
+    const stringToSign = [
+        method.toUpperCase(),
+        pathAndQuery,
+        `${requestHeaders.xMsDate};${requestHeaders.host};${requestHeaders.xMsContentSha256}`,
+    ].join('\n');
+    const expectedSignature = hmacSha256Base64(webhookSecret, stringToSign);
+    if (!safeEqual(providedSignature, expectedSignature)) {
+        throw new WebhookVerificationError('vipps', 'signature does not match the request');
+    }
+    const requestTimeMs = Date.parse(requestHeaders.xMsDate);
+    const ageSeconds = Math.abs((now() - requestTimeMs) / 1000);
+    if (!Number.isFinite(ageSeconds) || ageSeconds > toleranceSeconds) {
+        throw new WebhookVerificationError('vipps', `x-ms-date is ${Math.round(ageSeconds)}s old, outside the ${toleranceSeconds}s tolerance (possible replay)`);
+    }
+    let event;
+    try {
+        event = JSON.parse(rawBody);
+    }
+    catch {
+        throw new WebhookVerificationError('vipps', 'payload is not valid JSON');
+    }
+    const mapped = event.name ? WEBHOOK_EVENT_NAME[event.name] : undefined;
+    const type = event.success === false ? 'payment.failed' : (mapped ?? 'unknown');
+    return {
+        provider: 'vipps',
+        type,
+        eventId: event.idempotencyKey ??
+            `${event.reference ?? 'unknown'}:${event.name ?? 'unknown'}:${event.timestamp ?? ''}`,
+        paymentReference: event.reference ?? '',
+        amount: event.amount
+            ? { value: event.amount.value, currency: event.amount.currency.toUpperCase() }
+            : undefined,
+        raw: event,
+    };
+}

package/dist/webhook-crypto.d.ts

@@ -0,0 +1,16 @@
+/** Constant-time comparison of two strings of possibly-different length.
+ * `crypto.timingSafeEqual` throws on a length mismatch, which would itself
+ * leak timing information (a throw is fast; the real compare is not), so a
+ * length mismatch is treated as "not equal" up front rather than crashing
+ * or falling back to `===`. */
+export declare function safeEqual(a: string, b: string): boolean;
+/** hex-encoded HMAC-SHA256, as Stripe's `Stripe-Signature` header uses. */
+export declare function hmacSha256Hex(key: string, message: string): string;
+/** base64-encoded HMAC-SHA256, as Vipps' Azure-APIM-style `Authorization`
+ * header uses. `key` is the base64-encoded secret Vipps issues when a
+ * webhook is registered; it is decoded to raw bytes before use as the HMAC
+ * key, matching Azure API Management's HMAC validation scheme (Vipps'
+ * webhook infrastructure runs on APIM). */
+export declare function hmacSha256Base64(base64Key: string, message: string): string;
+/** base64-encoded SHA-256 of `body`, as Vipps' `x-ms-content-sha256` header carries. */
+export declare function sha256Base64(body: string): string;

package/dist/webhook-crypto.js

@@ -0,0 +1,35 @@
+/**
+ * Shared HMAC primitives for both adapters' webhook verification. Neither
+ * `stripe.ts` nor `vipps.ts` calls `node:crypto` directly outside this file,
+ * so the one place that must be correct is small and gets its own tests.
+ */
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+/** Constant-time comparison of two strings of possibly-different length.
+ * `crypto.timingSafeEqual` throws on a length mismatch, which would itself
+ * leak timing information (a throw is fast; the real compare is not), so a
+ * length mismatch is treated as "not equal" up front rather than crashing
+ * or falling back to `===`. */
+export function safeEqual(a, b) {
+    const bufA = Buffer.from(a, 'utf8');
+    const bufB = Buffer.from(b, 'utf8');
+    if (bufA.length !== bufB.length)
+        return false;
+    return timingSafeEqual(bufA, bufB);
+}
+/** hex-encoded HMAC-SHA256, as Stripe's `Stripe-Signature` header uses. */
+export function hmacSha256Hex(key, message) {
+    return createHmac('sha256', key).update(message, 'utf8').digest('hex');
+}
+/** base64-encoded HMAC-SHA256, as Vipps' Azure-APIM-style `Authorization`
+ * header uses. `key` is the base64-encoded secret Vipps issues when a
+ * webhook is registered; it is decoded to raw bytes before use as the HMAC
+ * key, matching Azure API Management's HMAC validation scheme (Vipps'
+ * webhook infrastructure runs on APIM). */
+export function hmacSha256Base64(base64Key, message) {
+    const keyBytes = Buffer.from(base64Key, 'base64');
+    return createHmac('sha256', keyBytes).update(message, 'utf8').digest('base64');
+}
+/** base64-encoded SHA-256 of `body`, as Vipps' `x-ms-content-sha256` header carries. */
+export function sha256Base64(body) {
+    return createHash('sha256').update(body, 'utf8').digest('base64');
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@wtfalch/payments",
+  "version": "0.1.0",
+  "description": "One PaymentProvider interface -- create a payment, capture, refund, set up and charge a recurring agreement, verify a webhook -- over Stripe and Vipps MobilePay. Holds no card data.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wtfalch/payments",
+    "directory": "packages/payments"
+  },
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.6"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}