@myzonerocks/pact 0.1.4 → 0.1.6

package/README.md

@@ -105,9 +105,9 @@ webhooks, so run them on a server, never in a browser bundle.
 
 ## Conformance
 
-The Go, TypeScript, and Dart SDKs are held to one wire format by shared vectors: a
-fixed intent produces a fixed canonical preimage, hash, and signature that all
-three reproduce byte-for-byte.
+The Go, TypeScript, Dart, Swift, and Kotlin SDKs are held to one wire format by
+shared vectors: a fixed intent produces a fixed canonical preimage, hash, and
+signature that every one of them reproduces byte-for-byte.
 
 ```
 bun run test

package/dist/src/adapters/erc20.d.ts

@@ -28,6 +28,22 @@ export interface Erc20Config {
     ids: () => string;
     decimals: number;
     minConfirmations?: number;
+    store?: SentStore;
+}
+export interface SentRecord {
+    intentId: string;
+    txHash: string;
+    to: string;
+    amount: bigint;
+}
+export interface SentStore {
+    save(rec: SentRecord): Promise<void>;
+    byIntent(intentId: string): Promise<SentRecord | undefined>;
+}
+export declare class MemorySentStore implements SentStore {
+    private readonly byIntentMap;
+    save(rec: SentRecord): Promise<void>;
+    byIntent(intentId: string): Promise<SentRecord | undefined>;
 }
 export declare class Erc20Leg implements PayInLeg, PayOutLeg {
     readonly id: string;
@@ -38,7 +54,7 @@ export declare class Erc20Leg implements PayInLeg, PayOutLeg {
     private readonly ids;
     private readonly decimals;
     private readonly minConf;
-    private readonly sent;
+    private readonly store;
     constructor(cfg: Erc20Config);
     private checkScale;
     payInCapabilities(): PayInCapabilities;

package/dist/src/adapters/erc20.js

@@ -14,6 +14,16 @@ const transferSelector = "a9059cbb";
 // success can still be reorged out, so a settlement waits for enough blocks on
 // top of it.
 const defaultMinConfirmations = 12;
+// MemorySentStore is the default in-process store.
+export class MemorySentStore {
+    byIntentMap = new Map();
+    async save(rec) {
+        this.byIntentMap.set(rec.intentId, rec);
+    }
+    async byIntent(intentId) {
+        return this.byIntentMap.get(intentId);
+    }
+}
 // Erc20Leg settles a payment as an ERC-20 token transfer. Refunds are a
 // counter-transfer only, because a token transfer is irreversible.
 export class Erc20Leg {
@@ -25,9 +35,9 @@ export class Erc20Leg {
     ids;
     decimals;
     minConf;
-    // Each broadcast transfer and what it was meant to move, so a settlement can
-    // confirm the mined transaction really matches the payment.
-    sent = new Map();
+    // Broadcast transfers, so a settlement can confirm the mined transaction really
+    // matches the payment, and a repeat returns the first transfer.
+    store;
     constructor(cfg) {
         if (!cfg.token || !cfg.currency) {
             throw new Error("erc20: config requires a token address and currency");
@@ -45,6 +55,7 @@ export class Erc20Leg {
         this.ids = cfg.ids;
         this.decimals = cfg.decimals;
         this.minConf = cfg.minConfirmations ?? defaultMinConfirmations;
+        this.store = cfg.store ?? new MemorySentStore();
     }
     // checkScale refuses an amount whose exponent does not match the token's
     // decimals, so a quote priced at the wrong scale never moves the wrong number
@@ -71,12 +82,12 @@ export class Erc20Leg {
         const net = quote.srcAmount.sub(quote.fees);
         // A repeat for the same intent returns the transfer already broadcast rather
         // than sending the payer's tokens twice.
-        const prev = this.sent.get(intentId);
+        const prev = await this.store.byIntent(intentId);
         if (prev) {
             return { providerRef: prev.txHash, received: net };
         }
         const txHash = await this.transfer(deliverTo, net.value());
-        this.sent.set(intentId, { txHash, to: normalizeAddress(deliverTo), amount: net.value() });
+        await this.store.save({ intentId, txHash, to: normalizeAddress(deliverTo), amount: net.value() });
         return { providerRef: txHash, received: net };
     }
     // disburse delivers the recipient's tokens.
@@ -84,13 +95,13 @@ export class Erc20Leg {
         this.checkScale(quote.dstAmount);
         // A repeat for the same intent returns the transfer already broadcast rather
         // than delivering the recipient's tokens twice.
-        const prev = this.sent.get(intentId);
+        const prev = await this.store.byIntent(intentId);
         if (prev) {
             return { providerRef: prev.txHash };
         }
         const amount = quote.dstAmount.value();
         const txHash = await this.transfer(recipientRef, amount);
-        this.sent.set(intentId, { txHash, to: normalizeAddress(recipientRef), amount });
+        await this.store.save({ intentId, txHash, to: normalizeAddress(recipientRef), amount });
         return { providerRef: txHash };
     }
     // refundIn refuses: an ERC-20 collection is irreversible and the leg holds no
@@ -113,7 +124,7 @@ export class Erc20Leg {
     // shallow success stays submitted so the host keeps polling; a revert or a
     // mismatch fails, so a dropped, reorged, or spoofed transfer never settles.
     async settlementEvent(intentId) {
-        const rec = this.sent.get(intentId);
+        const rec = await this.store.byIntent(intentId);
         if (!rec) {
             throw new Error("erc20: no broadcast transaction for intent");
         }

package/dist/src/adapters/mpesa.d.ts

@@ -20,6 +20,7 @@ export interface B2CParams {
     phone: string;
     reference: string;
     remarks: string;
+    idempotencyKey: string;
 }
 export interface B2CResult {
     conversationId: string;
@@ -35,19 +36,37 @@ export interface DarajaApi {
     b2cPayment(params: B2CParams): Promise<B2CResult>;
     query(checkoutRequestId: string): Promise<StkQueryResult>;
 }
+export interface PushRecord {
+    intentId: string;
+    checkoutId: string;
+    payerPhone: string;
+    amount: number;
+}
+export interface PushStore {
+    save(rec: PushRecord): Promise<void>;
+    byIntent(intentId: string): Promise<PushRecord | undefined>;
+    byCheckout(checkoutId: string): Promise<PushRecord | undefined>;
+}
+export declare class MemoryPushStore implements PushStore {
+    private readonly byIntentMap;
+    private readonly byCheckoutMap;
+    save(rec: PushRecord): Promise<void>;
+    byIntent(intentId: string): Promise<PushRecord | undefined>;
+    byCheckout(checkoutId: string): Promise<PushRecord | undefined>;
+}
 export interface MpesaConfig {
     id?: string;
     api: DarajaApi;
     callbackURL: string;
     ids: () => string;
+    store?: PushStore;
 }
 export declare class MpesaLeg implements PayInLeg, PayOutLeg {
     readonly id: string;
     private readonly api;
     private readonly callbackURL;
     private readonly ids;
-    private readonly byIntent;
-    private readonly byCheckout;
+    private readonly store;
     constructor(cfg: MpesaConfig);
     payInCapabilities(): PayInCapabilities;
     payOutCapabilities(): PayOutCapabilities;

package/dist/src/adapters/mpesa.js

@@ -9,14 +9,29 @@ const defaultBaseURL = "https://api.safaricom.co.ke";
 // checkout id to one we started is the authentication: an unrecognized id is
 // rejected rather than acted on.
 export const ErrUnknownCheckout = "mpesa: callback for an unknown checkout request";
+// MemoryPushStore is the default in-process store.
+export class MemoryPushStore {
+    byIntentMap = new Map();
+    byCheckoutMap = new Map();
+    async save(rec) {
+        this.byIntentMap.set(rec.intentId, rec);
+        if (rec.checkoutId)
+            this.byCheckoutMap.set(rec.checkoutId, rec);
+    }
+    async byIntent(intentId) {
+        return this.byIntentMap.get(intentId);
+    }
+    async byCheckout(checkoutId) {
+        return this.byCheckoutMap.get(checkoutId);
+    }
+}
 // MpesaLeg moves mobile money over M-Pesa.
 export class MpesaLeg {
     id;
     api;
     callbackURL;
     ids;
-    byIntent = new Map();
-    byCheckout = new Map();
+    store;
     constructor(cfg) {
         if (!cfg.callbackURL) {
             throw new Error("mpesa: config requires a callback URL");
@@ -25,6 +40,7 @@ export class MpesaLeg {
         this.api = cfg.api;
         this.callbackURL = cfg.callbackURL;
         this.ids = cfg.ids;
+        this.store = cfg.store ?? new MemoryPushStore();
     }
     payInCapabilities() {
         return { rails: ["mpesa"], currencies: ["KES"], refunds: RefundKind.CounterTransfer };
@@ -45,7 +61,6 @@ export class MpesaLeg {
         if (!phone) {
             throw new Error("mpesa: collect requires the payer's phone");
         }
-        const rec = { intentId, payerPhone: phone, amount, state: State.Unspecified };
         const result = await this.api.stkPush({
             amount,
             payerPhone: phone,
@@ -53,8 +68,7 @@ export class MpesaLeg {
             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 };
     }
     // disburse delivers the recipient's shillings by a business-to-customer payout
@@ -65,7 +79,7 @@ export class MpesaLeg {
         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
@@ -76,7 +90,7 @@ export class MpesaLeg {
             throw new Error("mpesa: a collection can only be refunded by counter-transfer");
         }
         const shillings = wholeShillings(amount);
-        const rec = this.byIntent.get(intentId);
+        const rec = await this.store.byIntent(intentId);
         if (!rec) {
             throw new Error(`mpesa: no push for intent ${intentId}`);
         }
@@ -89,6 +103,7 @@ export class MpesaLeg {
             phone: rec.payerPhone,
             reference: intentId,
             remarks: reason,
+            idempotencyKey: `pact:refund:${intentId}`,
         });
         return {
             intentId,
@@ -116,7 +131,7 @@ export class MpesaLeg {
     async parseWebhook(raw, _headers) {
         const envelope = JSON.parse(new TextDecoder().decode(raw));
         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);
         }
@@ -127,7 +142,6 @@ export class MpesaLeg {
             return [];
         }
         if (confirmed.resultCode !== 0) {
-            rec.state = State.Failed;
             return [
                 {
                     intentId: rec.intentId,
@@ -146,7 +160,6 @@ export class MpesaLeg {
             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,
@@ -301,6 +314,7 @@ class HttpDarajaApi {
     async b2cPayment(params) {
         const token = await this.token();
         const body = {
+            OriginatorConversationID: params.idempotencyKey,
             InitiatorName: this.creds.shortCode,
             CommandID: "BusinessPayment",
             Amount: params.amount,

package/dist/src/adapters/paypal.d.ts

@@ -52,14 +52,31 @@ export interface PaypalConfig {
     currencies: string[];
     api: PaypalApi;
     ids: () => string;
+    store?: CaptureStore;
+}
+export interface CaptureRecord {
+    intentId: string;
+    captureId: string;
+    expected: {
+        value: string;
+        currency: string;
+    };
+}
+export interface CaptureStore {
+    save(rec: CaptureRecord): Promise<void>;
+    byIntent(intentId: string): Promise<CaptureRecord | undefined>;
+}
+export declare class MemoryCaptureStore implements CaptureStore {
+    private readonly byIntentMap;
+    save(rec: CaptureRecord): Promise<void>;
+    byIntent(intentId: string): Promise<CaptureRecord | undefined>;
 }
 export declare class PaypalLeg implements InteractivePayInLeg, PayOutLeg {
     readonly id: string;
     private readonly currencies;
     private readonly api;
     private readonly ids;
-    private readonly captures;
-    private readonly expected;
+    private readonly store;
     constructor(cfg: PaypalConfig);
     payInCapabilities(): PayInCapabilities;
     payOutCapabilities(): PayOutCapabilities;

package/dist/src/adapters/paypal.js

@@ -17,21 +17,29 @@ const defaultBaseURL = "https://api-m.paypal.com";
 const referencePrefix = "pact:";
 // ErrSignatureMismatch reports a webhook PayPal could not authenticate.
 export const ErrSignatureMismatch = "paypal: webhook signature does not verify";
+// MemoryCaptureStore is the default in-process store.
+export class MemoryCaptureStore {
+    byIntentMap = new Map();
+    async save(rec) {
+        this.byIntentMap.set(rec.intentId, rec);
+    }
+    async byIntent(intentId) {
+        return this.byIntentMap.get(intentId);
+    }
+}
 // PaypalLeg moves money over PayPal, serving both sides of a corridor.
 export class PaypalLeg {
     id;
     currencies;
     api;
     ids;
-    captures = new Map();
-    // 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.
-    expected = new Map();
+    store;
     constructor(cfg) {
         this.id = cfg.id ?? "paypal";
         this.currencies = cfg.currencies;
         this.api = cfg.api;
         this.ids = cfg.ids;
+        this.store = cfg.store ?? new MemoryCaptureStore();
     }
     payInCapabilities() {
         return {
@@ -54,10 +62,10 @@ export class PaypalLeg {
             payee: deliverTo,
             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,
+        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) };
     }
@@ -78,9 +86,10 @@ export class PaypalLeg {
             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,
+        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" };
     }
@@ -102,10 +111,11 @@ export class PaypalLeg {
         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 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 = kind === RefundKind.Partial
@@ -146,10 +156,11 @@ export class PaypalLeg {
                 // 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) {
+                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}`);
                 }

package/dist/src/client.d.ts

@@ -65,6 +65,7 @@ export declare class Client {
     private pickBridge;
     select(quotes: Quote[], identity: string): Promise<Quote>;
     authorize(intent: Intent, quote: Quote, signer: Signer): Promise<Authorization>;
+    private resolvePayIn;
     initiate(intent: Intent, quote: Quote, auth: Authorization): Promise<State>;
     interactiveInitiate(intent: Intent, quote: Quote, auth: Authorization): Promise<{
         preparation: PayInPreparation;
@@ -76,6 +77,7 @@ export declare class Client {
     }>;
     private holdAndDisburse;
     private settleBridged;
+    private claimRefund;
     private unwind;
     refund(intentId: string, amount: Money, reason: string): Promise<{
         settlement: Settlement;

package/dist/src/client.js

@@ -98,6 +98,9 @@ export class Client {
                 continue;
             }
             try {
+                // Corridors are priced in order so the router sees a stable ranking, matching
+                // the other SDKs; the loop is bounded by the configured funding options.
+                // eslint-disable-next-line no-await-in-loop
                 quotes.push(await this.composeQuote(intent, payInLeg, f));
             }
             catch (err) {
@@ -223,11 +226,9 @@ export class Client {
     // driven forward by advance as provider events arrive, so no promise or
     // connection is held open per payment and durable state lives only in the
     // ledger.
-    async initiate(intent, quote, auth) {
-        verifyAuthorization(auth, intent, quote, this.verifier);
-        if (!this.signerAuth.authorized(auth.signerIdentity, intent.senderRef)) {
-            throw new Error("pact: signer is not authorized to act for the intent's sender");
-        }
+    // resolvePayIn rejects an expired intent and returns the corridor's pay-in leg — the
+    // expiry-and-leg check the immediate and interactive starts share.
+    resolvePayIn(intent, quote) {
         if (isExpired(intent.expiresAt, this.clock(), this.skew)) {
             throw new Error("pact: intent has expired");
         }
@@ -235,6 +236,14 @@ export class Client {
         if (!payInLeg) {
             throw new Error(`pact: no pay-in leg ${JSON.stringify(quote.payInAdapterId)}`);
         }
+        return payInLeg;
+    }
+    async initiate(intent, quote, auth) {
+        verifyAuthorization(auth, intent, quote, this.verifier);
+        if (!this.signerAuth.authorized(auth.signerIdentity, intent.senderRef)) {
+            throw new Error("pact: signer is not authorized to act for the intent's sender");
+        }
+        const payInLeg = this.resolvePayIn(intent, quote);
         // A retry of an already-submitted corridor must not collect a second time. The
         // pay-in leg carries its own provider idempotency for the narrow window where a
         // collection completed but its record was lost.
@@ -269,13 +278,7 @@ export class Client {
         if (!isDirect(quote)) {
             throw new Error("pact: interactive pay-in is only available on a direct corridor");
         }
-        if (isExpired(intent.expiresAt, this.clock(), this.skew)) {
-            throw new Error("pact: intent has expired");
-        }
-        const payInLeg = this.payIn.get(quote.payInAdapterId);
-        if (!payInLeg) {
-            throw new Error(`pact: no pay-in leg ${JSON.stringify(quote.payInAdapterId)}`);
-        }
+        const payInLeg = this.resolvePayIn(intent, quote);
         if (!isInteractivePayInLeg(payInLeg)) {
             throw new Error(`pact: pay-in leg ${JSON.stringify(quote.payInAdapterId)} does not offer interactive collection`);
         }
@@ -439,14 +442,29 @@ export class Client {
         };
         return this.finishAdvance(intentId, State.Settled, settlement);
     }
-    // unwind refunds the payer from escrow when a bridged corridor cannot complete
-    // its pay-out, moving to refunding then refunded.
-    async unwind(intentId, quote, authHash, reason) {
-        this.ledger.apply({
+    // claimRefund reserves the refunding step before any money moves. It returns the
+    // recorded outcome to echo when another refund already claimed the step, or null when
+    // this call won it and should proceed to move funds. Both refund paths go through it,
+    // so a refund is issued at most once however the calls race.
+    claimRefund(intentId, reason) {
+        const { created } = this.ledger.apply({
             intentId,
             to: State.Refunding,
             payloadHash: hashString(domain("refunding"), reason),
         });
+        if (created)
+            return null;
+        return { settlement: lastSettlement(this.ledger.events(intentId)), state: this.ledger.state(intentId) };
+    }
+    // unwind refunds the payer from escrow when a bridged corridor cannot complete
+    // its pay-out, moving to refunding then refunded.
+    async unwind(intentId, quote, authHash, reason) {
+        // Claim the refund before moving money. A duplicate pay-out-failed webhook enters
+        // unwind twice; only the call that wins the refunding step may issue the counter-
+        // transfer, so the refund cannot fire a second time.
+        const echo = this.claimRefund(intentId, reason);
+        if (echo)
+            return echo;
         const payInLeg = this.payIn.get(quote.payInAdapterId);
         if (payInLeg) {
             const kind = payInLeg.payInCapabilities().refunds;
@@ -513,6 +531,12 @@ export class Client {
             throw new Error(`pact: pay-in leg ${JSON.stringify(quote.payInAdapterId)} cannot perform this refund`);
         }
         const authHash = authorizationHash(intentHash(intent), quoteHash(quote), auth.signerIdentity, auth.signedAt);
+        // Claim the refunding step before moving money. Two overlapping refund calls both
+        // pass the settled check above; only the one that wins this step issues the return,
+        // so the payer is never refunded twice.
+        const echo = this.claimRefund(intentId, reason);
+        if (echo)
+            return echo;
         await payInLeg.refundIn(intentId, kind, amount, reason);
         const settlement = {
             intentId,

package/dist/src/state.js

@@ -51,7 +51,9 @@ const transitions = {
     [State.Held]: new Set([State.Disbursing, State.Refunding, State.Expired]),
     [State.Disbursing]: new Set([State.Settled, State.Failed, State.Refunding]),
     [State.Refunding]: new Set([State.Refunded, State.Failed]),
-    [State.Settled]: new Set([State.Refunded]),
+    // A settled intent refunds through the same refunding step a bridged unwind uses,
+    // so the refund is claimed before any money moves and cannot fire twice.
+    [State.Settled]: new Set([State.Refunding, State.Refunded]),
     [State.Failed]: new Set(),
     [State.Expired]: new Set(),
     [State.Refunded]: new Set(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myzonerocks/pact",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "TypeScript SDK for the PACT payment abstraction protocol",
   "license": "Apache-2.0",
   "repository": {

package/src/adapters/erc20.ts

@@ -74,6 +74,37 @@ export interface Erc20Config {
   // The confirmation depth a transfer must reach before it settles. Omitted uses
   // defaultMinConfirmations.
   minConfirmations?: number;
+  // Store persists broadcast transfers; defaults to an in-memory store. A deployment
+  // that must survive a restart with transfers in flight supplies a durable one.
+  store?: SentStore;
+}
+
+// SentRecord is the broadcast transfer a later settlement reads back: the intent, the
+// transaction hash, and the recipient and amount the on-chain receipt must match.
+export interface SentRecord {
+  intentId: string;
+  txHash: string;
+  to: string;
+  amount: bigint;
+}
+
+// SentStore records a broadcast transfer so its settlement can be polled after a
+// restart and a repeat for the same intent returns the first transfer. The default
+// keeps records in memory; a durable one survives a restart.
+export interface SentStore {
+  save(rec: SentRecord): Promise<void>;
+  byIntent(intentId: string): Promise<SentRecord | undefined>;
+}
+
+// MemorySentStore is the default in-process store.
+export class MemorySentStore implements SentStore {
+  private readonly byIntentMap = new Map<string, SentRecord>();
+  async save(rec: SentRecord): Promise<void> {
+    this.byIntentMap.set(rec.intentId, rec);
+  }
+  async byIntent(intentId: string): Promise<SentRecord | undefined> {
+    return this.byIntentMap.get(intentId);
+  }
 }
 
 // Erc20Leg settles a payment as an ERC-20 token transfer. Refunds are a
@@ -87,9 +118,9 @@ export class Erc20Leg implements PayInLeg, PayOutLeg {
   private readonly ids: () => string;
   private readonly decimals: number;
   private readonly minConf: number;
-  // Each broadcast transfer and what it was meant to move, so a settlement can
-  // confirm the mined transaction really matches the payment.
-  private readonly sent = new Map<string, { txHash: string; to: string; amount: bigint }>();
+  // Broadcast transfers, so a settlement can confirm the mined transaction really
+  // matches the payment, and a repeat returns the first transfer.
+  private readonly store: SentStore;
 
   constructor(cfg: Erc20Config) {
     if (!cfg.token || !cfg.currency) {
@@ -108,6 +139,7 @@ export class Erc20Leg implements PayInLeg, PayOutLeg {
     this.ids = cfg.ids;
     this.decimals = cfg.decimals;
     this.minConf = cfg.minConfirmations ?? defaultMinConfirmations;
+    this.store = cfg.store ?? new MemorySentStore();
   }
 
   // checkScale refuses an amount whose exponent does not match the token's
@@ -138,12 +170,12 @@ export class Erc20Leg implements PayInLeg, PayOutLeg {
     const net = quote.srcAmount.sub(quote.fees);
     // A repeat for the same intent returns the transfer already broadcast rather
     // than sending the payer's tokens twice.
-    const prev = this.sent.get(intentId);
+    const prev = await this.store.byIntent(intentId);
     if (prev) {
       return { providerRef: prev.txHash, received: net };
     }
     const txHash = await this.transfer(deliverTo, net.value());
-    this.sent.set(intentId, { txHash, to: normalizeAddress(deliverTo), amount: net.value() });
+    await this.store.save({ intentId, txHash, to: normalizeAddress(deliverTo), amount: net.value() });
     return { providerRef: txHash, received: net };
   }
 
@@ -152,13 +184,13 @@ export class Erc20Leg implements PayInLeg, PayOutLeg {
     this.checkScale(quote.dstAmount);
     // A repeat for the same intent returns the transfer already broadcast rather
     // than delivering the recipient's tokens twice.
-    const prev = this.sent.get(intentId);
+    const prev = await this.store.byIntent(intentId);
     if (prev) {
       return { providerRef: prev.txHash };
     }
     const amount = quote.dstAmount.value();
     const txHash = await this.transfer(recipientRef, amount);
-    this.sent.set(intentId, { txHash, to: normalizeAddress(recipientRef), amount });
+    await this.store.save({ intentId, txHash, to: normalizeAddress(recipientRef), amount });
     return { providerRef: txHash };
   }
 
@@ -184,7 +216,7 @@ export class Erc20Leg implements PayInLeg, PayOutLeg {
   // shallow success stays submitted so the host keeps polling; a revert or a
   // mismatch fails, so a dropped, reorged, or spoofed transfer never settles.
   async settlementEvent(intentId: string): Promise<AdapterEvent> {
-    const rec = this.sent.get(intentId);
+    const rec = await this.store.byIntent(intentId);
     if (!rec) {
       throw new Error("erc20: no broadcast transaction for intent");
     }

package/src/adapters/mpesa.ts

@@ -53,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.
@@ -82,14 +86,40 @@ export interface DarajaApi {
   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 {
@@ -97,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.
@@ -106,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) {
@@ -117,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 {
@@ -140,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,
@@ -148,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 };
   }
 
@@ -161,7 +192,7 @@ 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 };
   }
 
@@ -173,7 +204,7 @@ export class MpesaLeg implements PayInLeg, PayOutLeg {
       throw new Error("mpesa: a collection can only be refunded by counter-transfer");
     }
     const shillings = wholeShillings(amount);
-    const rec = this.byIntent.get(intentId);
+    const rec = await this.store.byIntent(intentId);
     if (!rec) {
       throw new Error(`mpesa: no push for intent ${intentId}`);
     }
@@ -186,6 +217,7 @@ export class MpesaLeg implements PayInLeg, PayOutLeg {
       phone: rec.payerPhone,
       reference: intentId,
       remarks: reason,
+      idempotencyKey: `pact:refund:${intentId}`,
     });
     return {
       intentId,
@@ -215,7 +247,7 @@ export class MpesaLeg implements PayInLeg, PayOutLeg {
   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);
     }
@@ -227,7 +259,6 @@ export class MpesaLeg implements PayInLeg, PayOutLeg {
       return [];
     }
     if (confirmed.resultCode !== 0) {
-      rec.state = State.Failed;
       return [
         {
           intentId: rec.intentId,
@@ -247,7 +278,6 @@ export class MpesaLeg implements PayInLeg, PayOutLeg {
     }
 
     const receipt = metadataString(cb.CallbackMetadata?.Item ?? [], "MpesaReceiptNumber");
-    rec.state = State.Settled;
     return [
       {
         intentId: rec.intentId,
@@ -447,6 +477,7 @@ class HttpDarajaApi implements DarajaApi {
   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,

package/src/adapters/paypal.ts

@@ -113,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.
@@ -121,16 +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>();
-  // 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 }>();
+  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 {
@@ -156,10 +185,10 @@ export class PaypalLeg implements InteractivePayInLeg, PayOutLeg {
       payee: deliverTo,
       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,
+    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) };
   }
@@ -181,9 +210,10 @@ export class PaypalLeg implements InteractivePayInLeg, PayOutLeg {
       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,
+    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" };
   }
@@ -207,10 +237,11 @@ export class PaypalLeg implements InteractivePayInLeg, PayOutLeg {
     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 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 =
@@ -255,10 +286,11 @@ export class PaypalLeg implements InteractivePayInLeg, PayOutLeg {
         // 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) {
+        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}`,

package/src/client.ts

@@ -164,6 +164,9 @@ export class Client {
         continue;
       }
       try {
+        // Corridors are priced in order so the router sees a stable ranking, matching
+        // the other SDKs; the loop is bounded by the configured funding options.
+        // eslint-disable-next-line no-await-in-loop
         quotes.push(await this.composeQuote(intent, payInLeg, f));
       } catch (err) {
         lastErr = err;
@@ -289,11 +292,9 @@ export class Client {
   // driven forward by advance as provider events arrive, so no promise or
   // connection is held open per payment and durable state lives only in the
   // ledger.
-  async initiate(intent: Intent, quote: Quote, auth: Authorization): Promise<State> {
-    verifyAuthorization(auth, intent, quote, this.verifier);
-    if (!this.signerAuth.authorized(auth.signerIdentity, intent.senderRef)) {
-      throw new Error("pact: signer is not authorized to act for the intent's sender");
-    }
+  // resolvePayIn rejects an expired intent and returns the corridor's pay-in leg — the
+  // expiry-and-leg check the immediate and interactive starts share.
+  private resolvePayIn(intent: Intent, quote: Quote): PayInLeg {
     if (isExpired(intent.expiresAt, this.clock(), this.skew)) {
       throw new Error("pact: intent has expired");
     }
@@ -301,6 +302,15 @@ export class Client {
     if (!payInLeg) {
       throw new Error(`pact: no pay-in leg ${JSON.stringify(quote.payInAdapterId)}`);
     }
+    return payInLeg;
+  }
+
+  async initiate(intent: Intent, quote: Quote, auth: Authorization): Promise<State> {
+    verifyAuthorization(auth, intent, quote, this.verifier);
+    if (!this.signerAuth.authorized(auth.signerIdentity, intent.senderRef)) {
+      throw new Error("pact: signer is not authorized to act for the intent's sender");
+    }
+    const payInLeg = this.resolvePayIn(intent, quote);
 
     // A retry of an already-submitted corridor must not collect a second time. The
     // pay-in leg carries its own provider idempotency for the narrow window where a
@@ -338,13 +348,7 @@ export class Client {
     if (!isDirect(quote)) {
       throw new Error("pact: interactive pay-in is only available on a direct corridor");
     }
-    if (isExpired(intent.expiresAt, this.clock(), this.skew)) {
-      throw new Error("pact: intent has expired");
-    }
-    const payInLeg = this.payIn.get(quote.payInAdapterId);
-    if (!payInLeg) {
-      throw new Error(`pact: no pay-in leg ${JSON.stringify(quote.payInAdapterId)}`);
-    }
+    const payInLeg = this.resolvePayIn(intent, quote);
     if (!isInteractivePayInLeg(payInLeg)) {
       throw new Error(`pact: pay-in leg ${JSON.stringify(quote.payInAdapterId)} does not offer interactive collection`);
     }
@@ -521,6 +525,20 @@ export class Client {
     return this.finishAdvance(intentId, State.Settled, settlement);
   }
 
+  // claimRefund reserves the refunding step before any money moves. It returns the
+  // recorded outcome to echo when another refund already claimed the step, or null when
+  // this call won it and should proceed to move funds. Both refund paths go through it,
+  // so a refund is issued at most once however the calls race.
+  private claimRefund(intentId: string, reason: string): { settlement: Settlement; state: State } | null {
+    const { created } = this.ledger.apply({
+      intentId,
+      to: State.Refunding,
+      payloadHash: hashString(domain("refunding"), reason),
+    });
+    if (created) return null;
+    return { settlement: lastSettlement(this.ledger.events(intentId)), state: this.ledger.state(intentId) };
+  }
+
   // unwind refunds the payer from escrow when a bridged corridor cannot complete
   // its pay-out, moving to refunding then refunded.
   private async unwind(
@@ -529,11 +547,11 @@ export class Client {
     authHash: Uint8Array,
     reason: string,
   ): Promise<{ settlement: Settlement; state: State }> {
-    this.ledger.apply({
-      intentId,
-      to: State.Refunding,
-      payloadHash: hashString(domain("refunding"), reason),
-    });
+    // Claim the refund before moving money. A duplicate pay-out-failed webhook enters
+    // unwind twice; only the call that wins the refunding step may issue the counter-
+    // transfer, so the refund cannot fire a second time.
+    const echo = this.claimRefund(intentId, reason);
+    if (echo) return echo;
     const payInLeg = this.payIn.get(quote.payInAdapterId);
     if (payInLeg) {
       const kind = payInLeg.payInCapabilities().refunds;
@@ -601,6 +619,11 @@ export class Client {
       throw new Error(`pact: pay-in leg ${JSON.stringify(quote.payInAdapterId)} cannot perform this refund`);
     }
     const authHash = authorizationHash(intentHash(intent), quoteHash(quote), auth.signerIdentity, auth.signedAt);
+    // Claim the refunding step before moving money. Two overlapping refund calls both
+    // pass the settled check above; only the one that wins this step issues the return,
+    // so the payer is never refunded twice.
+    const echo = this.claimRefund(intentId, reason);
+    if (echo) return echo;
     await payInLeg.refundIn(intentId, kind, amount, reason);
     const settlement: Settlement = {
       intentId,

package/src/state.ts

@@ -52,7 +52,9 @@ const transitions: Record<State, ReadonlySet<State>> = {
   [State.Held]: new Set([State.Disbursing, State.Refunding, State.Expired]),
   [State.Disbursing]: new Set([State.Settled, State.Failed, State.Refunding]),
   [State.Refunding]: new Set([State.Refunded, State.Failed]),
-  [State.Settled]: new Set([State.Refunded]),
+  // A settled intent refunds through the same refunding step a bridged unwind uses,
+  // so the refund is claimed before any money moves and cannot fire twice.
+  [State.Settled]: new Set([State.Refunding, State.Refunded]),
   [State.Failed]: new Set(),
   [State.Expired]: new Set(),
   [State.Refunded]: new Set(),