@stripe/stripe-react-native 0.68.0 → 0.70.0

package/src/functions.ts

@@ -14,6 +14,7 @@ import type {
   HandleNextActionResult,
   HandleNextActionForSetupResult,
   InitPaymentSheetResult,
+  LinkController,
   PaymentMethod,
   PaymentSheet,
   PresentPaymentSheetResult,
@@ -959,3 +960,50 @@ export const setFinancialConnectionsForceNativeFlow = async (
     // no-op
   }
 };
+
+/**
+ * Initializes the LinkController with the provided configuration.
+ * Must be called before `presentLinkController`.
+ *
+ * @PrivatePreview This API is in private preview and may change without notice.
+ * It will have no effect unless your Stripe account is enrolled in the private preview.
+ */
+export const initLinkController = async (
+  params: LinkController.Configuration
+): Promise<LinkController.InitResult> => {
+  try {
+    const { error } = await NativeStripeSdk.initLinkController(params);
+    if (error) {
+      return { error };
+    }
+    return {};
+  } catch (error: any) {
+    return { error };
+  }
+};
+
+/**
+ * Presents the Link flow. Must be called after `initLinkController`.
+ *
+ * Handles the full end-to-end flow: consumer lookup, authentication or signup,
+ * wallet display, and payment method creation.
+ *
+ * @PrivatePreview This API is in private preview and may change without notice.
+ * It will have no effect unless your Stripe account is enrolled in the private preview.
+ */
+export const presentLinkController =
+  async (): Promise<LinkController.PresentResult> => {
+    try {
+      const { paymentMethod, paymentMethodPreview, error } =
+        await NativeStripeSdk.presentLinkController();
+      if (error) {
+        return { error };
+      }
+      return {
+        paymentMethod: paymentMethod!,
+        paymentMethodPreview,
+      };
+    } catch (error: any) {
+      return { error };
+    }
+  };

package/src/hooks/useCheckout.tsx

@@ -114,18 +114,6 @@ export function useCheckout(
       ),
     [withLoading]
   );
-  const updateBillingAddress = useCallback<Checkout['updateBillingAddress']>(
-    (address, name, phone) =>
-      withLoading((key) =>
-        NativeStripeSdk.checkoutUpdateBillingAddress(
-          key,
-          address,
-          name ?? null,
-          phone ?? null
-        )
-      ),
-    [withLoading]
-  );
   const applyPromotionCode = useCallback<Checkout['applyPromotionCode']>(
     (code) =>
       withLoading((key) =>
@@ -192,7 +180,6 @@ export function useCheckout(
         return sessionKeyRef.current;
       },
       updateShippingAddress,
-      updateBillingAddress,
       applyPromotionCode,
       removePromotionCode,
       updateLineItemQuantity,
@@ -201,7 +188,6 @@ export function useCheckout(
     }),
     [
       updateShippingAddress,
-      updateBillingAddress,
       applyPromotionCode,
       removePromotionCode,
       updateLineItemQuantity,

package/src/hooks/useLinkController.tsx

@@ -0,0 +1,54 @@
+import { useState, useCallback } from 'react';
+import { initLinkController, presentLinkController } from '../functions';
+import type { LinkController } from '../types';
+
+/**
+ * `useLinkController` hook.
+ *
+ * Provides `initLinkController` and `presentLinkController` methods with a shared
+ * `loading` state. Call `initLinkController` once when your checkout screen loads,
+ * then `presentLinkController` when the customer taps your Link button.
+ *
+ * @PrivatePreview This API is in private preview and may change without notice.
+ */
+export function useLinkController() {
+  const [loading, setLoading] = useState(false);
+
+  const init = useCallback(
+    async (
+      params: LinkController.Configuration
+    ): Promise<LinkController.InitResult> => {
+      setLoading(true);
+      const result = await initLinkController(params);
+      setLoading(false);
+      return result;
+    },
+    []
+  );
+
+  const present =
+    useCallback(async (): Promise<LinkController.PresentResult> => {
+      setLoading(true);
+      const result = await presentLinkController();
+      setLoading(false);
+      return result;
+    }, []);
+
+  return {
+    /** Whether an operation is currently in progress. */
+    loading,
+    /**
+     * Initializes the LinkController with the provided configuration.
+     * Must be called before `presentLinkController`.
+     *
+     * @PrivatePreview
+     */
+    initLinkController: init,
+    /**
+     * Presents the Link flow. Must be called after `initLinkController`.
+     *
+     * @PrivatePreview
+     */
+    presentLinkController: present,
+  };
+}

package/src/hooks/useOnramp.tsx

@@ -5,8 +5,6 @@ import type { Address } from '../types';
 import { useCallback } from 'react';
 import { addOnrampListener } from '../events';
 import { CryptoPaymentToken } from '../types/Onramp';
-import { getCurrentPublishableKey } from '../internal/stripeConfig';
-import pjson from '../../package.json';
 
 export function requireOnrampModule() {
   if (NativeOnrampSdk == null) {
@@ -26,83 +24,6 @@ export function requireOnrampModule() {
 let onCheckoutClientSecretRequestedSubscription: EventSubscription | null =
   null;
 
-const legacyAppAttestationUnavailableMessages = [
-  'App attestation is missing or device cannot use native Link.',
-  'Native Link is not available',
-];
-const cryptoOnrampAppAttestationUnavailableCode = 'app_attestation_unavailable';
-
-function isLegacyAppAttestationUnavailableMessage(message?: string): boolean {
-  return (
-    message != null && legacyAppAttestationUnavailableMessages.includes(message)
-  );
-}
-
-function publishableKeyMode(): 'live' | 'test' | undefined {
-  const publishableKey = getCurrentPublishableKey();
-  if (publishableKey?.startsWith('pk_live_')) {
-    return 'live';
-  }
-  if (publishableKey?.startsWith('pk_test_')) {
-    return 'test';
-  }
-  return undefined;
-}
-
-// Temporary React Native shim: iOS/Android currently surface this configure/create
-// failure as a legacy SDK-level message instead of a typed rich error. This can be
-// removed once the native SDKs map it themselves, though keeping it is harmless as
-// a compatibility fallback for older native SDK versions.
-function mapLegacyConfigureAppAttestationError(result: {
-  error?: Onramp.CryptoOnrampError;
-}): { error?: Onramp.CryptoOnrampError } {
-  const error = result.error;
-  if (
-    error == null ||
-    error.onrampErrorType != null ||
-    (!isLegacyAppAttestationUnavailableMessage(error.message) &&
-      !isLegacyAppAttestationUnavailableMessage(error.localizedMessage))
-  ) {
-    return result;
-  }
-
-  const userMessage =
-    "This app couldn't be verified. Contact the app developer for help.";
-  const mode = publishableKeyMode();
-
-  const context = [
-    'Context:',
-    '  operation: configure',
-    mode != null ? `  mode: ${mode}` : undefined,
-  ].filter((line): line is string => line != null);
-  const appAttestationError = {
-    ...error,
-    message: userMessage,
-    localizedMessage: userMessage,
-    stripeErrorCode: cryptoOnrampAppAttestationUnavailableCode,
-    developerMessage: [
-      "App attestation unavailable: this app isn't configured to use Stripe Crypto Onramp.",
-      '',
-      "This usually means app attestation isn't enabled for this Stripe account, or this app isn't registered as a trusted application. Use your iOS bundle ID or Android package name and contact Stripe to enable app attestation or register the app for this account.",
-      '',
-      ...context,
-      '',
-      `Code: ${cryptoOnrampAppAttestationUnavailableCode}`,
-      '',
-      'Next step: confirm app attestation is enabled for this Stripe account and that the app identifier is registered as trusted, then call configure again.',
-      `SDK: stripe-react-native@${pjson.version}`,
-    ].join('\n'),
-    userMessage,
-    operation: 'configure',
-    mode,
-  } as unknown as Onramp.CryptoOnrampError;
-
-  return {
-    ...result,
-    error: appAttestationError,
-  };
-}
-
 /**
  * useOnramp hook
  */
@@ -111,9 +32,7 @@ export function useOnramp() {
     async (
       config: Onramp.Configuration
     ): Promise<{ error?: Onramp.CryptoOnrampError }> => {
-      return mapLegacyConfigureAppAttestationError(
-        await requireOnrampModule().configureOnramp(config)
-      );
+      return requireOnrampModule().configureOnramp(config);
     },
     []
   );
@@ -147,6 +66,32 @@ export function useOnramp() {
     []
   );
 
+  const _getWalletOwnershipChallenge = useCallback(
+    async (
+      walletAddress: string,
+      network: Onramp.CryptoNetwork
+    ): Promise<Onramp.GetWalletOwnershipChallengeResult> => {
+      return requireOnrampModule().getWalletOwnershipChallenge(
+        walletAddress,
+        network
+      );
+    },
+    []
+  );
+
+  const _submitWalletOwnershipSignature = useCallback(
+    async (
+      challengeId: string,
+      signature: string
+    ): Promise<Onramp.SubmitWalletOwnershipSignatureResult> => {
+      return requireOnrampModule().submitWalletOwnershipSignature(
+        challengeId,
+        signature
+      );
+    },
+    []
+  );
+
   const _attachKycInfo = useCallback(
     async (
       kycInfo: Onramp.KycInfo
@@ -292,7 +237,9 @@ export function useOnramp() {
   const _isAuthError = (error?: Onramp.CryptoOnrampError): boolean => {
     const stripeErrorCode =
       error?.stripeErrorCode ??
-      (error?.onrampErrorType ? error.apiErrorCode : undefined);
+      (error != null && 'apiErrorCode' in error
+        ? error.apiErrorCode
+        : undefined);
     if (stripeErrorCode == null) {
       return false;
     }
@@ -338,6 +285,26 @@ export function useOnramp() {
      */
     registerWalletAddress: _registerWalletAddress,
 
+    /**
+     * Creates a short-lived challenge for proving ownership of a registered wallet.
+     * Requires an authenticated Link user.
+     *
+     * @param walletAddress The registered crypto wallet address to verify
+     * @param network The crypto network for the wallet address
+     * @returns Promise that resolves to the challenge whose message must be signed, or an error
+     */
+    getWalletOwnershipChallenge: _getWalletOwnershipChallenge,
+
+    /**
+     * Verifies a signature over a previously issued wallet ownership challenge.
+     * Requires an authenticated Link user.
+     *
+     * @param challengeId The opaque identifier returned by `getWalletOwnershipChallenge`
+     * @param signature The signature produced over the exact challenge message
+     * @returns Promise that resolves to the verified consumer wallet, or an error
+     */
+    submitWalletOwnershipSignature: _submitWalletOwnershipSignature,
+
     /**
      * Attaches the specific KYC info to the current Link user. Requires an authenticated Link user.
      *

package/src/index.tsx

@@ -6,6 +6,7 @@ export { usePlatformPay } from './hooks/usePlatformPay';
 export { usePaymentSheet } from './hooks/usePaymentSheet';
 export { useFinancialConnectionsSheet } from './hooks/useFinancialConnectionsSheet';
 export { useOnramp } from './hooks/useOnramp';
+export { useLinkController } from './hooks/useLinkController';
 
 //components
 export { initStripe, StripeProvider } from './components/StripeProvider';

package/src/specs/NativeOnrampSdkModule.ts

@@ -16,6 +16,14 @@ export interface Spec extends TurboModule {
     walletAddress: string,
     network: string
   ): Promise<Onramp.VoidResult>;
+  getWalletOwnershipChallenge(
+    walletAddress: string,
+    network: string
+  ): Promise<Onramp.GetWalletOwnershipChallengeResult>;
+  submitWalletOwnershipSignature(
+    challengeId: string,
+    signature: string
+  ): Promise<Onramp.SubmitWalletOwnershipSignatureResult>;
   attachKycInfo(
     kycInfo: UnsafeObject<Onramp.KycInfo>
   ): Promise<Onramp.VoidResult>;

package/src/specs/NativeStripeSdkModule.ts

@@ -22,6 +22,7 @@ import type {
   InitialiseParams,
   InitPaymentSheetResult,
   IsCardInWalletResult,
+  LinkController,
   OpenApplePaySetupResult,
   PaymentIntent,
   PaymentMethod,
@@ -226,13 +227,6 @@ export interface Spec extends TurboModule {
     phone: string | null
   ): Promise<UnsafeObject<Checkout.State>>;
 
-  checkoutUpdateBillingAddress(
-    sessionKey: string,
-    address: UnsafeObject<Checkout.Address>,
-    name: string | null,
-    phone: string | null
-  ): Promise<UnsafeObject<Checkout.State>>;
-
   checkoutApplyPromotionCode(
     sessionKey: string,
     code: string
@@ -278,6 +272,16 @@ export interface Spec extends TurboModule {
   storeStripeConnectDeepLink(url: string): Promise<void>;
   pollAndClearPendingStripeConnectUrls(): Promise<string[]>;
 
+  // LinkController - Private Preview
+
+  /** @PrivatePreview */
+  initLinkController(
+    params: UnsafeObject<LinkController.Configuration>
+  ): Promise<UnsafeObject<LinkController.InitResult>>;
+
+  /** @PrivatePreview */
+  presentLinkController(): Promise<UnsafeObject<LinkController.PresentResult>>;
+
   // Events
   addListener: (eventType: string) => void;
   removeListeners: (count: number) => void;

package/src/types/Checkout.ts

@@ -103,7 +103,7 @@ export namespace Checkout {
     tax: Tax;
     /** Tax and discount details for the computed total amount. */
     total?: Total;
-    /** The billing address set via `updateBillingAddress`, if any. */
+    /** The billing address for this session, if any. */
     billingAddress?: ContactAddress;
   }
 
@@ -507,24 +507,6 @@ export interface Checkout {
     phone?: string
   ): Promise<void>;
 
-  /**
-   * Sets the billing address for this checkout.
-   *
-   * The address is stored locally and merged into PaymentSheet configuration
-   * when presenting payment UI. If automatic tax is enabled and the tax
-   * address source is "billing", the address is also sent to the server to
-   * compute updated tax amounts.
-   *
-   * @param address - The billing address to set.
-   * @param name - The customer's name.
-   * @param phone - The customer's phone number.
-   */
-  updateBillingAddress(
-    address: Checkout.Address,
-    name?: string,
-    phone?: string
-  ): Promise<void>;
-
   /**
    * Applies a promotion code to the session.
    * - Parameter code: The promotion code to apply (e.g. `"SUMMER2026"`).

package/src/types/Errors.ts

@@ -106,3 +106,12 @@ export enum RadarError {
   Failed = 'Failed',
   Unknown = 'Unknown',
 }
+
+/**
+ * @PrivatePreview
+ */
+export enum LinkControllerError {
+  Failed = 'Failed',
+  Canceled = 'Canceled',
+  Unknown = 'Unknown',
+}

package/src/types/LinkController.ts

@@ -0,0 +1,75 @@
+import type { Result as PaymentMethodResult } from './PaymentMethod';
+import type { LinkControllerError, StripeError } from './Errors';
+
+/**
+ * @PrivatePreview Payment method types supported by the Link flow.
+ */
+export enum LinkPaymentMethodType {
+  Card = 'card',
+  BankAccount = 'bankAccount',
+}
+
+/**
+ * @PrivatePreview Configuration for initializing the Link controller.
+ */
+export type Configuration = {
+  /** The customer's email address used for Link consumer lookup. */
+  email?: string;
+  /** Your customer-facing business name, displayed in Link UI. */
+  merchantDisplayName: string;
+  /** Payment method types to support in the Link sheet. If omitted, all available types are shown. */
+  supportedPaymentMethodTypes?: LinkPaymentMethodType[];
+  /** Customer phone number in E.164 format to prefill during signup. */
+  phoneNumber?: string;
+  /** Whether to allow the user to log out. Defaults to true. */
+  allowLogout?: boolean;
+  /**
+   * Optional SetupIntent client secret. When provided, the SDK confirms the SetupIntent
+   * with the selected payment method automatically before returning.
+   */
+  setupIntentClientSecret?: string;
+};
+
+/**
+ * @PrivatePreview A preview of the payment method the user selected in Link.
+ * Intended for display in the host app's checkout UI after the flow completes.
+ */
+export type PaymentMethodPreview = {
+  /**
+   * Payment method icon as a data URI PNG string (e.g., "data:image/png;base64,...").
+   * Suitable for rendering directly in a React Native `<Image source={{ uri: icon }}>` component.
+   */
+  icon: string;
+  /** The Link label to render in your screen. */
+  label: string;
+  /** Details about the selected Link payment method. This will typically render the display name of the payment method followed by the last four digits, e.g. `Visa Credit •••• 4242`. */
+  sublabel?: string;
+};
+
+/**
+ * @PrivatePreview Result returned from `initLinkController`.
+ */
+export type InitResult =
+  | { error?: undefined }
+  | { error: StripeError<LinkControllerError> };
+
+/**
+ * @PrivatePreview Result returned from `presentLinkController`.
+ */
+export type PresentResult =
+  | {
+      /** The payment method created from the user's Link selection. */
+      paymentMethod: PaymentMethodResult;
+      /** A preview of the selected payment method for display purposes. */
+      paymentMethodPreview?: PaymentMethodPreview;
+      error?: undefined;
+    }
+  | {
+      paymentMethod?: undefined;
+      paymentMethodPreview?: undefined;
+      /**
+       * Set when the operation failed or was canceled.
+       * Cancellation has `error.code === LinkControllerError.Canceled`.
+       */
+      error: StripeError<LinkControllerError>;
+    };

package/src/types/Onramp.ts

@@ -6,9 +6,9 @@ import type {
 } from './PlatformPay';
 
 /**
- * Generic error codes returned by Crypto Onramp APIs.
+ * Generic error statuses returned by Crypto Onramp APIs.
  */
-export enum OnrampError {
+export enum OnrampErrorStatus {
   Failed = 'Failed',
   Canceled = 'Canceled',
   Unknown = 'Unknown',
@@ -175,8 +175,39 @@ export enum CryptoNetwork {
   worldchain = 'worldchain',
   xrpl = 'xrpl',
   sui = 'sui',
+  arbitrum = 'arbitrum',
 }
 
+/**
+ * A short-lived server-issued challenge used to prove ownership of a registered wallet.
+ */
+export type WalletOwnershipChallenge = {
+  /** Opaque identifier for this challenge. */
+  challengeId: string;
+  /** The wallet address bound to this challenge. */
+  walletAddress: string;
+  /** The crypto network bound to this challenge. */
+  network: CryptoNetwork;
+  /** The exact opaque message the wallet must sign. */
+  message: string;
+  /** ISO 8601 timestamp indicating when this challenge expires. */
+  expiresAt: string;
+};
+
+/**
+ * A registered crypto consumer wallet.
+ */
+export type CryptoConsumerWallet = {
+  /** The consumer wallet's unique identifier. */
+  id: string;
+  /** The registered wallet address. */
+  walletAddress: string;
+  /** The crypto network for the registered wallet. */
+  network: CryptoNetwork;
+  /** Whether ownership of this wallet has been verified. */
+  verifiedOwnership: boolean;
+};
+
 /**
  * Represents a calendar date using day, month, and year components.
  * Example: March 31st, 1975 -> { day: 31, month: 3, year: 1975 }
@@ -269,36 +300,42 @@ export type ComplianceIdentifierRequirements = {
 };
 
 /**
- * Typed Crypto Onramp error discriminants returned by newer native SDKs.
+ * Typed Crypto Onramp API error discriminants.
  */
-export type OnrampErrorType = 'AppAttestationError' | 'UncategorizedApiError';
+export type OnrampApiErrorType =
+  | 'AppAttestationError'
+  | 'UncategorizedApiError';
 
 /**
- * A native SDK component and version included in Crypto Onramp diagnostics.
+ * Typed Crypto Onramp error discriminants returned by newer native SDKs.
  */
-export type SDKVersion = {
-  /** The SDK component name. */
-  name: string;
-  /** The SDK component version. */
-  version: string;
-};
+export type OnrampErrorType =
+  | OnrampApiErrorType
+  | 'AppAttestationUnavailableError';
 
-export type OnrampApiError = StripeError<OnrampError> & {
-  onrampErrorType: string;
+/**
+ * Base rich error shape returned by native Crypto Onramp SDK errors.
+ */
+export type OnrampSdkError = StripeError<OnrampErrorStatus> & {
+  onrampErrorType: OnrampErrorType;
   developerMessage: string;
   userMessage: string;
+  docUrl?: string;
+};
+
+/**
+ * API-context fields returned for Crypto Onramp API errors.
+ */
+export type OnrampApiError = OnrampSdkError & {
+  onrampErrorType: OnrampApiErrorType;
   reason?: string;
-  operation: string;
-  appPackageName: string;
-  mode?: 'live' | 'test';
-  sdkVersions?: SDKVersion[];
   requestId?: string;
   apiErrorCode?: string;
   apiErrorType?: string;
   apiErrorMessage?: string;
   apiUserMessage?: string;
-  docUrl?: string;
 };
+
 /**
  * A typed Crypto Onramp app attestation failure.
  */
@@ -313,6 +350,13 @@ export type UncategorizedApiError = OnrampApiError & {
   onrampErrorType: 'UncategorizedApiError';
 };
 
+/**
+ * A typed Crypto Onramp local SDK error for app attestation setup failures.
+ */
+export type AppAttestationUnavailableError = OnrampSdkError & {
+  onrampErrorType: 'AppAttestationUnavailableError';
+};
+
 /**
  * Error returned by Crypto Onramp APIs.
  *
@@ -321,11 +365,14 @@ export type UncategorizedApiError = OnrampApiError & {
  * `onrampErrorType`.
  */
 export type CryptoOnrampError =
-  | (StripeError<OnrampError> & {
-      onrampErrorType?: undefined;
+  | (StripeError<OnrampErrorStatus> & {
+      onrampErrorType?: never;
+      developerMessage?: never;
+      userMessage?: never;
     })
   | AppAttestationError
-  | UncategorizedApiError;
+  | UncategorizedApiError
+  | AppAttestationUnavailableError;
 
 /**
  * Result of retrieving missing compliance identifiers.
@@ -470,6 +517,36 @@ export type RegisterLinkUserResult =
       error: CryptoOnrampError;
     };
 
+/**
+ * Result of creating a wallet ownership challenge.
+ */
+export type GetWalletOwnershipChallengeResult =
+  | {
+      /** The short-lived challenge whose message must be signed by the wallet. */
+      challenge: WalletOwnershipChallenge;
+      error?: undefined;
+    }
+  | {
+      challenge?: undefined;
+      /** Present if challenge creation failed with an error. */
+      error: CryptoOnrampError;
+    };
+
+/**
+ * Result of submitting a wallet ownership signature.
+ */
+export type SubmitWalletOwnershipSignatureResult =
+  | {
+      /** The registered wallet after ownership verification. */
+      consumerWallet: CryptoConsumerWallet;
+      error?: undefined;
+    }
+  | {
+      consumerWallet?: undefined;
+      /** Present if signature verification failed with an error. */
+      error: CryptoOnrampError;
+    };
+
 /**
  * Describes the payment method currently selected by the user.
  */