@whop/elements-react-native 0.1.0

package/scripts/mirror.mjs

@@ -0,0 +1,112 @@
+/**
+ * Which React Native files mirror a web elements change.
+ *
+ * `src/core/` is ported from the web elements, so a fix that lands only on web silently leaves the
+ * React Native SDK on the old behaviour. Nothing in a normal web PR points here: the port headers
+ * run RN -> web, so an author editing `apps/web/src/elements/payments/lib/currency.ts` sees no sign
+ * a second copy exists. This closes that direction.
+ *
+ *   node scripts/mirror.mjs                 # counterparts for what changed vs origin/main
+ *   node scripts/mirror.mjs <file>...       # counterparts for named web files
+ *   node scripts/mirror.mjs --validate      # every mapping still points at a real file
+ *
+ * Ported files map themselves: the `ported from <path>` header each one carries IS the edge, so a
+ * new port registers by existing. Only the element components need the table below, because they
+ * are reimplementations against native primitives rather than ports, and carry no such header.
+ */
+
+import { execSync } from 'node:child_process';
+import { existsSync, globSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = join(fileURLToPath(new URL('.', import.meta.url)), '..');
+const repo = join(root, '..', '..', '..');
+const WEB = 'frontend/apps/web/src/elements';
+
+/** Element components: reimplemented on native primitives, so no port header names the source. */
+const ELEMENTS = {
+  'src/elements/payment/index.tsx': [`${WEB}/payments/payment.tsx`],
+  'src/elements/payment/declared-fields.tsx': [`${WEB}/payments/payment.tsx`],
+  'src/elements/payment/wallet.tsx': [`${WEB}/payments/lib/payment-request.ts`],
+  'src/elements/address.tsx': [`${WEB}/payments/address.tsx`],
+  'src/elements/card.tsx': [`${WEB}/payments/card.tsx`],
+  'src/elements/card-fields/index.tsx': [`${WEB}/payments/card-fields/controller.tsx`],
+  'src/elements/card-fields/fields.tsx': [
+    `${WEB}/payments/card-fields/card-number.tsx`,
+    `${WEB}/payments/card-fields/card-expiry.tsx`,
+    `${WEB}/payments/card-fields/card-cvc.tsx`,
+  ],
+  'src/elements/email.tsx': [`${WEB}/payments/email.tsx`],
+  'src/elements/tax-id.tsx': [`${WEB}/payments/tax-id.tsx`],
+  'src/elements/branding.tsx': [`${WEB}/payments/branding.tsx`],
+  'src/controller/actions.ts': [`${WEB}/payments/controller.tsx`],
+  'src/controller/store.ts': [`${WEB}/payments/controller.tsx`],
+  'src/ui/suggestions.tsx': [`${WEB}/payments/address-suggestions.tsx`],
+  'src/ui/payment-method-icon.tsx': [`${WEB}/payments/lib/payment-method-icon.tsx`],
+  'src/ui/whop-logo.tsx': [`${WEB}/payments/whop-logo.tsx`],
+};
+
+function portedHeaders() {
+  const pairs = {};
+  for (const abs of globSync('src/**/*.{ts,tsx}', { cwd: root }).map((p) => join(root, p))) {
+    const head = readFileSync(abs, 'utf8').slice(0, 1200);
+    const sources = [...head.matchAll(/frontend\/apps\/web\/src\/elements\/[\w\-./]+\.tsx?/g)].map((m) => m[0]);
+    if (sources.length > 0) pairs[relative(root, abs)] = [...new Set(sources)];
+  }
+  return pairs;
+}
+
+function buildMap() {
+  const map = { ...portedHeaders() };
+  for (const [rn, web] of Object.entries(ELEMENTS)) map[rn] = [...new Set([...(map[rn] ?? []), ...web])];
+  return map;
+}
+
+/** web path -> the RN files claiming it. */
+function invert(map) {
+  const back = new Map();
+  for (const [rn, webs] of Object.entries(map)) for (const web of webs) back.set(web, [...(back.get(web) ?? []), rn]);
+  return back;
+}
+
+const map = buildMap();
+const args = process.argv.slice(2);
+
+if (args.includes('--validate')) {
+  const missing = [];
+  for (const [rn, webs] of Object.entries(map)) {
+    if (!existsSync(join(root, rn))) missing.push(`  ${rn} (react native side is gone)`);
+    for (const web of webs) if (!existsSync(join(repo, web))) missing.push(`  ${rn} -> ${web} (web side is gone)`);
+  }
+  if (missing.length > 0) {
+    console.error('whop elements: mirror map is stale. A file moved or was deleted:\n' + missing.join('\n'));
+    console.error('\nFix the port header, or the ELEMENTS table in scripts/mirror.mjs.');
+    process.exit(1);
+  }
+  console.log(`whop elements: mirror map is valid (${Object.keys(map).length} react native files)`);
+  process.exit(0);
+}
+
+const changed =
+  args.length > 0
+    ? args
+    : execSync('git diff --name-only origin/main...HEAD', { cwd: repo, encoding: 'utf8' }).split('\n').filter(Boolean);
+
+const back = invert(map);
+const hits = changed.flatMap((f) => (back.get(f) ?? []).map((rn) => [f, rn]));
+
+if (hits.length === 0) {
+  console.log('whop elements: no react native counterpart for the changed web files.');
+  process.exit(0);
+}
+
+const byWeb = new Map();
+for (const [web, rn] of hits) byWeb.set(web, [...(byWeb.get(web) ?? []), rn]);
+
+console.log('whop elements: these web changes have a React Native counterpart.\n');
+for (const [web, rns] of byWeb) {
+  console.log(`  ${web}`);
+  for (const rn of rns) console.log(`    -> packages/elements-react-native/${rn}`);
+}
+console.log('\nPort the change or say why it does not apply. Read .ai-skills/elements-react-native/SKILL.md first.');

package/src/api/client.ts

@@ -0,0 +1,202 @@
+import type {
+	ConfirmationTokenCreateParams,
+	ConfirmationTokenResource,
+	PageInfo,
+	PaymentMethodTypeResource,
+	PaymentResource,
+	PlanResource,
+} from './types';
+
+/**
+ * The API origin is an ENUM over two Whop-owned hosts, never a consumer-supplied string.
+ *
+ * A consumer-settable origin would let the embedding app point a payment surface at a host it
+ * controls and read everything a buyer types into it. The web elements hold the same line
+ * (`elements-framework/src/builder/api-base.ts`); this is that rule on React Native.
+ */
+export const API_BASES = {
+	production: 'https://api.whop.com',
+	sandbox: 'https://api.sandbox.whop.com',
+} as const;
+
+export type WhopEnvironment = keyof typeof API_BASES;
+
+/**
+ * Pinned so a server-side schema roll cannot change what a shipped app parses.
+ *
+ * Must be a REAL released version: the API rejects an unknown date outright, before it even looks
+ * at the request. The published list is `Api::Versioning::RELEASED` in
+ * backend/lib/api/versioning.rb — bump this to a date from there, never to today's date.
+ */
+const API_VERSION_DATE = '2026-08-25';
+
+export class WhopError extends Error {
+	readonly status: number;
+	/** Alias of `status`; the ported payments error helpers read this name. */
+	readonly statusCode: number;
+	readonly code: string | undefined;
+	readonly body: unknown;
+
+	constructor(message: string, status: number, code?: string, body?: unknown) {
+		super(message);
+		this.name = 'WhopError';
+		this.status = status;
+		this.statusCode = status;
+		this.code = code;
+		this.body = body;
+	}
+}
+
+export interface WhopClientOptions {
+	environment?: WhopEnvironment;
+	/** Resolved per request, so a rotating buyer token is never pinned to boot. */
+	getToken?: () => Promise<string | null | undefined> | string | null | undefined;
+	/** The Sardine correlation key, stamped as `x-ssk` when a flow surface is armed. */
+	getSessionKey?: () => string | null | undefined;
+	fetch?: typeof fetch;
+}
+
+interface RequestOptions {
+	query?: Record<string, string | number | boolean | undefined>;
+	body?: unknown;
+	token?: string | null;
+	/** The recognition probe is IP-throttled, so retrying a 5xx spends a buyer's budget. */
+	maxRetries?: number;
+	signal?: AbortSignal;
+}
+
+const RETRYABLE = new Set([408, 429, 500, 502, 503, 504]);
+
+export class WhopClient {
+	readonly baseUrl: string;
+	private readonly options: WhopClientOptions;
+	private readonly doFetch: typeof fetch;
+
+	constructor(options: WhopClientOptions = {}) {
+		this.options = options;
+		this.baseUrl = API_BASES[options.environment ?? 'production'];
+		this.doFetch = options.fetch ?? globalThis.fetch;
+	}
+
+	async request<T>(method: string, path: string, opts: RequestOptions = {}): Promise<T> {
+		const url = new URL(`/api/v1${path}`, this.baseUrl);
+		for (const [key, value] of Object.entries(opts.query ?? {})) {
+			if (value !== undefined) url.searchParams.set(key, String(value));
+		}
+
+		const token = opts.token !== undefined ? opts.token : await this.options.getToken?.();
+		const sessionKey = this.options.getSessionKey?.();
+
+		const headers: Record<string, string> = {
+			accept: 'application/json',
+			'api-version-date': API_VERSION_DATE,
+		};
+		if (opts.body !== undefined) headers['content-type'] = 'application/json';
+		if (token) headers.authorization = `Bearer ${token}`;
+		if (sessionKey) headers['x-ssk'] = sessionKey;
+
+		const maxRetries = opts.maxRetries ?? 2;
+		let lastError: unknown;
+
+		for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+			let response: Response;
+			try {
+				response = await this.doFetch(url.toString(), {
+					method,
+					headers,
+					body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+					signal: opts.signal,
+				});
+			} catch (err) {
+				lastError = new WhopError(
+					err instanceof Error ? err.message : 'the network request failed',
+					0,
+					'NETWORK_UNAVAILABLE',
+				);
+				if (attempt === maxRetries) throw lastError;
+				await backoff(attempt);
+				continue;
+			}
+
+			if (response.ok) {
+				if (response.status === 204) return undefined as T;
+				return (await response.json()) as T;
+			}
+
+			const body = await response.json().catch(() => undefined);
+			const error = new WhopError(errorMessage(body, response.status), response.status, errorCode(body), body);
+			if (!RETRYABLE.has(response.status) || attempt === maxRetries) throw error;
+			lastError = error;
+			await backoff(attempt);
+		}
+
+		throw lastError instanceof Error ? lastError : new WhopError('the request failed', 0);
+	}
+
+	readonly plans = {
+		retrieve: (id: string): Promise<PlanResource> => this.request('GET', `/plans/${encodeURIComponent(id)}`),
+	};
+
+	readonly paymentMethodTypes = {
+		list: (query: {
+			account_id?: string;
+			currency?: string;
+			amount?: number;
+			surface?: string;
+		}): Promise<{ data: PaymentMethodTypeResource[]; page_info: PageInfo }> =>
+			this.request('GET', '/payment_method_types', { query }),
+
+		retrieve: (type: string, query: { account_id?: string }): Promise<PaymentMethodTypeResource> =>
+			this.request('GET', `/payment_method_types/${encodeURIComponent(type)}`, { query }),
+
+		/** Authorizes a Basis Theory session against the nonce-derived card-assembly container. */
+		createSession: (
+			type: string,
+			body: { account_id: string; nonce: string },
+		): Promise<{ object: string; type: string; session: { container: string } }> =>
+			this.request('POST', `/payment_method_types/${encodeURIComponent(type)}/session`, { body }),
+	};
+
+	readonly confirmationTokens = {
+		create: (body: ConfirmationTokenCreateParams): Promise<ConfirmationTokenResource> =>
+			this.request('POST', '/confirmation_tokens', { body, maxRetries: 0 }),
+
+		retrieve: (id: string): Promise<ConfirmationTokenResource> =>
+			this.request('GET', `/confirmation_tokens/${encodeURIComponent(id)}`),
+	};
+
+	readonly payments = {
+		/** The client secret both identifies and authorizes, so no payment id is needed. */
+		retrieveBySecret: (clientSecret: string): Promise<PaymentResource> =>
+			this.request('GET', `/payments/${encodeURIComponent(paymentTagFrom(clientSecret))}`, {
+				query: { client_secret: clientSecret },
+			}),
+
+		updateBySecret: (clientSecret: string, body: { return_url?: string }): Promise<PaymentResource> =>
+			this.request('PATCH', `/payments/${encodeURIComponent(paymentTagFrom(clientSecret))}`, {
+				query: { client_secret: clientSecret },
+				body,
+				maxRetries: 0,
+			}),
+	};
+}
+
+/** `pay_<tag>_secret_v<n>` — the tag is embedded, which is why the secret is the whole reference. */
+export function paymentTagFrom(clientSecret: string): string {
+	const marker = clientSecret.indexOf('_secret_');
+	return marker === -1 ? clientSecret : clientSecret.slice(0, marker);
+}
+
+function errorMessage(body: unknown, status: number): string {
+	const detail = (body as { error?: { message?: string }; message?: string } | undefined) ?? undefined;
+	return detail?.error?.message ?? detail?.message ?? `the request failed with status ${status}`;
+}
+
+function errorCode(body: unknown): string | undefined {
+	const detail = (body as { error?: { type?: string; code?: string } } | undefined) ?? undefined;
+	return detail?.error?.code ?? detail?.error?.type;
+}
+
+function backoff(attempt: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, 2 ** attempt * 250));
+}

package/src/api/types.ts

@@ -0,0 +1,166 @@
+/**
+ * The slice of Whop's REST `/api/v1` surface the payments elements actually read, typed by hand.
+ *
+ * Deliberately not `@whop/sdk`: that client is generated for the web and carries a transport this
+ * package does not want. The field names here are the wire names, so a payload built from these
+ * types is the payload the backend expects.
+ */
+
+export type Money = { amount: number; currency: string };
+
+/** The API's own `enabled` / `disabled` / `include_platform_defaults` filtering shape. */
+export interface PaymentMethodConfigurationShape {
+	enabled?: string[];
+	disabled?: string[];
+	include_platform_defaults?: boolean;
+}
+
+export interface PlanResource {
+	id: string;
+	object: 'plan';
+	currency: string;
+	/** MAJOR units, decimal. `chargeFromPlan` converts, truncating the way the backend does. */
+	initial_price?: number | null;
+	plan_type?: string | null;
+	account?: { id?: string } | null;
+	/**
+	 * The GOVERNING configuration, already resolved server-side through every layer. `null` means
+	 * platform defaults; there is deliberately no client-side fallback to the plan's own override.
+	 */
+	effective_payment_method_configuration?: PaymentMethodConfigurationShape | null;
+	trial_period_days?: number | null;
+}
+
+export interface CountryBound {
+	country: string;
+	min_amount: number | null;
+	max_amount: number | null;
+}
+
+export interface CurrencyBound {
+	min_amount: number | null;
+	max_amount: number | null;
+	countries: CountryBound[];
+}
+
+export interface RequiredField {
+	name: string;
+	kind: 'billing_details' | 'payment_method';
+	placeholder?: string;
+	secure?: boolean;
+	/** Country-keyed validation patterns, with `*` as the fallback. */
+	formats?: Record<string, string>;
+	input_formats?: Record<string, string>;
+}
+
+export interface MethodDetail {
+	/** `none` | `redirect` | `bank_wire` | `wallet_sheet` */
+	template: string;
+	icon?: string;
+	short_name?: string;
+}
+
+/**
+ * One colorway of one icon shape. The SVG is the API's preferred file, but React Native's `Image`
+ * renders no vectors and every SVG library that could is a native peer this package refuses to
+ * take on, so the raster set is what the elements draw.
+ */
+export interface PaymentMethodIconFiles {
+	svg?: string;
+	/** The shape's native size: 32px square, 48x30 card. */
+	png_1x?: string;
+	png_2x?: string;
+	png_4x?: string;
+}
+
+export interface PaymentMethodIconVariants {
+	light?: PaymentMethodIconFiles | null;
+	dark?: PaymentMethodIconFiles | null;
+}
+
+export interface PaymentMethodIcons {
+	/** The square tile (32x32). */
+	square?: PaymentMethodIconVariants | null;
+	/** The credit-card-proportioned tile (48x30). */
+	card?: PaymentMethodIconVariants | null;
+}
+
+export interface CardNetworkArt {
+	brand: string;
+	display_name?: string;
+	icons?: PaymentMethodIcons;
+}
+
+export interface PaymentMethodTypeResource {
+	object: 'payment_method_type';
+	type: string;
+	category: 'card' | 'wallet' | 'redirect' | 'bank_debit' | 'bank_transfer' | 'voucher' | 'crypto' | 'balance';
+	display_name: string;
+	icons?: PaymentMethodIcons;
+	detail: MethodDetail;
+	required_fields?: RequiredField[];
+	currencies?: Record<string, CurrencyBound>;
+	platform_default?: boolean;
+	usage?: { one_time?: boolean; off_session?: boolean; on_session?: boolean };
+	card?: { public_key?: string | null; networks?: CardNetworkArt[] } | null;
+	wallet?: {
+		public_key?: string | null;
+		gateway?: string;
+		gateway_merchant_id?: string;
+		environment?: string;
+		allowed_card_networks?: string[];
+		allowed_auth_methods?: string[];
+		merchants?: Array<{ merchant_identifier?: string; country?: string; domains?: string[] }>;
+	} | null;
+	config?: Record<string, unknown> | null;
+}
+
+export interface PageInfo {
+	end_cursor: string | null;
+	has_next_page: boolean;
+	has_previous_page: boolean;
+	start_cursor: string | null;
+}
+
+export interface ConfirmationTokenResource {
+	id: string;
+	object: 'confirmation_token';
+	payment_method?: { type: string; category: string } & Record<string, unknown>;
+}
+
+export interface PaymentResource {
+	id: string;
+	object: 'payment';
+	status: string;
+	client_secret?: string;
+	next_action?: {
+		type: string;
+		redirect?: { url: string; return_url?: string | null };
+		[key: string]: unknown;
+	} | null;
+	last_payment_error?: {
+		code?: string | null;
+		decline_code?: string | null;
+		message?: string | null;
+	} | null;
+}
+
+export interface BrowserInfo {
+	platform?: string;
+	color_depth?: number;
+	screen_height?: number;
+	screen_width?: number;
+	language?: string;
+	java_enabled?: boolean;
+	browser_time_difference?: number;
+	user_agent?: string;
+}
+
+export interface ConfirmationTokenCreateParams {
+	account_id: string;
+	payment_method: { type?: string; category: string } & Record<string, unknown>;
+	billing_details: Record<string, unknown>;
+	return_url?: string;
+	setup_future_usage?: 'off_session' | 'on_session';
+	browser_info?: BrowserInfo;
+}

package/src/controller/actions.ts

@@ -0,0 +1,197 @@
+import type { PaymentResource } from '../api/types';
+import { mergeBillingWithCollected } from '../core/payments/billing-merge';
+import { BrandingRequiredError } from '../core/payments/errors';
+import { PaymentsRefusalError } from '../core/payments/refusals';
+import { mintConfirmationToken, type MintBillingDetails, validateBillingEmail } from '../core/payments/mint';
+import { WhopAuthSession } from '../native';
+import type { PaymentsStore } from './store';
+
+export interface CreateConfirmationTokenInput {
+	billingDetails?: Partial<MintBillingDetails>;
+	/** Declared inputs a method requires on `billing_details`. */
+	billingExtra?: Record<string, string>;
+}
+
+export interface CreateConfirmationTokenResult {
+	confirmationToken: string;
+	type: string;
+}
+
+/**
+ * The one mint. Resolves the live collection surface, merges the billing block underneath any
+ * explicit input, and posts `POST /confirmation_tokens`.
+ */
+export async function createConfirmationToken(
+	store: PaymentsStore,
+	input: CreateConfirmationTokenInput = {},
+): Promise<CreateConfirmationTokenResult> {
+	const state = store.getSnapshot();
+
+	if (state.confirmInFlight) {
+		throw new PaymentsRefusalError(
+			'CONFIRMATION_IN_FLIGHT',
+			'A confirmation token is already being created for this handle.',
+		);
+	}
+	// Whop is the merchant of record on these sales, so the buyer has to be told so on the screen
+	// where they pay. The web element cannot demand this of already-shipped integrations; a first
+	// release can, and does.
+	if (!state.brandingMounted) {
+		throw new BrandingRequiredError(
+			'BRANDING_NOT_MOUNTED',
+			'Mount <BrandingElement /> alongside your payment surface — it carries the merchant-of-record notice.',
+		);
+	}
+	if (!state.charge.configured) {
+		throw new PaymentsRefusalError(
+			'CHARGE_CONFIG_MISSING',
+			'This handle has no charge config — pass a plan or currency and amount.',
+		);
+	}
+
+	const surface = store.liveSurface();
+	if (!surface) {
+		throw new PaymentsRefusalError(
+			'NO_COLLECTION_SURFACE',
+			'No collection surface is mounted — render <PaymentElement />, <CardElement />, or <CardFields>.',
+		);
+	}
+
+	store.patch({ confirmInFlight: true });
+	try {
+		const seeded = {
+			...input.billingDetails,
+			email: input.billingDetails?.email ?? state.buyerEmail,
+		};
+		const collected = await surface.collect({ billingDetails: seeded });
+
+		// Re-read AFTER collect: card and wallet collection take seconds, and a buyer editing their
+		// address or email meanwhile must have the live values minted, not the pre-collect snapshot.
+		const settled = store.getSnapshot();
+		const email = input.billingDetails?.email ?? settled.buyerEmail ?? seeded.email;
+
+		const billing = mergeBillingWithCollected(
+			{ ...collected.billingDetails, ...input.billingDetails, email: email || collected.billingDetails.email },
+			settled.addressLive ? settled.addressCollected : undefined,
+		);
+
+		return await mintConfirmationToken(
+			store.client,
+			{
+				accountId: settled.accountId,
+				returnUrl: settled.returnUrl,
+				setupFutureUsage: settled.charge.configured ? settled.charge.setupFutureUsage : undefined,
+			},
+			collected.paymentMethod,
+			validateBillingEmail(billing),
+			{ ...collected.billingExtra, ...input.billingExtra },
+		);
+	} finally {
+		store.patch({ confirmInFlight: false });
+	}
+}
+
+export interface HandleNextActionInput {
+	/** Identifies AND authorizes the payment — its tag is embedded in the secret. */
+	clientSecret: string;
+	returnUrl?: string;
+	/** @default 2500 */
+	pollIntervalMs?: number;
+	/** @default 300000 */
+	timeoutMs?: number;
+}
+
+export interface HandleNextActionResult {
+	status: string;
+	redirected: boolean;
+	lastPaymentError: PaymentResource['last_payment_error'];
+}
+
+const RESTING = new Set(['succeeded', 'failed', 'canceled', 'cancelled', 'requires_payment_method']);
+
+/**
+ * Completes a confirmed payment's pending step.
+ *
+ * The redirect leg opens the system browser and then **polls the payment to rest**. Polling is the
+ * authority rather than a callback because the API refuses anything but https or loopback for a
+ * return URL (`PaymentsApi::ValidateReturnUrl`), so a custom-scheme deep link back into the app is
+ * not available. Dismissing the browser therefore returns the payment's current status, which may
+ * still be pending — the same contract the web action documents.
+ */
+export async function handleNextAction(
+	store: PaymentsStore,
+	input: HandleNextActionInput,
+): Promise<HandleNextActionResult> {
+	// One at a time, like the mint. Two overlapping calls each open a system browser and each run
+	// their own poll, and whichever finishes first calls dismiss() — closing the OTHER buyer-facing
+	// challenge mid-flow and orphaning its presentation. A double-tapped submit is enough to do it.
+	if (store.getSnapshot().nextActionInFlight) {
+		throw new PaymentsRefusalError(
+			'NEXT_ACTION_IN_FLIGHT',
+			'A payment step is already being handled for this handle.',
+		);
+	}
+	store.patch({ nextActionInFlight: true });
+
+	try {
+		return await runNextAction(store, input);
+	} finally {
+		store.patch({ nextActionInFlight: false });
+	}
+}
+
+async function runNextAction(
+	store: PaymentsStore,
+	input: HandleNextActionInput,
+): Promise<HandleNextActionResult> {
+	const pollIntervalMs = input.pollIntervalMs ?? 2500;
+	const timeoutMs = input.timeoutMs ?? 300_000;
+
+	if (input.returnUrl) {
+		// A failed update rejects BEFORE any step runs, so the buyer is never sent somewhere the
+		// payment does not know about.
+		await store.client.payments.updateBySecret(input.clientSecret, { return_url: input.returnUrl });
+	}
+
+	let payment = await store.client.payments.retrieveBySecret(input.clientSecret);
+	const url = payment.next_action?.redirect?.url;
+
+	if (!payment.next_action || !url) {
+		return { status: payment.status, redirected: false, lastPaymentError: payment.last_payment_error ?? null };
+	}
+
+	// A mutable box rather than a bare `let`: the assignment happens inside a callback, which control
+	// flow analysis does not see, so a plain binding narrows to `null` at every read below.
+	const presented: { error: Error | null } = { error: null };
+	const presentation = WhopAuthSession.present(url).catch((error: unknown) => {
+		presented.error = error instanceof Error ? error : new Error(String(error));
+	});
+	const deadline = Date.now() + timeoutMs;
+
+	try {
+		while (Date.now() < deadline) {
+			await delay(pollIntervalMs);
+			// The buyer cannot be completing a step that never opened. Without this the poll runs the
+			// full timeout and then reports a redirect that never happened.
+			if (presented.error) break;
+			payment = await store.client.payments.retrieveBySecret(input.clientSecret).catch(() => payment);
+			if (RESTING.has(payment.status) || !payment.next_action) break;
+		}
+	} finally {
+		WhopAuthSession.dismiss();
+		await presentation;
+	}
+
+	if (presented.error) {
+		throw new PaymentsRefusalError(
+			'NEXT_ACTION_PRESENTATION_FAILED',
+			`The payment step could not be opened: ${presented.error.message}`,
+		);
+	}
+
+	return { status: payment.status, redirected: true, lastPaymentError: payment.last_payment_error ?? null };
+}
+
+function delay(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}