vona-module-test-pay 5.0.4 → 5.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-module-test-pay",
-  "version": "5.0.4",
+  "version": "5.0.5",
   "description": "",
   "keywords": [
     "Vona Module"
@@ -30,8 +30,9 @@
     "postpack": "clean-package restore"
   },
   "dependencies": {
-    "vona-module-a-pay": "5.0.5",
-    "vona-module-pay-mock": "5.0.5"
+    "vona-module-a-pay": "5.0.6",
+    "vona-module-pay-mock": "5.0.6",
+    "vona-module-pay-stripe": "5.0.6"
   },
   "title": "test-pay",
   "vonaModule": {
@@ -51,5 +52,5 @@
       }
     }
   },
-  "gitHead": "f56eaba77347037643b625c8e6c5af408ff2d495"
+  "gitHead": "75a09e6a22891e958802ee649ed454db38f90c16"
 }

package/test/paymentSession.test.ts

@@ -132,7 +132,7 @@ describe('paymentSession.test.ts', { concurrency: false }, () => {
             amountMinor: 1299,
             currency: 'USD',
             correlationId: `payment-${suffix}`,
-            providerCandidateKey: 'stripe',
+            providerCandidateKey: 'unavailable-provider',
           }),
           error =>
             isZodCustomError(
@@ -490,6 +490,97 @@ describe('paymentSession.test.ts', { concurrency: false }, () => {
     });
   });
 
+  it('finalizes an exhausted payment start operation from provider failure', async () => {
+    await app.bean.executor.mockCtx(async () => {
+      const fixture = await createFixture(new Date(Date.now() + 60_000));
+      try {
+        const scope = app.scope('a-pay');
+        const operation = await scope.service.providerOperation.ensureStart(
+          fixture.paymentSessionId!,
+        );
+        const claimed = await scope.service.providerOperation.claim(operation.id);
+        assert.ok(claimed?.claimToken);
+        await scope.service.providerOperation.markSubmitted(operation.id, claimed.claimToken);
+        await scope.model.providerOperation.updateById(operation.id, { attemptCount: 10 });
+
+        await scope.service.providerOperation.releaseForReconciliation(
+          operation.id,
+          claimed.claimToken,
+          new Error('provider start failed'),
+        );
+
+        const [storedSession, storedOperation, audits, outbox] = await Promise.all([
+          scope.model.paymentSession.getById(fixture.paymentSessionId!),
+          scope.model.providerOperation.getById(operation.id),
+          scope.model.paymentAudit.select({
+            where: { paymentSessionId: fixture.paymentSessionId! },
+          }),
+          scope.model.outboxEvent.select({
+            where: { paymentSessionId: fixture.paymentSessionId! },
+          }),
+        ]);
+        assert.equal(storedSession?.state, 'failed');
+        assert.ok(storedSession?.finalizedAt);
+        assert.equal(storedOperation?.state, 'failed');
+        assert.equal(storedOperation?.claimToken, undefined);
+        assert.equal(storedOperation?.nextAttemptAt, undefined);
+        assert.equal(storedOperation?.errorCode, 'provider_operation_failed');
+        assert.equal(
+          storedOperation?.errorSummary,
+          'Provider operation failed and will be reconciled',
+        );
+        assert.equal(audits.length, 2);
+        assert.equal(audits[1].providerOperationId, operation.id);
+        assert.equal(audits[1].fromState, 'starting');
+        assert.equal(audits[1].toState, 'failed');
+        assert.equal(audits[1].source, 'providerOperation.start.attemptsExhausted');
+        assert.equal(outbox.length, 1);
+        assert.equal(outbox[0].eventType, 'payment.outcome.v1');
+        assert.deepEqual((outbox[0].payload as any).state, 'failed');
+      } finally {
+        await cleanup(fixture);
+      }
+    });
+  });
+
+  it('finalizes an exhausted eligible payment operation only once', async () => {
+    await app.bean.executor.mockCtx(async () => {
+      const fixture = await createFixture(new Date(Date.now() + 60_000));
+      try {
+        const scope = app.scope('a-pay');
+        const operation = await scope.service.providerOperation.ensureStart(
+          fixture.paymentSessionId!,
+        );
+        await scope.model.providerOperation.updateById(operation.id, {
+          attemptCount: 10,
+          nextAttemptAt: new Date(0),
+          errorCode: 'provider_operation_failed',
+          errorSummary: 'Provider operation failed and will be reconciled',
+        });
+
+        assert.equal(await scope.service.providerOperation.claim(operation.id), undefined);
+        assert.equal(await scope.service.providerOperation.claim(operation.id), undefined);
+
+        const [storedSession, storedOperation, audits, outbox] = await Promise.all([
+          scope.model.paymentSession.getById(fixture.paymentSessionId!),
+          scope.model.providerOperation.getById(operation.id),
+          scope.model.paymentAudit.select({
+            where: { paymentSessionId: fixture.paymentSessionId! },
+          }),
+          scope.model.outboxEvent.select({
+            where: { paymentSessionId: fixture.paymentSessionId! },
+          }),
+        ]);
+        assert.equal(storedSession?.state, 'failed');
+        assert.equal(storedOperation?.state, 'failed');
+        assert.equal(audits.length, 2);
+        assert.equal(outbox.length, 1);
+      } finally {
+        await cleanup(fixture);
+      }
+    });
+  });
+
   it('allows only one competing start to call the provider', async () => {
     const fixture = await app.bean.executor.mockCtx(async () => {
       return await createFixture(new Date(Date.now() + 60_000));

package/test/paypalLifecycle.test.ts

@@ -362,6 +362,11 @@ describe('paypalLifecycle.test.ts', { concurrency: false, sequential: true }, ()
           const returnUrl = await callbackToken(started.id as number, 'return');
           const returnState = new URL(returnUrl).searchParams.get('state');
           assert.ok(returnState);
+          const callback = await pay.service.paymentCallback.consume('return', returnState);
+          assert.equal(
+            callback.continuationPath,
+            `/commerce/commerce/trade/payment/${started.id}/${fixture.orderId}?providerResult=return`,
+          );
           await assert.rejects(
             app.bean.executor.performAction('get', '/pay/payment-callback/return', {
               query: { state: returnState },
@@ -1227,6 +1232,8 @@ describe('paypalLifecycle.test.ts', { concurrency: false, sequential: true }, ()
           assert.equal(outboxes[0]?.payload.state, 'failed');
           await pay.queue.outboxDispatch.pushAsync({ outboxEventId: outboxes[0]!.id });
           await pay.queue.outboxDispatch.pushAsync({ outboxEventId: outboxes[0]!.id });
+          const dispatched = await pay.model.outboxEvent.getById(outboxes[0]!.id);
+          assert.equal(dispatched?.state, 'dispatched', dispatched?.errorSummary);
           const [settledOrder, request, attempt, line, balance] = await Promise.all([
             app.scope('commerce-trade').model.order.getById(fixture.orderId!),
             app.scope('commerce-payment').model.refundRequest.getById(executed.refundRequestId!),

package/test/stripeLifecycle.test.ts

@@ -0,0 +1,545 @@
+import assert from 'node:assert';
+import { randomUUID } from 'node:crypto';
+import { after, before, describe, it } from 'node:test';
+import { acquireTestLock, app } from 'vona-mock';
+
+interface IFixture {
+  categoryId?: number;
+  productId?: number;
+  skuId?: number;
+  balanceId?: number;
+  addressId?: number;
+  cartId?: number;
+  userId?: number;
+  customerName?: string;
+  orderId?: number;
+  paymentAttemptId?: number;
+  paymentSessionId?: number;
+}
+
+interface IGatewayState {
+  checkoutSessionId?: string;
+  paymentIntentId?: string;
+  providerInvoiceReference?: string;
+  providerCorrelationReference?: string;
+  createFailuresRemaining?: number;
+  retrieveFailuresRemaining?: number;
+  calls: Array<{ kind: string; input: unknown }>;
+}
+
+function createGateway(state: IGatewayState) {
+  return {
+    async createCheckoutSession(_options: unknown, input: any) {
+      state.calls.push({ kind: 'createCheckoutSession', input });
+      state.providerCorrelationReference = input.body.client_reference_id;
+      state.providerInvoiceReference = input.body.metadata.providerInvoiceReference;
+      if (state.createFailuresRemaining) {
+        state.createFailuresRemaining -= 1;
+        throw new Error('transient Stripe Checkout creation failure');
+      }
+      state.checkoutSessionId = `stripe-checkout-${state.providerCorrelationReference}`;
+      state.paymentIntentId = `stripe-payment-${state.providerCorrelationReference}`;
+      return checkoutSessionRecord(state);
+    },
+    async retrieveCheckoutSession(_options: unknown, input: unknown) {
+      state.calls.push({ kind: 'retrieveCheckoutSession', input });
+      if (state.retrieveFailuresRemaining) {
+        state.retrieveFailuresRemaining -= 1;
+        throw new Error('transient Stripe Checkout retrieval failure');
+      }
+      return checkoutSessionRecord(state, { settled: true });
+    },
+    async constructWebhookEvent(_options: unknown, input: unknown) {
+      state.calls.push({ kind: 'constructWebhookEvent', input });
+      return {
+        id: `evt_${state.providerCorrelationReference}`,
+        type: 'checkout.session.completed',
+        data: { object: checkoutSessionRecord(state, { settled: true }) },
+      };
+    },
+  };
+}
+
+function checkoutSessionRecord(state: IGatewayState, options: { settled?: boolean } = {}) {
+  return {
+    id: state.checkoutSessionId,
+    amount_total: 1299,
+    currency: 'usd',
+    livemode: false,
+    status: options.settled ? 'complete' : 'open',
+    payment_status: options.settled ? 'paid' : 'unpaid',
+    url: `https://checkout.stripe.test/${state.checkoutSessionId}`,
+    client_reference_id: state.providerCorrelationReference,
+    metadata: {
+      providerCorrelationReference: state.providerCorrelationReference,
+      providerInvoiceReference: state.providerInvoiceReference,
+    },
+    ...(options.settled && {
+      payment_intent: {
+        id: state.paymentIntentId,
+        amount: 1299,
+        currency: 'usd',
+        status: 'succeeded',
+        metadata: {
+          providerCorrelationReference: state.providerCorrelationReference,
+          providerInvoiceReference: state.providerInvoiceReference,
+        },
+      },
+    }),
+  };
+}
+
+function providerState(gateway: ReturnType<typeof createGateway>) {
+  return {
+    'pay-stripe:stripe/default': {
+      secretCredential: 'sk_test_lifecycle',
+      secretWebhook: 'whsec_test_lifecycle',
+      gateway,
+    },
+  } as never;
+}
+
+function providerExtraData(gateway: ReturnType<typeof createGateway>) {
+  return {
+    state: { payProviderClientOptions: providerState(gateway) } as never,
+  };
+}
+
+async function cleanup(fixture: IFixture) {
+  const trade = app.scope('commerce-trade');
+  const payment = app.scope('commerce-payment');
+  const catalog = app.scope('commerce-catalog');
+  const member = app.scope('commerce-member');
+  const pay = app.scope('a-pay');
+  if (fixture.paymentSessionId !== undefined) {
+    const refunds = await pay.model.refundOperation.select({
+      where: { paymentSessionId: fixture.paymentSessionId },
+    });
+    for (const refund of refunds) {
+      const providerOperation = await pay.model.providerOperation.get({
+        refundOperationId: refund.id,
+        kind: 'refund',
+      });
+      if (providerOperation) {
+        await pay.model.providerOperationRecoveryAudit.delete({
+          providerOperationId: providerOperation.id,
+        });
+      }
+      await pay.model.providerOperation.delete({
+        refundOperationId: refund.id,
+      });
+      await pay.model.outboxEvent.delete({ refundOperationId: refund.id });
+      await pay.model.webhookInbox.delete({ refundOperationId: refund.id });
+      await pay.model.refundOperation.delete({ id: refund.id });
+    }
+    await pay.model.providerOperation.delete({
+      paymentSessionId: fixture.paymentSessionId,
+    });
+    await pay.model.outboxEvent.delete({
+      paymentSessionId: fixture.paymentSessionId,
+    });
+    await pay.model.webhookInbox.delete({
+      paymentSessionId: fixture.paymentSessionId,
+    });
+    await pay.model.paymentAudit.delete({
+      paymentSessionId: fixture.paymentSessionId,
+    });
+  }
+  if (fixture.orderId !== undefined) {
+    const requests = await payment.model.refundRequest.select({
+      where: { orderId: fixture.orderId },
+    });
+    for (const request of requests) {
+      await payment.model.refundAudit.delete({ refundRequestId: request.id });
+      await payment.model.refundAttempt.delete({ refundRequestId: request.id });
+    }
+    await payment.model.refundRequest.delete({ orderId: fixture.orderId });
+    await trade.model.orderAudit.delete({ orderId: fixture.orderId });
+    const lines = await trade.model.orderLine.select({
+      where: { orderId: fixture.orderId },
+    });
+    for (const line of lines) await trade.model.stockReservation.delete({ orderLineId: line.id });
+    await trade.model.orderLine.delete({ orderId: fixture.orderId });
+    await trade.model.order.delete({ id: fixture.orderId });
+  }
+  if (fixture.paymentAttemptId !== undefined) {
+    await payment.model.paymentAudit.delete({
+      paymentAttemptId: fixture.paymentAttemptId,
+    });
+    await payment.model.paymentAttempt.delete({ id: fixture.paymentAttemptId });
+  }
+  if (fixture.paymentSessionId !== undefined) {
+    await pay.model.paymentSession.delete({ id: fixture.paymentSessionId });
+  }
+  if (fixture.cartId !== undefined) {
+    await trade.model.cartItem.delete({ cartId: fixture.cartId });
+    await trade.model.cart.delete({ id: fixture.cartId });
+  }
+  if (fixture.addressId !== undefined) await member.model.address.delete({ id: fixture.addressId });
+  if (fixture.balanceId !== undefined)
+    await trade.model.stockBalance.delete({ id: fixture.balanceId });
+  if (fixture.skuId !== undefined) await catalog.model.sku.delete({ id: fixture.skuId });
+  if (fixture.productId !== undefined)
+    await catalog.model.product.delete({ id: fixture.productId });
+  if (fixture.categoryId !== undefined) {
+    await catalog.model.category.delete({ id: fixture.categoryId });
+  }
+  if (fixture.userId !== undefined) {
+    await app.scope('home-user').model.roleUser.delete({ userId: fixture.userId });
+    await app.bean.user.removeById(fixture.userId);
+  }
+}
+
+async function createCheckout(suffix: string): Promise<IFixture> {
+  const fixture: IFixture = {};
+  await app.bean.passport.signinMock();
+  fixture.categoryId = await app.bean.executor.performAction('post', '/commerce/catalog/category', {
+    body: { name: `stripe-category-${suffix}`, published: true },
+  });
+  fixture.productId = await app.bean.executor.performAction('post', '/commerce/catalog/product', {
+    body: {
+      categoryId: fixture.categoryId,
+      title: `stripe-product-${suffix}`,
+      published: true,
+    },
+  });
+  fixture.skuId = await app.bean.executor.performAction('post', '/commerce/catalog/sku', {
+    body: {
+      productId: fixture.productId,
+      code: `stripe-sku-${suffix}`,
+      priceCents: 1299,
+      attributes: [],
+      lifecycle: 'active',
+    },
+  });
+  fixture.balanceId = (
+    await app.scope('commerce-trade').service.stockBalance.adjustStock({
+      skuId: fixture.skuId,
+      delta: 1,
+      reason: 'Stripe lifecycle fixture',
+      correlationId: `stripe-stock-${suffix}`,
+    })
+  ).id as number;
+  await app.bean.passport.signout();
+  fixture.customerName = `stripe-customer-${suffix}`;
+  const customer = await app.bean.user.register({ name: fixture.customerName }, true);
+  fixture.userId = customer.id as number;
+  await app.bean.passport.signinMock(fixture.customerName as any);
+  const userId = app.bean.passport.currentUser!.id;
+  fixture.addressId = await app.bean.executor.performAction(
+    'post',
+    '/commerce/member/address/createMine',
+    {
+      body: {
+        recipientName: 'Stripe Customer',
+        phone: '15555550137',
+        countryCode: 'US',
+        region: 'California',
+        city: 'San Francisco',
+        postalCode: '94105',
+        addressLine1: '10 Market Street',
+      },
+    },
+  );
+  const cart = await app.scope('commerce-trade').model.cart.insert({ userId });
+  fixture.cartId = cart.id as number;
+  await app.scope('commerce-trade').model.cartItem.insert({
+    cartId: cart.id,
+    skuId: fixture.skuId,
+    quantity: 1,
+  });
+  const checkout = await app.scope('commerce-trade').service.order.checkout({
+    addressId: fixture.addressId,
+    correlationId: `stripe-checkout-${suffix}`,
+    providerCandidateKey: 'stripe',
+  });
+  fixture.orderId = checkout.orderId as number;
+  fixture.paymentAttemptId = checkout.paymentAttemptId as number;
+  fixture.paymentSessionId = checkout.paymentSessionId as number;
+  return fixture;
+}
+
+async function callbackToken(sessionId: number) {
+  const session = await app.scope('a-pay').model.paymentSession.getById(sessionId);
+  assert.ok(session);
+  return (await app.scope('a-pay').service.paymentCallback.createUrls(session)).returnUrl;
+}
+
+async function consumeReturnCallback(sessionId: number, gateway: ReturnType<typeof createGateway>) {
+  const state = new URL(await callbackToken(sessionId)).searchParams.get('state');
+  assert.ok(state);
+  await assert.rejects(
+    app.bean.executor.performAction('get', '/pay/payment-callback/return', {
+      query: { state },
+      extraData: providerExtraData(gateway),
+    }),
+    { status: 302 },
+  );
+}
+
+async function dispatchPaymentOutcome(paymentSessionId: number) {
+  const pay = app.scope('a-pay');
+  const outbox = await pay.model.outboxEvent.get({
+    paymentSessionId,
+    eventType: 'payment.outcome.v1',
+  });
+  assert.ok(outbox);
+  await pay.queue.outboxDispatch.pushAsync({ outboxEventId: outbox.id });
+  await pay.queue.outboxDispatch.pushAsync({ outboxEventId: outbox.id });
+  return outbox;
+}
+
+describe('stripeLifecycle.test.ts', { concurrency: false, sequential: true }, () => {
+  const releases: Array<() => void> = [];
+  let originalServe: { protocol?: string; host?: string };
+
+  before(async () => {
+    for (const scene of ['a-commerce', 'a-pay']) releases.push(await acquireTestLock(scene));
+    originalServe = { ...app.config.server.serve };
+    (app.config.server.serve as any).protocol = 'http';
+    (app.config.server.serve as any).host = 'localhost';
+  });
+
+  after(() => {
+    Object.assign(app.config.server.serve, originalServe);
+    for (const release of releases.reverse()) release();
+  });
+
+  it('starts Stripe Checkout and settles its return callback through Commerce', async () => {
+    const state: IGatewayState = { calls: [] };
+    const gateway = createGateway(state);
+    await app.bean.executor.mockCtx(
+      async () => {
+        const fixture: IFixture = {};
+        try {
+          const options = app.bean.payProvider.getOptions('pay-stripe:stripe', 'default') as any;
+          assert.equal(options.secretCredential, 'sk_test_lifecycle');
+          Object.assign(fixture, await createCheckout(randomUUID().slice(0, 12)));
+          const pay = app.scope('a-pay');
+          const selected = await pay.model.paymentSession.getById(fixture.paymentSessionId!);
+          assert.equal(selected?.providerName, 'pay-stripe:stripe');
+          assert.equal(selected?.environment, 'sandbox');
+          const started = await pay.service.paymentSession.start(fixture.paymentSessionId!);
+          assert.equal(started.state, 'requires_action');
+          assert.deepEqual(started.nextAction, {
+            kind: 'redirect',
+            url: `https://checkout.stripe.test/${state.checkoutSessionId}`,
+          });
+          const operation = await pay.model.providerOperation.get({
+            paymentSessionId: started.id,
+            kind: 'start',
+          });
+          assert.equal(operation?.state, 'succeeded');
+          assert.match(
+            operation?.idempotencyKey ?? '',
+            /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+          );
+          assert.equal(operation?.providerRequestId, operation?.idempotencyKey);
+          const createCall = state.calls.find(call => call.kind === 'createCheckoutSession') as any;
+          assert.equal(createCall.input.idempotencyKey, operation?.idempotencyKey);
+          assert.equal(
+            createCall.input.body.client_reference_id,
+            started.providerCorrelationReference,
+          );
+          assert.deepEqual(createCall.input.body.metadata, {
+            paymentSessionId: String(started.id),
+            providerCorrelationReference: started.providerCorrelationReference,
+            providerInvoiceReference: started.providerInvoiceReference,
+          });
+          assert.equal(started.providerOrderId, state.checkoutSessionId);
+          await consumeReturnCallback(started.id as number, gateway);
+          const outbox = await dispatchPaymentOutcome(started.id as number);
+          const order = await app.scope('commerce-trade').model.order.getById(fixture.orderId!);
+          const attempt = await app
+            .scope('commerce-payment')
+            .model.paymentAttempt.getById(fixture.paymentAttemptId!);
+          assert.deepEqual(
+            [order?.state, attempt?.state, (await pay.model.outboxEvent.getById(outbox.id))?.state],
+            ['paid', 'succeeded', 'dispatched'],
+          );
+          assert.equal(
+            state.calls.filter(call => call.kind === 'retrieveCheckoutSession').length,
+            1,
+          );
+        } finally {
+          await cleanup(fixture);
+          await app.bean.passport.signout();
+        }
+      },
+      { extraData: providerExtraData(gateway) },
+    );
+  });
+
+  it('reuses an immutable Checkout request after a transient creation failure', async () => {
+    const state: IGatewayState = { createFailuresRemaining: 1, calls: [] };
+    const gateway = createGateway(state);
+    await app.bean.executor.mockCtx(
+      async () => {
+        const fixture: IFixture = {};
+        try {
+          Object.assign(fixture, await createCheckout(randomUUID().slice(0, 12)));
+          const pay = app.scope('a-pay');
+          const started = await pay.service.paymentSession.start(fixture.paymentSessionId!);
+          assert.equal(started.state, 'starting');
+          const operation = await pay.model.providerOperation.get({
+            paymentSessionId: started.id,
+            kind: 'start',
+          });
+          assert.equal(operation?.state, 'reconciliation_required');
+          assert.ok(operation?.startInputSnapshot);
+          assert.match(operation?.startInputSnapshot?.returnUrl ?? '', /payment-callback\/return/);
+          assert.match(operation?.startInputSnapshot?.cancelUrl ?? '', /payment-callback\/cancel/);
+          await pay.model.providerOperation.updateById(operation!.id, {
+            nextAttemptAt: new Date(Date.now() - 1_000),
+          });
+          assert.equal(await pay.service.providerOperation.queueDue(), 1);
+          const retried = await pay.model.paymentSession.getById(started.id);
+          assert.equal(retried?.state, 'requires_action');
+          const createCalls = state.calls.filter(
+            call => call.kind === 'createCheckoutSession',
+          ) as any[];
+          assert.equal(createCalls.length, 2);
+          assert.deepEqual(createCalls[1]?.input, createCalls[0]?.input);
+          assert.equal(createCalls[0]?.input.idempotencyKey, operation?.idempotencyKey);
+          assert.deepEqual(createCalls[0]?.input.body.managed_payments, { enabled: false });
+        } finally {
+          await cleanup(fixture);
+          await app.bean.passport.signout();
+        }
+      },
+      { extraData: providerExtraData(gateway) },
+    );
+  });
+
+  it('deduplicates a signed Stripe payment webhook before Commerce settlement', async () => {
+    const state: IGatewayState = { calls: [] };
+    const gateway = createGateway(state);
+    await app.bean.executor.mockCtx(
+      async () => {
+        const fixture: IFixture = {};
+        try {
+          Object.assign(fixture, await createCheckout(randomUUID().slice(0, 12)));
+          const pay = app.scope('a-pay');
+          const started = await pay.service.paymentSession.start(fixture.paymentSessionId!);
+          const rawBody = JSON.stringify({
+            id: `stripe-webhook-${started.id}`,
+          });
+          const verified = await pay.bean.payProvider.get('pay-stripe:stripe').verifyWebhook(
+            {
+              rawBody,
+              body: JSON.parse(rawBody),
+              headers: { 'stripe-signature': 'stripe-signature-test' },
+            },
+            pay.bean.payProvider.getOptions('pay-stripe:stripe', 'default'),
+          );
+          await pay.service.webhook.receive({
+            providerName: 'pay-stripe:stripe',
+            clientName: 'default',
+            environment: 'sandbox',
+            rawBody,
+            verified,
+          });
+          await pay.service.webhook.receive({
+            providerName: 'pay-stripe:stripe',
+            clientName: 'default',
+            environment: 'sandbox',
+            rawBody,
+            verified,
+          });
+          const inboxes = await pay.model.webhookInbox.select({
+            where: { paymentSessionId: started.id },
+          });
+          assert.equal(inboxes.length, 1);
+          const outboxes = await pay.model.outboxEvent.select({
+            where: {
+              paymentSessionId: started.id,
+              eventType: 'payment.outcome.v1',
+            },
+          });
+          assert.equal(outboxes.length, 1);
+          const webhookCall = state.calls.find(
+            call => call.kind === 'constructWebhookEvent',
+          ) as any;
+          assert.deepEqual(webhookCall.input, {
+            rawBody,
+            body: JSON.parse(rawBody),
+            headers: { 'stripe-signature': 'stripe-signature-test' },
+          });
+          await pay.queue.outboxDispatch.pushAsync({
+            outboxEventId: outboxes[0]!.id,
+          });
+          await pay.queue.outboxDispatch.pushAsync({
+            outboxEventId: outboxes[0]!.id,
+          });
+          const dispatched = await pay.model.outboxEvent.getById(outboxes[0]!.id);
+          assert.equal(
+            dispatched?.state,
+            'dispatched',
+            dispatched?.errorSummary ?? 'outbox did not dispatch',
+          );
+          const order = await app.scope('commerce-trade').model.order.getById(fixture.orderId!);
+          const attempt = await app
+            .scope('commerce-payment')
+            .model.paymentAttempt.getById(fixture.paymentAttemptId!);
+          assert.deepEqual([order?.state, attempt?.state], ['paid', 'succeeded']);
+        } finally {
+          await cleanup(fixture);
+          await app.bean.passport.signout();
+        }
+      },
+      { extraData: providerExtraData(gateway) },
+    );
+  });
+
+  it('recovers a transient Stripe Checkout retrieval failure through reconciliation', async () => {
+    const state: IGatewayState = { retrieveFailuresRemaining: 1, calls: [] };
+    const gateway = createGateway(state);
+    await app.bean.executor.mockCtx(
+      async () => {
+        const fixture: IFixture = {};
+        try {
+          Object.assign(fixture, await createCheckout(randomUUID().slice(0, 12)));
+          const pay = app.scope('a-pay');
+          const started = await pay.service.paymentSession.start(fixture.paymentSessionId!);
+          await consumeReturnCallback(started.id as number, gateway);
+          const operation = await pay.model.providerOperation.get({
+            paymentSessionId: started.id,
+            kind: 'confirm',
+          });
+          assert.equal(operation?.state, 'reconciliation_required');
+          assert.equal(operation?.errorSummary, 'Provider operation failed and will be reconciled');
+          assert.ok(operation?.nextAttemptAt);
+          assert.equal(
+            await pay.model.outboxEvent.get({
+              paymentSessionId: started.id,
+              eventType: 'payment.outcome.v1',
+            }),
+            undefined,
+          );
+          assert.equal(
+            (await app.scope('commerce-trade').model.order.getById(fixture.orderId!))?.state,
+            'awaiting_payment',
+          );
+          await pay.model.providerOperation.updateById(operation!.id, {
+            nextAttemptAt: new Date(Date.now() - 1_000),
+          });
+          assert.equal(await pay.service.providerOperation.queueDue(), 1);
+          assert.equal((await pay.model.paymentSession.getById(started.id))?.state, 'succeeded');
+          await dispatchPaymentOutcome(started.id as number);
+          assert.equal(
+            (await app.scope('commerce-trade').model.order.getById(fixture.orderId!))?.state,
+            'paid',
+          );
+          assert.equal(
+            state.calls.filter(call => call.kind === 'retrieveCheckoutSession').length,
+            2,
+          );
+        } finally {
+          await cleanup(fixture);
+          await app.bean.passport.signout();
+        }
+      },
+      { extraData: providerExtraData(gateway) },
+    );
+  });
+});

package/test/stripeProvider.test.ts

@@ -0,0 +1,300 @@
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+import { app } from 'vona-mock';
+
+function createOptions(gateway: Record<string, unknown>) {
+  const { clientOptions } = app.bean.payProvider.resolveByName('pay-stripe:stripe', 'default');
+  return {
+    ...clientOptions,
+    secretCredential: 'sk_test_1',
+    secretWebhook: 'whsec_1',
+    gateway,
+  } as never;
+}
+
+const paymentInput = {
+  paymentSessionId: 101,
+  businessReference: 'business-1',
+  providerInvoiceReference: 'payment-invoice-reference',
+  providerCorrelationReference: 'payment-correlation-reference',
+  idempotencyKey: 'payment-key',
+  amountMinor: 1299,
+  currency: 'USD',
+  providerOrderId: 'cs_1',
+};
+
+const refundInput = {
+  paymentSessionId: 101,
+  refundOperationId: 201,
+  businessReference: 'refund-business-1',
+  providerInvoiceReference: 'refund-invoice-reference',
+  providerCorrelationReference: 'refund-correlation-reference',
+  idempotencyKey: 'refund-key',
+  amountMinor: 500,
+  currency: 'USD',
+  providerCaptureId: 'pi_1',
+};
+
+function checkoutSession(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 'cs_1',
+    amount_total: 1299,
+    currency: 'usd',
+    livemode: false,
+    status: 'open',
+    payment_status: 'unpaid',
+    url: 'https://checkout.stripe.test/c/pay/cs_1',
+    client_reference_id: 'payment-correlation-reference',
+    metadata: {
+      paymentSessionId: '101',
+      providerCorrelationReference: 'payment-correlation-reference',
+      providerInvoiceReference: 'payment-invoice-reference',
+    },
+    ...overrides,
+  };
+}
+
+function paymentIntent(status: string, overrides: Record<string, unknown> = {}) {
+  return {
+    id: 'pi_1',
+    amount: 1299,
+    currency: 'usd',
+    status,
+    metadata: {
+      paymentSessionId: '101',
+      providerCorrelationReference: 'payment-correlation-reference',
+      providerInvoiceReference: 'payment-invoice-reference',
+    },
+    ...overrides,
+  };
+}
+
+function refundRecord(status: string, overrides: Record<string, unknown> = {}) {
+  return {
+    id: 're_1',
+    amount: 500,
+    currency: 'usd',
+    payment_intent: 'pi_1',
+    status,
+    metadata: {
+      paymentSessionId: '101',
+      refundOperationId: '201',
+      providerCorrelationReference: 'refund-correlation-reference',
+      providerInvoiceReference: 'refund-invoice-reference',
+    },
+    ...overrides,
+  };
+}
+
+describe('stripeProvider.test.ts', { concurrency: false }, () => {
+  it('creates a hosted Checkout Session with durable references and redirect action', async () => {
+    await app.bean.executor.mockCtx(async () => {
+      const calls: unknown[] = [];
+      const gateway = {
+        async createCheckoutSession(_options: unknown, input: unknown) {
+          calls.push(input);
+          return checkoutSession();
+        },
+      };
+      const { provider } = app.bean.payProvider.resolveByName('pay-stripe:stripe', 'default');
+      const payment = await provider.startPayment(
+        {
+          ...paymentInput,
+          providerOrderId: undefined,
+          returnUrl: 'https://shop.test/pay/return',
+          cancelUrl: 'https://shop.test/pay/cancel',
+        },
+        createOptions(gateway),
+      );
+
+      assert.deepEqual(payment, {
+        state: 'requires_action',
+        providerPaymentId: 'cs_1',
+        providerOrderId: 'cs_1',
+        nextAction: {
+          kind: 'redirect',
+          url: 'https://checkout.stripe.test/c/pay/cs_1',
+        },
+      });
+      assert.deepEqual(calls, [
+        {
+          idempotencyKey: 'payment-key',
+          body: {
+            mode: 'payment',
+            success_url: 'https://shop.test/pay/return',
+            cancel_url: 'https://shop.test/pay/cancel',
+            client_reference_id: 'payment-correlation-reference',
+            metadata: {
+              paymentSessionId: '101',
+              providerCorrelationReference: 'payment-correlation-reference',
+              providerInvoiceReference: 'payment-invoice-reference',
+            },
+            payment_intent_data: {
+              metadata: {
+                paymentSessionId: '101',
+                providerCorrelationReference: 'payment-correlation-reference',
+                providerInvoiceReference: 'payment-invoice-reference',
+              },
+            },
+            managed_payments: { enabled: false },
+            line_items: [
+              {
+                quantity: 1,
+                price_data: {
+                  currency: 'usd',
+                  unit_amount: 1299,
+                  product_data: { name: 'Payment payment-invoice-reference' },
+                },
+              },
+            ],
+          },
+        },
+      ]);
+    });
+  });
+
+  it('treats a definitive Stripe Checkout rejection as terminal', async () => {
+    await app.bean.executor.mockCtx(async () => {
+      const gateway = {
+        async createCheckoutSession() {
+          const error = new Error('Stripe rejected the request');
+          (error as Error & { type: string }).type = 'StripeInvalidRequestError';
+          throw error;
+        },
+      };
+      const { provider } = app.bean.payProvider.resolveByName('pay-stripe:stripe', 'default');
+      await assert.rejects(
+        provider.startPayment(
+          {
+            ...paymentInput,
+            providerOrderId: undefined,
+            returnUrl: 'https://shop.test/pay/return',
+            cancelUrl: 'https://shop.test/pay/cancel',
+          },
+          createOptions(gateway),
+        ),
+        { failureCode: 'stripe_request_rejected' },
+      );
+    });
+  });
+
+  it('maps Checkout and PaymentIntent facts without trusting conflicting resources', async () => {
+    await app.bean.executor.mockCtx(async () => {
+      let result: unknown = checkoutSession({
+        payment_intent: paymentIntent('succeeded'),
+      });
+      const gateway = {
+        async retrieveCheckoutSession() {
+          return result;
+        },
+      };
+      const { provider } = app.bean.payProvider.resolveByName('pay-stripe:stripe', 'default');
+      const options = createOptions(gateway);
+
+      const payment = await provider.queryPayment(paymentInput, options);
+      assert.deepEqual(payment, {
+        state: 'succeeded',
+        providerPaymentId: 'pi_1',
+        providerOrderId: 'cs_1',
+        providerCaptureId: 'pi_1',
+        nextAction: { kind: 'completed' },
+      });
+      result = checkoutSession({ amount_total: 1399 });
+      await assert.rejects(provider.queryPayment(paymentInput, options), {
+        status: 409,
+      });
+    });
+  });
+
+  it('maps full and partial Stripe refunds and preserves ambiguous failures', async () => {
+    await app.bean.executor.mockCtx(async () => {
+      let status = 'succeeded';
+      let error: Error | undefined;
+      const gateway = {
+        async createRefund(_options: unknown, input: unknown) {
+          if (error) {
+            throw new Error(`Stripe gateway failed: ${error.message}`, {
+              cause: error,
+            });
+          }
+          assert.deepEqual(input, {
+            idempotencyKey: 'refund-key',
+            body: {
+              payment_intent: 'pi_1',
+              amount: 500,
+              metadata: {
+                paymentSessionId: '101',
+                refundOperationId: '201',
+                providerCorrelationReference: 'refund-correlation-reference',
+                providerInvoiceReference: 'refund-invoice-reference',
+              },
+            },
+          });
+          return refundRecord(status);
+        },
+        async retrieveRefund() {
+          return refundRecord(status);
+        },
+      };
+      const { provider } = app.bean.payProvider.resolveByName('pay-stripe:stripe', 'default');
+      const options = createOptions(gateway);
+      for (const [nextStatus, state] of [
+        ['succeeded', 'succeeded'],
+        ['pending', 'pending'],
+        ['failed', 'failed'],
+        ['canceled', 'cancelled'],
+      ] as const) {
+        status = nextStatus;
+        assert.equal((await provider.createRefund(refundInput, options)).state, state);
+        assert.equal(
+          (await provider.queryRefund!({ ...refundInput, providerRefundId: 're_1' }, options))
+            .state,
+          state,
+        );
+      }
+      error = new Error('transport failure');
+      await assert.rejects(provider.createRefund(refundInput, options), /transport failure/);
+    });
+  });
+
+  it('maps signed terminal Stripe webhook facts through its gateway', async () => {
+    await app.bean.executor.mockCtx(async () => {
+      const gateway = {
+        async constructWebhookEvent(_options: unknown, input: unknown) {
+          assert.deepEqual(input, {
+            rawBody: '{"id":"evt_1"}',
+            body: {},
+            headers: { 'stripe-signature': 'sig' },
+          });
+          return {
+            id: 'evt_1',
+            type: 'checkout.session.async_payment_failed',
+            data: { object: checkoutSession() },
+          };
+        },
+      };
+      const pay = app.scope('a-pay');
+      const originalGet = pay.model.paymentSession.get;
+      (pay.model.paymentSession as any).get = async () => ({
+        ...paymentInput,
+        id: 101,
+        providerOrderId: 'cs_1',
+      });
+      try {
+        const { provider } = app.bean.payProvider.resolveByName('pay-stripe:stripe', 'default');
+        const verified = await provider.verifyWebhook(
+          {
+            rawBody: '{"id":"evt_1"}',
+            body: {},
+            headers: { 'stripe-signature': 'sig' },
+          },
+          createOptions(gateway),
+        );
+        assert.equal(verified.paymentSessionId, 101);
+        assert.equal(verified.payment?.state, 'failed');
+      } finally {
+        (pay.model.paymentSession as any).get = originalGet;
+      }
+    });
+  });
+});