@myzonerocks/pact 0.1.2 → 0.1.4

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,
@@ -60,12 +61,25 @@ 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
@@ -154,16 +168,21 @@ export class MpesaLeg implements PayInLeg, PayOutLeg {
   // 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 shillings = wholeShillings(amount);
     const rec = this.byIntent.get(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,
@@ -187,11 +206,13 @@ 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;
@@ -199,7 +220,13 @@ export class MpesaLeg implements PayInLeg, PayOutLeg {
       throw new Error(ErrUnknownCheckout);
     }
 
-    if (cb.ResultCode !== 0) {
+    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) {
       rec.state = State.Failed;
       return [
         {
@@ -207,11 +234,17 @@ export class MpesaLeg implements PayInLeg, PayOutLeg {
           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;
@@ -258,6 +291,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 +348,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 +358,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,6 +413,37 @@ 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 = {
@@ -375,7 +464,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,15 +5,19 @@
 // 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 {
-  PayInLeg,
   PayOutLeg,
+  InteractivePayInLeg,
   PayInCapabilities,
   PayOutCapabilities,
   CollectResult,
   DisburseResult,
+  PayInPreparation,
 } from "../leg.js";
 
 // The public base of the PayPal REST API. It is the same for every live
@@ -36,6 +40,18 @@ export interface CreateOrderParams {
   currencyCode: string;
   payee: string;
   referenceId: string;
+  // platformFee, when set, is the decimal-major cut the platform takes from the
+  // payee's proceeds.
+  platformFee?: string;
+}
+
+// Order is a created-but-not-yet-captured order: the buyer approves it on their own
+// device, then it is captured. approveUrl is PayPal's hosted approval link, offered
+// for hosts that redirect rather than drive the JS SDK.
+export interface Order {
+  id: string;
+  status: string;
+  approveUrl: string;
 }
 
 // Capture is the result of capturing an order: the capture id is the reference a
@@ -65,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.
@@ -80,6 +100,9 @@ export interface Refund {
 // endpoint, so the verification secret never lives in this package.
 export interface PaypalApi {
   createAndCaptureOrder(params: CreateOrderParams): Promise<Capture>;
+  // createOrder creates an order the buyer approves and captures on their own
+  // device — the interactive pay-in path — rather than capturing it server-side.
+  createOrder(params: CreateOrderParams): Promise<Order>;
   sendPayout(params: PayoutParams): Promise<Payout>;
   refundCapture(params: RefundParams): Promise<Refund>;
   verifyWebhook(headers: Record<string, string[]>, body: Uint8Array): Promise<boolean>;
@@ -93,12 +116,15 @@ export interface PaypalConfig {
 }
 
 // PaypalLeg moves money over PayPal, serving both sides of a corridor.
-export class PaypalLeg implements PayInLeg, PayOutLeg {
+export class PaypalLeg implements InteractivePayInLeg, PayOutLeg {
   readonly id: string;
   private readonly currencies: string[];
   private readonly api: PaypalApi;
   private readonly ids: () => string;
   private readonly captures = new Map<string, string>();
+  // What each intent was quoted to collect, so a capture webhook can be
+  // cross-checked: the paid amount and currency must match before it settles.
+  private readonly expected = new Map<string, { value: string; currency: string }>();
 
   constructor(cfg: PaypalConfig) {
     this.id = cfg.id ?? "paypal";
@@ -112,7 +138,7 @@ export class PaypalLeg implements PayInLeg, PayOutLeg {
       rails: ["paypal"],
       currencies: this.currencies,
       methods: ["paypal", "venmo", "card"],
-      refunds: RefundKind.Full,
+      refunds: RefundKind.Partial,
     };
   }
 
@@ -131,9 +157,37 @@ export class PaypalLeg implements PayInLeg, PayOutLeg {
       referenceId: referencePrefix + intentId,
     });
     this.captures.set(intentId, capture.captureId);
+    this.expected.set(intentId, {
+      value: majorAmount(quote.srcAmount.minor(), quote.srcAmount.exponent),
+      currency: quote.srcAmount.currency,
+    });
     return { providerRef: capture.captureId, received: quote.srcAmount.sub(quote.fees) };
   }
 
+  // prepare creates an order the payer approves and captures on their own device
+  // through the PayPal or Venmo flow — the interactive pay-in path — so nothing is
+  // captured here. The order names the recipient as payee and our cut as a platform
+  // fee; the buyer's capture then fires PAYMENT.CAPTURE.COMPLETED, which advances
+  // the corridor through the same pay-in path as a server-side collection. The
+  // order id is the token the payer's PayPal buttons need.
+  async prepare(intentId: string, quote: Quote, _auth: Authorization, deliverTo: string): Promise<PayInPreparation> {
+    const params: CreateOrderParams = {
+      value: majorAmount(quote.srcAmount.minor(), quote.srcAmount.exponent),
+      currencyCode: quote.srcAmount.currency,
+      payee: deliverTo,
+      referenceId: referencePrefix + intentId,
+    };
+    if (!quote.fees.isZero()) {
+      params.platformFee = majorAmount(quote.fees.minor(), quote.fees.exponent);
+    }
+    const order = await this.api.createOrder(params);
+    this.expected.set(intentId, {
+      value: majorAmount(quote.srcAmount.minor(), quote.srcAmount.exponent),
+      currency: quote.srcAmount.currency,
+    });
+    return { providerRef: order.id, clientSecret: order.id, method: "paypal" };
+  }
+
   // disburse sends a payout of the recipient's amount to recipientRef and returns
   // the batch id.
   async disburse(intentId: string, quote: Quote, recipientRef: string): Promise<DisburseResult> {
@@ -146,18 +200,24 @@ export class PaypalLeg implements PayInLeg, 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) {
       throw new Error(`paypal: no capture for intent ${intentId}`);
     }
-    const refund = await this.api.refundCapture({ captureId, reason });
+    // 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,
@@ -190,8 +250,22 @@ export class PaypalLeg implements PayInLeg, 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 want = this.expected.get(intentId);
+        if (!want) {
+          throw new Error(`paypal: capture for unknown intent ${JSON.stringify(intentId)}`);
+        }
+        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":
@@ -204,7 +278,12 @@ export class PaypalLeg implements PayInLeg, 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 {
@@ -269,7 +348,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",
@@ -291,10 +370,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 ?? "" };
@@ -302,6 +382,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) {
@@ -310,6 +391,38 @@ class HttpPaypalApi implements PaypalApi {
     return { orderId: captured.id ?? "", captureId: capture.id ?? "", status: capture.status ?? "" };
   }
 
+  // createOrder creates an order the buyer approves and captures on their own
+  // device. It carries custom_id so the capture webhook ties back to the intent,
+  // and a platform fee via payment_instruction when one is set.
+  async createOrder(params: CreateOrderParams): Promise<Order> {
+    const unit: Record<string, unknown> = {
+      reference_id: params.referenceId,
+      custom_id: params.referenceId,
+      amount: { currency_code: params.currencyCode, value: params.value },
+    };
+    if (params.payee) {
+      unit.payee = { email_address: params.payee };
+    }
+    if (params.platformFee) {
+      unit.payment_instruction = {
+        platform_fees: [{ amount: { currency_code: params.currencyCode, value: params.platformFee } }],
+      };
+    }
+    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") {
+        approve = link.href ?? "";
+        break;
+      }
+    }
+    return { id: created.id ?? "", status: created.status ?? "", approveUrl: approve };
+  }
+
   async sendPayout(params: PayoutParams): Promise<Payout> {
     const out = await this.postJSON<{ batch_header?: { payout_batch_id?: string; batch_status?: string } }>(
       "/v1/payments/payouts",
@@ -333,9 +446,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 ?? "" };
   }
@@ -345,24 +463,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}`);
@@ -377,6 +522,7 @@ interface PaypalOrder {
   id?: string;
   status?: string;
   purchase_units?: Array<{ payments?: { captures?: Array<{ id?: string; status?: string }> } }>;
+  links?: Array<{ href?: string; rel?: string }>;
 }
 
 function firstCapture(order: PaypalOrder): { id?: string; status?: string } | undefined {

package/src/adapters/stripe.ts

@@ -10,6 +10,8 @@ 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 { idempotencyKey } from "../protocol.js";
+import { fetchWithTimeout } from "./http.js";
 import type { InteractivePayInLeg, PayInCapabilities, CollectResult, PayInPreparation } from "../leg.js";
 
 // The public base of the Stripe REST API. It is the same for every integration
@@ -29,7 +31,6 @@ const metadataIntentKey = "pact_intent_id";
 const defaultToleranceSeconds = 300;
 
 // The protocol identifier used to bind an idempotency key to one protocol step.
-const idPrefix = "pact";
 
 // PaymentIntent is the subset of Stripe's PaymentIntent this leg reads.
 // clientSecret is present only on a freshly created intent and is the single
@@ -108,9 +109,8 @@ export interface StripeConfig {
   currencies: string[];
   api: StripeApi;
   webhookKey: string;
-  // clock returns the current time in Unix seconds, for webhook timestamp
-  // checks. When absent, timestamps are checked against zero.
-  clock?: () => number;
+  // clock returns the current time in Unix seconds, for webhook timestamp checks.
+  clock: () => number;
   // tolerance is the webhook timestamp tolerance in seconds; defaults to 300.
   tolerance?: number;
   ids: () => string;
@@ -136,11 +136,16 @@ export class StripeLeg implements InteractivePayInLeg {
     if (!cfg.webhookKey) {
       throw new Error("stripe: config requires a webhook signing key");
     }
+    // Without a clock every webhook timestamp reads as far in the past and
+    // silently fails the tolerance check, so a real webhook never verifies.
+    if (!cfg.clock) {
+      throw new Error("stripe: config requires a clock for webhook timestamp checks");
+    }
     this.id = cfg.id ?? "stripe";
     this.currencies = cfg.currencies;
     this.api = cfg.api;
     this.webhookKey = cfg.webhookKey;
-    this.clock = cfg.clock ?? (() => 0);
+    this.clock = cfg.clock;
     this.tolerance = cfg.tolerance ?? defaultToleranceSeconds;
     this.ids = cfg.ids;
     this.methods = cfg.methods;
@@ -204,13 +209,16 @@ export class StripeLeg implements InteractivePayInLeg {
   // refundIn reverses a captured payment, in full or in part. Stripe supports
   // both, so the leg accepts the full and partial refund kinds and rejects a
   // counter-transfer it cannot express.
-  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.Full && kind !== RefundKind.Partial) {
       throw new Error(`stripe: cannot perform refund kind ${kind}`);
     }
     const pi = await this.api.findPaymentIntent(intentId);
+    // Stripe refunds the full capture when no amount is set, so a full refund
+    // leaves amount zero and a partial one carries the exact minor units to return.
+    const minor = kind === RefundKind.Partial ? minorToInteger(amount) : 0;
     const refund = await this.api.createRefund(
-      { paymentIntentId: pi.id, amount: 0, reason },
+      { paymentIntentId: pi.id, amount: minor, reason },
       idempotencyKey(intentId, "refund"),
     );
     return {
@@ -249,11 +257,6 @@ function signatureHeader(headers: Record<string, string[]>): string {
   return "";
 }
 
-// idempotencyKey binds a Stripe mutation to one protocol step so a retry reuses
-// the original result instead of acting twice.
-function idempotencyKey(ref: string, step: string): string {
-  return `${idPrefix}:${ref}:${step}`;
-}
 
 // minorToInteger narrows a Money amount to the safe integer Stripe expects,
 // refusing anything that would overflow. Fiat amounts fit comfortably; the guard
@@ -484,7 +487,7 @@ class HttpStripeApi implements StripeApi {
       Authorization: `Bearer ${this.secretKey}`,
       "Stripe-Version": apiVersion,
     };
-    const resp = await fetch(this.baseURL + path, { ...init, headers });
+    const resp = await fetchWithTimeout(this.baseURL + path, { ...init, headers });
     const body = await resp.text();
     if (resp.status >= 300) {
       throw new Error(`stripe: ${path} returned ${resp.status}: ${stripeErrorMessage(body)}`);

package/src/bridge.ts

@@ -131,14 +131,21 @@ export function applyInverseRate(dst: Money, rate: string, srcCurrency: string,
 // parseRate reads a decimal rate like "129.45" into a numerator and denominator,
 // so the conversion stays exact integer arithmetic with no floating point.
 export function parseRate(rate: string): [bigint, bigint] {
+  // Bound the length so an untrusted rate can't force a huge bigint parse and
+  // exponentiation in the FX math.
+  if (rate.length > 80) {
+    throw new Error("pact: rate has more than 80 characters");
+  }
+  // A non-negative integer part with no leading zeros and an optional fractional
+  // part; no sign, no radix prefix, no whitespace, matching the amount grammar so
+  // the SDKs never disagree on a rate's validity or value.
+  if (!/^(0|[1-9][0-9]*)(\.[0-9]+)?$/.test(rate)) {
+    throw new Error(`pact: ${JSON.stringify(rate)} is not a canonical decimal rate`);
+  }
   const dot = rate.indexOf(".");
   const whole = dot < 0 ? rate : rate.slice(0, dot);
   const frac = dot < 0 ? "" : rate.slice(dot + 1);
-  const digits = whole + frac;
-  if (!/^\d+$/.test(digits)) {
-    throw new Error(`pact: ${JSON.stringify(rate)} is not a decimal rate`);
-  }
-  const num = BigInt(digits);
+  const num = BigInt(whole + frac);
   const den = frac.length > 0 ? pow10(frac.length) : 1n;
   return [num, den];
 }