0
# Payment Elements
1

2
Modern payment elements supporting multiple payment methods with unified interfaces. These elements provide the core payment collection functionality with built-in support for various payment methods.
3

4
## Capabilities
5

6
### PaymentElement
7

8
Universal payment element that automatically displays relevant payment methods based on your configuration and the customer's location.
9

10
```typescript { .api }
11
/**
12
 * Universal payment element supporting multiple payment methods
13
 * @param props - Payment element configuration props
14
 * @returns JSX element for payment method collection
15
 */
16
function PaymentElement(props: PaymentElementProps): JSX.Element;
17

18
interface PaymentElementProps extends ElementProps {
19
  /** Configuration options for the Payment Element */
20
  options?: StripePaymentElementOptions;
21
  /** Triggered when data exposed by this Element is changed */
22
  onChange?: (event: StripePaymentElementChangeEvent) => any;
23
  /** Triggered when the Element is fully rendered and can accept focus */
24
  onReady?: (element: StripePaymentElement) => any;
25
  /** Triggered when the escape key is pressed within the Element */
26
  onEscape?: () => any;
27
  /** Triggered when the Element fails to load */
28
  onLoadError?: (event: {elementType: 'payment'; error: StripeError}) => any;
29
  /** Triggered when the loader UI is mounted to the DOM */
30
  onLoaderStart?: (event: {elementType: 'payment'}) => any;
31
  /**
32
   * Requires beta access: Contact Stripe support for more information.
33
   * Triggered when the user removes a saved payment method from the Payment Element.
34
   */
35
  onSavedPaymentMethodRemove?: (event: {
36
    elementType: 'payment';
37
    success: boolean;
38
    error?: string;
39
    payment_method: StripePaymentElementChangeEvent['value']['payment_method'];
40
  }) => any;
41
  /**
42
   * Requires beta access: Contact Stripe support for more information.
43
   * Triggered when the user updates a saved payment method from the Payment Element.
44
   */
45
  onSavedPaymentMethodUpdate?: (event: {
46
    elementType: 'payment';
47
    success: boolean;
48
    error?: string;
49
    payment_method: StripePaymentElementChangeEvent['value']['payment_method'];
50
  }) => any;
51
}
52

53
interface StripePaymentElementOptions {
54
  /** Layout configuration */
55
  layout?: 'tabs' | 'accordion' | 'auto';
56
  /** Payment method types to display */
57
  paymentMethodTypes?: string[];
58
  /** Default payment method values */
59
  defaultValues?: {
60
    billingDetails?: {
61
      name?: string;
62
      email?: string;
63
      phone?: string;
64
      address?: {
65
        line1?: string;
66
        line2?: string;
67
        city?: string;
68
        state?: string;
69
        postal_code?: string;
70
        country?: string;
71
      };
72
    };
73
  };
74
  /** Business information for tax calculation */
75
  business?: {name?: string};
76
  /** Terms of service options */
77
  terms?: {
78
    card?: 'auto' | 'always' | 'never';
79
    bancontact?: 'auto' | 'always' | 'never';
80
    eps?: 'auto' | 'always' | 'never';
81
    fpx?: 'auto' | 'always' | 'never';
82
    giropay?: 'auto' | 'always' | 'never';
83
    ideal?: 'auto' | 'always' | 'never';
84
    p24?: 'auto' | 'always' | 'never';
85
    sepaDebit?: 'auto' | 'always' | 'never';
86
    sofort?: 'auto' | 'always' | 'never';
87
  };
88
  /** Wallet display options */
89
  wallets?: {
90
    applePay?: 'auto' | 'always' | 'never';
91
    googlePay?: 'auto' | 'always' | 'never';
92
  };
93
}
94
```
95

96
**Usage Examples:**
97

98
```typescript
99
import React from 'react';
100
import { PaymentElement, useStripe, useElements } from '@stripe/react-stripe-js';
101

102
const PaymentForm = () => {
103
  const stripe = useStripe();
104
  const elements = useElements();
105

106
  return (
107
    <form onSubmit={handleSubmit}>
108
      {/* Basic PaymentElement */}
109
      <PaymentElement />
110
      
111
      {/* PaymentElement with options */}
112
      <PaymentElement
113
        options={{
114
          layout: 'tabs',
115
          defaultValues: {
116
            billingDetails: {
117
              name: 'Jenny Rosen',
118
              email: 'jenny@example.com',
119
            }
120
          }
121
        }}
122
        onChange={handlePaymentChange}
123
        onReady={handlePaymentReady}
124
      />
125
      <button disabled={!stripe}>Submit</button>
126
    </form>
127
  );
128
};
129

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

134
const handlePaymentReady = (element) => {
135
  console.log('Payment element ready:', element);
136
};
137
```
138

139
### ExpressCheckoutElement
140

141
Express checkout button supporting Apple Pay, Google Pay, and other express payment methods.
142

143
```typescript { .api }
144
/**
145
 * Express checkout button element for one-click payments
146
 * @param props - Express checkout element configuration props
147
 * @returns JSX element for express payment methods
148
 */
149
function ExpressCheckoutElement(props: ExpressCheckoutElementProps): JSX.Element;
150

151
interface ExpressCheckoutElementProps extends ElementProps {
152
  /** Configuration options for the Express Checkout Element */
153
  options?: StripeExpressCheckoutElementOptions;
154
  /** Triggered when an express payment button is clicked */
155
  onClick?: (event: StripeExpressCheckoutElementClickEvent) => any;
156
  /** Triggered when express checkout is cancelled */
157
  onCancel?: (event: {elementType: 'expressCheckout'}) => any;
158
  /** Triggered when express checkout is confirmed - REQUIRED */
159
  onConfirm: (event: StripeExpressCheckoutElementConfirmEvent) => any;
160
  /** Triggered when shipping address changes */
161
  onShippingAddressChange?: (event: StripeExpressCheckoutElementShippingAddressChangeEvent) => any;
162
  /** Triggered when shipping rate changes */
163
  onShippingRateChange?: (event: StripeExpressCheckoutElementShippingRateChangeEvent) => any;
164
  /** Triggered when the Element is fully rendered */
165
  onReady?: (event: StripeExpressCheckoutElementReadyEvent) => any;
166
  /** Triggered when the escape key is pressed */
167
  onEscape?: () => any;
168
  /** Triggered when the Element fails to load */
169
  onLoadError?: (event: {elementType: 'expressCheckout'; error: StripeError}) => any;
170
}
171

172
interface StripeExpressCheckoutElementOptions {
173
  /** Payment method types to enable */
174
  paymentMethods?: {
175
    applePay?: 'auto' | 'always' | 'never';
176
    googlePay?: 'auto' | 'always' | 'never';
177
    link?: 'auto' | 'always' | 'never';
178
    amazonPay?: 'auto' | 'always' | 'never';
179
  };
180
  /** Button theme customization */
181
  buttonTheme?: {
182
    applePay?: 'black' | 'white' | 'white-outline';
183
    googlePay?: 'black' | 'white';
184
  };
185
  /** Button type customization */
186
  buttonType?: {
187
    applePay?: 'buy' | 'set-up' | 'donate' | 'check-out' | 'book' | 'subscribe';
188
    googlePay?: 'buy' | 'donate' | 'checkout';
189
  };
190
  /** Button height in pixels */
191
  buttonHeight?: number;
192
  /** Layout configuration */
193
  layout?: {
194
    maxColumns?: number;
195
    maxRows?: number;
196
    overflow?: 'scrollable' | 'hidden';
197
  };
198
}
199
```
200

201
**Usage Examples:**
202

203
```typescript
204
import React from 'react';
205
import { ExpressCheckoutElement } from '@stripe/react-stripe-js';
206

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

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

217
  return (
218
    <ExpressCheckoutElement
219
      options={{
220
        paymentMethods: {
221
          applePay: 'auto',
222
          googlePay: 'auto',
223
          link: 'auto'
224
        },
225
        buttonTheme: {
226
          applePay: 'black',
227
          googlePay: 'black'
228
        },
229
        buttonHeight: 48
230
      }}
231
      onClick={handleExpressClick}
232
      onConfirm={handleExpressConfirm}
233
      onCancel={() => console.log('Express payment cancelled')}
234
    />
235
  );
236
};
237
```
238

239
### PaymentRequestButtonElement
240

241
Legacy payment request button for Apple Pay and Google Pay integration.
242

243
```typescript { .api }
244
/**
245
 * Payment request button element for Apple Pay and Google Pay
246
 * @param props - Payment request button configuration props
247
 * @returns JSX element for payment request functionality
248
 */
249
function PaymentRequestButtonElement(props: PaymentRequestButtonElementProps): JSX.Element;
250

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

262
interface StripePaymentRequestButtonElementOptions {
263
  /** Payment request object configuration */
264
  paymentRequest: StripePaymentRequest;
265
  /** Button style customization */
266
  style?: {
267
    paymentRequestButton?: {
268
      type?: 'default' | 'book' | 'buy' | 'donate';
269
      theme?: 'dark' | 'light' | 'light-outline';
270
      height?: string;
271
    };
272
  };
273
}
274
```
275

276
**Usage Examples:**
277

278
```typescript
279
import React, { useMemo } from 'react';
280
import { PaymentRequestButtonElement, useStripe } from '@stripe/react-stripe-js';
281

282
const PaymentRequestButton = () => {
283
  const stripe = useStripe();
284

285
  const paymentRequest = useMemo(() => {
286
    if (!stripe) return null;
287
    
288
    return stripe.paymentRequest({
289
      country: 'US',
290
      currency: 'usd',
291
      total: {
292
        label: 'Demo total',
293
        amount: 1099,
294
      },
295
      requestPayerName: true,
296
      requestPayerEmail: true,
297
    });
298
  }, [stripe]);
299

300
  if (!paymentRequest) return null;
301

302
  return (
303
    <PaymentRequestButtonElement
304
      options={{
305
        paymentRequest,
306
        style: {
307
          paymentRequestButton: {
308
            type: 'buy',
309
            theme: 'dark',
310
            height: '40px',
311
          },
312
        },
313
      }}
314
      onClick={(event) => {
315
        console.log('Payment request clicked:', event);
316
      }}
317
    />
318
  );
319
};
320
```
321

322
## Common Event Types
323

324
```typescript { .api }
325
interface StripePaymentElementChangeEvent {
326
  elementType: 'payment';
327
  empty: boolean;
328
  complete: boolean;
329
  collapsed?: boolean;
330
  value: {
331
    type: string;
332
  };
333
}
334

335
interface StripeExpressCheckoutElementClickEvent {
336
  elementType: 'expressCheckout';
337
  expressPaymentType: 'applePay' | 'googlePay' | 'link' | 'amazonPay';
338
  resolve: (options?: {}) => void;
339
}
340

341
interface StripeExpressCheckoutElementConfirmEvent {
342
  elementType: 'expressCheckout';
343
  expressPaymentType: 'applePay' | 'googlePay' | 'link' | 'amazonPay';
344
  paymentMethod: StripePaymentMethod;
345
  billingDetails?: StripeBillingDetails;
346
  shippingAddress?: StripeShippingAddress;
347
  shippingRate?: StripeShippingRate;
348
}
349
```