@myzonerocks/pact 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,123 @@
+# @myzonerocks/pact
+
+The TypeScript SDK for **PACT**, a payment abstraction protocol. PACT expresses a
+payment as a small sequence of typed, signed messages that any settlement provider
+can fulfil, carried over any transport. Every payment is a **corridor** — collect
+from the payer, convert the money, deliver to the recipient — so any pay-in
+provider composes with any pay-out provider across any currency, whether the money
+moves over a card network, a mobile-money wallet, or a blockchain.
+
+This package is the browser- and Node-ready kernel plus the provider adapters. It
+owns the protocol messages, the state machine, the event-sourced ledger, the
+corridor router, and the leg, bridge, and compliance seams. It does **not** own
+transport, key custody, liquidity, the FX feed, or KYC policy — those are seams you
+inject, so the same code serves a wallet app and a custodial backend alike.
+
+## Install
+
+```
+bun add @myzonerocks/pact
+# or: npm install @myzonerocks/pact
+```
+
+The kernel is exported from the package root; each adapter is a subpath so a bundle
+pulls in only the providers it uses.
+
+```ts
+import { Client, Money, encodePayload, decodePayload } from "@myzonerocks/pact";
+import { StripeLeg } from "@myzonerocks/pact/adapters/stripe";
+import { Erc20Leg } from "@myzonerocks/pact/adapters/erc20";
+```
+
+## Drive a corridor
+
+`intent.amount` is what the **recipient receives**; the corridor grosses it up into
+what the payer pays, with exact-integer math that always rounds in the recipient's
+favour. Settlement is route-and-forget: `initiate` kicks off the pay-in and returns,
+and a normalized provider event feeds `advance`, which is idempotent so a payment
+settles once.
+
+```ts
+const client = new Client({ payIn: [stripe], payOut: [payout], verifier });
+
+const intent = client.createIntent({
+  senderRef: payer,
+  recipientRef: merchantAccount,
+  amount: Money.parse("USD", 2, "1500"), // recipient receives $15.00
+  expiresAt: now + 600_000,
+  allowedRails: ["card"],
+});
+
+const quotes = await client.quoteOptions(intent, [{ payInAdapterId: "stripe", currency: "USD", exponent: 2 }]);
+const quote = await client.select(quotes, payer);
+const auth = await client.authorize(intent, quote, signer);
+
+// The payer confirms the card on their own device, so create the intent awaiting
+// their confirmation and hand the client secret to the card form.
+const { preparation } = await client.interactiveInitiate(intent, quote, auth);
+// ...payer confirms; the provider's webhook is normalized and fed to advance:
+await client.advance(intent.id, "stripe", event); // -> settled, once
+```
+
+For a server-side or saved-method charge, use `initiate` instead, which collects in
+one step rather than waiting on the payer.
+
+## Carry a payment over your transport
+
+The kernel emits and consumes opaque bytes; it never touches transport. Wrap a
+message with `encodePayload` to get a self-identifying, versioned blob to place
+inside your own envelope — a chat message, a queue entry — and `decodePayload` on
+receipt. No plaintext ever needs to reach a relay.
+
+```ts
+const blob = encodePayload(intent);        // place inside your E2EE envelope
+const message = decodePayload(received);   // recover on the other side
+```
+
+## Adapters
+
+An adapter translates between PACT messages and one provider, as a pay-in leg
+(collect), a pay-out leg (disburse), or both. Be honest in `payInCapabilities` /
+`payOutCapabilities` — the kernel refuses any operation you did not promise, so an
+irreversible rail declares a counter-transfer refund rather than fake a reversal.
+
+| Subpath | Provider | Legs |
+|---|---|---|
+| `@myzonerocks/pact/adapters/stripe` | Stripe | card pay-in (brings Apple Pay, Google Pay, Cash App Pay as methods) |
+| `@myzonerocks/pact/adapters/erc20` | ERC-20 | crypto pay-in + pay-out |
+| `@myzonerocks/pact/adapters/mpesa` | M-Pesa | STK pay-in + B2C pay-out |
+| `@myzonerocks/pact/adapters/paypal` | PayPal | Orders pay-in (Venmo) + Payouts pay-out |
+
+Server-side adapters (Stripe, M-Pesa, PayPal) hold provider secrets and verify
+webhooks, so run them on a server, never in a browser bundle.
+
+## Design commitments
+
+- **Money is exact integer minor units** at arbitrary precision, never a float —
+  an 18-decimal token overflows 64 bits at nine whole tokens.
+- **Signing is over a canonical preimage, not JSON or protobuf bytes**, with a
+  domain-separation tag per message kind, so a signature verifies across every
+  SDK and can never be replayed across message kinds, intents, or quotes.
+- **Every step is idempotent and replay-safe**; a duplicated webhook settles once.
+- **The state machine is total**: every illegal transition is rejected.
+- **Cross-provider settlement is never faked as atomic**: value rests in escrow
+  between the legs, so a failed pay-out unwinds to a refund rather than a loss.
+
+## 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.
+
+```
+bun run test
+```
+
+## Learn more
+
+The protocol is specified in the repository at
+[github.com/myzonerocks/pact](https://github.com/myzonerocks/pact) — `spec/PACT.md`
+for messages, canonical signing, the ledger, and conformance, and
+`spec/cross-rail.md` for the corridor model.
+
+Licensed under Apache-2.0.

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

@@ -1,12 +1,13 @@
 import type { Quote, Authorization, Settlement } from "../message.js";
 import { RefundKind, type AdapterEvent } from "../adapter.js";
-import type { PayInLeg, PayInCapabilities, CollectResult } from "../leg.js";
+import type { InteractivePayInLeg, PayInCapabilities, CollectResult, PayInPreparation } from "../leg.js";
 export interface PaymentIntent {
     id: string;
     status: string;
     amount: number;
     currency: string;
     latestCharge: string;
+    clientSecret: string;
     metadata: Record<string, string>;
     created: number;
 }
@@ -15,10 +16,16 @@ export interface Refund {
     status: string;
     amount: number;
 }
+export declare enum Capture {
+    Manual = "manual",
+    OnConfirmation = "on_confirmation"
+}
 export interface CreateIntentParams {
     amount: number;
     currency: string;
     destination: string;
+    applicationFee?: number;
+    capture?: Capture;
     metadata: Record<string, string>;
 }
 export interface CreateRefundParams {
@@ -41,7 +48,7 @@ export interface StripeConfig {
     tolerance?: number;
     ids: () => string;
 }
-export declare class StripeLeg implements PayInLeg {
+export declare class StripeLeg implements InteractivePayInLeg {
     readonly id: string;
     private readonly currencies;
     private readonly api;
@@ -52,6 +59,7 @@ export declare class StripeLeg implements PayInLeg {
     constructor(cfg: StripeConfig);
     payInCapabilities(): PayInCapabilities;
     collect(intentId: string, quote: Quote, _auth: Authorization, deliverTo: string): Promise<CollectResult>;
+    prepare(intentId: string, quote: Quote, _auth: Authorization, deliverTo: string): Promise<PayInPreparation>;
     refundIn(intentId: string, kind: RefundKind, reason: string): Promise<Settlement>;
     parseWebhook(raw: Uint8Array, headers: Record<string, string[]>): AdapterEvent[];
 }

package/dist/src/adapters/stripe.js

@@ -22,6 +22,16 @@ const metadataIntentKey = "pact_intent_id";
 const defaultToleranceSeconds = 300;
 // The protocol identifier used to bind an idempotency key to one protocol step.
 const idPrefix = "pact";
+// Capture selects when the charge is captured. Manual creates the intent already
+// carrying a payment method for the server to capture immediately — the flow an
+// agent or a saved-card charge uses. OnConfirmation defers capture to the moment
+// the payer confirms on their own device, which is what an interactive card form
+// needs: there is no payment method until the payer supplies one.
+export var Capture;
+(function (Capture) {
+    Capture["Manual"] = "manual";
+    Capture["OnConfirmation"] = "on_confirmation";
+})(Capture || (Capture = {}));
 // StripeLeg collects card payments through Stripe. It exposes the wallets that
 // ride on the card rail as funding methods, and answers a refund with a full or
 // partial reversal.
@@ -66,11 +76,30 @@ export class StripeLeg {
             amount,
             currency: quote.srcAmount.currency,
             destination: deliverTo,
+            capture: Capture.Manual,
             metadata: { [metadataIntentKey]: intentId },
         }, idempotencyKey(intentId, "collect"));
         const captured = await this.api.capturePaymentIntent(pi.id, idempotencyKey(intentId, "capture"));
         return { providerRef: captured.id, received: quote.srcAmount.sub(quote.fees) };
     }
+    // prepare creates a PaymentIntent the payer confirms on their own device, which
+    // is how an interactive card form collects: there is no payment method until the
+    // payer supplies one, so nothing is captured here. It returns the client secret
+    // the card form needs and lets Stripe capture the instant the payer confirms, at
+    // which point payment_intent.succeeded advances the corridor. The platform fee is
+    // collected by Stripe onto our own account, so we earn on the movement without
+    // ever holding the funds.
+    async prepare(intentId, quote, _auth, deliverTo) {
+        const pi = await this.api.createPaymentIntent({
+            amount: minorToInteger(quote.srcAmount),
+            currency: quote.srcAmount.currency,
+            destination: deliverTo,
+            applicationFee: minorToInteger(quote.fees),
+            capture: Capture.OnConfirmation,
+            metadata: { [metadataIntentKey]: intentId },
+        }, idempotencyKey(intentId, "prepare"));
+        return { providerRef: pi.id, clientSecret: pi.clientSecret, method: "card" };
+    }
     // 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.
@@ -242,11 +271,19 @@ class HttpStripeApi {
         const form = new URLSearchParams();
         form.set("amount", String(params.amount));
         form.set("currency", params.currency.toLowerCase());
-        form.set("capture_method", "manual");
+        // Manual capture waits for a server capture once a payment method is present;
+        // on-confirmation capture lets Stripe take the funds the instant the payer
+        // confirms in their own card form, firing payment_intent.succeeded straight away.
+        if ((params.capture ?? Capture.Manual) === Capture.Manual) {
+            form.set("capture_method", "manual");
+        }
         form.set("automatic_payment_methods[enabled]", "true");
         if (params.destination) {
             form.set("transfer_data[destination]", params.destination);
         }
+        if (params.applicationFee && params.applicationFee > 0) {
+            form.set("application_fee_amount", String(params.applicationFee));
+        }
         for (const [k, v] of Object.entries(params.metadata)) {
             form.set(`metadata[${k}]`, v);
         }
@@ -325,6 +362,7 @@ function normalizeIntent(p) {
         amount: p.amount ?? 0,
         currency: (p.currency ?? "").toUpperCase(),
         latestCharge: p.latest_charge ?? "",
+        clientSecret: p.client_secret ?? "",
         metadata: p.metadata ?? {},
         created: p.created ?? 0,
     };

package/dist/src/client.d.ts

@@ -3,7 +3,7 @@ import { Money } from "./money.js";
 import { type Intent, type Quote, type Authorization, type Settlement } from "./message.js";
 import { type Signer, type Verifier } from "./signing.js";
 import { type Bridge } from "./bridge.js";
-import { type PayInLeg, type PayOutLeg } from "./leg.js";
+import { type PayInLeg, type PayOutLeg, type PayInPreparation } from "./leg.js";
 import type { AdapterEvent } from "./adapter.js";
 import { type Policy } from "./router.js";
 import { type KycProvider, type RiskHook } from "./compliance.js";
@@ -64,6 +64,10 @@ export declare class Client {
     select(quotes: Quote[], identity: string): Promise<Quote>;
     authorize(intent: Intent, quote: Quote, signer: Signer): Promise<Authorization>;
     initiate(intent: Intent, quote: Quote, auth: Authorization): Promise<State>;
+    interactiveInitiate(intent: Intent, quote: Quote, auth: Authorization): Promise<{
+        preparation: PayInPreparation;
+        state: State;
+    }>;
     advance(intentId: string, adapterId: string, event: AdapterEvent): Promise<{
         settlement: Settlement;
         state: State;

package/dist/src/client.js

@@ -6,7 +6,7 @@ import { CanonicalWriter, hashPreimage } from "./canonical.js";
 import { intentHash, quoteHash, authorizationHash, corridorReceipt, isDirect, BRIDGE_PASSTHROUGH, } from "./message.js";
 import { authorize as signAuthorization, verifyAuthorization } from "./signing.js";
 import { PassThroughBridge } from "./bridge.js";
-import { railInList } from "./leg.js";
+import { railInList, isInteractivePayInLeg } from "./leg.js";
 import { route, PolicyKind, NoQuoteError, isExpired } from "./router.js";
 import { permissiveKyc, allowRisk, withinLimits } from "./compliance.js";
 import { MemoryLedger, eventReceipt } from "./ledger.js";
@@ -224,6 +224,32 @@ export class Client {
         this.ledger.apply({ intentId: intent.id, to, payloadHash: submitHash(collected.providerRef), collect: collected });
         return to;
     }
+    // interactiveInitiate kicks off a corridor whose pay-in the payer completes on
+    // their own device. It creates the provider intent awaiting the payer's
+    // confirmation, records the corridor as submitted, and returns the preparation
+    // the payer's device needs. The confirming provider event then advances the
+    // corridor to settled through the same pay-in path as an immediate collection.
+    // Only a direct corridor is interactive; a bridged pay-in still collects
+    // server-side into escrow, and the leg must offer interactive collection.
+    async interactiveInitiate(intent, quote, auth) {
+        verifyAuthorization(auth, intent, quote, this.verifier);
+        if (!isDirect(quote)) {
+            throw new Error("pact: interactive pay-in is only available on a direct corridor");
+        }
+        const payInLeg = this.payIn.get(quote.payInAdapterId);
+        if (!payInLeg) {
+            throw new Error(`pact: no pay-in leg ${JSON.stringify(quote.payInAdapterId)}`);
+        }
+        if (!isInteractivePayInLeg(payInLeg)) {
+            throw new Error(`pact: pay-in leg ${JSON.stringify(quote.payInAdapterId)} does not offer interactive collection`);
+        }
+        const preparation = await payInLeg.prepare(intent.id, quote, auth, recipientDestination(intent));
+        // Record the same shape a direct collection would, so the confirming webhook
+        // advances the corridor to settled through the unchanged pay-in path.
+        const collected = { providerRef: preparation.providerRef, received: quote.srcAmount.sub(quote.fees) };
+        this.ledger.apply({ intentId: intent.id, to: State.Submitted, payloadHash: submitHash(preparation.providerRef), collect: collected });
+        return { preparation, state: State.Submitted };
+    }
     // advance resumes a corridor when a provider event arrives — a webhook, a
     // callback, a chain receipt, already normalized into an AdapterEvent. It reads
     // the corridor's state from the ledger, interprets the event against it, and

package/dist/src/index.d.ts

@@ -5,7 +5,7 @@ export { CanonicalWriter, hashPreimage } from "./canonical.js";
 export { type Intent, type Quote, type Authorization, type Settlement, BRIDGE_PASSTHROUGH, intentPreimage, intentHash, quotePreimage, quoteHash, isDirect, signingPreimage, authorizationHash, receiptHash, corridorReceipt, } from "./message.js";
 export { type Signer, type Verifier, authorize, verifyAuthorization, Ed25519Signer, Ed25519Verifier, BadSignatureError, } from "./signing.js";
 export { RefundKind, type AdapterEvent, type WebhookParser } from "./adapter.js";
-export { railInList, type PayInLeg, type PayOutLeg, type PayInCapabilities, type PayOutCapabilities, type CollectResult, type DisburseResult, } from "./leg.js";
+export { railInList, isInteractivePayInLeg, type PayInLeg, type InteractivePayInLeg, type PayOutLeg, type PayInCapabilities, type PayOutCapabilities, type CollectResult, type PayInPreparation, type DisburseResult, } from "./leg.js";
 export { BRIDGE_USDC, PassThroughBridge, UsdcBridge, applyRate, applyInverseRate, parseRate, type Bridge, type BridgeQuote, type ConvertResult, type RateSource, type EscrowVault, } from "./bridge.js";
 export { type KycProvider, type KycStatus, type KycLimits, type RiskHook, type RiskDecision, permissiveKyc, allowRisk, withinLimits, } from "./compliance.js";
 export { PolicyKind, type Policy, route, isExpired, NoQuoteError } from "./router.js";

package/dist/src/index.js

@@ -5,7 +5,7 @@ export { CanonicalWriter, hashPreimage } from "./canonical.js";
 export { BRIDGE_PASSTHROUGH, intentPreimage, intentHash, quotePreimage, quoteHash, isDirect, signingPreimage, authorizationHash, receiptHash, corridorReceipt, } from "./message.js";
 export { authorize, verifyAuthorization, Ed25519Signer, Ed25519Verifier, BadSignatureError, } from "./signing.js";
 export { RefundKind } from "./adapter.js";
-export { railInList, } from "./leg.js";
+export { railInList, isInteractivePayInLeg, } from "./leg.js";
 export { BRIDGE_USDC, PassThroughBridge, UsdcBridge, applyRate, applyInverseRate, parseRate, } from "./bridge.js";
 export { permissiveKyc, allowRisk, withinLimits, } from "./compliance.js";
 export { PolicyKind, route, isExpired, NoQuoteError } from "./router.js";

package/dist/src/leg.d.ts

@@ -17,6 +17,15 @@ export interface PayInLeg {
     collect(intentId: string, quote: Quote, auth: Authorization, deliverTo: string): Promise<CollectResult>;
     refundIn(intentId: string, kind: RefundKind, reason: string): Promise<Settlement>;
 }
+export interface PayInPreparation {
+    providerRef: string;
+    clientSecret: string;
+    method: string;
+}
+export interface InteractivePayInLeg extends PayInLeg {
+    prepare(intentId: string, quote: Quote, auth: Authorization, deliverTo: string): Promise<PayInPreparation>;
+}
+export declare function isInteractivePayInLeg(leg: PayInLeg): leg is InteractivePayInLeg;
 export interface PayOutCapabilities {
     rails: string[];
     currencies: string[];

package/dist/src/leg.js

@@ -1,3 +1,9 @@
+// isInteractivePayInLeg reports whether a pay-in leg can prepare an interactive
+// collection, so the client can offer a payer-completed corridor where the rail
+// supports one and fall back to server-side collection otherwise.
+export function isInteractivePayInLeg(leg) {
+    return typeof leg.prepare === "function";
+}
 // railInList reports whether a set of rails contains the requested rail.
 export function railInList(rails, rail) {
     return rails.includes(rail);

package/dist/test/stripe.test.js

@@ -7,7 +7,7 @@ import { isDirect } from "../src/message.js";
 import { RefundKind } from "../src/adapter.js";
 import { Ed25519Signer, Ed25519Verifier } from "../src/signing.js";
 import { fromHex } from "../src/crypto.js";
-import { StripeLeg, ErrNoSignature, ErrSignatureMismatch, ErrTimestampOutOfTolerance, } from "../src/adapters/stripe.js";
+import { StripeLeg, Capture, ErrNoSignature, ErrSignatureMismatch, ErrTimestampOutOfTolerance, } from "../src/adapters/stripe.js";
 function counter() {
     let n = 0;
     return () => `pi_test_${String(++n).padStart(3, "0")}`;
@@ -26,12 +26,17 @@ class FakeStripe {
         this.ids = ids;
     }
     async createPaymentIntent(params, _idempotencyKey) {
+        // Manual capture presumes a method is already attached (server capture); an
+        // on-confirmation intent still awaits the payer supplying one on their device.
+        const status = (params.capture ?? Capture.Manual) === Capture.OnConfirmation ? "requires_payment_method" : "requires_capture";
+        const id = this.ids();
         const pi = {
-            id: this.ids(),
-            status: "requires_capture",
+            id,
+            status,
             amount: params.amount,
             currency: params.currency,
             latestCharge: "",
+            clientSecret: `${id}_secret`,
             metadata: params.metadata,
             created: 1_700_000_000,
         };
@@ -173,4 +178,41 @@ describe("stripe direct card corridor", () => {
         await leg.refundIn(intent.id, RefundKind.Full, "changed mind");
         await expect(leg.refundIn(intent.id, RefundKind.CounterTransfer, "wrong kind")).rejects.toThrow();
     });
+    it("prepares a payer-confirmed intent and settles on the confirming webhook", async () => {
+        const { signer, verifier } = signerVerifier("alice");
+        const api = new FakeStripe(counter());
+        const leg = buildLeg(api);
+        const client = new Client({
+            payIn: [leg],
+            payOut: [new CardPayout(leg.id)],
+            verifier,
+            clock: () => now,
+            idGen: counter(),
+        });
+        const intent = client.createIntent({
+            senderRef: "alice",
+            recipientRef: "acct_merchant",
+            amount: Money.parse("USD", 2, "1500"),
+            expiresAt: now + 600_000,
+            allowedRails: ["card"],
+        });
+        const quotes = await client.quoteOptions(intent, [{ payInAdapterId: leg.id, currency: "USD", exponent: 2 }]);
+        const quote = await client.select(quotes, signer.identity());
+        const auth = await client.authorize(intent, quote, signer);
+        const { preparation, state } = await client.interactiveInitiate(intent, quote, auth);
+        expect(state).toBe(State.Submitted);
+        expect(preparation.clientSecret).not.toBe("");
+        expect(preparation.providerRef).not.toBe("");
+        expect(preparation.method).toBe("card");
+        // Nothing is captured until the payer confirms; the intent still awaits a method.
+        const pending = await api.findPaymentIntent(intent.id);
+        expect(pending.status).toBe("requires_payment_method");
+        // The payer confirms and Stripe fires payment_intent.succeeded, which settles
+        // the corridor — once, even if the webhook is redelivered.
+        await client.advance(intent.id, leg.id, { intentId: intent.id, state: State.Settled, providerTxRef: "", onchainTxHash: "", reason: "", settledAt: 0 });
+        expect(client.state(intent.id)).toBe(State.Settled);
+        const before = client.history(intent.id).length;
+        await client.advance(intent.id, leg.id, { intentId: intent.id, state: State.Settled, providerTxRef: "", onchainTxHash: "", reason: "", settledAt: 0 });
+        expect(client.history(intent.id).length).toBe(before);
+    });
 });

package/package.json

@@ -1,12 +1,10 @@
 {
   "name": "@myzonerocks/pact",
-  "version": "0.1.0",
-  "description": "Reference TypeScript SDK for the PACT payment abstraction protocol",
+  "version": "0.1.1",
+  "description": "TypeScript SDK for the PACT payment abstraction protocol",
   "license": "Apache-2.0",
+  "repository": { "type": "git", "url": "git+https://github.com/myzonerocks/pact.git", "directory": "sdk/ts" },
   "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
   "exports": {
@@ -39,8 +37,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "vitest run",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "npm run build"
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/src/adapters/stripe.ts

@@ -10,7 +10,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 type { PayInLeg, PayInCapabilities, CollectResult } from "../leg.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
 // and carries no secret; tests point the leg at a local server instead.
@@ -32,12 +32,16 @@ const defaultToleranceSeconds = 300;
 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
+// token the payer's device needs to confirm the payment; it is never logged or
+// persisted server-side.
 export interface PaymentIntent {
   id: string;
   status: string;
   amount: number;
   currency: string;
   latestCharge: string;
+  clientSecret: string;
   metadata: Record<string, string>;
   created: number;
 }
@@ -49,14 +53,28 @@ export interface Refund {
   amount: number;
 }
 
+// Capture selects when the charge is captured. Manual creates the intent already
+// carrying a payment method for the server to capture immediately — the flow an
+// agent or a saved-card charge uses. OnConfirmation defers capture to the moment
+// the payer confirms on their own device, which is what an interactive card form
+// needs: there is no payment method until the payer supplies one.
+export enum Capture {
+  Manual = "manual",
+  OnConfirmation = "on_confirmation",
+}
+
 // CreateIntentParams describes a PaymentIntent to create. destination is the
 // account the captured funds settle to: the recipient's connected account for a
 // direct corridor, the escrow account for a bridged one. An empty destination
-// leaves the funds on the platform account.
+// leaves the funds on the platform account. applicationFee is the platform's cut,
+// collected by Stripe onto the platform account so we earn on the movement
+// without ever holding the funds; zero takes no fee.
 export interface CreateIntentParams {
   amount: number;
   currency: string;
   destination: string;
+  applicationFee?: number;
+  capture?: Capture;
   metadata: Record<string, string>;
 }
 
@@ -97,7 +115,7 @@ export interface StripeConfig {
 // StripeLeg collects card payments through Stripe. It exposes the wallets that
 // ride on the card rail as funding methods, and answers a refund with a full or
 // partial reversal.
-export class StripeLeg implements PayInLeg {
+export class StripeLeg implements InteractivePayInLeg {
   readonly id: string;
   private readonly currencies: string[];
   private readonly api: StripeApi;
@@ -142,6 +160,7 @@ export class StripeLeg implements PayInLeg {
         amount,
         currency: quote.srcAmount.currency,
         destination: deliverTo,
+        capture: Capture.Manual,
         metadata: { [metadataIntentKey]: intentId },
       },
       idempotencyKey(intentId, "collect"),
@@ -150,6 +169,28 @@ export class StripeLeg implements PayInLeg {
     return { providerRef: captured.id, received: quote.srcAmount.sub(quote.fees) };
   }
 
+  // prepare creates a PaymentIntent the payer confirms on their own device, which
+  // is how an interactive card form collects: there is no payment method until the
+  // payer supplies one, so nothing is captured here. It returns the client secret
+  // the card form needs and lets Stripe capture the instant the payer confirms, at
+  // which point payment_intent.succeeded advances the corridor. The platform fee is
+  // collected by Stripe onto our own account, so we earn on the movement without
+  // ever holding the funds.
+  async prepare(intentId: string, quote: Quote, _auth: Authorization, deliverTo: string): Promise<PayInPreparation> {
+    const pi = await this.api.createPaymentIntent(
+      {
+        amount: minorToInteger(quote.srcAmount),
+        currency: quote.srcAmount.currency,
+        destination: deliverTo,
+        applicationFee: minorToInteger(quote.fees),
+        capture: Capture.OnConfirmation,
+        metadata: { [metadataIntentKey]: intentId },
+      },
+      idempotencyKey(intentId, "prepare"),
+    );
+    return { providerRef: pi.id, clientSecret: pi.clientSecret, method: "card" };
+  }
+
   // 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.
@@ -356,11 +397,19 @@ class HttpStripeApi implements StripeApi {
     const form = new URLSearchParams();
     form.set("amount", String(params.amount));
     form.set("currency", params.currency.toLowerCase());
-    form.set("capture_method", "manual");
+    // Manual capture waits for a server capture once a payment method is present;
+    // on-confirmation capture lets Stripe take the funds the instant the payer
+    // confirms in their own card form, firing payment_intent.succeeded straight away.
+    if ((params.capture ?? Capture.Manual) === Capture.Manual) {
+      form.set("capture_method", "manual");
+    }
     form.set("automatic_payment_methods[enabled]", "true");
     if (params.destination) {
       form.set("transfer_data[destination]", params.destination);
     }
+    if (params.applicationFee && params.applicationFee > 0) {
+      form.set("application_fee_amount", String(params.applicationFee));
+    }
     for (const [k, v] of Object.entries(params.metadata)) {
       form.set(`metadata[${k}]`, v);
     }
@@ -449,6 +498,7 @@ interface StripePaymentIntentWire {
   amount?: number;
   currency?: string;
   latest_charge?: string;
+  client_secret?: string;
   metadata?: Record<string, string>;
   created?: number;
 }
@@ -466,6 +516,7 @@ function normalizeIntent(p: StripePaymentIntentWire): PaymentIntent {
     amount: p.amount ?? 0,
     currency: (p.currency ?? "").toUpperCase(),
     latestCharge: p.latest_charge ?? "",
+    clientSecret: p.client_secret ?? "",
     metadata: p.metadata ?? {},
     created: p.created ?? 0,
   };

package/src/client.ts

@@ -17,7 +17,7 @@ import {
 } from "./message.js";
 import { authorize as signAuthorization, verifyAuthorization, type Signer, type Verifier } from "./signing.js";
 import { PassThroughBridge, type Bridge, type ConvertResult } from "./bridge.js";
-import { railInList, type PayInLeg, type PayOutLeg, type CollectResult } from "./leg.js";
+import { railInList, isInteractivePayInLeg, type PayInLeg, type PayOutLeg, type CollectResult, type PayInPreparation } from "./leg.js";
 import type { AdapterEvent } from "./adapter.js";
 import { route, type Policy, PolicyKind, NoQuoteError, isExpired } from "./router.js";
 import { permissiveKyc, allowRisk, withinLimits, type KycProvider, type RiskHook } from "./compliance.js";
@@ -284,6 +284,33 @@ export class Client {
     return to;
   }
 
+  // interactiveInitiate kicks off a corridor whose pay-in the payer completes on
+  // their own device. It creates the provider intent awaiting the payer's
+  // confirmation, records the corridor as submitted, and returns the preparation
+  // the payer's device needs. The confirming provider event then advances the
+  // corridor to settled through the same pay-in path as an immediate collection.
+  // Only a direct corridor is interactive; a bridged pay-in still collects
+  // server-side into escrow, and the leg must offer interactive collection.
+  async interactiveInitiate(intent: Intent, quote: Quote, auth: Authorization): Promise<{ preparation: PayInPreparation; state: State }> {
+    verifyAuthorization(auth, intent, quote, this.verifier);
+    if (!isDirect(quote)) {
+      throw new Error("pact: interactive pay-in is only available on a direct corridor");
+    }
+    const payInLeg = this.payIn.get(quote.payInAdapterId);
+    if (!payInLeg) {
+      throw new Error(`pact: no pay-in leg ${JSON.stringify(quote.payInAdapterId)}`);
+    }
+    if (!isInteractivePayInLeg(payInLeg)) {
+      throw new Error(`pact: pay-in leg ${JSON.stringify(quote.payInAdapterId)} does not offer interactive collection`);
+    }
+    const preparation = await payInLeg.prepare(intent.id, quote, auth, recipientDestination(intent));
+    // Record the same shape a direct collection would, so the confirming webhook
+    // advances the corridor to settled through the unchanged pay-in path.
+    const collected: CollectResult = { providerRef: preparation.providerRef, received: quote.srcAmount.sub(quote.fees) };
+    this.ledger.apply({ intentId: intent.id, to: State.Submitted, payloadHash: submitHash(preparation.providerRef), collect: collected });
+    return { preparation, state: State.Submitted };
+  }
+
   // advance resumes a corridor when a provider event arrives — a webhook, a
   // callback, a chain receipt, already normalized into an AdapterEvent. It reads
   // the corridor's state from the ledger, interprets the event against it, and

package/src/index.ts

@@ -30,11 +30,14 @@ export {
 export { RefundKind, type AdapterEvent, type WebhookParser } from "./adapter.js";
 export {
   railInList,
+  isInteractivePayInLeg,
   type PayInLeg,
+  type InteractivePayInLeg,
   type PayOutLeg,
   type PayInCapabilities,
   type PayOutCapabilities,
   type CollectResult,
+  type PayInPreparation,
   type DisburseResult,
 } from "./leg.js";
 export {

package/src/leg.ts

@@ -36,6 +36,34 @@ export interface PayInLeg {
   refundIn(intentId: string, kind: RefundKind, reason: string): Promise<Settlement>;
 }
 
+// PayInPreparation is what an interactive pay-in leg hands back so the payer can
+// complete the collection on their own device. clientSecret is the single opaque
+// token the payer's form needs and is never persisted server-side; method names
+// the funding surface presented (a card, a wallet).
+export interface PayInPreparation {
+  providerRef: string;
+  clientSecret: string;
+  method: string;
+}
+
+// InteractivePayInLeg is a pay-in leg whose collection the payer completes on
+// their own device — a card form, a hosted redirect — rather than the server
+// capturing an already-authorized method. prepare creates the provider intent
+// awaiting the payer's confirmation and returns what their device needs; the
+// confirming provider event then advances the corridor through the same pay-in
+// path as an immediate collection. A leg offers this in addition to collect, so a
+// host can drive either an interactive payer or a server-side charge.
+export interface InteractivePayInLeg extends PayInLeg {
+  prepare(intentId: string, quote: Quote, auth: Authorization, deliverTo: string): Promise<PayInPreparation>;
+}
+
+// isInteractivePayInLeg reports whether a pay-in leg can prepare an interactive
+// collection, so the client can offer a payer-completed corridor where the rail
+// supports one and fall back to server-side collection otherwise.
+export function isInteractivePayInLeg(leg: PayInLeg): leg is InteractivePayInLeg {
+  return typeof (leg as InteractivePayInLeg).prepare === "function";
+}
+
 // PayOutCapabilities describes what a pay-out leg can deliver. reversible reports
 // whether a completed payout can be pulled back; an irreversible rail answers a
 // refund with a counter-transfer, never a reversal.