Elements with Checkout Sessions API changelogPublic preview

Elements with Checkout Sessions API uses two kinds of beta versions:

• A Stripe.js beta header (e.g., custom_checkout_beta_5), which is set on your front-end integration.
• An API version beta header (e.g., custom_checkout_beta=v1), which is set on your back-end integration.

Frontend beta versions

Specify the front-end beta version when initializing Stripe.js.

custom_checkout_beta_5

• Breaking The initCustomCheckout function has been renamed to initCheckout
  • Within React Stripe.js, CustomCheckoutProvider has been renamed to CheckoutProvider and useCustomCheckout has been renamed to useCheckout.
• Breaking To confirm the Express Checkout Element, call confirm, passing the confirm event as expressCheckoutConfirmEvent
  • Previously, Express Checkout Element was confirmed by calling event.confirm().
• Breaking When confirm is called, Payment Element and Address Element will validate form inputs and render any errors.
• Breaking Error messages have been standardized and improved.
  • Errors returned/resolved by a function represent known scenarios like invalid payment details or insufficient funds. These are predictable issues that can be communicated to your customer by displaying the message on the checkout page.
  • Errors thrown/rejected by a function represent errors in the integration itself, such as invalid parameters or configuration. These errors are not meant to be displayed to your customers.
• Breaking Asynchronous methods, such as confirm or applyPromotionCode, resolve with a different schema:
  • A type="success"|"error" discriminator field has been added.
  • If successful, the updated session state is populated under the success key. Previously, this was under the session key.
  • Otherwise, the error continues to be populated under the error key.
• Added the email, phoneNumber, billingAddress, and shippingAddress options to confirm.
• Breaking Address Element no longer automatically updates the billingAddress or shippingAddress fields on the Session.
  • So long as Address Element is mounted, form values will automatically be used when calling confirm.
  • Listen to the change event to use the Address Element value before confirmation.

custom_checkout_beta_4

• Added images to the Session object.
• Added fields as an option when creating the Payment Element.
• Added paymentMethods as an option when creating the Express Checkout Element.
• Breaking Passing invalid options to createElement now throws an error. Previously, unrecognized options would be silently ignored.
• Breaking updateEmail and updatePhoneNumber apply changes asynchronously. Calling these methods before the customer finishes entering complete values might cause poor performance.
  • Instead of calling updateEmail or updatePhoneNumber on each input’s change event, wait until your customer finishes the input, such as on input blur or when they submit the form for payment.
  • updateEmail now validates that the input is a properly formed email address and returns an error if an invalid input is used.
  • updatePhoneNumber still performs no validation on the input string.

custom_checkout_beta_3

• The following fields have been added to the Session object:
  • id
  • livemode
  • businessName
• Saved cards can now be reused. Learn how to save and reuse payment methods.
• Breaking The default layout of the Payment Element has been changed to accordion.
  • To continue using the previous default layout, you must explicitly specify layout='tabs'.
• Breaking The default behavior of confirm has been changed to always redirect to your return_url after a successful confirmation.
  • Previously, confirm redirected only if the customer chooses a redirect-based payment method. To continue using the old behavior, you must pass redirect=‘if_required’ to confirm.

custom_checkout_beta_2

• Breaking The lineItem.recurring.interval_count field has been removed and replaced with lineItem.recurring.intervalCount.
• Breaking The lineItem.amount field has been removed and replaced with the following:
  • lineItem.amountSubtotal
  • lineItem.amountDiscount
  • lineItem.amountTaxInclusive
  • lineItem.amountTaxExclusive

custom_checkout_beta_1

This is the initial front-end beta version.

Back-end changelog

Specify the back-end beta version when setting up your server library.

There are no changes to the back-end beta version.