Guia de migração do Checkout
A versão antiga do Checkout apresentava aos clientes um modal que coletava dados do cartão e retornava um token ou fonte para o seu site. Por outro lado, a versão atual do Checkout é uma página de pagamentos inteligente, hospedada pela Stripe, que cria pagamentos ou assinaturas. Ele é compatível com Apple Pay, 3D Secure dinâmico e vários outros recursos.
A versão atual do Checkout oferece mais flexibilidade, com suporte para itens de linha dinâmicos, Connect, reutilização de clientes e recursos avançados de assinatura. Você também pode usar a integração somente no cliente para começar a usar em menos tempo ou quando o seu catálogo de produtos é mais simples.
Para migrar da versão antiga para a atual, siga o guia mais adequado ao seu modelo de negócios. Cada guia recomenda um caminho de integração, com exemplos de código.
Catálogo de produtos e preços dinâmicos
Se você tem um grande catálogo de produtos ou precisa de suporte para itens de linha gerados dinamicamente (como doações ou impostos).
Se você fornece SaaS e precisa de recursos avançados para cobrar seus usuários.
Plataformas e marketplaces do Connect
Se você opera um marketplace que conecta prestadores de serviços aos clientes.
Salvar formas de pagamento para uso futuro
Se você opera uma empresa que só cobra o cliente depois de prestar os serviços.
Catálogo simples de produtos com preços fixos
Se você vende poucos produtos, com preços predeterminados.
Se você fornece SaaS com plano de assinatura mensal.
Enquanto segue o guia de migração adequado, você também pode usar a tabela de conversões como referência para mapear parâmetros e opções de configuração específicas entre as duas versões do Checkout.
Catálogo de produtos e preços dinâmicos
Se a quantidade ou valor dos itens de linha são definidos dinamicamente para seus produtos (com um grande catálogo de produtos ou no caso de doações, por exemplo), consulte receber pagamentos avulsos.
Você pode ter usado a versão antiga do Checkout para criar um token ou fonte para o cliente, transferindo-o para seu servidor para criar uma cobrança. A versão atual da integração de servidor do Checkout inverte esse fluxo. Você cria a sessão no seu servidor, passa o ID da sessão para o cliente, encaminha-o para o Checkout, e ele é reencaminhado para o seu aplicativo depois de finalizar o pagamento.
Antes
Na versão antiga do Checkout, você mostrava o valor dinâmico e a descrição, e coletava os dados do cartão do cliente.
<form action="/purchase" method="POST"> <script src="https://checkout.stripe.com/checkout.js" class="stripe-button" data-key=
data-name="Custom t-shirt" data-description="Your custom designed t-shirt" data-amount="{{ORDER_AMOUNT}}" data-currency="usd"> </script> </form>"pk_test_TYooMQauvdEDq54NiTphI7jx"
Depois você enviava o token ou fonte gerado para o seu servidor e fazia a cobrança.
Depois
Com a versão atual do Checkout, você cria primeiro uma sessão do Checkout no seu servidor.
Observação
Se você usa uma das nossas bibliotecas de clientes, atualize para a versão mais recente da biblioteca para usar a API Checkout Sessions.
Depois, você envia o ID da Sessão para seu cliente, redirecionando-o para o Checkout para finalizar o pagamento.
const stripe = Stripe(
); const checkoutButton = document.getElementById('checkout-button'); checkoutButton.addEventListener('click', () => { stripe.redirectToCheckout({ // Make the id field from the Checkout Session creation API response // available to this file, so you can provide it as argument here // instead of the {{CHECKOUT_SESSION_ID}} placeholder. sessionId: '{{CHECKOUT_SESSION_ID}}' }) // If `redirectToCheckout` fails due to a browser or network // error, display the localized error message to your customer // using `error.message`. });'pk_test_TYooMQauvdEDq54NiTphI7jx'
O cliente é redirecionado para success_url
depois de concluir o pagamento.
Se você precisa executar o pedido de mercadorias depois do pagamento, consulte Execução de compras no Checkout.
Assinaturas dinâmicas
Se você oferece serviços de assinatura que são determinados dinamicamente ou exigem suporte para outros recursos avançados, consulte como configurar uma assinatura.
Você pode ter usado a versão antiga do Checkout para criar um token ou fonte para o cliente, transferindo-o para seu servidor para criar o cliente e a assinatura. A versão atual da integração de servidor do Checkout inverte esse fluxo. Primeiro, você cria a sessão no seu servidor, passa o ID da sessão para o cliente, encaminha-o para o Checkout, e ele é reencaminhado para o seu aplicativo depois de finalizar o pagamento.
Antes
Na versão antiga do Checkout, você mostrava os dados da assinatura e coletava os dados do cartão do cliente.
<form action="/subscribe" method="POST"> <script src="https://checkout.stripe.com/checkout.js" class="stripe-button" data-key=
data-name="Gold Tier" data-description="Monthly subscription with 30 days trial" data-amount="2000" data-label="Subscribe"> </script> </form>"pk_test_TYooMQauvdEDq54NiTphI7jx"
Depois você enviava o token ou fonte gerado para o seu servidor a fim de criar o cliente e a assinatura.
Depois
Com a versão atual do Checkout, você cria primeiro uma sessão do Checkout no seu servidor.
Observação
Se você usa uma das nossas bibliotecas de clientes, atualize para a versão mais recente da biblioteca para usar a API Checkout Sessions.
Depois, você envia o ID da Sessão para seu cliente, redirecionando-o para o Checkout para finalizar o pagamento.
const stripe = Stripe(
); const checkoutButton = document.getElementById('checkout-button'); checkoutButton.addEventListener('click', () => { stripe.redirectToCheckout({ // Make the id field from the Checkout Session creation API response // available to this file, so you can provide it as argument here // instead of the {{CHECKOUT_SESSION_ID}} placeholder. sessionId: '{{CHECKOUT_SESSION_ID}}' }) // If `redirectToCheckout` fails due to a browser or network // error, display the localized error message to your customer // using `error.message`. });'pk_test_TYooMQauvdEDq54NiTphI7jx'
O cliente é redirecionado para success_url
depois da criação do cliente e da assinatura.
Se você precisa executar serviços depois do pagamento, consulte Execução de compras no Checkout.
Você também pode atualizar dados da assinatura pelo Checkout.
Conectar plataformas e marketplaces
Se você opera uma plataforma ou marketplace do Connect e cria pagamentos com contas conectadas, considere usar a versão atual de integração de servidor do Checkout. Siga as instruções do guia do Connect para migrar sua integração.
O exemplo a seguir demonstra o uso da API Checkout Sessions para processar uma cobrança direta. Siga o guia do Connect para saber como criar cobranças de destino.
Antes
Com a versão antiga do Checkout, você coletava dados do cartão de seu cliente na instância do cliente.
<form action="/purchase" method="POST"> <script src="https://checkout.stripe.com/checkout.js" class="stripe-button" data-key=
data-name="Food Marketplace" data-description="10 cucumbers from Roger's Farm" data-amount="2000"> </script> </form>"pk_test_TYooMQauvdEDq54NiTphI7jx"
Depois você enviava o token ou fonte gerados para o seu servidor e fazia a cobrança em nome da conta conectada.
Depois
Com a versão atual do Checkout, você cria primeiro uma sessão do Checkout no seu servidor em nome da conta conectada.
Observação
Se você usa uma das nossas bibliotecas de clientes, atualize para a versão mais recente da biblioteca para usar a API Checkout Sessions.
Depois, você envia o ID da Sessão para seu cliente, redirecionando-o para o Checkout para finalizar o pagamento. Não se esqueça de fornecer o ID da conta conectada ao inicializar Stripe.js.
// Initialize Stripe.js with the same connected account ID used when creating // the Checkout Session. const stripe = Stripe(
, { stripeAccount:'pk_test_TYooMQauvdEDq54NiTphI7jx'}); const checkoutButton = document.getElementById('checkout-button'); checkoutButton.addEventListener('click', () => { stripe.redirectToCheckout({ // Make the id field from the Checkout Session creation API response // available to this file, so you can provide it as argument here // instead of the {{CHECKOUT_SESSION_ID}} placeholder. sessionId: '{{CHECKOUT_SESSION_ID}}' }) // If `redirectToCheckout` fails due to a browser or network // error, display the localized error message to your customer // using `error.message`. });'{{CONNECTED_ACCOUNT_ID}}'
O cliente é redirecionado para success_url
depois de concluir o pagamento.
Se você precisa executar o pedido de mercadorias ou serviços depois do pagamento, consulte Execução de compras no Checkout.
Salvar formas de pagamento para uso futuro
Se você presta serviços que não cobram os clientes imediatamente, saiba como configurar pagamentos futuros.
Você pode ter usado a versão antiga do Checkout para criar um token ou fonte para o cliente, transferindo-o para seu servidor para uso posterior. A versão atual da integração de servidor do Checkout inverte esse fluxo. Primeiro, você cria a sessão no seu servidor, passa o ID da sessão para o cliente, encaminha-o para o Checkout, e ele é reencaminhado para o seu aplicativo depois de finalizar o pagamento.
Antes
Na versão antiga do Checkout, você mostrava os dados da cobrança eram exibidos e coletava os dados do cartão.
<form action="/subscribe" method="POST"> <script src="https://checkout.stripe.com/checkout.js" class="stripe-button" data-key=
data-name="Cleaning Service" data-description="Charged after your home is spotless" data-amount="2000"> </script> </form>"pk_test_TYooMQauvdEDq54NiTphI7jx"
Depois, você enviava o token ou fonte gerados para o seu servidor para finalmente criar uma cobrança.
Depois
Com a versão atual do Checkout, você cria primeiro uma sessão do Checkout no seu servidor usando o modo de configuração.
Observação
Se você usa uma das nossas bibliotecas de clientes, atualize para a versão mais recente da biblioteca para usar a API Checkout Sessions.
Em seguida, envie o ID da Sessão para seu cliente e reencaminhe-o para o Checkout para receber os dados da forma de pagamento.
const stripe = Stripe(
); const checkoutButton = document.getElementById('checkout-button'); checkoutButton.addEventListener('click', () => { stripe.redirectToCheckout({ // Make the id field from the Checkout Session creation API response // available to this file, so you can provide it as argument here // instead of the {{CHECKOUT_SESSION_ID}} placeholder. sessionId: '{{CHECKOUT_SESSION_ID}}' }) // If `redirectToCheckout` fails due to a browser or network // error, display the localized error message to your customer // using `error.message`. });'pk_test_TYooMQauvdEDq54NiTphI7jx'
O cliente é redirecionado para success_url
depois de concluir o fluxo.
Lá é possível acessar o Setup Intent pelo fluxo do Checkout e usá-lo para preparar sua transação.
Catálogo simples de produtos com preços fixos
Se você vende produtos com preços fixos (como camisetas ou e-books), consulte o guia sobre pagamentos avulsos para saber como gerar um trecho de código para inserir em seu site.
Você pode ter usado a versão antiga do Checkout para criar um token ou fonte para o cliente, transferindo-o para seu servidor para criar a cobrança. A versão atual da integração de servidor do Checkout cria o pagamento automaticamente para você, sem necessidade de integração de servidor.
Código do lado do cliente
Código do lado do servidor
A tabela de conversão abaixo mapeia as opções de configuração entre as duas versões do Checkout. Veja uma lista completa de opções de configuração da versão atual na referência redirectToCheckout
.
Assinaturas simples
Se você oferece um serviço de assinaturas simples (como uma mensalidade para acessar um software), consulte o guia sobre assinaturas para saber como criar um plano no Dashboard e gerar um trecho de código para acrescentar ao seu site.
Você pode ter usado a versão antiga do Checkout para criar um token ou fonte para o cliente, transferindo-o para seu servidor para criar o cliente e a assinatura. A versão atual da integração de servidor do Checkout cria o cliente e a assinatura automaticamente para você, sem necessidade de integração de servidor.
Código do lado do cliente
Código do lado do servidor
A tabela de conversão abaixo mapeia as opções de configuração entre as duas versões do Checkout. Veja uma lista completa de opções de configuração da versão atual na referência redirectToCheckout
.
Conversão de parâmetros
A versão atual do Checkout é compatível com a maioria das funções da versão antiga, mas elas não compartilham a mesma API. A tabela abaixo indica as opções de configuração e parâmetros entre a versão antiga e a atual.
Veja uma lista completa de opções de configuração aceitas pela versão atual do Checkout na referência para Stripe.js e na referência da API para sessões do Checkout.
Versão antiga | Versão atual | Dicas para integração |
---|---|---|
allowRememberMe |
| A versão atual do Checkout não tem a função “Lembrar”. Para reutilizar clientes existentes, recomendamos especificar o parâmetro customer ao criar uma sessão do Checkout. |
amount |
| O valor total é a soma dos itens de linha enviados ao Checkout. |
billingAddress |
| O Checkout coleta automaticamente o endereço de cobrança quando necessário para prevenção de fraudes ou regulamentação. Defina este parâmetro como required para sempre coletar o endereço de cobrança. |
billingAddress |
| O Checkout coleta automaticamente o endereço de cobrança quando necessário para prevenção de fraudes ou regulamentação. Defina este parâmetro como required para sempre coletar o endereço de cobrança. |
closed |
| Quando um cliente quer fechar o Checkout, ele pode fechar a guia do navegador ou acessar cancelUrl . |
currency |
| |
description |
| Se você especificar um preço, o Checkout exibe uma descrição calculada automaticamente da frequência de ocorrência dos pagamentos. Se você especificar Session.line_items , o Checkout exibe o name de cada item de linha. |
email |
| Se você já tem o e-mail do cliente, insira-o aqui para que o cliente não precise informá-lo novamente. |
image |
| O Checkout usa imagens específicas para a marca da sua empresa e para os produtos à venda. O Checkout exibe o logotipo da empresa por padrão e recorre ao ícone da empresa com o nome da empresa. |
key |
| |
locale |
| Você pode especificar uma localização aceita ao criar uma Sessão do Checkout. |
name |
| Se você especificar um preço, o Checkout mostrará o nome do produto ao preço e ao cliente. Se você especificar Session.line_items , o Checkout mostrará o name de cada item de linha. |
panelLabel |
| O Checkout personaliza o texto do botão automaticamente, dependendo dos itens à venda. Para pagamentos avulsos, use submit_type para personalizar o texto do botão. |
shippingAddress |
| Colete dados do endereço de entrega passando uma matriz de allowed_countries com os países onde você deseja fazer entregas. |
token ou source |
| Não há mais um retorno de chamada em JavaScript quando o pagamento é concluído. Como o cliente está pagando em outra página, configure a successUrl para reencaminhar o cliente depois de concluir o pagamento. |
zipCode |
| O Checkout coleta automaticamente o código postal quando necessário para prevenção de fraudes ou obrigatório por lei. |