Pular para o conteúdo
Criar conta ou Entrar
O logotipo da documentação da Stripe
/
Criar contaLogin
Visão geralAceitar um pagamentoAtualize sua integração
Pagamentos online
Visão geralEncontre seu caso de usoUsar o Managed PaymentsPagamentos recorrentes
Pagamentos presenciais
Formas de pagamento
Operações de pagamento
Saldos e tempo de liquidaçãoRecibosReembolsos e cancelamentos
Integrações avançadas
Muito mais que pagamentos

Elements com changelog beta da API Checkout Sessions

Acompanhe as alterações do Elements com a integração beta da API Checkout Sessions.

Aviso

Este documento contém changelogs relacionados às versões beta do Elements com API Checkout Sessions.

Se você já está na versão Clover do Elements com a API Checkout Sessions, esse changelog não se aplica a você.

Como migrar para Clover

Alterações do Clover

  • Breaking Agora, o método stripe.initCheckout é 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 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 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 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.
    • useCheckout now returns a disjoint union describing the asynchronous state ({type: 'loading'}, {type: 'success', checkout: ...}, or {type: 'error', error: ...}) instead of throwing an error.
    • CheckoutProvider now renders children unconditionally instead of rendering null when initCheckout hasn’t succeeded.

Atualização Clover

Antes de migrar para Clover, primeiro atualize sua integração 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 da seguinte forma:
checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>
  • Atualize a versão da API para no mínimo 2025-09-30.clover na sua integração de back-end.

Atualize sua integração da seguinte forma:

  1. Remova qualquer chamada await ou.then() associada ao initCheckout.
  2. Substitua a função fetchClientSecret por uma string de client secret ou uma Promise que se resolve em uma string de client secret.”
  3. 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.
  4. Se você anteriormente envolveu initCheckout em um bloco ttry...catch, analise o valor type resolvido de loadActions() em vez disso para verificar erros.
checkout.js
const clientSecret = fetch("/create-checkout-session", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
})
  .then((r) => r.json())
  .then((r) => r.clientSecret);

const checkout = await stripe.initCheckout({
  fetchClientSecret: () => clientSecret
});
const checkout = stripe.initCheckout({
  clientSecret
});
const paymentElement = checkout.createPaymentElement();
paymentElement.mount("#payment-element");

const session = checkout.session();
const loadActionsResult = await checkout.loadActions();
if (loadActionsResult.type === 'success') {
  const session = loadActionsResult.actions.getSession();
}

Para mais detalhes, confira a entrada do registro de alterações Updates initCheckout to be synchronous.

Migração para o Basil

Alterações no Basil

  • Breaking Métodos assíncronos, como confirm ou applyPromotionCode, 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 em confirmar quando 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 em confirmar ou 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 para encontrar a fatura associada.
    • Para saber mais, leia o changelog da API 2025-03-31.basil.
  • Adicionou percentOff a discountAmounts como opção para exibir descontos.

Atualização Basil

Antes de migrar para o Basil, atualize sua integração 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 da seguinte maneira:
checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/v3/stripe.js"></script>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>
  • Remova o cabeçalho beta Stripe.js ao inicializar o Stripe.js.
checkout.js
const stripe = Stripe(
  
'pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  betas: ['custom_checkout_beta_6'],
  }
);
  • 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.
Antes
Depois
TypeScript
Node.js
Ruby
PHP
Python
Go
.NET
Java
No results
// 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';
const stripe = new Stripe(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
, {
  apiVersion: '2025-12-15.clover; custom_checkout_beta=v1' as any,
});
TypeScript
Node.js
Ruby
PHP
Python
Go
.NET
Java
No results
// 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';
const stripe = new Stripe(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
, {
  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.

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 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. 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 agora responde a qualquer Billing Address Element ou Shipping Address Element montado.
    • canConfirm agora se torna false se houver uma confirmação em andamento.
    • confirmationRequirements removido.
  • Breaking e-mail de atualização agora gera um erro se 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 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.
    • 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.
  • Os IDs fiscais dos clientes já podem ser coletados. Saiba como coletar IDs fiscais.
  • 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
    • Dentro do React Stripe.js, CustomCheckoutProvider foi renomeado para CheckoutProvider useCustomCheckout useCheckout.
  • Breaking Para confirmar o Element do Checkout Express, chame confirm, passando o evento confirm como expressCheckoutConfirmEvent.
    • Anteriormente, o Express Checkout Element era confirmado chamando event.confirm().
  • Breaking Quando 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 erros na própria integração, como parâmetros ou configuração inválidos. Esses erros não devem ser exibidos aos clientes.
  • Breaking Métodos assíncronos, como confirm ou applyPromotionCode, 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.
  • O Breaking Address Element não atualiza mais automaticamente os campos billingAddress ou shippingAddress na sessão.
    • Desde que o Address Element esteja montado, os valores de formulário serão usados automaticamente ao chamar confirm
    • Escute o evento change para usar o valor do Address Element antes da confirmação.

custom_checkout_beta_4

  • Imagens adicionadas ao objeto Session.
  • Adicionou campos como opção ao criar o Payment Element.
  • Adicionou paymentMethods como opção ao criar o Express Checkout Element.
  • Breaking Passar opções inválidas para createElement agora gera um erro. Anteriormente, opções não reconhecidas eram ignoradas silenciosamente.
  • Breaking updateEmail e updatePhoneNumber 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:
  • Cartões salvos agora podem ser reutilizados. Saiba como salvar e reutilizar formas de pagamento.
  • Breaking O 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 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’ para confirm.

custom_checkout_beta_2

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.

Não há alterações na versão beta do backend.