# Elements com changelog beta da API Checkout Sessions
Acompanhe as alterações do Elements com a integração beta da API Checkout Sessions.
> Este documento contém changelogs relacionados às versões beta do Elements com API Checkout Sessions.
>
> Este changelog não se aplica se você estiver usando o [Clover](https://docs.stripe.com/changelog/clover.md) ou posterior. Consulte o [changelog da Stripe](https://docs.stripe.com/changelog.md).
## Como migrar para Clover
### Alterações do Clover
- (Breaking) Agora, o método [stripe.initCheckout](https://docs.stripe.com/js/custom_checkout/init) é síncrono em vez de assíncrono. Isso reduz a latência de renderização e permite que o Elements exiba os placeholders de carregamento mais cedo. Confira [Updates initCheckout to be synchronous](https://docs.stripe.com/changelog/clover/2025-09-30/update-init-checkout-synchronous.md) para detalhes sobre migração.
- (Breaking) As formas de pagamento salvas agora são ativadas automaticamente no Payment Element quando configuradas na sessão do checkout, sem necessidade de configuração adicional pelo cliente. Confira [Atualiza o comportamento padrão para formas de pagamento salvas](https://docs.stripe.com/changelog/clover/2025-09-30/custom-checkout-saved-payment-method-defaults.md) para detalhes.
- (Breaking) Os códigos postais não são mais coletados automaticamente para pagamento com cartão no Canadá, Reino Unido e Porto Rico. Confira [Remover o código postar para pagamento com cartão](https://docs.stripe.com/changelog/clover/2025-09-30/postal_code_in_card_form_for_non_us_countries.md) se você confiar nesses dados.
- (Breaking) Para integrações do React::
- Os caminhos de importação mudaram de `@stripe/react-stripe-js` para `@stripe/react-stripe-js/checkout`.
- O [useCheckout](https://docs.stripe.com/js/react_stripe_js/checkout/use_checkout) agora retorna uma união disjunta descrevendo o estado assíncrono(`{type: 'loading'}`, `{type: 'success', checkout: ...}`, ou `{type: 'error', error: ...}`) em vez de lançar um erro.
- O [CheckoutProvider](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider) agora renderiza os elementos filhos incondicionalmente, em vez de renderizar `null` quando o [initCheckout](https://docs.stripe.com/js/custom_checkout/init) não foi bem-sucedido.
### Atualização Clover
Antes de migrar para Clover, primeiro [atualize sua integração](https://docs.stripe.com/checkout/elements-with-checkout-sessions-api/changelog.md#migrating-to-basil) para Basil.
- Se você estiver usando algum pacote Stripe NPM, deve atualizar `@stripe/stripe-js` para pelo menos `8.0.0` e `@stripe/react-stripe-js` para pelo menos `5.0.0`.
- Se você estiver carregando Stripe.js pela tag script, atualize a tag para fazer referência a `clover` usando a [versioned Stripe.js nomenclature](https://docs.stripe.com/sdks/stripejs-versioning.md) da seguinte forma:
```html
Checkout
```
- Atualize a versão da API para no mínimo `2025-09-30.clover` na sua integração de back-end.
#### HTML + JS
Atualize sua integração da seguinte forma:
1. Remova qualquer chamada `await` ou`.then()` associada ao `initCheckout`.
1. Substitua a função `fetchClientSecret` por uma string de client secret ou uma Promise que se resolve em uma string de client secret.”
1. Chame a nova função assíncrona `checkout.loadActions()` para acessar ações como `getSession()`, que substitui `session()`, ou `confirm()`. Só é necessário chamar `loadActions()` uma vez.
1. Se você anteriormente envolveu `initCheckout` em um bloco `ttry...catch`, analise o valor `type` resolvido de `loadActions()` em vez disso para verificar erros.
```javascript
const clientSecret = fetch("/create-checkout-session", {
method: "POST",
headers: { "Content-Type": "application/json" },
})
.then((r) => r.json())
.then((r) => r.clientSecret);
const checkout = stripe.initCheckout({
clientSecret
});
const paymentElement = checkout.createPaymentElement();
paymentElement.mount("#payment-element");
const loadActionsResult = await checkout.loadActions();
if (loadActionsResult.type === 'success') {
const session = loadActionsResult.actions.getSession();
}
```
#### React
Atualize a dependência `@stripe/react-stripe-js` no mínimo para a versão`5.0.0`. Se você atualizar de uma versão anterior à `4.0.0`, certifique-se de ler as [notas de versão v4.0.0](https://github.com/stripe/react-stripe-js/releases/tag/v4.0.0) para saber quais são as etapas extras de migração.
#### Mudanças nas importações
Atualize suas importações para usar o novo ponto de entrada específico para o checkout:
```jsx
import {useCheckout, PaymentElement} from '@stripe/react-stripe-js/checkout';
```
#### Alterações em CheckoutProvider e useCheckout
Substitua `fetchClientSecret` por `clientSecret`. Agora você pode renderizar Elements sem antes verificar se `useCheckout` retornou `type: 'success'`, o que reduz a latência e permite que o Elements exiba os placeholders de carregamento mais cedo.
```jsx
const App = () => {
const promise = useMemo(() => {
return fetch('/create-checkout-session', {
method: 'POST',
headers: { "Content-Type": "application/json" },
})
.then((res) => res.json())
.then((data) => data.clientSecret);
}, []);
return (
);
}
const CheckoutPage = () => {
const {type, ...rest} = useCheckout();
return (
);
}
```
Para mais detalhes, confira a entrada do registro de alterações [Updates initCheckout to be synchronous](https://docs.stripe.com/changelog/clover/2025-09-30/update-init-checkout-synchronous.md).
## Migração para o Basil
### Alterações no Basil
- (Breaking) Métodos assíncronos, como [confirm](https://docs.stripe.com/js/custom_checkout/confirm) ou [applyPromotionCode](https://docs.stripe.com/js/custom_checkout/apply_promotion_code), são resolvidos com um esquema diferente:
- Se bem-sucedido, o estado da sessão atualizada será preenchido sob a chave `session`. Antes, isso estava sob a chave `success`.
- (Breaking) Um erro é lançado ao passar em [returnUrl](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-returnUrl) em [confirmar](https://docs.stripe.com/js/custom_checkout/confirm) quando [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-return_url) já foi definido na sessão do Checkout.
- (Breaking) O URL de retorno para o qual foi redirecionado após uma confirmação bem-sucedida tinha parâmetros de consulta inconsistentes. Os parâmetros extras foram removidos e o URL só contém o que é informado em [returnUrl](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-returnUrl) em [confirmar](https://docs.stripe.com/js/custom_checkout/confirm) ou [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-return_url) na sessão do Checkout.
- (Breaking) Melhora a latência na API Checkout Sessions para sessões no modo de assinatura e corrige um erro que impedia seus clientes de atualizar uma sessão após a primeira tentativa de pagamento
- A alteração cria a assinatura depois que o usuário conclui o pagamento, de modo que `checkout_session.invoice` e `checkout_session.subscription` ficam nulos até a conclusão da sessão do Checkout.
- Se você usa o campo `payment_intent.invoice` obsoleto, recomendamos usar o webhook `checkout_session.completed`, que garante a presença da fatura, e `checkout_session.invoice` ou a [lista Invoice Payment](https://docs.stripe.com/api/invoice-payment/list.md) para encontrar a fatura associada.
- Para saber mais, leia o [changelog da API 2025-03-31.basil](https://docs.stripe.com/changelog/basil/2025-03-31/checkout-legacy-subscription-upgrade.md).
- Adicionou [percentOff](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-discountAmounts-percentOff) a [discountAmounts](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-discountAmounts) como opção para exibir descontos.
### Atualização Basil
Antes de migrar para o Basil, [atualize sua integração](https://docs.stripe.com/checkout/elements-with-checkout-sessions-api/changelog.md#beta-changelog) para `custom_checkout_beta_6`.
- Se estiver usando qualquer pacote Stripe NPM, primeiro você deve atualizar `@stripe/stripe-js` para pelo menos `7.0.0` e `@stripe/react-stripe-js` para pelo menos `3.6.0`.
- Se você estiver carregando o Stripe.js por meio da tag script e ainda estiver usando `v3` ou `acacia`, atualize a tag para fazer referência a `basil` usando a [nomenclatura Stripe.js versionada](https://docs.stripe.com/sdks/stripejs-versioning.md) da seguinte maneira:
```html
Checkout
```
- Remova o cabeçalho beta Stripe.js ao inicializar o Stripe.js.
#### HTML + JS
```js
const stripe = Stripe(
'<>', {
}
);
```
#### React
```javascript
import {loadStripe} from '@stripe/stripe-js';
const stripe = loadStripe("<>", {
});
```
- Remova o cabeçalho beta da versão API e especifique a versão API com pelo menos `2025-03-31.basil` na sua integração do backend.
### Before
#### TypeScript
```javascript
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
import Stripe from 'stripe';
// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
const stripe = new Stripe('<>', {
apiVersion: '2026-04-22.dahlia; custom_checkout_beta=v1' as any,
});
```
### After
#### TypeScript
```javascript
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
import Stripe from 'stripe';
// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
const stripe = new Stripe('<>', {
apiVersion: '2025-03-31.basil' as any,
});
```
## Changelog beta
O Elements com a API Checkout Sessions beta usa dois tipos de versões beta:
- Um cabeçalho Stripe.js Beta (por exemplo,`custom_checkout_Beta_6`), que é definido na sua integração frontend.
- Um cabeçalho Beta da versão da API (por exemplo,`custom_checkout_Beta=v1`), que está configurado na sua integração backend.
### Versões beta do frontend
Especifique a versão Beta do front-end ao [inicializar o Stripe.js](https://docs.stripe.com/payments/quickstart-checkout-sessions.md).
#### custom_checkout_beta_6
Se estiver usando qualquer pacote NPM da Stripe, primeiro você deve atualizar `@stripe/stripe-js` para pelo menos `6.1.0` e `@stripe/react-stripe-js` para pelo menos `3.5.0`.
- (Breaking) O sinal de [total.appliedBalance](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-total-appliedBalance) foi invertido. Um número positivo agora aumenta o valor a ser pago, e um número negativo diminui o valor a ser pago.
- (Breaking) Substituiu `clientSecret` por [fetchClientSecret](https://docs.stripe.com/js/custom_checkout/init#custom_checkout_init-options-clientSecret). Atualize sua integração para passar uma função assíncrona resolvendo para o segredo do cliente em vez de passar um valor estático.
- (Breaking) Os métodos do Elements foram renomeados.
- Se você estiver usando o Stripe.js do React, não é preciso fazer nada além de atualizar `@stripe/react-stripe-js`.
- Se estiver usando HTML/JS:
- Use `createPaymentElement()` em vez de `createElement('payment')`.
- Use `createBillingAddressElement()` em vez de `createElement('address', {mode: 'billing'})`.
- Use `createShippingAddressElement()` em vez de `createElement('address', {mode: 'shipping'})`.
- Use `createExpressCheckoutElement()` em vez de `createElement('expressCheckout')`.
- Use `getPaymentElement()` em vez de `getElement('payment')`.
- Use `getBillingAddressElement()` em vez de `getElement('address', {mode: 'billing'})`.
- Use `getShippingAddressElement()` em vez de `getElement('address', {mode: 'shipping'})`.
- Use `getExpressCheckoutElement()` em vez de `getElement('expressCheckout')`.
- (Breaking) Campos atualizados relacionados à confirmação para refletir com mais precisão o estado da sessão.
- [canConfirm](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-canConfirm) agora responde a qualquer Billing Address Element ou Shipping Address Element montado.
- [canConfirm](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-canConfirm) agora se torna `false` se houver uma confirmação em andamento.
- `confirmationRequirements` removido.
- (Breaking) [e-mail de atualização](https://docs.stripe.com/js/custom_checkout/update_email) agora gera um erro se [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email) tiver sido informado ao criar a sessão do Checkout. Se você pretende preencher antecipadamente um e-mail que seu cliente pode atualizar, chame `updateEmail` assim que a página carregar, em vez de passar `customer_email`.
- (Breaking) [returnUrl](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-returnUrl) deve ser um URL absoluto (por exemplo, começa com `https://` em vez de um URL relativo, como `/success`).
- (Breaking) Campos de preços atualizados para um objeto aninhado para facilitar a renderização.
- Valores numéricos substituídos por um objeto contendo `amount` (uma cadeia de caracteres formatada, como `$10.00`) e `minorUnitsAmount`, um número inteiro que representa o valor na menor unidade da moeda. Se você já está lendo o valor, leia em `minorUnitsAmount`.
- Por exemplo, substitua `total.total` por [`total.total.minorUnitsAmount`](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-total-total-minorUnitsAmount).
- Você deve ler `total.total.amount` ou cada um de `total.total.minorUnitsAmount`, `currency` e `minorUnitsAmountDivisor` no objeto `checkout` e exibir na sua IU. Caso contrário, um erro será gerado. Isso ajuda a manter sua página de checkout sincronizada enquanto a CheckoutSession é atualizada, incluindo a adição de recursos futuros da Stripe, com alterações mínimas no código da IU.
- Agora é possível recolher IDs de imposto de clientes. Saiba mais como [recolher IDs de imposto](https://docs.stripe.com/tax/checkout/tax-ids.md).
- Um assistente apenas em modo de teste está disponível na parte inferior da página de checkout, oferecendo orientações para sua integração e atalhos para cenários de teste comuns.
#### custom_checkout_beta_5
- (Breaking) A função `initCustomCheckout` foi renomeada para [initCheckout](https://docs.stripe.com/js/custom_checkout/init)
- Dentro do React Stripe.js, `CustomCheckoutProvider` foi renomeado para `CheckoutProvider` `useCustomCheckout` `useCheckout`.
- (Breaking) Para confirmar o Element do Checkout Express, chame [confirm](https://docs.stripe.com/js/custom_checkout/confirm), passando o evento [confirm](https://docs.stripe.com/js/elements_object/express_checkout_element_confirm_event) como `expressCheckoutConfirmEvent`.
- Anteriormente, o Express Checkout Element era confirmado chamando `event.confirm()`.
- (Breaking) Quando [confirm](https://docs.stripe.com/js/custom_checkout/confirm) é chamada, o Payment Element e o Address Element validam as entradas de formulário e processam os erros.
- (Breaking) As mensagens de erro foram padronizadas e aprimoradas.
- Os erros retornados/resolvidos por uma função representam cenários conhecidos, como dados de pagamento inválidos ou fundos insuficientes. Esses são problemas previsíveis, que podem ser comunicados ao cliente exibindo a `message` na página de checkout.
- Erros lançados/rejeitados por uma função representam falhas na própria integração, como parâmetros inválidos ou problemas de configuração. Esses erros não devem ser exibidos aos seus clientes.
- (Breaking) Métodos assíncronos, como [confirm](https://docs.stripe.com/js/custom_checkout/confirm) ou [applyPromotionCode](https://docs.stripe.com/js/custom_checkout/apply_promotion_code), são resolvidos com um esquema diferente:
- Um campo discriminador `type="success"|"error"` foi adicionado.
- Se for bem-sucedido, o estado da sessão atualizada será preenchido sob a chave `success`. Anteriormente, isso estava sob a chave `session`.
- Caso contrário, o erro continuará a ser preenchido sob a chave `error`.
- Adicionadas as opções `email`, `phoneNumber`, `billingAddress` e `shippingAddress` para [confirma](https://docs.stripe.com/js/custom_checkout/confirm).
- O (Breaking) Address Element não atualiza mais automaticamente os campos [billingAddress](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-billingAddress) ou [shippingAddress](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-shippingAddress) na sessão.
- Desde que o Address Element esteja montado, os valores de formulário serão usados automaticamente ao chamar [confirm](https://docs.stripe.com/js/custom_checkout/confirm)
- Escute o [evento change](https://docs.stripe.com/js/element/events/on_change?type=addressElement) para usar o valor do Address Element antes da confirmação.
#### custom_checkout_beta_4
- [Imagens](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-images) adicionadas ao [objeto Session](https://docs.stripe.com/js/custom_checkout/session_object).
- Adicionou [campos](https://docs.stripe.com/js/custom_checkout/create_payment_element#custom_checkout_create_payment_element-options-fields) como opção ao criar o Payment Element.
- Adicionou [paymentMethods](https://docs.stripe.com/js/custom_checkout/create_express_checkout_element#custom_checkout_create_express_checkout_element-options-paymentMethods) como opção ao criar o Express Checkout Element.
- (Breaking) Passar opções inválidas para [createElement](https://docs.stripe.com/js/custom_checkout/create_payment_element) agora gera um erro. Anteriormente, opções não reconhecidas eram ignoradas silenciosamente.
- (Breaking) [updateEmail](https://docs.stripe.com/js/custom_checkout/update_email) e [updatePhoneNumber](https://docs.stripe.com/js/custom_checkout/update_phone_number) aplicam alterações de forma assíncrona. Chamar esses métodos antes que o cliente termine de inserir valores completos pode causar baixo desempenho.
- Em vez de chamar `updateEmail` ou `updatePhoneNumber` no evento de alteração de cada entrada, aguarde até que o cliente conclua a entrada, como no desfoque da entrada ou quando envia o formulário para pagamento.
- `updateEmail` agora, valida se a entrada é um endereço de e-mail formado corretamente e retorna um erro se uma entrada inválida for usada.
- `updatePhoneNumber` ainda não executa nenhuma validação na cadeia de caracteres de entrada.
#### custom_checkout_beta_3
- Os seguintes campos foram adicionados ao [objeto Session](https://docs.stripe.com/js/custom_checkout/session_object):
- [id](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-id)
- [livemode](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-livemode)
- [businessName](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-businessName)
- Cartões salvos agora podem ser reutilizados. Saiba como [salvar e reutilizar](https://docs.stripe.com/payments/checkout/save-during-payment.md) formas de pagamento.
- (Breaking) O [layout](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout) padrão do Payment Element foi alterado para `accordion`.
- Para continuar usando o layout padrão anterior, você deve especificar `layout='tabs'` explicitamente.
- (Breaking) O comportamento padrão de [confirm](https://docs.stripe.com/js/custom_checkout/confirm) foi alterado para sempre redirecionar para o após `return_url` uma confirmação bem-sucedida.
- Anteriormente, `confirm` era redirecionado somente se o cliente escolhesse uma forma de pagamento baseada em redirecionamento. Para continuar usando o comportamento antigo, passe [redirect=‘if_required’](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-redirect) para `confirm`.
#### custom_checkout_beta_2
- (Breaking) O campo `lineItem.recurring.interval_count` foi removido e substituído por [lineItem.recurring.intervalCount](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-recurring-intervalCount).
- (Breaking) O campo `lineItem.amount` foi removido e substituído pelo seguinte:
- [lineItem.amountSubtotal](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountSubtotal)
- [lineItem.amountDiscount](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountDiscount)
- [lineItem.amountTaxInclusive](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountTaxInclusive)
- [lineItem.amountTaxExclusive](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountTaxExclusive)
#### custom_checkout_beta_1
*Esta é a versão beta inicial do frontend.*
### Versões de backend
Especifique a versão Beta do back-end ao [configurar a biblioteca do servidor](https://docs.stripe.com/payments/quickstart-checkout-sessions.md#init-stripe).
*Não há alterações na versão beta do backend.*