Payment Elements

/**
 * Universal payment element supporting multiple payment methods
 * @param props - Payment element configuration props
 * @returns JSX element for payment method collection
 */
function PaymentElement(props: PaymentElementProps): JSX.Element;

interface PaymentElementProps extends ElementProps {
  /** Configuration options for the Payment Element */
  options?: StripePaymentElementOptions;
  /** Triggered when data exposed by this Element is changed */
  onChange?: (event: StripePaymentElementChangeEvent) => any;
  /** Triggered when the Element is fully rendered and can accept focus */
  onReady?: (element: StripePaymentElement) => any;
  /** Triggered when the escape key is pressed within the Element */
  onEscape?: () => any;
  /** Triggered when the Element fails to load */
  onLoadError?: (event: {elementType: 'payment'; error: StripeError}) => any;
  /** Triggered when the loader UI is mounted to the DOM */
  onLoaderStart?: (event: {elementType: 'payment'}) => any;
  /**
   * Requires beta access: Contact Stripe support for more information.
   * Triggered when the user removes a saved payment method from the Payment Element.
   */
  onSavedPaymentMethodRemove?: (event: {
    elementType: 'payment';
    success: boolean;
    error?: string;
    payment_method: StripePaymentElementChangeEvent['value']['payment_method'];
  }) => any;
  /**
   * Requires beta access: Contact Stripe support for more information.
   * Triggered when the user updates a saved payment method from the Payment Element.
   */
  onSavedPaymentMethodUpdate?: (event: {
    elementType: 'payment';
    success: boolean;
    error?: string;
    payment_method: StripePaymentElementChangeEvent['value']['payment_method'];
  }) => any;
}

interface StripePaymentElementOptions {
  /** Layout configuration */
  layout?: 'tabs' | 'accordion' | 'auto';
  /** Payment method types to display */
  paymentMethodTypes?: string[];
  /** Default payment method values */
  defaultValues?: {
    billingDetails?: {
      name?: string;
      email?: string;
      phone?: string;
      address?: {
        line1?: string;
        line2?: string;
        city?: string;
        state?: string;
        postal_code?: string;
        country?: string;
      };
    };
  };
  /** Business information for tax calculation */
  business?: {name?: string};
  /** Terms of service options */
  terms?: {
    card?: 'auto' | 'always' | 'never';
    bancontact?: 'auto' | 'always' | 'never';
    eps?: 'auto' | 'always' | 'never';
    fpx?: 'auto' | 'always' | 'never';
    giropay?: 'auto' | 'always' | 'never';
    ideal?: 'auto' | 'always' | 'never';
    p24?: 'auto' | 'always' | 'never';
    sepaDebit?: 'auto' | 'always' | 'never';
    sofort?: 'auto' | 'always' | 'never';
  };
  /** Wallet display options */
  wallets?: {
    applePay?: 'auto' | 'always' | 'never';
    googlePay?: 'auto' | 'always' | 'never';
  };
}

import React from 'react';
import { PaymentElement, useStripe, useElements } from '@stripe/react-stripe-js';

const PaymentForm = () => {
  const stripe = useStripe();
  const elements = useElements();

  return (
    <form onSubmit={handleSubmit}>
      {/* Basic PaymentElement */}
      <PaymentElement />
      
      {/* PaymentElement with options */}
      <PaymentElement
        options={{
          layout: 'tabs',
          defaultValues: {
            billingDetails: {
              name: 'Jenny Rosen',
              email: 'jenny@example.com',
            }
          }
        }}
        onChange={handlePaymentChange}
        onReady={handlePaymentReady}
      />
      <button disabled={!stripe}>Submit</button>
    </form>
  );
};

const handlePaymentChange = (event) => {
  console.log('Payment method changed:', event);
};

const handlePaymentReady = (element) => {
  console.log('Payment element ready:', element);
};

/**
 * Express checkout button element for one-click payments
 * @param props - Express checkout element configuration props
 * @returns JSX element for express payment methods
 */
function ExpressCheckoutElement(props: ExpressCheckoutElementProps): JSX.Element;

interface ExpressCheckoutElementProps extends ElementProps {
  /** Configuration options for the Express Checkout Element */
  options?: StripeExpressCheckoutElementOptions;
  /** Triggered when an express payment button is clicked */
  onClick?: (event: StripeExpressCheckoutElementClickEvent) => any;
  /** Triggered when express checkout is cancelled */
  onCancel?: (event: {elementType: 'expressCheckout'}) => any;
  /** Triggered when express checkout is confirmed - REQUIRED */
  onConfirm: (event: StripeExpressCheckoutElementConfirmEvent) => any;
  /** Triggered when shipping address changes */
  onShippingAddressChange?: (event: StripeExpressCheckoutElementShippingAddressChangeEvent) => any;
  /** Triggered when shipping rate changes */
  onShippingRateChange?: (event: StripeExpressCheckoutElementShippingRateChangeEvent) => any;
  /** Triggered when the Element is fully rendered */
  onReady?: (event: StripeExpressCheckoutElementReadyEvent) => any;
  /** Triggered when the escape key is pressed */
  onEscape?: () => any;
  /** Triggered when the Element fails to load */
  onLoadError?: (event: {elementType: 'expressCheckout'; error: StripeError}) => any;
}

interface StripeExpressCheckoutElementOptions {
  /** Payment method types to enable */
  paymentMethods?: {
    applePay?: 'auto' | 'always' | 'never';
    googlePay?: 'auto' | 'always' | 'never';
    link?: 'auto' | 'always' | 'never';
    amazonPay?: 'auto' | 'always' | 'never';
  };
  /** Button theme customization */
  buttonTheme?: {
    applePay?: 'black' | 'white' | 'white-outline';
    googlePay?: 'black' | 'white';
  };
  /** Button type customization */
  buttonType?: {
    applePay?: 'buy' | 'set-up' | 'donate' | 'check-out' | 'book' | 'subscribe';
    googlePay?: 'buy' | 'donate' | 'checkout';
  };
  /** Button height in pixels */
  buttonHeight?: number;
  /** Layout configuration */
  layout?: {
    maxColumns?: number;
    maxRows?: number;
    overflow?: 'scrollable' | 'hidden';
  };
}

import React from 'react';
import { ExpressCheckoutElement } from '@stripe/react-stripe-js';

const ExpressCheckout = () => {
  const handleExpressClick = (event) => {
    console.log('Express payment clicked:', event.expressPaymentType);
  };

  const handleExpressConfirm = async (event) => {
    // Handle the express payment confirmation
    console.log('Express payment confirmed:', event);
  };

  return (
    <ExpressCheckoutElement
      options={{
        paymentMethods: {
          applePay: 'auto',
          googlePay: 'auto',
          link: 'auto'
        },
        buttonTheme: {
          applePay: 'black',
          googlePay: 'black'
        },
        buttonHeight: 48
      }}
      onClick={handleExpressClick}
      onConfirm={handleExpressConfirm}
      onCancel={() => console.log('Express payment cancelled')}
    />
  );
};

/**
 * Payment request button element for Apple Pay and Google Pay
 * @param props - Payment request button configuration props
 * @returns JSX element for payment request functionality
 */
function PaymentRequestButtonElement(props: PaymentRequestButtonElementProps): JSX.Element;

interface PaymentRequestButtonElementProps extends ElementProps {
  /** Configuration options for the Payment Request Button */
  options?: StripePaymentRequestButtonElementOptions;
  /** Triggered when the payment request button is clicked */
  onClick?: (event: StripePaymentRequestButtonElementClickEvent) => any;
  /** Triggered when the Element is fully rendered */
  onReady?: (element: StripePaymentRequestButtonElement) => any;
  /** Triggered when the escape key is pressed */
  onEscape?: () => any;
}

interface StripePaymentRequestButtonElementOptions {
  /** Payment request object configuration */
  paymentRequest: StripePaymentRequest;
  /** Button style customization */
  style?: {
    paymentRequestButton?: {
      type?: 'default' | 'book' | 'buy' | 'donate';
      theme?: 'dark' | 'light' | 'light-outline';
      height?: string;
    };
  };
}

import React, { useMemo } from 'react';
import { PaymentRequestButtonElement, useStripe } from '@stripe/react-stripe-js';

const PaymentRequestButton = () => {
  const stripe = useStripe();

  const paymentRequest = useMemo(() => {
    if (!stripe) return null;
    
    return stripe.paymentRequest({
      country: 'US',
      currency: 'usd',
      total: {
        label: 'Demo total',
        amount: 1099,
      },
      requestPayerName: true,
      requestPayerEmail: true,
    });
  }, [stripe]);

  if (!paymentRequest) return null;

  return (
    <PaymentRequestButtonElement
      options={{
        paymentRequest,
        style: {
          paymentRequestButton: {
            type: 'buy',
            theme: 'dark',
            height: '40px',
          },
        },
      }}
      onClick={(event) => {
        console.log('Payment request clicked:', event);
      }}
    />
  );
};

interface StripePaymentElementChangeEvent {
  elementType: 'payment';
  empty: boolean;
  complete: boolean;
  collapsed?: boolean;
  value: {
    type: string;
  };
}

interface StripeExpressCheckoutElementClickEvent {
  elementType: 'expressCheckout';
  expressPaymentType: 'applePay' | 'googlePay' | 'link' | 'amazonPay';
  resolve: (options?: {}) => void;
}

interface StripeExpressCheckoutElementConfirmEvent {
  elementType: 'expressCheckout';
  expressPaymentType: 'applePay' | 'googlePay' | 'link' | 'amazonPay';
  paymentMethod: StripePaymentMethod;
  billingDetails?: StripeBillingDetails;
  shippingAddress?: StripeShippingAddress;
  shippingRate?: StripeShippingRate;
}