@myzonerocks/pact 0.1.3 → 0.1.6

package/src/adapters/mpesa.ts

@@ -9,6 +9,7 @@ import { Money } from "../money.js";
 import { State } from "../state.js";
 import type { Quote, Authorization, Settlement } from "../message.js";
 import { RefundKind, type AdapterEvent } from "../adapter.js";
+import { fetchWithTimeout } from "./http.js";
 import type {
   PayInLeg,
   PayOutLeg,
@@ -52,6 +53,10 @@ export interface B2CParams {
   phone: string;
   reference: string;
   remarks: string;
+  // Same across retries of one logical transfer and distinct between different
+  // transfers on the same intent (a payout versus a refund), so Daraja collapses a
+  // retry but never merges two separate movements.
+  idempotencyKey: string;
 }
 
 // B2CResult is what Daraja returns when a payout is accepted for delivery.
@@ -60,22 +65,61 @@ export interface B2CResult {
   responseCode: string;
 }
 
+// StkQueryResult is the authoritative outcome of a push, read back from Daraja by
+// its checkout id. pending means Daraja is still processing and the outcome isn't
+// known yet; otherwise resultCode 0 is success and any other code is a failure.
+export interface StkQueryResult {
+  resultCode: number;
+  resultDesc: string;
+  pending: boolean;
+}
+
 // DarajaApi is the surface of Daraja this leg depends on. Depending on an
 // interface keeps the leg unit-testable without a network and without
 // credentials.
 export interface DarajaApi {
   stkPush(params: StkPushParams): Promise<StkPushResult>;
   b2cPayment(params: B2CParams): Promise<B2CResult>;
+  // query reads a push's real outcome back from Daraja by its checkout id. The
+  // STK callback is unsigned, so this authenticated read — not the callback body
+  // — is what a settlement is trusted to.
+  query(checkoutRequestId: string): Promise<StkQueryResult>;
 }
 
-// push remembers what settling an STK collection needs between initiating it and
-// the unsigned callback that reports its outcome: the intent, the payer to
-// refund, the amount, and the last state the callback recorded.
-interface PushRecord {
+// PushRecord is what settling or refunding an M-Pesa collection needs after the STK
+// push: the intent, the checkout id the unsigned callback arrives under, the payer to
+// refund, and the amount authorized.
+export interface PushRecord {
   intentId: string;
+  checkoutId: string;
   payerPhone: string;
   amount: number;
-  state: State;
+}
+
+// PushStore holds push records between initiating a collection and the callback that
+// resolves it. The default store keeps them in memory; a deployment that runs more than
+// one instance, or must survive a restart with collections in flight, supplies a
+// durable one so a callback never arrives to find its checkout forgotten.
+export interface PushStore {
+  save(rec: PushRecord): Promise<void>;
+  byIntent(intentId: string): Promise<PushRecord | undefined>;
+  byCheckout(checkoutId: string): Promise<PushRecord | undefined>;
+}
+
+// MemoryPushStore is the default in-process store.
+export class MemoryPushStore implements PushStore {
+  private readonly byIntentMap = new Map<string, PushRecord>();
+  private readonly byCheckoutMap = new Map<string, PushRecord>();
+  async save(rec: PushRecord): Promise<void> {
+    this.byIntentMap.set(rec.intentId, rec);
+    if (rec.checkoutId) this.byCheckoutMap.set(rec.checkoutId, rec);
+  }
+  async byIntent(intentId: string): Promise<PushRecord | undefined> {
+    return this.byIntentMap.get(intentId);
+  }
+  async byCheckout(checkoutId: string): Promise<PushRecord | undefined> {
+    return this.byCheckoutMap.get(checkoutId);
+  }
 }
 
 export interface MpesaConfig {
@@ -83,6 +127,9 @@ export interface MpesaConfig {
   api: DarajaApi;
   callbackURL: string;
   ids: () => string;
+  // Store persists push records; defaults to an in-memory store. A deployment that
+  // scales beyond one instance or must survive a restart supplies a durable one.
+  store?: PushStore;
 }
 
 // MpesaLeg moves mobile money over M-Pesa.
@@ -92,8 +139,7 @@ export class MpesaLeg implements PayInLeg, PayOutLeg {
   private readonly callbackURL: string;
   private readonly ids: () => string;
 
-  private readonly byIntent = new Map<string, PushRecord>();
-  private readonly byCheckout = new Map<string, PushRecord>();
+  private readonly store: PushStore;
 
   constructor(cfg: MpesaConfig) {
     if (!cfg.callbackURL) {
@@ -103,6 +149,7 @@ export class MpesaLeg implements PayInLeg, PayOutLeg {
     this.api = cfg.api;
     this.callbackURL = cfg.callbackURL;
     this.ids = cfg.ids;
+    this.store = cfg.store ?? new MemoryPushStore();
   }
 
   payInCapabilities(): PayInCapabilities {
@@ -126,7 +173,6 @@ export class MpesaLeg implements PayInLeg, PayOutLeg {
     if (!phone) {
       throw new Error("mpesa: collect requires the payer's phone");
     }
-    const rec: PushRecord = { intentId, payerPhone: phone, amount, state: State.Unspecified };
     const result = await this.api.stkPush({
       amount,
       payerPhone: phone,
@@ -134,8 +180,7 @@ export class MpesaLeg implements PayInLeg, PayOutLeg {
       description: "payment",
       callbackURL: this.callbackURL,
     });
-    this.byIntent.set(intentId, rec);
-    this.byCheckout.set(result.checkoutRequestId, rec);
+    await this.store.save({ intentId, checkoutId: result.checkoutRequestId, payerPhone: phone, amount });
     return { providerRef: result.checkoutRequestId, received: net };
   }
 
@@ -147,26 +192,32 @@ export class MpesaLeg implements PayInLeg, PayOutLeg {
     if (!phone) {
       throw new Error("mpesa: disburse requires the recipient's phone");
     }
-    const result = await this.api.b2cPayment({ amount, phone, reference: intentId, remarks: "payout" });
+    const result = await this.api.b2cPayment({ amount, phone, reference: intentId, remarks: "payout", idempotencyKey: `pact:payout:${intentId}` });
     return { providerRef: result.conversationId };
   }
 
   // refundIn answers a collected payment with a business-to-customer payout back
   // to the payer. An STK collection cannot be reversed in place, so a
   // counter-transfer is the only refund this rail supports.
-  async refundIn(intentId: string, kind: RefundKind, reason: string): Promise<Settlement> {
+  async refundIn(intentId: string, kind: RefundKind, amount: Money, reason: string): Promise<Settlement> {
     if (kind !== RefundKind.CounterTransfer) {
       throw new Error("mpesa: a collection can only be refunded by counter-transfer");
     }
-    const rec = this.byIntent.get(intentId);
+    const shillings = wholeShillings(amount);
+    const rec = await this.store.byIntent(intentId);
     if (!rec) {
       throw new Error(`mpesa: no push for intent ${intentId}`);
     }
+    // A refund cannot return more shillings than the push collected.
+    if (shillings > rec.amount) {
+      throw new Error(`mpesa: refund of ${shillings} exceeds the ${rec.amount} collected`);
+    }
     const result = await this.api.b2cPayment({
-      amount: rec.amount,
+      amount: shillings,
       phone: rec.payerPhone,
       reference: intentId,
       remarks: reason,
+      idempotencyKey: `pact:refund:${intentId}`,
     });
     return {
       intentId,
@@ -187,34 +238,46 @@ export class MpesaLeg implements PayInLeg, PayOutLeg {
   }
 
   // parseWebhook reads an STK callback and normalizes it into a protocol event.
-  // The callback is unsigned, so it is authenticated by matching its checkout id
-  // to a push this leg started; an unrecognized id is refused. The headers are
-  // accepted for interface symmetry and for a host that adds its own IP or
-  // shared-secret gate on top.
-  parseWebhook(raw: Uint8Array, _headers: Record<string, string[]>): AdapterEvent[] {
+  // The callback is unsigned and its CheckoutRequestID is a value we hand back to
+  // the caller — not a secret — so the callback body is treated only as a nudge.
+  // The real outcome is read back from Daraja with our own credentials, and a
+  // settlement is emitted only when that authenticated query confirms success and
+  // the amount Daraja paid equals the amount we authorized. The headers are
+  // accepted for interface symmetry and for a host that adds its own gate on top.
+  async parseWebhook(raw: Uint8Array, _headers: Record<string, string[]>): Promise<AdapterEvent[]> {
     const envelope = JSON.parse(new TextDecoder().decode(raw)) as StkCallbackEnvelope;
     const cb = envelope.Body?.stkCallback;
-    const rec = cb ? this.byCheckout.get(cb.CheckoutRequestID) : undefined;
+    const rec = cb ? await this.store.byCheckout(cb.CheckoutRequestID) : undefined;
     if (!cb || !rec) {
       throw new Error(ErrUnknownCheckout);
     }
 
-    if (cb.ResultCode !== 0) {
-      rec.state = State.Failed;
+    const confirmed = await this.api.query(cb.CheckoutRequestID);
+    // No outcome yet — wait for a later callback rather than settling or failing
+    // on an unconfirmed body.
+    if (confirmed.pending) {
+      return [];
+    }
+    if (confirmed.resultCode !== 0) {
       return [
         {
           intentId: rec.intentId,
           state: State.Failed,
           providerTxRef: cb.CheckoutRequestID,
           onchainTxHash: "",
-          reason: cb.ResultDesc ?? "",
+          reason: confirmed.resultDesc,
           settledAt: 0,
         },
       ];
     }
+    // The amount Daraja collected must equal the amount we authorized; a partial
+    // or tampered collection settles nothing.
+    const paid = metadataInt(cb.CallbackMetadata?.Item ?? [], "Amount");
+    if (paid !== rec.amount) {
+      throw new Error(`mpesa: confirmed amount ${paid} does not match the authorized ${rec.amount}`);
+    }
 
     const receipt = metadataString(cb.CallbackMetadata?.Item ?? [], "MpesaReceiptNumber");
-    rec.state = State.Settled;
     return [
       {
         intentId: rec.intentId,
@@ -258,6 +321,20 @@ function wholeShillings(m: Money): number {
   return Number(amount);
 }
 
+// metadataInt pulls a named numeric value out of the callback metadata items,
+// used to read the paid Amount. M-Pesa amounts are whole shillings but may arrive
+// as a number with a fractional part, so it is floored to the shilling.
+function metadataInt(items: StkCallbackItem[], name: string): number {
+  for (const item of items) {
+    if (item.Name !== name) {
+      continue;
+    }
+    const n = Number(item.Value);
+    return Number.isFinite(n) ? Math.floor(n) : 0;
+  }
+  return 0;
+}
+
 // metadataString pulls a named string value out of the callback metadata items.
 function metadataString(items: StkCallbackItem[], name: string): string {
   for (const item of items) {
@@ -301,6 +378,8 @@ class HttpDarajaApi implements DarajaApi {
   private readonly creds: Credentials;
   private readonly baseURL: string;
   private readonly now: () => Date;
+  private cachedToken = "";
+  private tokenExpiryMs = 0;
 
   constructor(creds: Credentials, now: () => Date) {
     this.creds = creds;
@@ -309,16 +388,25 @@ class HttpDarajaApi implements DarajaApi {
   }
 
   private async token(): Promise<string> {
+    // Reuse the cached token until it is within a minute of expiry, so a burst of
+    // pushes does not re-authenticate against Daraja on every call.
+    if (this.cachedToken && this.now().getTime() < this.tokenExpiryMs - 60_000) {
+      return this.cachedToken;
+    }
     const basic = Buffer.from(`${this.creds.consumerKey}:${this.creds.consumerSecret}`).toString("base64");
-    const resp = await fetch(`${this.baseURL}/oauth/v1/generate?grant_type=client_credentials`, {
+    const resp = await fetchWithTimeout(`${this.baseURL}/oauth/v1/generate?grant_type=client_credentials`, {
       method: "GET",
       headers: { Authorization: `Basic ${basic}` },
     });
     if (resp.status >= 300) {
       throw new Error(`mpesa: /oauth/v1/generate returned ${resp.status}`);
     }
-    const out = (await resp.json()) as { access_token?: string };
-    return out.access_token ?? "";
+    const out = (await resp.json()) as { access_token?: string; expires_in?: string | number };
+    // Daraja tokens live an hour; fall back to that if the field is absent.
+    const ttlSeconds = Number(out.expires_in) > 0 ? Number(out.expires_in) : 3599;
+    this.cachedToken = out.access_token ?? "";
+    this.tokenExpiryMs = this.now().getTime() + ttlSeconds * 1000;
+    return this.cachedToken;
   }
 
   // password is the base64 of shortcode+passkey+timestamp Daraja requires on each
@@ -355,9 +443,41 @@ class HttpDarajaApi implements DarajaApi {
     };
   }
 
+  async query(checkoutRequestId: string): Promise<StkQueryResult> {
+    const token = await this.token();
+    const timestamp = formatTimestamp(this.now());
+    const body = {
+      BusinessShortCode: this.creds.shortCode,
+      Password: this.password(timestamp),
+      Timestamp: timestamp,
+      CheckoutRequestID: checkoutRequestId,
+    };
+    const resp = await fetchWithTimeout(this.baseURL + "/mpesa/stkpushquery/v1/query", {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+      body: JSON.stringify(body),
+    });
+    const out = (await resp.json()) as {
+      ResultCode?: string;
+      ResultDesc?: string;
+      errorCode?: string;
+    };
+    // Daraja answers a query for a push it is still processing with an error code
+    // rather than a result; treat that as pending so the outcome is confirmed on a
+    // later query rather than mistaken for a failure.
+    if (out.errorCode === "500.001.1001") {
+      return { resultCode: 0, resultDesc: "", pending: true };
+    }
+    if (resp.status >= 300) {
+      throw new Error(`mpesa: stk query returned ${resp.status}`);
+    }
+    return { resultCode: Number(out.ResultCode ?? -1), resultDesc: out.ResultDesc ?? "", pending: false };
+  }
+
   async b2cPayment(params: B2CParams): Promise<B2CResult> {
     const token = await this.token();
     const body = {
+      OriginatorConversationID: params.idempotencyKey,
       InitiatorName: this.creds.shortCode,
       CommandID: "BusinessPayment",
       Amount: params.amount,
@@ -375,7 +495,7 @@ class HttpDarajaApi implements DarajaApi {
   }
 
   private async postJSON<T>(token: string, path: string, body: unknown): Promise<T> {
-    const resp = await fetch(this.baseURL + path, {
+    const resp = await fetchWithTimeout(this.baseURL + path, {
       method: "POST",
       headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
       body: JSON.stringify(body),

package/src/adapters/paypal.ts

@@ -5,8 +5,11 @@
 // Venmo flow client-side; this package never sees card data. A captured payment
 // can be refunded in full, but a delivered payout cannot be pulled back.
 import { State } from "../state.js";
+import type { Money } from "../money.js";
 import type { Quote, Authorization, Settlement } from "../message.js";
 import { RefundKind, type AdapterEvent } from "../adapter.js";
+import { idempotencyKey } from "../protocol.js";
+import { fetchWithTimeout } from "./http.js";
 import type {
   PayOutLeg,
   InteractivePayInLeg,
@@ -78,6 +81,10 @@ export interface Payout {
 export interface RefundParams {
   captureId: string;
   reason: string;
+  // value and currencyCode name a partial refund in major units; both absent
+  // refunds the full capture.
+  value?: string;
+  currencyCode?: string;
 }
 
 // Refund is the result of refunding a capture.
@@ -106,6 +113,37 @@ export interface PaypalConfig {
   currencies: string[];
   api: PaypalApi;
   ids: () => string;
+  // Store persists capture records; defaults to an in-memory store. A deployment that
+  // scales beyond one instance or must survive a restart supplies a durable one.
+  store?: CaptureStore;
+}
+
+// CaptureRecord is what settling or refunding a PayPal collection needs: the intent,
+// the capture id a refund binds to (empty until a server-side capture returns one),
+// and the amount the intent was quoted to collect.
+export interface CaptureRecord {
+  intentId: string;
+  captureId: string;
+  expected: { value: string; currency: string };
+}
+
+// CaptureStore holds capture records between creating an order and the webhook that
+// resolves it. The default keeps them in memory; a durable one lets a capture webhook
+// resolve across a restart or on a second instance.
+export interface CaptureStore {
+  save(rec: CaptureRecord): Promise<void>;
+  byIntent(intentId: string): Promise<CaptureRecord | undefined>;
+}
+
+// MemoryCaptureStore is the default in-process store.
+export class MemoryCaptureStore implements CaptureStore {
+  private readonly byIntentMap = new Map<string, CaptureRecord>();
+  async save(rec: CaptureRecord): Promise<void> {
+    this.byIntentMap.set(rec.intentId, rec);
+  }
+  async byIntent(intentId: string): Promise<CaptureRecord | undefined> {
+    return this.byIntentMap.get(intentId);
+  }
 }
 
 // PaypalLeg moves money over PayPal, serving both sides of a corridor.
@@ -114,13 +152,14 @@ export class PaypalLeg implements InteractivePayInLeg, PayOutLeg {
   private readonly currencies: string[];
   private readonly api: PaypalApi;
   private readonly ids: () => string;
-  private readonly captures = new Map<string, string>();
+  private readonly store: CaptureStore;
 
   constructor(cfg: PaypalConfig) {
     this.id = cfg.id ?? "paypal";
     this.currencies = cfg.currencies;
     this.api = cfg.api;
     this.ids = cfg.ids;
+    this.store = cfg.store ?? new MemoryCaptureStore();
   }
 
   payInCapabilities(): PayInCapabilities {
@@ -128,7 +167,7 @@ export class PaypalLeg implements InteractivePayInLeg, PayOutLeg {
       rails: ["paypal"],
       currencies: this.currencies,
       methods: ["paypal", "venmo", "card"],
-      refunds: RefundKind.Full,
+      refunds: RefundKind.Partial,
     };
   }
 
@@ -146,7 +185,11 @@ export class PaypalLeg implements InteractivePayInLeg, PayOutLeg {
       payee: deliverTo,
       referenceId: referencePrefix + intentId,
     });
-    this.captures.set(intentId, capture.captureId);
+    await this.store.save({
+      intentId,
+      captureId: capture.captureId,
+      expected: { value: majorAmount(quote.srcAmount.minor(), quote.srcAmount.exponent), currency: quote.srcAmount.currency },
+    });
     return { providerRef: capture.captureId, received: quote.srcAmount.sub(quote.fees) };
   }
 
@@ -167,6 +210,11 @@ export class PaypalLeg implements InteractivePayInLeg, PayOutLeg {
       params.platformFee = majorAmount(quote.fees.minor(), quote.fees.exponent);
     }
     const order = await this.api.createOrder(params);
+    await this.store.save({
+      intentId,
+      captureId: "",
+      expected: { value: majorAmount(quote.srcAmount.minor(), quote.srcAmount.exponent), currency: quote.srcAmount.currency },
+    });
     return { providerRef: order.id, clientSecret: order.id, method: "paypal" };
   }
 
@@ -182,18 +230,25 @@ export class PaypalLeg implements InteractivePayInLeg, PayOutLeg {
     return { providerRef: payout.batchId };
   }
 
-  // refundIn reverses a captured payment in full. PayPal captures the order id in
-  // the capture id it returned from collect, so the refund binds to that
-  // reference.
-  async refundIn(intentId: string, kind: RefundKind, reason: string): Promise<Settlement> {
-    if (kind !== RefundKind.Full) {
+  // refundIn reverses a captured payment, in full or in part. PayPal captures the
+  // order id in the capture id it returned from collect, so the refund binds to
+  // that reference; a partial refund names the amount to return.
+  async refundIn(intentId: string, kind: RefundKind, amount: Money, reason: string): Promise<Settlement> {
+    if (kind !== RefundKind.Full && kind !== RefundKind.Partial) {
       throw new Error(`paypal: cannot perform refund kind ${kind}`);
     }
-    const captureId = this.captures.get(intentId);
-    if (!captureId) {
+    const rec = await this.store.byIntent(intentId);
+    if (!rec || !rec.captureId) {
       throw new Error(`paypal: no capture for intent ${intentId}`);
     }
-    const refund = await this.api.refundCapture({ captureId, reason });
+    const captureId = rec.captureId;
+    // A partial refund names the amount in major units; a full refund leaves it
+    // absent so PayPal returns the whole capture.
+    const params: RefundParams =
+      kind === RefundKind.Partial
+        ? { captureId, reason, value: majorAmount(amount.minor(), amount.exponent), currencyCode: amount.currency }
+        : { captureId, reason };
+    const refund = await this.api.refundCapture(params);
     return {
       intentId,
       state: State.Refunded,
@@ -226,8 +281,23 @@ export class PaypalLeg implements InteractivePayInLeg, PayOutLeg {
     const providerRef = resource.id ?? "";
 
     switch (event.event_type) {
-      case "PAYMENT.CAPTURE.COMPLETED":
+      case "PAYMENT.CAPTURE.COMPLETED": {
+        // The custom_id that ties a capture to an intent is chosen by whoever
+        // created the order, so a genuine, signed capture for a different order can
+        // carry a target intent's id. Settle only when the captured amount and
+        // currency match what the intent was quoted to collect.
+        const rec = await this.store.byIntent(intentId);
+        if (!rec) {
+          throw new Error(`paypal: capture for unknown intent ${JSON.stringify(intentId)}`);
+        }
+        const want = rec.expected;
+        if (resource.amount?.value !== want.value || resource.amount?.currency_code !== want.currency) {
+          throw new Error(
+            `paypal: captured ${resource.amount?.value} ${resource.amount?.currency_code} does not match the quoted ${want.value} ${want.currency}`,
+          );
+        }
         return [oneEvent(intentId, State.Settled, providerRef, "")];
+      }
       case "PAYMENT.CAPTURE.DENIED":
         return [oneEvent(intentId, State.Failed, providerRef, "capture denied")];
       case "PAYMENT.CAPTURE.REFUNDED":
@@ -240,7 +310,12 @@ export class PaypalLeg implements InteractivePayInLeg, PayOutLeg {
 
 interface PaypalWebhook {
   event_type?: string;
-  resource?: { id?: string; custom_id?: string; invoice_id?: string };
+  resource?: {
+    id?: string;
+    custom_id?: string;
+    invoice_id?: string;
+    amount?: { currency_code?: string; value?: string };
+  };
 }
 
 function oneEvent(intentId: string, state: State, providerRef: string, reason: string): AdapterEvent {
@@ -305,7 +380,7 @@ class HttpPaypalApi implements PaypalApi {
       return this.token;
     }
     const basic = Buffer.from(`${this.creds.clientId}:${this.creds.clientSecret}`).toString("base64");
-    const resp = await fetch(`${this.baseURL}/v1/oauth2/token`, {
+    const resp = await fetchWithTimeout(`${this.baseURL}/v1/oauth2/token`, {
       method: "POST",
       headers: { Authorization: `Basic ${basic}`, "Content-Type": "application/x-www-form-urlencoded" },
       body: "grant_type=client_credentials",
@@ -327,10 +402,11 @@ class HttpPaypalApi implements PaypalApi {
     if (params.payee) {
       unit.payee = { email_address: params.payee };
     }
-    const created = await this.postJSON<PaypalOrder>("/v2/checkout/orders", {
-      intent: "CAPTURE",
-      purchase_units: [unit],
-    });
+    const created = await this.postJSON<PaypalOrder>(
+      "/v2/checkout/orders",
+      { intent: "CAPTURE", purchase_units: [unit] },
+      idempotencyKey(params.referenceId, "paypal-order"),
+    );
     const existing = firstCapture(created);
     if (existing) {
       return { orderId: created.id ?? "", captureId: existing.id ?? "", status: existing.status ?? "" };
@@ -338,6 +414,7 @@ class HttpPaypalApi implements PaypalApi {
     const captured = await this.postJSON<PaypalOrder>(
       `/v2/checkout/orders/${encodeURIComponent(created.id ?? "")}/capture`,
       {},
+      idempotencyKey(params.referenceId, "paypal-capture"),
     );
     const capture = firstCapture(captured);
     if (!capture) {
@@ -363,10 +440,11 @@ class HttpPaypalApi implements PaypalApi {
         platform_fees: [{ amount: { currency_code: params.currencyCode, value: params.platformFee } }],
       };
     }
-    const created = await this.postJSON<PaypalOrder>("/v2/checkout/orders", {
-      intent: "CAPTURE",
-      purchase_units: [unit],
-    });
+    const created = await this.postJSON<PaypalOrder>(
+      "/v2/checkout/orders",
+      { intent: "CAPTURE", purchase_units: [unit] },
+      idempotencyKey(params.referenceId, "paypal-order"),
+    );
     let approve = "";
     for (const link of created.links ?? []) {
       if (link.rel === "approve" || link.rel === "payer-action") {
@@ -400,9 +478,14 @@ class HttpPaypalApi implements PaypalApi {
     if (params.reason) {
       body.note_to_payer = params.reason;
     }
+    // A partial refund names the amount; an absent value refunds the full capture.
+    if (params.value) {
+      body.amount = { value: params.value, currency_code: params.currencyCode };
+    }
     const out = await this.postJSON<{ id?: string; status?: string }>(
       `/v2/payments/captures/${encodeURIComponent(params.captureId)}/refund`,
       body,
+      idempotencyKey(params.captureId, "paypal-refund"),
     );
     return { id: out.id ?? "", status: out.status ?? "" };
   }
@@ -412,24 +495,51 @@ class HttpPaypalApi implements PaypalApi {
   // binds a payload to this integration; PayPal reports whether the signature is
   // authentic.
   async verifyWebhook(headers: Record<string, string[]>, body: Uint8Array): Promise<boolean> {
-    const out = await this.postJSON<{ verification_status?: string }>("/v1/notifications/verify-webhook-signature", {
+    // PayPal's signature covers the exact bytes of the event it delivered, so the
+    // event is forwarded verbatim. Parsing and re-serializing it would reorder
+    // keys or restyle numbers and make an authentic webhook fail verification.
+    const rawEvent = new TextDecoder().decode(body);
+    const sentinel = "__pact_raw_webhook_event__";
+    const envelope = JSON.stringify({
       webhook_id: this.creds.webhookId,
       transmission_id: header(headers, "PayPal-Transmission-Id"),
       transmission_time: header(headers, "PayPal-Transmission-Time"),
       transmission_sig: header(headers, "PayPal-Transmission-Sig"),
       cert_url: header(headers, "PayPal-Cert-Url"),
       auth_algo: header(headers, "PayPal-Auth-Algo"),
-      webhook_event: JSON.parse(new TextDecoder().decode(body)),
+      webhook_event: sentinel,
     });
+    const payload = envelope.replace(`"${sentinel}"`, rawEvent);
+    const out = await this.postSerialized<{ verification_status?: string }>(
+      "/v1/notifications/verify-webhook-signature",
+      payload,
+    );
     return out.verification_status === "SUCCESS";
   }
 
-  private async postJSON<T>(path: string, body: unknown): Promise<T> {
+  // requestId, when set, is sent as PayPal-Request-Id. PayPal deduplicates a
+  // mutation that carries a request id it has already seen, so a retry after a
+  // lost response reuses the first order, capture, or refund rather than creating
+  // a second.
+  private async postJSON<T>(path: string, body: unknown, requestId?: string): Promise<T> {
+    return this.postSerialized<T>(path, JSON.stringify(body), requestId);
+  }
+
+  // postSerialized posts an already-serialized JSON payload, so a caller that must
+  // control the exact bytes on the wire — a webhook forwarded verbatim — can do so.
+  private async postSerialized<T>(path: string, payload: string, requestId?: string): Promise<T> {
     const token = await this.accessToken();
-    const resp = await fetch(this.baseURL + path, {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`,
+    };
+    if (requestId) {
+      headers["PayPal-Request-Id"] = requestId;
+    }
+    const resp = await fetchWithTimeout(this.baseURL + path, {
       method: "POST",
-      headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
-      body: JSON.stringify(body),
+      headers,
+      body: payload,
     });
     if (resp.status >= 300) {
       throw new Error(`paypal: ${path} returned ${resp.status}`);