[SDK] Fix Universal Bridge onramp reporting success when it did not complete

.changeset/onramp-success-guard.md

@@ -0,0 +1,5 @@
+---
+"thirdweb": patch
+---
+
+Fixed Universal Bridge onramp checkout incorrectly reporting success when the onramp did not complete. A failed onramp now surfaces the error instead of a false success, and retrying a failed onramp prepares a fresh payment session rather than replaying the expired one (post-onramp transaction failures still retry in place, so completed onramps are never charged twice).

packages/thirdweb/src/react/core/hooks/useStepExecutor.test.tsx

@@ -0,0 +1,134 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { TEST_CLIENT } from "~test/test-clients.js";
+import type { WindowAdapter } from "../adapters/WindowAdapter.js";
+import type { BridgePrepareResult } from "./useBridgePrepare.js";
+import { useStepExecutor } from "./useStepExecutor.js";
+
+// Avoid firing analytics network calls while executing.
+vi.mock("../../../analytics/track/pay.js", () => ({
+  trackPayEvent: vi.fn(),
+}));
+
+const { onrampStatusMock } = vi.hoisted(() => ({
+  onrampStatusMock: vi.fn(),
+}));
+vi.mock("../../../bridge/index.js", () => ({
+  Onramp: {
+    status: (options: unknown) => onrampStatusMock(options),
+  },
+}));
+
+// Minimal onramp quote with no follow-up transactions, so the executor's
+// behaviour depends solely on the onramp outcome.
+const ONRAMP_QUOTE: Extract<BridgePrepareResult, { type: "onramp" }> = {
+  currency: "USD",
+  currencyAmount: 30,
+  destinationAmount: 30000000n,
+  destinationToken: {
+    address: "0x0000000000000000000000000000000000000000",
+    chainId: 8453,
+    decimals: 6,
+    name: "USD Coin",
+    prices: {},
+    symbol: "USDC",
+  },
+  id: "onramp-session-id",
+  intent: {
+    chainId: 8453,
+    onramp: "transak",
+    receiver: "0x0000000000000000000000000000000000000001",
+    tokenAddress: "0x0000000000000000000000000000000000000000",
+  },
+  link: "https://onramp.example.com/session",
+  steps: [],
+  type: "onramp",
+};
+
+function createWindowAdapter(): WindowAdapter {
+  return { open: vi.fn(async () => {}) };
+}
+
+describe("useStepExecutor onramp guards", () => {
+  it("surfaces an error when the onramp reports FAILED", async () => {
+    onrampStatusMock.mockResolvedValue({ status: "FAILED", transactions: [] });
+    const windowAdapter = createWindowAdapter();
+
+    const { result } = renderHook(() =>
+      useStepExecutor({
+        client: TEST_CLIENT,
+        preparedQuote: ONRAMP_QUOTE,
+        windowAdapter,
+      }),
+    );
+
+    await act(async () => {
+      result.current.start();
+    });
+
+    await waitFor(() => expect(result.current.onrampStatus).toBe("failed"));
+    expect(result.current.error?.message).toBe("Payment failed");
+    expect(result.current.executionState).toBe("idle");
+    expect(windowAdapter.open).toHaveBeenCalledWith(ONRAMP_QUOTE.link);
+  });
+
+  it("does not report success when a prior onramp attempt failed", async () => {
+    onrampStatusMock.mockResolvedValue({ status: "FAILED", transactions: [] });
+    const windowAdapter = createWindowAdapter();
+    const onComplete = vi.fn();
+
+    const { result } = renderHook(() =>
+      useStepExecutor({
+        client: TEST_CLIENT,
+        onComplete,
+        preparedQuote: ONRAMP_QUOTE,
+        windowAdapter,
+      }),
+    );
+
+    // First attempt fails and leaves the onramp in the "failed" state.
+    await act(async () => {
+      result.current.start();
+    });
+    await waitFor(() => expect(result.current.onrampStatus).toBe("failed"));
+
+    // Retrying must fail fast on the incomplete onramp rather than proceeding.
+    await act(async () => {
+      result.current.retry();
+    });
+    await waitFor(() =>
+      expect(result.current.error?.message).toBe("Onramp did not complete"),
+    );
+    expect(result.current.error?.statusCode).toBe(500);
+    // Success must never be reported for an incomplete onramp.
+    expect(onComplete).not.toHaveBeenCalled();
+  });
+
+  it("marks the onramp complete before reporting success", async () => {
+    onrampStatusMock.mockResolvedValue({
+      status: "COMPLETED",
+      transactions: [],
+    });
+    const windowAdapter = createWindowAdapter();
+    const onComplete = vi.fn();
+
+    const { result } = renderHook(() =>
+      useStepExecutor({
+        client: TEST_CLIENT,
+        onComplete,
+        preparedQuote: ONRAMP_QUOTE,
+        windowAdapter,
+      }),
+    );
+
+    await act(async () => {
+      result.current.start();
+    });
+
+    await waitFor(() => expect(result.current.onrampStatus).toBe("completed"), {
+      timeout: 5000,
+    });
+    expect(result.current.error).toBeUndefined();
+    expect(onComplete).toHaveBeenCalledTimes(1);
+  });
+});

packages/thirdweb/src/react/core/hooks/useStepExecutor.ts

@@ -466,6 +466,7 @@ export function useStepExecutor(
           return { completed: true };
         } else if (status === "FAILED") {
           setOnrampStatus("failed");
+          throw new Error("Payment failed");
         }
 
         return { completed: false };
@@ -517,12 +518,25 @@ export function useStepExecutor(
       }
 
       // Execute onramp first if configured and not already completed
+      let onrampCompleted =
+        preparedQuote.type !== "onramp" || onrampStatus === "completed";
       if (preparedQuote.type === "onramp" && onrampStatus === "pending") {
         await executeOnramp(
           preparedQuote,
           completedStatusResults,
           abortController.signal,
         );
+        onrampCompleted = true;
+      }
+
+      // An onramp must complete before any follow-up transactions run or
+      // success is reported.
+      if (!onrampCompleted) {
+        throw new ApiError({
+          code: "INTERNAL_SERVER_ERROR",
+          message: "Onramp did not complete",
+          statusCode: 500,
+        });
       }
 
       if (flatTxs.length > 0) {

packages/thirdweb/src/react/web/ui/Bridge/BuyWidget.tsx

@@ -731,6 +731,13 @@
             completedStatuses,
           });
         }}
+        onQuoteUpdate={(quote) => {
+          // A failed onramp is retried with a fresh session; keep the success
+          // payload pointed at the session that actually completes.
+          setScreen((prev) =>
+            prev.id === "5:execute" ? { ...prev, preparedQuote: quote } : prev,
+          );
+        }}
         request={screen.request}
         wallet={screen.paymentMethod.payerWallet}
         windowAdapter={webWindowAdapter}

packages/thirdweb/src/react/web/ui/Bridge/CheckoutWidget.tsx

@@ -720,6 +720,13 @@ function CheckoutWidgetContent(
             completedStatuses,
           });
         }}
+        onQuoteUpdate={(quote) => {
+          // A failed onramp is retried with a fresh session; keep the success
+          // payload pointed at the session that actually completes.
+          setScreen((prev) =>
+            prev.id === "5:execute" ? { ...prev, preparedQuote: quote } : prev,
+          );
+        }}
         request={screen.request}
         wallet={screen.paymentMethod.payerWallet}
         windowAdapter={webWindowAdapter}

packages/thirdweb/src/react/web/ui/Bridge/StepRunner.test.tsx

@@ -0,0 +1,143 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { TEST_CLIENT } from "~test/test-clients.js";
+import type { WindowAdapter } from "../../../core/adapters/WindowAdapter.js";
+import { CustomThemeProvider } from "../../../core/design-system/CustomThemeProvider.js";
+import type {
+  BridgePrepareRequest,
+  BridgePrepareResult,
+} from "../../../core/hooks/useBridgePrepare.js";
+import { StepRunner } from "./StepRunner.js";
+
+// Controllable executor + prepare seams so the test drives the retry branch
+// purely off `onrampStatus`.
+const { executor, retrySpy, refetchSpy, FRESH_QUOTE } = vi.hoisted(() => ({
+  executor: {
+    error: undefined as Error | undefined,
+    onrampStatus: undefined as
+      | "pending"
+      | "executing"
+      | "completed"
+      | "failed"
+      | undefined,
+  },
+  FRESH_QUOTE: {
+    id: "fresh-session",
+    link: "https://onramp.example.com/fresh",
+    type: "onramp",
+  },
+  refetchSpy: vi.fn(),
+  retrySpy: vi.fn(),
+}));
+
+vi.mock("../../../core/hooks/useStepExecutor.js", () => ({
+  useStepExecutor: () => ({
+    cancel: vi.fn(),
+    currentStep: undefined,
+    error: executor.error,
+    executionState: "idle" as const,
+    onrampStatus: executor.onrampStatus,
+    progress: 0,
+    retry: retrySpy,
+    start: vi.fn(),
+    steps: [],
+  }),
+}));
+
+vi.mock("../../../core/hooks/useBridgePrepare.js", async (importOriginal) => {
+  const actual =
+    await importOriginal<
+      typeof import("../../../core/hooks/useBridgePrepare.js")
+    >();
+  return { ...actual, useBridgePrepare: () => ({ refetch: refetchSpy }) };
+});
+
+const ONRAMP_REQUEST: BridgePrepareRequest = {
+  chainId: 8453,
+  client: TEST_CLIENT,
+  onramp: "transak",
+  receiver: "0x0000000000000000000000000000000000000001",
+  tokenAddress: "0x0000000000000000000000000000000000000000",
+  type: "onramp",
+};
+
+const ONRAMP_QUOTE: Extract<BridgePrepareResult, { type: "onramp" }> = {
+  currency: "USD",
+  currencyAmount: 30,
+  destinationAmount: 30000000n,
+  destinationToken: {
+    address: "0x0000000000000000000000000000000000000000",
+    chainId: 8453,
+    decimals: 6,
+    name: "USD Coin",
+    prices: {},
+    symbol: "USDC",
+  },
+  id: "onramp-session-id",
+  intent: {
+    chainId: 8453,
+    onramp: "transak",
+    receiver: "0x0000000000000000000000000000000000000001",
+    tokenAddress: "0x0000000000000000000000000000000000000000",
+  },
+  link: "https://onramp.example.com/session",
+  steps: [],
+  type: "onramp",
+};
+
+function renderStepRunner() {
+  const onQuoteUpdate = vi.fn();
+  render(
+    <CustomThemeProvider theme="dark">
+      <StepRunner
+        autoStart={false}
+        client={TEST_CLIENT}
+        onBack={vi.fn()}
+        onCancel={vi.fn()}
+        onComplete={vi.fn()}
+        onQuoteUpdate={onQuoteUpdate}
+        preparedQuote={ONRAMP_QUOTE}
+        request={ONRAMP_REQUEST}
+        title={undefined}
+        wallet={undefined}
+        windowAdapter={{ open: vi.fn(async () => {}) } as WindowAdapter}
+      />
+    </CustomThemeProvider>,
+  );
+  return { onQuoteUpdate };
+}
+
+describe("StepRunner onramp retry recovery", () => {
+  beforeEach(() => {
+    retrySpy.mockReset();
+    refetchSpy.mockReset();
+    refetchSpy.mockResolvedValue({ data: FRESH_QUOTE });
+    executor.error = new Error("Payment failed");
+  });
+
+  it("re-prepares a fresh session when a failed onramp is retried", async () => {
+    executor.onrampStatus = "failed";
+    const { onQuoteUpdate } = renderStepRunner();
+
+    fireEvent.click(screen.getByText("Retry"));
+
+    await waitFor(() => expect(refetchSpy).toHaveBeenCalledTimes(1));
+    // Must NOT replay the dead session in place.
+    expect(retrySpy).not.toHaveBeenCalled();
+    await waitFor(() =>
+      expect(onQuoteUpdate).toHaveBeenCalledWith(FRESH_QUOTE),
+    );
+  });
+
+  it("retries in place (never re-onramps) once the onramp has completed", async () => {
+    // A post-onramp transaction failed: funds already arrived, so re-onramping
+    // would double-charge the buyer.
+    executor.onrampStatus = "completed";
+    renderStepRunner();
+
+    fireEvent.click(screen.getByText("Retry"));
+
+    expect(retrySpy).toHaveBeenCalledTimes(1);
+    expect(refetchSpy).not.toHaveBeenCalled();
+  });
+});