@stripe/stripe-react-native 0.63.0 → 0.64.1

package/src/types/Checkout.ts

@@ -0,0 +1,377 @@
+/**
+ * All types for the Checkout Session API.
+ * @internal
+ */
+export namespace Checkout {
+  /**
+   * Configuration options for a `useCheckout` instance.
+   * @internal
+   */
+  export interface Configuration {
+    /**
+     * Controls whether adaptive pricing is requested for this session.
+     *
+     * When allowed, Stripe may present prices in the customer's local
+     * currency alongside the merchant's settlement currency.
+     *
+     * Default: `{ allowed: false }`.
+     */
+    adaptivePricing?: AdaptivePricing;
+  }
+
+  /**
+   * Options for adaptive pricing behavior.
+   * @internal
+   */
+  export interface AdaptivePricing {
+    /**
+     * Whether the integration allows adaptive pricing for this session.
+     *
+     * Set to `false` to prevent Stripe from activating adaptive pricing even
+     * if the Checkout Session is configured for it on the server.
+     *
+     * Default: `false`.
+     */
+    allowed: boolean;
+  }
+
+  /**
+   * The loading state of the checkout session.
+   *
+   * Returned as `state` from `useCheckout`. React re-renders automatically
+   * whenever the session changes.
+   *
+   * - `loading` – a mutation or refresh is in flight; `session` is the most
+   *   recently loaded value and may be stale.
+   * - `loaded`  – session is current and ready.
+   *
+   * Before the initial session load completes, `state` is `null`.
+   * @internal
+   */
+  export type State =
+    | {
+        /**
+         * `loading` while a mutation or refresh is in flight.
+         *
+         * The associated `session` value is the most recently loaded copy and
+         * may be stale.
+         */
+        status: 'loading';
+        /** The most recently loaded session value. */
+        session: Session;
+      }
+    | {
+        /** `loaded` when the session is current and ready to use. */
+        status: 'loaded';
+        /** The latest checkout session value from Stripe. */
+        session: Session;
+      };
+
+  /**
+   * The status of a checkout session.
+   *
+   * - `unknown` - A status not recognized by this version of the SDK.
+   * - `open` - The checkout session is still in progress.
+   * - `complete` - The checkout session is complete.
+   * - `expired` - The checkout session has expired.
+   * @internal
+   */
+  export type Status = 'unknown' | 'open' | 'complete' | 'expired';
+
+  /**
+   * The payment status of a checkout session.
+   *
+   * - `unknown` - A payment status not recognized by this version of the SDK.
+   * - `paid` - The payment funds are available in your account.
+   * - `unpaid` - The payment funds are not yet available in your account.
+   * - `noPaymentRequired` - No payment is currently required for the session.
+   * @internal
+   */
+  export type PaymentStatus =
+    | 'unknown'
+    | 'paid'
+    | 'unpaid'
+    | 'noPaymentRequired';
+
+  /**
+   * A read-only snapshot of a Stripe Checkout Session.
+   * @internal
+   */
+  export interface Session {
+    /** Unique identifier for this checkout session. */
+    id: string;
+    /** The current session state, if available. */
+    status?: Status;
+    /** The payment status for this checkout session. */
+    paymentStatus: PaymentStatus;
+    /** Three-letter ISO 4217 currency code in lowercase (e.g. `"usd"`). */
+    currency?: string;
+    /** Indicates whether this session was created in live mode. */
+    livemode: boolean;
+    /** A summary of monetary totals for this session, if available. */
+    totals?: Totals;
+    /** The line items purchased by the customer. */
+    lineItems: LineItem[];
+    /** The shipping rate options available for this session. */
+    shippingOptions: ShippingOption[];
+    /** The discounts applied to this session. */
+    discounts: Discount[];
+    /** The Stripe customer ID attached to this session, if any. */
+    customerId?: string;
+    /** The customer's email address, if available. */
+    customerEmail?: string;
+    /** The billing address set via `updateBillingAddress`, if any. */
+    billingAddress?: AddressUpdate;
+    /** The shipping address set via `updateShippingAddress`, if any. */
+    shippingAddress?: AddressUpdate;
+  }
+
+  /**
+   * Monetary totals for a checkout session.
+   *
+   * All amounts are in the smallest currency unit (e.g. cents for USD).
+   * @internal
+   */
+  export interface Totals {
+    /** The subtotal amount before discounts, shipping, and tax. */
+    subtotal: number;
+    /** The final total after discounts, shipping, and tax. */
+    total: number;
+    /** The amount currently due from the customer. */
+    due: number;
+    /** The total discount amount applied to the session. */
+    discount: number;
+    /** The total shipping amount. */
+    shipping: number;
+    /** The total tax amount applied to the session. */
+    tax: number;
+  }
+
+  /**
+   * A line item in a checkout session.
+   * @internal
+   */
+  export interface LineItem {
+    /** Unique identifier for this line item. */
+    id: string;
+    /** The display name shown for this line item. */
+    name: string;
+    /** The quantity for this line item. */
+    quantity: number;
+    /** The per-unit price in the smallest currency unit. */
+    unitAmount: number;
+    /** Three-letter ISO 4217 currency code in lowercase. */
+    currency: string;
+  }
+
+  /**
+   * A shipping option available in a checkout session.
+   * @internal
+   */
+  export interface ShippingOption {
+    /** The shipping rate identifier. */
+    id: string;
+    /** The display name shown to the customer. */
+    displayName: string;
+    /** The shipping amount in the smallest currency unit. */
+    amount: number;
+    /** Three-letter ISO 4217 currency code in lowercase. */
+    currency: string;
+    /** The estimated delivery window shown to the customer, if available. */
+    deliveryEstimate?: string;
+  }
+
+  /**
+   * A discount applied to a checkout session.
+   * @internal
+   */
+  export interface Discount {
+    /** The coupon associated with this discount. */
+    coupon: Coupon;
+    /** The promotion code used to apply this discount, if any. */
+    promotionCode?: string;
+    /** The discount amount in the smallest currency unit. */
+    amount: number;
+  }
+
+  /**
+   * A coupon associated with a checkout discount.
+   * @internal
+   */
+  export interface Coupon {
+    /** The coupon identifier. */
+    id: string;
+    /** The display name of the coupon, if one exists. */
+    name?: string;
+    /** The percentage off, if this is a percentage-based coupon. */
+    percentOff?: number;
+    /** The fixed amount off, in the smallest currency unit, if applicable. */
+    amountOff?: number;
+  }
+
+  /**
+   * A locally stored address override for checkout.
+   *
+   * Address updates are merged into PaymentSheet configuration and may also be
+   * sent to Stripe when tax calculation depends on the billing or shipping
+   * address.
+   * @internal
+   */
+  export interface AddressUpdate {
+    /** The customer's or recipient's name, if provided. */
+    name?: string;
+    /** The customer's or recipient's phone number, if provided. */
+    phone?: string;
+    /** The postal address to use for the update. */
+    address: Address;
+  }
+
+  /**
+   * A postal address used for billing, shipping, or tax updates.
+   * @internal
+   */
+  export interface Address {
+    /** The country for this address, such as `"US"`. */
+    country: string;
+    /** The first address line. */
+    line1?: string;
+    /** The second address line. */
+    line2?: string;
+    /** The city, district, suburb, town, or village. */
+    city?: string;
+    /** The state, county, province, or region. */
+    state?: string;
+    /** The postal or ZIP code. */
+    postalCode?: string;
+  }
+
+  /**
+   * A Checkout-specific error returned from `useCheckout` or a Checkout
+   * mutation method.
+   * @internal
+   */
+  export interface Error {
+    /** A machine-readable error code describing the failure. */
+    code: ErrorCode;
+    /** A human-readable message describing the failure. */
+    message: string;
+  }
+
+  /**
+   * The set of Checkout-specific error codes.
+   *
+   * - `Failed` - The operation could not be completed.
+   * - `InvalidClientSecret` - The provided Checkout Session client secret is
+   *   invalid.
+   * - `SessionNotOpen` - The Checkout Session is no longer open for updates.
+   * - `SheetCurrentlyPresented` - The operation is unavailable while
+   *   PaymentSheet is being presented.
+   * - `Canceled` - The operation was canceled before completion.
+   * @internal
+   */
+  export type ErrorCode =
+    | 'Failed'
+    | 'InvalidClientSecret'
+    | 'SessionNotOpen'
+    | 'SheetCurrentlyPresented'
+    | 'Canceled';
+}
+
+/**
+ * A handle to a live Checkout Session.
+ *
+ * Returned by `useCheckout`. Call mutation methods to update the session;
+ * the hook's `state` updates automatically after each mutation.
+ * @internal
+ */
+export interface Checkout {
+  /** @internal Opaque key for the native Checkout instance. Used by `initPaymentSheet`. */
+  readonly sessionKey: string;
+
+  /**
+   * Sets the shipping 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 "shipping", the address is also sent to the server to
+   * compute updated tax amounts.
+   *
+   * @param address - The shipping address to set.
+   * @param name - The recipient's name.
+   * @param phone - The recipient's phone number.
+   */
+  updateShippingAddress(
+    address: Checkout.Address,
+    name?: string,
+    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"`).
+   * - Throws: `CheckoutError` if applying the promotion code fails.
+   * @internal
+   */
+  applyPromotionCode(code: string): Promise<void>;
+
+  /**
+   * Removes the currently applied promotion code.
+   * - Throws: `CheckoutError` if removing the promotion code fails.
+   * @internal
+   */
+  removePromotionCode(): Promise<void>;
+
+  /**
+   * Updates the quantity of a line item.
+   * @param lineItemId - The ID of the line item to update.
+   * @param quantity - The new quantity to set.
+   * - Throws: `CheckoutError` if updating the line item quantity fails.
+   * @internal
+   */
+  updateLineItemQuantity(lineItemId: string, quantity: number): Promise<void>;
+
+  /**
+   * Selects a shipping option for the session.
+   * @param id - The ID of the shipping rate to select.
+   * - Throws: `CheckoutError` if selecting the shipping option fails.
+   * @internal
+   */
+  selectShippingOption(id: string): Promise<void>;
+
+  /**
+   * Sets the customer's tax ID on the session.
+   * @param type - The tax ID type (e.g. `"eu_vat"`).
+   * @param value - The tax ID value (e.g. `"DE123456789"`).
+   * - Throws: `CheckoutError` if updating the tax ID fails.
+   * @internal
+   */
+  updateTaxId(type: string, value: string): Promise<void>;
+
+  /**
+   * Refreshes the session by fetching the latest copy from Stripe.
+   *
+   * Call this after making server-side changes to the Checkout Session
+   * so the local state stays in sync.
+   * - Throws: `CheckoutError` if refreshing the session fails.
+   * @internal
+   */
+  refresh(): Promise<void>;
+}

package/src/types/EmbeddedPaymentElement.tsx

@@ -13,6 +13,7 @@ import type {
   CardBrand,
 } from './Common';
 import type { PaymentMethod } from '.';
+import type { Checkout } from './Checkout';
 import type * as ConfirmationToken from './ConfirmationToken';
 import * as PaymentSheetTypes from './PaymentSheet';
 import NativeStripeSdkModule from '../specs/NativeStripeSdkModule';
@@ -222,21 +223,38 @@ export interface EmbeddedPaymentElementConfiguration {
   opensCardScannerAutomatically?: boolean;
 }
 
+// Narrows a value to `Checkout` vs. `IntentConfiguration`.
+const isCheckoutSession = (
+  value: PaymentSheetTypes.IntentConfiguration | Checkout
+): value is Checkout =>
+  typeof value === 'object' &&
+  value !== null &&
+  'sessionKey' in value &&
+  !('mode' in value);
+
 // -----------------------------------------------------------------------------
 // Embedded API
 // -----------------------------------------------------------------------------
 
 class EmbeddedPaymentElement {
   /**
-   * Call this when the intent configuration changes (e.g., amount or currency).
+   * Call this when the intent configuration or Checkout Session changes.
    * Cancels any in-progress update. Ensures the correct payment methods are shown and fields are collected.
    * If the selected payment option becomes invalid, it may be cleared.
    * Returns the final result of the update; earlier in-flight updates will return `{ status: 'canceled' }`.
    */
-  async update(intentConfig: PaymentSheetTypes.IntentConfiguration) {
-    const result =
-      await NativeStripeSdkModule.updateEmbeddedPaymentElement(intentConfig);
-    return result;
+  async updateIntent(
+    intentConfig: PaymentSheetTypes.IntentConfiguration
+  ): Promise<unknown> {
+    return await NativeStripeSdkModule.updateEmbeddedPaymentElement(
+      intentConfig
+    );
+  }
+
+  async updateCheckout(checkout: Checkout): Promise<unknown> {
+    return await NativeStripeSdkModule.updateEmbeddedPaymentElementWithCheckout(
+      checkout.sessionKey
+    );
   }
 
   /**
@@ -268,21 +286,28 @@ let customPaymentMethodConfirmCallback: EventSubscription | null = null;
 let rowSelectionCallback: EventSubscription | null = null;
 
 async function createEmbeddedPaymentElement(
-  intentConfig: PaymentSheetTypes.IntentConfiguration,
+  intent: PaymentSheetTypes.IntentConfiguration | Checkout,
   configuration: EmbeddedPaymentElementConfiguration
 ): Promise<EmbeddedPaymentElement> {
-  setupConfirmAndSelectionHandlers(intentConfig, configuration);
+  setupConfigurationHandlers(configuration);
 
-  await NativeStripeSdkModule.createEmbeddedPaymentElement(
-    intentConfig,
-    configuration
-  );
+  if (isCheckoutSession(intent)) {
+    await NativeStripeSdkModule.createEmbeddedPaymentElementWithCheckout(
+      intent.sessionKey,
+      configuration
+    );
+  } else {
+    setupIntentConfirmHandlers(intent);
+    await NativeStripeSdkModule.createEmbeddedPaymentElement(
+      intent,
+      configuration
+    );
+  }
   return new EmbeddedPaymentElement();
 }
 
-function setupConfirmAndSelectionHandlers(
-  intentConfig: PaymentSheetTypes.IntentConfiguration,
-  configuration: EmbeddedPaymentElementConfiguration
+function setupIntentConfirmHandlers(
+  intentConfig: PaymentSheetTypes.IntentConfiguration
 ) {
   const confirmHandler = intentConfig.confirmHandler;
   if (confirmHandler) {
@@ -323,7 +348,11 @@ function setupConfirmAndSelectionHandlers(
       }
     );
   }
+}
 
+function setupConfigurationHandlers(
+  configuration: EmbeddedPaymentElementConfiguration
+) {
   if (configuration.formSheetAction?.type === 'confirm') {
     const confirmFormSheetHandler =
       configuration.formSheetAction.onFormSheetConfirmComplete;
@@ -409,7 +438,16 @@ export interface UseEmbeddedPaymentElementResult {
    * @note Upon completion, `paymentOption` may become null if it's no longer available.
    * @note If you call `update` while a previous call to `update` is still in progress, the previous call is canceled.
    */
-  update: (intentConfig: PaymentSheetTypes.IntentConfiguration) => void;
+  update: {
+    (intentConfig: PaymentSheetTypes.IntentConfiguration): void;
+    /**
+     * Call this method when the Checkout Session values you used to initialize
+     * `EmbeddedPaymentElement` change.
+     * @checkoutSessionsPreview
+     * @internal
+     */
+    (checkout: Checkout): void;
+  };
   // Sets the currently selected payment option to null
   clearPaymentOption: () => void;
   // Any error encountered during creation/update, or null
@@ -429,6 +467,38 @@ export interface UseEmbeddedPaymentElementResult {
 export function useEmbeddedPaymentElement(
   intentConfig: PaymentSheetTypes.IntentConfiguration,
   configuration: EmbeddedPaymentElementConfiguration
+): UseEmbeddedPaymentElementResult;
+/**
+ * Initializes an `EmbeddedPaymentElement` from a Stripe Checkout Session.
+ *
+ * Pass a loaded handle from `useCheckout`. Render the consumer in a child
+ * component so the hook only runs once `state.status === 'loaded'`.
+ *
+ * @example
+ * function Cart() {
+ *   const { checkout, state } = useCheckout(clientSecret);
+ *   if (state?.status !== 'loaded') return null;
+ *   return <EmbeddedCheckout checkout={checkout} />;
+ * }
+ *
+ * function EmbeddedCheckout({ checkout }: { checkout: Checkout }) {
+ *   const { embeddedPaymentElementView } =
+ *     useEmbeddedPaymentElement(checkout, configuration);
+ *   return embeddedPaymentElementView;
+ * }
+ *
+ * @param checkout - A loaded `Checkout` handle from `useCheckout`.
+ * @param configuration - Configuration for the embedded element.
+ * @checkoutSessionsPreview
+ * @internal
+ */
+export function useEmbeddedPaymentElement(
+  checkout: Checkout,
+  configuration: EmbeddedPaymentElementConfiguration
+): UseEmbeddedPaymentElementResult;
+export function useEmbeddedPaymentElement(
+  intent: PaymentSheetTypes.IntentConfiguration | Checkout,
+  configuration: EmbeddedPaymentElementConfiguration
 ): UseEmbeddedPaymentElementResult {
   const isAndroid = Platform.OS === 'android';
   const elementRef = useRef<EmbeddedPaymentElement | null>(null);
@@ -454,12 +524,18 @@ export function useEmbeddedPaymentElement(
     return ref.current;
   }
 
+  // Re-key on the session key (Checkout) or intent object so we only
+  // recreate the element when the source actually changes.
+  const intentKey = isCheckoutSession(intent) ? intent.sessionKey : intent;
+  const intentRef = useRef(intent);
+  intentRef.current = intent;
+
   // Create embedded payment element
   useEffect(() => {
     let active = true;
     (async () => {
       const el = await createEmbeddedPaymentElement(
-        intentConfig,
+        intentRef.current,
         configuration
       );
       if (!active) return;
@@ -471,7 +547,7 @@ export function useEmbeddedPaymentElement(
       elementRef.current = null;
       setElement(null);
     };
-  }, [intentConfig, configuration, viewRef, isAndroid]);
+  }, [intentKey, configuration, viewRef, isAndroid]);
 
   useEffect(() => {
     const sub = addListener(
@@ -509,13 +585,19 @@ export function useEmbeddedPaymentElement(
 
   // Render the embedded view
   const embeddedPaymentElementView = useMemo(() => {
-    if (isAndroid && configuration && intentConfig) {
+    // `intentKey` is the session key string for Checkout, the IntentConfiguration object otherwise.
+    const intentProps =
+      typeof intentKey === 'string'
+        ? { checkout: { sessionKey: intentKey } }
+        : { intentConfiguration: intentKey };
+
+    if (isAndroid && configuration && intentKey) {
       return (
         <NativeEmbeddedPaymentElement
           ref={viewRef}
           style={[{ width: '100%', height: height }]}
           configuration={configuration}
-          intentConfiguration={intentConfig}
+          {...intentProps}
         />
       );
     }
@@ -525,10 +607,10 @@ export function useEmbeddedPaymentElement(
         ref={viewRef}
         style={{ width: '100%', height }}
         configuration={configuration}
-        intentConfiguration={intentConfig}
+        {...intentProps}
       />
     );
-  }, [configuration, element, height, intentConfig, isAndroid]);
+  }, [configuration, element, height, intentKey, isAndroid]);
 
   // Other APIs
   const confirm = useCallback((): Promise<EmbeddedPaymentElementResult> => {
@@ -560,19 +642,25 @@ export function useEmbeddedPaymentElement(
     return getElementOrThrow(elementRef).confirm();
   }, [isAndroid]);
   const update = useCallback(
-    (cfg: PaymentSheetTypes.IntentConfiguration) => {
+    (
+      updateSource: PaymentSheetTypes.IntentConfiguration | Checkout
+    ): Promise<unknown> => {
       if (isAndroid) {
         const currentRef = viewRef.current;
         if (currentRef) {
-          return new Promise<{ status: string } | null>((resolve) => {
+          return new Promise((resolve) => {
             const sub = addListener(
               'embeddedPaymentElementUpdateComplete',
-              (result: { status: string } | null) => {
+              (result) => {
                 sub.remove();
                 resolve(result);
               }
             );
-            Commands.update(currentRef, JSON.stringify(cfg));
+            if (isCheckoutSession(updateSource)) {
+              Commands.updateWithCheckout(currentRef, updateSource.sessionKey);
+            } else {
+              Commands.update(currentRef, JSON.stringify(updateSource));
+            }
           });
         }
         return Promise.reject(
@@ -581,7 +669,10 @@ export function useEmbeddedPaymentElement(
       }
 
       // iOS: use native module directly
-      return getElementOrThrow(elementRef).update(cfg);
+      const embeddedElement = getElementOrThrow(elementRef);
+      return isCheckoutSession(updateSource)
+        ? embeddedElement.updateCheckout(updateSource)
+        : embeddedElement.updateIntent(updateSource);
     },
     [isAndroid]
   );

package/src/types/NextAction.ts

@@ -4,6 +4,7 @@ export type NextAction =
   | WeChatRedirectAction
   | AlipayRedirectAction
   | BoletoVoucherAction
+  | MultibancoVoucherAction
   | OxxoVoucherAction;
 
 export type VerifyWithMicrodepositsAction = {
@@ -39,6 +40,14 @@ export type KonbiniVoucherAction = {
   voucherURL: string;
 };
 
+export type MultibancoVoucherAction = {
+  type: 'multibanco';
+  voucherURL: string;
+  entity?: string;
+  reference?: string;
+  expiresAt?: number;
+};
+
 export type OxxoVoucherAction = {
   type: 'oxxoVoucher';
   expiration: number;