@wtfalch/payments 0.3.0 → 0.4.0

package/README.md

@@ -42,6 +42,7 @@ const payment = await stripe.createPayment({
 ```ts
 await stripe.capturePayment(payment.providerReference); // full capture
 await stripe.refundPayment(payment.providerReference, { reason: 'requested_by_customer' });
+await stripe.cancelPayment(payment.providerReference); // a reserved, uncaptured payment
 ```
 
 ### Recurring agreements
@@ -68,12 +69,32 @@ await vipps.chargeRecurringAgreement(agreement.agreementReference, {
 // the payer approves it, or on a schedule) -- what refreshAgreementStatus
 // below calls under the hood.
 await vipps.getRecurringAgreement(agreement.agreementReference);
+
+// Stop it (e.g. Archon cancelling a company's subscription) and change its
+// price (a plan change). A caller also tracking this agreement in the store
+// below should follow stopRecurringAgreement with refreshAgreementStatus --
+// or let the resulting agreement.stopped webhook reach applyWebhookEvent --
+// to persist the transition; these two calls only reach the provider.
+await vipps.stopRecurringAgreement(agreement.agreementReference);
+await vipps.updateRecurringAgreement(agreement.agreementReference, {
+  amount: { value: 39900, currency: 'NOK' },
+});
+
+// Cancel a charge that was created but never settles (e.g. its period was
+// credited before it captured).
+await vipps.cancelRecurringCharge(agreement.agreementReference, chargeReference);
 ```
 
 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. `getRecurringAgreement` reads that same SetupIntent back.
+`stopRecurringAgreement` cancels that SetupIntent (there is no Subscription
+object here to cancel); `updateRecurringAgreement` keeps its
+`metadata[amount]` in sync, since a SetupIntent carries no real price of its
+own; `cancelRecurringCharge` cancels the PaymentIntent that
+`chargeRecurringAgreement` created (Stripe has no separate "recurring
+charge" resource).
 
 ### Store
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { CapturePaymentInput, ChargeRecurringAgreementInput, CreatePaymentInput, CreateRecurringAgreementInput, Money, NormalizedWebhookEvent, NormalizedWebhookEventType, PaymentResult, PaymentStatus, RecurringAgreementResult, RecurringAgreementStatus, RefundInput, RefundResult, } from './types.js';
+export type { CancelPaymentInput, CancelRecurringChargeInput, CapturePaymentInput, ChargeRecurringAgreementInput, CreatePaymentInput, CreateRecurringAgreementInput, Money, NormalizedWebhookEvent, NormalizedWebhookEventType, PaymentResult, PaymentStatus, RecurringAgreementResult, RecurringAgreementStatus, RefundInput, RefundResult, StopRecurringAgreementInput, UpdateRecurringAgreementInput, } from './types.js';
 export { PaymentProviderError, WebhookVerificationError } from './types.js';
 export type { PaymentProvider } from './provider.js';
 export type { FetchInit, FetchLike, FetchResponseLike } from './http.js';

package/dist/provider.d.ts

@@ -1,4 +1,4 @@
-import type { CapturePaymentInput, ChargeRecurringAgreementInput, CreatePaymentInput, CreateRecurringAgreementInput, PaymentResult, RecurringAgreementResult, RefundInput, RefundResult } from './types.js';
+import type { CancelPaymentInput, CancelRecurringChargeInput, CapturePaymentInput, ChargeRecurringAgreementInput, CreatePaymentInput, CreateRecurringAgreementInput, PaymentResult, RecurringAgreementResult, RefundInput, RefundResult, StopRecurringAgreementInput, UpdateRecurringAgreementInput } from './types.js';
 /**
  * One shape, two adapters (`createStripeProvider`, `createVippsProvider`).
  * Webhook verification is deliberately not a method here: it needs no
@@ -12,6 +12,13 @@ export interface PaymentProvider {
     createPayment(input: CreatePaymentInput): Promise<PaymentResult>;
     capturePayment(providerReference: string, input?: CapturePaymentInput): Promise<PaymentResult>;
     refundPayment(providerReference: string, input?: RefundInput): Promise<RefundResult>;
+    /** Cancels a reserved, uncaptured payment (Vipps: `POST
+     * /epayment/v1/payments/{reference}/cancel`; Stripe: `POST
+     * /payment_intents/{id}/cancel`) -- a payment this store has not yet
+     * captured, left otherwise for the payer to see until it expires. Throws
+     * `PaymentProviderError` if the payment is not in a cancelable state
+     * (already captured, refunded, or already canceled). */
+    cancelPayment(providerReference: string, input?: CancelPaymentInput): Promise<PaymentResult>;
     createRecurringAgreement(input: CreateRecurringAgreementInput): Promise<RecurringAgreementResult>;
     chargeRecurringAgreement(agreementReference: string, input: ChargeRecurringAgreementInput): Promise<PaymentResult>;
     /** The agreement's current status, read fresh from the provider -- what
@@ -19,4 +26,32 @@ export interface PaymentProvider {
      * since neither adapter's create call itself learns of a payer's later
      * approval/rejection (that arrives by webhook, or by polling this). */
     getRecurringAgreement(agreementReference: string): Promise<RecurringAgreementResult>;
+    /** Stops the agreement (Vipps: `PATCH /recurring/v3/agreements/{id}`,
+     * `status: STOPPED`, idempotent -- stopping an already-stopped agreement
+     * is a no-op; Stripe: cancelling the SetupIntent that backs this
+     * adapter's agreement, `POST /setup_intents/{id}/cancel`). A caller that
+     * also tracks this agreement in `store.ts` should follow this with
+     * `refreshAgreementStatus` (or let the resulting webhook --
+     * `agreement.stopped` -- reach `applyWebhookEvent`) to persist the
+     * transition; this call only reaches the provider. */
+    stopRecurringAgreement(agreementReference: string, input?: StopRecurringAgreementInput): Promise<RecurringAgreementResult>;
+    /** Changes the agreement's price (Vipps: the same `PATCH
+     * .../agreements/{id}` as `stopRecurringAgreement`, with `pricing.amount`;
+     * Stripe: updates the SetupIntent's own `metadata[amount]`, kept in sync
+     * for symmetry with Vipps -- see `UpdateRecurringAgreementInput`'s doc
+     * comment). Required so a later `chargeRecurringAgreement` above the
+     * agreement's old amount is not refused by the provider. */
+    updateRecurringAgreement(agreementReference: string, input: UpdateRecurringAgreementInput): Promise<RecurringAgreementResult>;
+    /** Cancels a pending/reserved recurring charge that has not yet been
+     * captured -- e.g. one created for a billing period that is then credited
+     * before it settles (Vipps: `DELETE
+     * /recurring/v3/agreements/{agreementId}/charges/{chargeId}`, permitted
+     * for a PENDING/DUE/RESERVED charge; Stripe: the charge is a PaymentIntent
+     * -- see `chargeRecurringAgreement`'s doc comment -- so this is the same
+     * PaymentIntent cancel `cancelPayment` makes). Neither vendor's response
+     * gives a body worth normalizing (Vipps: 202/204, no body; Stripe's body
+     * is discarded for symmetry) -- the caller learns the resulting status the
+     * same way `chargeRecurringAgreement`'s caller already does, via a webhook
+     * (`charge.canceled` / `payment.cancelled`) reaching `applyWebhookEvent`. */
+    cancelRecurringCharge(agreementReference: string, chargeReference: string, input?: CancelRecurringChargeInput): Promise<void>;
 }

package/dist/stripe.js

@@ -10,6 +10,16 @@ import { PaymentProviderError, WebhookVerificationError, } from './types.js';
  *   - https://docs.stripe.com/api/refunds/create
  *   - https://docs.stripe.com/api/setup_intents
  *   - https://docs.stripe.com/webhooks (manual signature verification)
+ *
+ * Re-fetched 2026-09-28 (still primary docs, no live calls) for
+ * `stopRecurringAgreement`/`cancelPayment`/`cancelRecurringCharge`
+ * (https://docs.stripe.com/api/setup_intents/cancel,
+ * https://docs.stripe.com/api/payment_intents/cancel) and
+ * `updateRecurringAgreement` (https://docs.stripe.com/api/setup_intents/update).
+ * This adapter's "recurring agreement" is a SetupIntent, not a Subscription
+ * (see `createRecurringAgreement`'s doc comment below) -- there is no
+ * Subscription object anywhere in this file, so its cancel/update endpoints
+ * are never the ones used here.
  */
 import { hmacSha256Hex, safeEqual } from './webhook-crypto.js';
 /** Form-urlencodes Stripe's `/v1` request bodies, including one level of
@@ -159,6 +169,18 @@ export function createStripeProvider(options) {
                 raw: refund,
             };
         },
+        async cancelPayment(providerReference, input = {}) {
+            // https://docs.stripe.com/api/payment_intents/cancel (fetched
+            // 2026-09-28). Cancelable from requires_payment_method,
+            // requires_capture, requires_confirmation, requires_action, or (rarely)
+            // processing -- Stripe itself refuses any other status.
+            const pi = await call(`/payment_intents/${providerReference}/cancel`, {}, input.idempotencyKey ?? `cnc:${providerReference}`);
+            // Same integrity check as capturePayment/refundPayment.
+            if (pi.id !== providerReference) {
+                throw new PaymentProviderError('stripe', `cancel response id "${pi.id}" does not match the requested payment "${providerReference}"`, { raw: pi });
+            }
+            return toPaymentResult(pi);
+        },
         async createRecurringAgreement(input) {
             // Vipps-only: a SetupIntent has no pricing type or cap to declare up
             // front -- it only saves a payment method, and the amount for each
@@ -212,6 +234,64 @@ export function createStripeProvider(options) {
                 raw: si,
             };
         },
+        async stopRecurringAgreement(agreementReference, input = {}) {
+            // https://docs.stripe.com/api/setup_intents/cancel (fetched
+            // 2026-09-28). This adapter's "recurring agreement" is a SetupIntent,
+            // not a Subscription (module doc comment) -- stopping it is cancelling
+            // that SetupIntent, the same transition `WEBHOOK_EVENT_TYPE`'s
+            // `setup_intent.canceled` -> `agreement.stopped` mapping already
+            // assumes. Cancelable only from requires_payment_method,
+            // requires_confirmation or requires_action; Stripe refuses any other
+            // status (e.g. an already-`succeeded` SetupIntent) with an error this
+            // call surfaces as `PaymentProviderError`.
+            const si = await call(`/setup_intents/${agreementReference}/cancel`, {}, input.idempotencyKey ?? `stop:${agreementReference}`);
+            if (si.id !== agreementReference) {
+                throw new PaymentProviderError('stripe', `cancel response id "${si.id}" does not match the requested agreement "${agreementReference}"`, { raw: si });
+            }
+            return {
+                provider: 'stripe',
+                agreementReference: si.id,
+                status: SETUP_INTENT_STATUS[si.status] ?? 'pending',
+                clientSecret: si.client_secret,
+                raw: si,
+            };
+        },
+        async updateRecurringAgreement(agreementReference, input) {
+            // https://docs.stripe.com/api/setup_intents/update (fetched
+            // 2026-09-28). A SetupIntent has no price of its own to change (module
+            // doc comment) -- this keeps `metadata[amount]`/`metadata[currency]`
+            // (set at `createRecurringAgreement` time, for symmetry with Vipps) in
+            // sync with a caller's own plan/price change; `chargeRecurringAgreement`
+            // always reads its charge amount from its own caller, never from here,
+            // so this has no effect on what a later charge actually bills.
+            const si = await call(`/setup_intents/${agreementReference}`, {
+                'metadata[amount]': input.amount.value,
+                'metadata[currency]': input.amount.currency.toUpperCase(),
+            }, input.idempotencyKey ??
+                `upd:${agreementReference}:${input.amount.value}:${input.amount.currency.toUpperCase()}`);
+            if (si.id !== agreementReference) {
+                throw new PaymentProviderError('stripe', `update response id "${si.id}" does not match the requested agreement "${agreementReference}"`, { raw: si });
+            }
+            return {
+                provider: 'stripe',
+                agreementReference: si.id,
+                status: SETUP_INTENT_STATUS[si.status] ?? 'pending',
+                clientSecret: si.client_secret,
+                raw: si,
+            };
+        },
+        async cancelRecurringCharge(_agreementReference, chargeReference, input = {}) {
+            // A recurring charge is a PaymentIntent here (`chargeRecurringAgreement`'s
+            // doc comment) -- Stripe has no separate "recurring charge" resource
+            // the way Vipps' Recurring API does, so cancelling one is the same
+            // PaymentIntent cancel call `cancelPayment` makes.
+            // https://docs.stripe.com/api/payment_intents/cancel (fetched
+            // 2026-09-28).
+            const pi = await call(`/payment_intents/${chargeReference}/cancel`, {}, input.idempotencyKey ?? `dch:${chargeReference}`);
+            if (pi.id !== chargeReference) {
+                throw new PaymentProviderError('stripe', `cancel response id "${pi.id}" does not match the requested charge "${chargeReference}"`, { raw: pi });
+            }
+        },
     };
 }
 const WEBHOOK_EVENT_TYPE = {

package/dist/types.d.ts

@@ -37,6 +37,9 @@ export interface RefundInput {
     readonly reason?: 'duplicate' | 'fraudulent' | 'requested_by_customer';
     readonly idempotencyKey?: string;
 }
+export interface CancelPaymentInput {
+    readonly idempotencyKey?: string;
+}
 export interface PaymentResult {
     readonly provider: 'stripe' | 'vipps';
     /** The provider's own identifier for this payment (Stripe: PaymentIntent
@@ -114,6 +117,24 @@ export interface ChargeRecurringAgreementInput {
     readonly dueDate?: string;
     readonly idempotencyKey?: string;
 }
+export interface StopRecurringAgreementInput {
+    readonly idempotencyKey?: string;
+}
+/** A plan/price change to an existing agreement. Vipps: `PATCH
+ * /recurring/v3/agreements/{id}` with `pricing.amount` (the LEGACY fixed
+ * price) -- see `updateRecurringAgreement`'s doc comment on each adapter for
+ * why a VARIABLE or FLEXIBLE agreement's payer-driven cap is not covered by
+ * this input, and why Vipps refuses this update outright on either. Stripe:
+ * no price lives on a SetupIntent, so this keeps its
+ * `metadata[amount]`/`metadata[currency]` (set at `createRecurringAgreement`
+ * time, for symmetry with Vipps) in sync with a caller's own plan change. */
+export interface UpdateRecurringAgreementInput {
+    readonly amount: Money;
+    readonly idempotencyKey?: string;
+}
+export interface CancelRecurringChargeInput {
+    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.
@@ -152,9 +173,18 @@ export declare class PaymentProviderError extends Error {
     readonly provider: 'stripe' | 'vipps';
     readonly status?: number;
     readonly raw?: unknown;
+    /** A narrow, provider-adapter-defined tag for a failure a caller needs to
+     * distinguish from an ordinary provider-call failure -- e.g. Vipps'
+     * `cancelPayment` sets `'cancel_amount_unknown'` when a cancel went
+     * through but no amount could be read even after re-reading the payment,
+     * so a caller can tell that apart from "the cancel itself failed" instead
+     * of both looking like the same generic error. Absent on a plain HTTP/network
+     * failure. */
+    readonly code?: string;
     constructor(provider: 'stripe' | 'vipps', message: string, options?: {
         status?: number;
         raw?: unknown;
+        code?: string;
     });
 }
 /** A webhook payload failed to verify: missing/malformed signature header,

package/dist/types.js

@@ -10,12 +10,21 @@ export class PaymentProviderError extends Error {
     provider;
     status;
     raw;
+    /** A narrow, provider-adapter-defined tag for a failure a caller needs to
+     * distinguish from an ordinary provider-call failure -- e.g. Vipps'
+     * `cancelPayment` sets `'cancel_amount_unknown'` when a cancel went
+     * through but no amount could be read even after re-reading the payment,
+     * so a caller can tell that apart from "the cancel itself failed" instead
+     * of both looking like the same generic error. Absent on a plain HTTP/network
+     * failure. */
+    code;
     constructor(provider, message, options = {}) {
         super(`payments(${provider}): ${message}`);
         this.name = 'PaymentProviderError';
         this.provider = provider;
         this.status = options.status;
         this.raw = options.raw;
+        this.code = options.code;
     }
 }
 /** A webhook payload failed to verify: missing/malformed signature header,

package/dist/vipps.js

@@ -13,6 +13,12 @@ import { PaymentProviderError, WebhookVerificationError, } from './types.js';
  *   - https://developer.vippsmobilepay.com/docs/knowledge-base/across-borders/ (Nordic markets)
  *   - https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide/
  *
+ * Re-fetched 2026-09-28 (still primary docs, no live calls) for
+ * `stopRecurringAgreement`/`updateRecurringAgreement` (`PATCH
+ * /recurring/v3/agreements/{id}`), `cancelRecurringCharge` (`DELETE
+ * /recurring/v3/agreements/{id}/charges/{chargeId}`) and `cancelPayment`
+ * (`POST /epayment/v1/payments/{reference}/cancel`) -- same two URLs above.
+ *
  * One Recurring/ePayment API serves all three Nordic markets (see
  * docs/adr/0006-payment-store.md's "MobilePay" section and this package's
  * README, "MobilePay (Denmark, Finland)"): same base URL, same headers, same
@@ -209,6 +215,68 @@ export function createVippsProvider(options) {
         }
         return parsed;
     }
+    /** Reads any error body a non-2xx response carries, but never throws on a
+     * body that fails to parse (used by `patch`/`del` below, whose *success*
+     * responses are documented as empty -- see each call site). */
+    async function readErrorBody(response) {
+        try {
+            return await response.json();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** `PATCH /recurring/v3/agreements/{id}` (`stopRecurringAgreement`,
+     * `updateRecurringAgreement`) documents a `204 No Content` success
+     * response -- https://developer.vippsmobilepay.com/api/recurring/
+     * (fetched 2026-09-28) -- so this never calls `response.json()` on the
+     * success path, unlike `post`/`get` above. */
+    async function patch(path, body, idempotencyKey) {
+        const response = await fetchImpl(`${baseUrl}${path}`, {
+            method: 'PATCH',
+            headers: await resolveHeaders(idempotencyKey),
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok) {
+            throw new PaymentProviderError('vipps', `HTTP ${response.status}`, {
+                status: response.status,
+                raw: await readErrorBody(response),
+            });
+        }
+    }
+    /** `DELETE /recurring/v3/agreements/{id}/charges/{chargeId}`
+     * (`cancelRecurringCharge`) documents a `202 Accepted`/`204 No Content`
+     * success response with no body -- same source and fetch date as `patch`
+     * above. */
+    async function del(path, idempotencyKey) {
+        const response = await fetchImpl(`${baseUrl}${path}`, {
+            method: 'DELETE',
+            headers: await resolveHeaders(idempotencyKey),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok) {
+            throw new PaymentProviderError('vipps', `HTTP ${response.status}`, {
+                status: response.status,
+                raw: await readErrorBody(response),
+            });
+        }
+    }
+    /** Shared by `getRecurringAgreement` and the two `PATCH .../agreements`
+     * calls (`stopRecurringAgreement`, `updateRecurringAgreement`), neither of
+     * which gets its resulting status back in its own (empty) response body --
+     * both re-read the agreement the same way `getRecurringAgreement` always
+     * has. */
+    async function fetchAgreement(agreementReference) {
+        const agreement = await get(`/recurring/v3/agreements/${agreementReference}`);
+        return {
+            provider: 'vipps',
+            agreementReference: agreement.id,
+            status: (agreement.status ? AGREEMENT_STATUS[agreement.status] : undefined) ?? 'pending',
+            confirmationUrl: agreement.vippsConfirmationUrl,
+            raw: agreement,
+        };
+    }
     return {
         name: 'vipps',
         async createPayment(input) {
@@ -273,6 +341,39 @@ export function createVippsProvider(options) {
                 raw: payment,
             };
         },
+        async cancelPayment(providerReference, input = {}) {
+            // POST /epayment/v1/payments/{reference}/cancel --
+            // https://developer.vippsmobilepay.com/api/epayment/ (fetched
+            // 2026-09-28). Cancels a reserved, uncaptured payment; Vipps does not
+            // document an Idempotency-Key requirement here (unlike capture/refund),
+            // but this adapter still sends one, consistent with every other
+            // mutating call in this package.
+            const payment = await post(`/epayment/v1/payments/${providerReference}/cancel`, {}, input.idempotencyKey ?? `cnc:${providerReference}`);
+            // Same integrity check as capturePayment/refundPayment.
+            if (payment.reference !== providerReference) {
+                throw new PaymentProviderError('vipps', `cancel response reference "${payment.reference}" does not match the requested payment "${providerReference}"`, { raw: payment });
+            }
+            // The cancel response does not always carry an amount (neither
+            // `amount` nor `aggregate.authorizedAmount`) -- when it does not,
+            // re-read the payment rather than assume Vipps left it as-is. If the
+            // re-read also has no amount, a caller must never read a made-up
+            // amount as if Vipps reported it: a defaulted 0/NOK is simply wrong
+            // for a EUR or DKK merchant. Throw instead, with a distinct `code` so
+            // a caller can tell "cancelled, amount unknown, re-read later" apart
+            // from a plain cancel failure.
+            const resolved = (payment.amount ?? payment.aggregate?.authorizedAmount)
+                ? payment
+                : await get(`/epayment/v1/payments/${providerReference}`);
+            const knownAmount = resolved.amount ?? resolved.aggregate?.authorizedAmount;
+            if (!knownAmount) {
+                throw new PaymentProviderError('vipps', `cancel response for payment ${providerReference} carries no amount to report, even after re-reading the payment`, { raw: resolved, code: 'cancel_amount_unknown' });
+            }
+            const fallback = {
+                value: knownAmount.value,
+                currency: knownAmount.currency.toUpperCase(),
+            };
+            return toPaymentResult(resolved, fallback);
+        },
         async createRecurringAgreement(input) {
             // pricing.type LEGACY (fixed amount) vs VARIABLE (suggestedMaxAmount,
             // no fixed amount): https://developer.vippsmobilepay.com/api/recurring/
@@ -335,14 +436,72 @@ export function createVippsProvider(options) {
             };
         },
         async getRecurringAgreement(agreementReference) {
-            const agreement = await get(`/recurring/v3/agreements/${agreementReference}`);
-            return {
-                provider: 'vipps',
-                agreementReference: agreement.agreementId,
-                status: (agreement.status ? AGREEMENT_STATUS[agreement.status] : undefined) ?? 'pending',
-                confirmationUrl: agreement.vippsConfirmationUrl,
-                raw: agreement,
-            };
+            return fetchAgreement(agreementReference);
+        },
+        async stopRecurringAgreement(agreementReference, input = {}) {
+            // PATCH /recurring/v3/agreements/{id}, { status: 'STOPPED' } --
+            // https://developer.vippsmobilepay.com/api/recurring/ (fetched
+            // 2026-09-28). Idempotent on Vipps' side: stopping an already-STOPPED
+            // agreement returns 204 with no further effect. The response has no
+            // body, so this reads the resulting status back the same way
+            // `getRecurringAgreement` always has.
+            await patch(`/recurring/v3/agreements/${agreementReference}`, { status: 'STOPPED' }, input.idempotencyKey ?? `stop:${agreementReference}`);
+            return fetchAgreement(agreementReference);
+        },
+        async updateRecurringAgreement(agreementReference, input) {
+            // Same PATCH endpoint as stopRecurringAgreement. The update body's
+            // `pricing` is `UpdateAgreementPricingRequest` in Vipps' own Recurring
+            // v3 OpenAPI spec (recurring-swagger-id.yaml, "Recurring Payments
+            // Merchant API" 3.2.3, fetched 2026-09-29 from
+            // https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml,
+            // linked from https://developer.vippsmobilepay.com/api/recurring/):
+            //
+            //   PricingUpdateRequest:
+            //     title: UpdateAgreementPricingRequest
+            //     type: object
+            //     properties:
+            //       amount: { type: integer, ... }
+            //       suggestedMaxAmount: { type: integer, ... }
+            //
+            // No `currency`, no `type` -- unlike `PricingRequestV3` (create), which
+            // requires both. An agreement's currency is fixed at creation and
+            // cannot be changed through this endpoint, so this checks the
+            // agreement's current currency (from a GET, `pricing.currency` on
+            // `AgreementResponseV3`) before sending anything, and refuses a
+            // currency change with a clear `PaymentProviderError` instead of
+            // sending a field Vipps' spec does not list and getting back a 400.
+            // This is the LEGACY (fixed-price) `amount` field; a VARIABLE
+            // agreement's `suggestedMaxAmount` cap is a separate, payer-driven
+            // value this method does not touch -- see
+            // `UpdateRecurringAgreementInput`'s doc comment. Vipps itself refuses
+            // (400) a price change on a stopped agreement; this adapter does not
+            // duplicate that check. It does refuse anything but a LEGACY
+            // agreement below, because Vipps applies `pricing.amount` only to a
+            // LEGACY one -- a PATCH against a VARIABLE or FLEXIBLE agreement
+            // returns 204 and changes nothing, which would otherwise read to this
+            // method's caller as a silent no-op success.
+            const nextCurrency = input.amount.currency.toUpperCase();
+            const current = await get(`/recurring/v3/agreements/${agreementReference}`);
+            if (current.pricing?.type !== 'LEGACY') {
+                throw new PaymentProviderError('vipps', `agreement ${agreementReference} has pricing.type "${current.pricing?.type ?? 'unknown'}"; updateRecurringAgreement's amount can only be updated on a LEGACY agreement`, { raw: current });
+            }
+            const currentCurrency = current.pricing?.currency?.toUpperCase();
+            if (currentCurrency && currentCurrency !== nextCurrency) {
+                throw new PaymentProviderError('vipps', `agreement ${agreementReference} is priced in ${currentCurrency}; updateRecurringAgreement cannot change its currency to ${nextCurrency} (Vipps’ update-agreement pricing body takes amount only)`, { raw: current });
+            }
+            await patch(`/recurring/v3/agreements/${agreementReference}`, { pricing: { amount: input.amount.value } }, input.idempotencyKey ?? `upd:${agreementReference}:${input.amount.value}:${nextCurrency}`);
+            return fetchAgreement(agreementReference);
+        },
+        async cancelRecurringCharge(agreementReference, chargeReference, input = {}) {
+            // DELETE /recurring/v3/agreements/{agreementId}/charges/{chargeId} --
+            // https://developer.vippsmobilepay.com/api/recurring/ (fetched
+            // 2026-09-28). Permitted for a PENDING/DUE/RESERVED charge; a
+            // PARTIALLY_CAPTURED charge has its remaining funds released back to
+            // the payer. Returns 202/204 with no body -- the caller learns the
+            // outcome via the resulting `recurring.charge-canceled.v1` webhook
+            // (`charge.canceled`, already wired to `applyWebhookEvent`), the same
+            // way a created charge's own outcome already arrives.
+            await del(`/recurring/v3/agreements/${agreementReference}/charges/${chargeReference}`, input.idempotencyKey ?? `dch:${chargeReference}`);
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/payments",
-  "version": "0.3.0",
+  "version": "0.4.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, plus a provider-neutral Postgres store for agreements and charges. Holds no card data.",
   "repository": {
     "type": "git",