0
# Message Elements
1

2
Elements for displaying financing options and payment method messaging to customers. These elements help communicate available payment options and financing terms to enhance the checkout experience.
3

4
## Capabilities
5

6
### PaymentMethodMessagingElement
7

8
Displays messaging about available payment methods and their benefits to customers during checkout.
9

10
```typescript { .api }
11
/**
12
 * Payment method messaging element for displaying payment options information
13
 * @param props - Payment method messaging element configuration props
14
 * @returns JSX element for payment method messaging
15
 */
16
function PaymentMethodMessagingElement(props: PaymentMethodMessagingElementProps): JSX.Element;
17

18
interface PaymentMethodMessagingElementProps {
19
  /** Passes through to the Element's container */
20
  id?: string;
21
  /** Passes through to the Element's container */
22
  className?: string;
23
  /** Configuration options for the Payment Method Messaging Element */
24
  options?: StripePaymentMethodMessagingElementOptions;
25
  /** Triggered when the Element is fully rendered and can accept focus */
26
  onReady?: (element: StripePaymentMethodMessagingElement) => any;
27
  /** Triggered when the escape key is pressed within the Element */
28
  onEscape?: () => any;
29
  /** Triggered when the Element fails to load */
30
  onLoadError?: (event: {elementType: 'paymentMethodMessaging'; error: StripeError}) => any;
31
  /** Triggered when the loader UI is mounted to the DOM */
32
  onLoaderStart?: (event: {elementType: 'paymentMethodMessaging'}) => any;
33
}
34

35
interface StripePaymentMethodMessagingElementOptions {
36
  /** Amount for payment method messaging */
37
  amount?: number;
38
  /** Currency for the amount */
39
  currency?: string;
40
  /** Payment method types to show messaging for */
41
  paymentMethodTypes?: string[];
42
  /** Country code for localization */
43
  countryCode?: string;
44
}
45
```
46

47
**Usage Examples:**
48

49
```typescript
50
import React from 'react';
51
import { PaymentMethodMessagingElement } from '@stripe/react-stripe-js';
52

53
const PaymentOptionsMessaging = ({ amount, currency }) => {
54
  return (
55
    <div className="payment-messaging">
56
      <h3>Payment Options</h3>
57
      <PaymentMethodMessagingElement
58
        options={{
59
          amount: amount * 100, // Amount in cents
60
          currency: currency.toLowerCase(),
61
          paymentMethodTypes: ['card', 'klarna', 'afterpay_clearpay'],
62
          countryCode: 'US'
63
        }}
64
        onReady={() => console.log('Payment messaging ready')}
65
        onLoadError={(event) => console.error('Payment messaging load error:', event.error)}
66
      />
67
    </div>
68
  );
69
};
70

71
// Usage in checkout
72
const CheckoutPage = () => {
73
  const orderAmount = 99.99;
74
  
75
  return (
76
    <div>
77
      <div className="order-summary">
78
        <p>Total: ${orderAmount}</p>
79
      </div>
80
      
81
      <PaymentOptionsMessaging 
82
        amount={orderAmount} 
83
        currency="USD" 
84
      />
85
      
86
      <PaymentElement />
87
    </div>
88
  );
89
};
90
```
91

92
### AffirmMessageElement
93

94
Displays Affirm financing options and payment messaging for eligible purchases.
95

96
```typescript { .api }
97
/**
98
 * Affirm message element for displaying financing options
99
 * @param props - Affirm message element configuration props
100
 * @returns JSX element for Affirm financing messaging
101
 */
102
function AffirmMessageElement(props: AffirmMessageElementProps): JSX.Element;
103

104
interface AffirmMessageElementProps {
105
  /** Passes through to the Element's container */
106
  id?: string;
107
  /** Passes through to the Element's container */
108
  className?: string;
109
  /** Configuration options for the Affirm Message Element */
110
  options?: StripeAffirmMessageElementOptions;
111
  /** Triggered when the Element is fully rendered and can accept focus */
112
  onReady?: (element: StripeAffirmMessageElement) => any;
113
  /** Triggered when the escape key is pressed within the Element */
114
  onEscape?: () => any;
115
  /** Triggered when the Element fails to load */
116
  onLoadError?: (event: {elementType: 'affirmMessage'; error: StripeError}) => any;
117
  /** Triggered when the loader UI is mounted to the DOM */
118
  onLoaderStart?: (event: {elementType: 'affirmMessage'}) => any;
119
}
120

121
interface StripeAffirmMessageElementOptions {
122
  /** Amount for Affirm messaging calculation */
123
  amount: number;
124
  /** Currency for the amount */
125
  currency: string;
126
  /** Type of Affirm message to display */
127
  type?: 'payment-options' | 'product-messaging';
128
  /** Message theme */
129
  theme?: 'light' | 'dark';
130
  /** Text color */
131
  colorScheme?: 'light' | 'dark' | 'auto';
132
}
133
```
134

135
**Usage Examples:**
136

137
```typescript
138
import React, { useState } from 'react';
139
import { AffirmMessageElement } from '@stripe/react-stripe-js';
140

141
const ProductPage = ({ product }) => {
142
  const [selectedVariant, setSelectedVariant] = useState(product.variants[0]);
143

144
  return (
145
    <div className="product-page">
146
      <div className="product-info">
147
        <h1>{product.name}</h1>
148
        <p className="price">${selectedVariant.price}</p>
149
        
150
        {/* Show Affirm financing options */}
151
        <AffirmMessageElement
152
          options={{
153
            amount: selectedVariant.price * 100, // Amount in cents
154
            currency: 'usd',
155
            type: 'product-messaging',
156
            theme: 'light',
157
            colorScheme: 'auto'
158
          }}
159
          onReady={() => console.log('Affirm message ready')}
160
        />
161
        
162
        <select 
163
          value={selectedVariant.id} 
164
          onChange={(e) => setSelectedVariant(
165
            product.variants.find(v => v.id === e.target.value)
166
          )}
167
        >
168
          {product.variants.map(variant => (
169
            <option key={variant.id} value={variant.id}>
170
              {variant.name} - ${variant.price}
171
            </option>
172
          ))}
173
        </select>
174
      </div>
175
    </div>
176
  );
177
};
178

179
// Checkout page usage
180
const CheckoutWithAffirm = ({ cartTotal }) => {
181
  return (
182
    <div className="checkout">
183
      <div className="payment-options">
184
        <h3>Payment Options</h3>
185
        
186
        <AffirmMessageElement
187
          options={{
188
            amount: cartTotal * 100,
189
            currency: 'usd',
190
            type: 'payment-options',
191
            theme: 'light'
192
          }}
193
        />
194
        
195
        <PaymentElement 
196
          options={{
197
            paymentMethodTypes: ['card', 'affirm']
198
          }}
199
        />
200
      </div>
201
    </div>
202
  );
203
};
204
```
205

206
### AfterpayClearpayMessageElement
207

208
Displays Afterpay/Clearpay financing options and payment messaging for eligible purchases.
209

210
```typescript { .api }
211
/**
212
 * Afterpay/Clearpay message element for displaying buy-now-pay-later options
213
 * @param props - Afterpay/Clearpay message element configuration props
214
 * @returns JSX element for Afterpay/Clearpay messaging
215
 */
216
function AfterpayClearpayMessageElement(props: AfterpayClearpayMessageElementProps): JSX.Element;
217

218
interface AfterpayClearpayMessageElementProps {
219
  /** Passes through to the Element's container */
220
  id?: string;
221
  /** Passes through to the Element's container */
222
  className?: string;
223
  /** Configuration options for the Afterpay/Clearpay Message Element */
224
  options?: StripeAfterpayClearpayMessageElementOptions;
225
  /** Triggered when the Element is fully rendered and can accept focus */
226
  onReady?: (element: StripeAfterpayClearpayMessageElement) => any;
227
  /** Triggered when the escape key is pressed within the Element */
228
  onEscape?: () => any;
229
  /** Triggered when the Element fails to load */
230
  onLoadError?: (event: {elementType: 'afterpayClearpayMessage'; error: StripeError}) => any;
231
  /** Triggered when the loader UI is mounted to the DOM */
232
  onLoaderStart?: (event: {elementType: 'afterpayClearpayMessage'}) => any;
233
}
234

235
interface StripeAfterpayClearpayMessageElementOptions {
236
  /** Amount for Afterpay/Clearpay messaging calculation */
237
  amount: number;
238
  /** Currency for the amount */
239
  currency: string;
240
  /** Message display mode */
241
  displayType?: 'logo' | 'text';
242
  /** Introductory text */
243
  introText?: 'default' | 'in_installments';
244
}
245
```
246

247
**Usage Examples:**
248

249
```typescript
250
import React from 'react';
251
import { AfterpayClearpayMessageElement } from '@stripe/react-stripe-js';
252

253
const ProductWithAfterpay = ({ product }) => {
254
  const isEligibleForAfterpay = product.price >= 1 && product.price <= 2000;
255

256
  return (
257
    <div className="product-details">
258
      <h2>{product.name}</h2>
259
      <p className="price">${product.price}</p>
260
      
261
      {isEligibleForAfterpay && (
262
        <div className="financing-options">
263
          <AfterpayClearpayMessageElement
264
            options={{
265
              amount: product.price * 100, // Amount in cents
266
              currency: 'usd',
267
              displayType: 'logo',
268
              introText: 'in_installments'
269
            }}
270
            onReady={() => console.log('Afterpay message ready')}
271
            onLoadError={(event) => {
272
              console.error('Afterpay message failed to load:', event.error);
273
            }}
274
          />
275
        </div>
276
      )}
277
      
278
      <button className="add-to-cart">Add to Cart</button>
279
    </div>
280
  );
281
};
282

283
// Shopping cart usage
284
const CartWithAfterpay = ({ items, total }) => {
285
  const afterpayEligible = total >= 1 && total <= 2000;
286

287
  return (
288
    <div className="cart">
289
      <div className="cart-items">
290
        {items.map(item => (
291
          <div key={item.id} className="cart-item">
292
            <span>{item.name}</span>
293
            <span>${item.price}</span>
294
          </div>
295
        ))}
296
      </div>
297
      
298
      <div className="cart-total">
299
        <p>Total: ${total}</p>
300
        
301
        {afterpayEligible && (
302
          <AfterpayClearpayMessageElement
303
            options={{
304
              amount: total * 100,
305
              currency: 'usd',
306
              displayType: 'text',
307
              introText: 'default'
308
            }}
309
          />
310
        )}
311
      </div>
312
      
313
      <button className="checkout">Checkout</button>
314
    </div>
315
  );
316
};
317
```
318

319
**Combined Financing Messages Example:**
320

321
```typescript
322
import React from 'react';
323
import { 
324
  AffirmMessageElement, 
325
  AfterpayClearpayMessageElement,
326
  PaymentMethodMessagingElement 
327
} from '@stripe/react-stripe-js';
328

329
const FinancingOptionsDisplay = ({ amount, currency = 'usd' }) => {
330
  const amountInCents = amount * 100;
331
  
332
  // Define eligibility rules
333
  const affirmEligible = amount >= 50 && amount <= 17500;
334
  const afterpayEligible = amount >= 1 && amount <= 2000;
335

336
  return (
337
    <div className="financing-options">
338
      <h3>Flexible Payment Options</h3>
339
      
340
      {/* General payment method messaging */}
341
      <PaymentMethodMessagingElement
342
        options={{
343
          amount: amountInCents,
344
          currency,
345
          paymentMethodTypes: ['card', 'klarna', 'afterpay_clearpay', 'affirm']
346
        }}
347
      />
348
      
349
      {/* Affirm-specific messaging */}
350
      {affirmEligible && (
351
        <div className="affirm-messaging">
352
          <AffirmMessageElement
353
            options={{
354
              amount: amountInCents,
355
              currency,
356
              type: 'payment-options',
357
              theme: 'light'
358
            }}
359
          />
360
        </div>
361
      )}
362
      
363
      {/* Afterpay-specific messaging */}
364
      {afterpayEligible && (
365
        <div className="afterpay-messaging">
366
          <AfterpayClearpayMessageElement
367
            options={{
368
              amount: amountInCents,
369
              currency,
370
              displayType: 'logo',
371
              introText: 'in_installments'
372
            }}
373
          />
374
        </div>
375
      )}
376
      
377
      {!affirmEligible && !afterpayEligible && (
378
        <p className="financing-unavailable">
379
          Financing options are not available for this amount.
380
        </p>
381
      )}
382
    </div>
383
  );
384
};
385

386
// Usage in e-commerce flow
387
const ProductCheckout = () => {
388
  const [cartTotal, setCartTotal] = useState(150.00);
389

390
  return (
391
    <div className="checkout-flow">
392
      <div className="order-summary">
393
        <h2>Order Summary</h2>
394
        <p>Total: ${cartTotal}</p>
395
      </div>
396
      
397
      <FinancingOptionsDisplay amount={cartTotal} />
398
      
399
      <PaymentElement 
400
        options={{
401
          paymentMethodTypes: ['card', 'affirm', 'afterpay_clearpay', 'klarna']
402
        }}
403
      />
404
    </div>
405
  );
406
};
407
```
408

409
## Message Element Styling
410

411
Message elements automatically adapt to your site's theme, but you can customize their appearance:
412

413
```typescript
414
// Custom styling example
415
const StyledMessagingElements = ({ amount }) => {
416
  return (
417
    <div className="custom-financing-messages">
418
      <style jsx>{`
419
        .custom-financing-messages {
420
          padding: 16px;
421
          background-color: #f8f9fa;
422
          border-radius: 8px;
423
          margin: 16px 0;
424
        }
425
        
426
        .financing-section {
427
          margin-bottom: 12px;
428
        }
429
        
430
        .financing-section:last-child {
431
          margin-bottom: 0;
432
        }
433
      `}</style>
434
      
435
      <div className="financing-section">
436
        <AffirmMessageElement
437
          options={{
438
            amount: amount * 100,
439
            currency: 'usd',
440
            colorScheme: 'auto', // Adapts to your site's theme
441
            theme: 'light'
442
          }}
443
        />
444
      </div>
445
      
446
      <div className="financing-section">
447
        <AfterpayClearpayMessageElement
448
          options={{
449
            amount: amount * 100,
450
            currency: 'usd',
451
            displayType: 'text'
452
          }}
453
        />
454
      </div>
455
    </div>
456
  );
457
};
458
```
459

460
## Error Handling
461

462
```typescript
463
const MessagingWithErrorHandling = ({ amount }) => {
464
  const [messagingErrors, setMessagingErrors] = useState({});
465

466
  const handleLoadError = (elementType) => (event) => {
467
    setMessagingErrors(prev => ({
468
      ...prev,
469
      [elementType]: event.error.message
470
    }));
471
    console.error(`${elementType} messaging failed:`, event.error);
472
  };
473

474
  return (
475
    <div>
476
      <AffirmMessageElement
477
        options={{ amount: amount * 100, currency: 'usd' }}
478
        onLoadError={handleLoadError('affirm')}
479
      />
480
      
481
      {messagingErrors.affirm && (
482
        <div className="error-message">
483
          Affirm messaging unavailable: {messagingErrors.affirm}
484
        </div>
485
      )}
486
      
487
      <AfterpayClearpayMessageElement
488
        options={{ amount: amount * 100, currency: 'usd' }}
489
        onLoadError={handleLoadError('afterpay')}
490
      />
491
      
492
      {messagingErrors.afterpay && (
493
        <div className="error-message">
494
          Afterpay messaging unavailable: {messagingErrors.afterpay}
495
        </div>
496
      )}
497
    </div>
498
  );
499
};
500
```