Elements com changelog beta da API Checkout Sessions

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

Copiar página

Aviso

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

Se você já estiver na versão do Basil do Elements com a API Checkout Sessions, este documento não se aplica a você.

Migração para o Basil

Alterações

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
- The change creates the subscription after the user has completed the payment, so checkout_session.invoice and checkout_session.subscription are null until the Checkout Session completes.
- If you currently rely on the deprecated payment_intent.invoice field, we recommend using the checkout_session.completed webhook, which ensures an invoice is present, and checkout_session.invoice or Invoice Payment list to find the associated invoice.
- Para saber mais, leia o log de alterações da API.
Adicionou percentOff a discountAmounts como opção para exibir descontos.

Upgrade

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 estiver carregando o Stripe.js usando a tag de script, atualize-o para usar o Stripe.js da versão substituindo-o da seguinte forma:

checkout.html
<head>
 <title>Checkout</title>
 <script src="https://js.stripe.com/v3"></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

Changelog beta

O Elements com a API Checkout Sessions beta usa dois tipos de versões beta:

Um cabeçalho Stripe.js beta (e.g., custom_checkout_beta_6), definido na sua integração de frontend.
Um cabeçalho beta da versão da API (por exemplo, custom_checkout_beta=v1), definido na sua integração de backend.

Versões beta do frontend

Especifique a versão beta do frontend 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.
  - Por exemplo, substitua total.total por 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.
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 Express Checkout Element, 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

Breaking O campo lineItem.recurring.interval_count foi removido e substituído por lineItem.recurring.intervalCount.
Breaking O campo lineItem.amount foi removido e substituído pelo seguinte:

custom_checkout_beta_1

Esta é a versão beta inicial do frontend.

Changelog do backend

Especifique a versão beta do backend quando configurar a biblioteca do servidor.

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