# Guia de migração do Checkout Saiba como migrar para as mais recentes integrações da Stripe. ![](https://b.stripecdn.com/docs-statics-srv/assets/migration.4db0b4061fb36d6a43762c3f23ef9c00.png) A versão antiga do Checkout mostrava aos clientes uma caixa de diálogo dinâmica para coletar dados de cartão, retornando um token ou fonte para seu site. Já o [Payment Links](https://docs.stripe.com/payment-links.md) e a versão atual do [Checkout](https://docs.stripe.com/payments/checkout.md) são páginas inteligentes hospedadas pela Stripe que criam pagamentos ou *assinaturas* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis). As duas integrações aceitam Apple Pay, Google Pay, *3D Secure* (3D Secure (3DS) provides an additional layer of authentication for credit card transactions that protects businesses from liability for fraudulent card payments) dinâmico, *Connect* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients), reutilização de *Clientes* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) e muitos outros recursos. Você também pode [comparar outras integrações de pagamento](https://docs.stripe.com/payments/online-payments.md#compare-features-and-availability) se o Payment Links ou o Checkout não se encaixarem no seu caso de uso. ## Before you begin Se você usa as [SDKs](https://docs.stripe.com/sdks.md) da Stripe, atualize para a versão mais recente. ## Escolha o modelo de negócio Para migrar da versão antiga do Checkout, siga o guia mais adequado ao seu modelo de negócio. Cada guia recomenda um caminho de integração, com exemplos de código. - [Catálogo de produtos e preços dinâmicos](https://docs.stripe.com/payments/checkout/migration.md#api-products) Se você tem um grande catálogo de produtos ou precisa de suporte para itens de linha gerados dinamicamente (como doações ou impostos). - [Assinaturas dinâmicas](https://docs.stripe.com/payments/checkout/migration.md#api-subscriptions) Se você fornece SaaS e precisa de recursos avançados para cobrar seus usuários. - [Plataformas e marketplaces do Connect](https://docs.stripe.com/payments/checkout/migration.md#connect) Se você opera um marketplace que conecta prestadores de serviços aos clientes. - [Salvar formas de pagamento para uso futuro](https://docs.stripe.com/payments/checkout/migration.md#setup-mode) 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](https://docs.stripe.com/payments/checkout/migration.md#simple-products) Se você vende poucos produtos, com preços predeterminados. - [Assinaturas simples](https://docs.stripe.com/payments/checkout/migration.md#simple-subscriptions) 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](https://docs.stripe.com/payments/checkout/migration.md#parameter-conversion) como referência para mapear parâmetros e opções de configuração específicas. ## Catálogo de produtos e preços dinâmicos Se o valor ou os 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](https://docs.stripe.com/payments/accept-a-payment.md?integration=checkout). Você pode ter usado a versão antiga do Checkout para criar um token ou fonte no cliente, transferindo-o para seu servidor para criar uma cobrança. A versão atual do Checkout inverte esse fluxo. Você cria a sessão no seu servidor e encaminha o cliente para o Checkout. Após o pagamento, ele é encaminhado de volta para o seu aplicativo. ### 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. ```html
``` Depois você enviava o token ou fonte gerado para o seu servidor e fazia a cobrança. #### curl ```bash curl https://api.stripe.com/v1/customers \ -u <>: \ -d "email"="customer@example.com" \ -d "source"="{{STRIPE_TOKEN}}" curl https://api.stripe.com/v1/charges \ -u <>: \ -d "customer"="{{CUSTOMER_ID}}" \ -d "description"="Custom t-shirt" \ -d "amount"="{{ORDER_AMOUNT}}" \ -d "currency"="usd" ``` ### Depois Adicione um botão de checkout ao site para chamar um endpoint do lado do servidor e criar uma [sessão do Checkout](https://docs.stripe.com/api/checkout/sessions/create.md). ```html Buy cool new product
``` A sessão do Checkout é a representação programática do que seu cliente vê ao ser redirecionado a um formulário de pagamento. Você pode configurá-la com opções como: - [Itens de linha](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items) a cobrar - Moedas a usar Inclua um `success_url` com o URL de uma página em seu site para a qual o cliente é redirecionado após concluir o pagamento. ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "line_items[0][price_data][currency]=usd" \ -d "line_items[0][price_data][product_data][name]=Custom t-shirt" \ -d "line_items[0][price_data][unit_amount]=2000" \ -d "line_items[0][quantity]=1" \ -d mode=payment \ --data-urlencode "success_url=https://example.com/success" ``` Depois de criar uma sessão do Checkout, redirecione o cliente ao [URL](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-url) retornado na resposta. Se precisar processar produtos comprados após o pagamento, consulte [Executar pagamentos no Checkout e em links de pagamento](https://docs.stripe.com/checkout/fulfillment.md). ## 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](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md). Você pode ter usado a versão antiga do Checkout para criar um token ou fonte no cliente, transferindo-o para seu servidor para criar um cliente e uma assinatura. A versão atual do Checkout inverte esse fluxo. Antes, você cria a sessão no seu servidor e encaminha o cliente para o Checkout. Após a conclusão bem-sucedida, ele é encaminhado de volta para o seu aplicativo. ### Antes Na versão antiga do Checkout, você mostrava os dados da assinatura e coletava os dados do cartão do cliente. ```html
``` Depois você enviava o token ou fonte gerado para o seu servidor a fim de criar o cliente e a assinatura. #### curl ```bash curl https://api.stripe.com/v1/customers \ -u <>: \ -d "email"="customer@example.com" \ -d "source"="{{STRIPE_TOKEN}}" curl https://api.stripe.com/v1/subscriptions \ -u <>: \ -d "customer"="{{CUSTOMER_ID}}" \ -d "items[0][price]"="{PRICE_ID}" \ -d "trial_period_days"=30 ``` ### Depois Adicione um botão de checkout ao site para chamar um endpoint do lado do servidor e criar uma [sessão do Checkout](https://docs.stripe.com/api/checkout/sessions/create.md). ```html Subscribe to cool new service
``` A sessão do Checkout é a representação programática do que seu cliente vê ao ser redirecionado a um formulário de pagamento. Você pode configurá-la com opções como: - [Itens de linha](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items) a cobrar - Moedas a usar Inclua um `success_url` com o URL de uma página em seu site para a qual o cliente é redirecionado após concluir o pagamento. ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "line_items[0][price]={{PRICE_ID}}" \ -d "line_items[0][quantity]=1" \ -d "subscription_data[trial_period_days]=30" \ -d mode=subscription \ --data-urlencode "success_url=https://example.com/success" ``` Depois de criar uma sessão do Checkout, redirecione o cliente ao [URL](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-url) retornado na resposta. O cliente é encaminhado ao `success_url` após a criação do cliente e da assinatura. Se precisar processar serviços comprados após o pagamento, consulte [Executar pagamentos no Checkout e em links de pagamento](https://docs.stripe.com/checkout/fulfillment.md). ## 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 do Checkout. O exemplo a seguir demonstra o uso da API Checkout Sessions para processar uma cobrança direta. Você também pode usar o Checkout e o Connect com [Destination Charges](https://docs.stripe.com/connect/destination-charges.md?platform=web&ui=stripe-hosted) e [cobranças e transferências separadas](https://docs.stripe.com/connect/separate-charges-and-transfers.md?platform=web&ui=stripe-hosted). ### Antes Com a versão antiga do Checkout, você coletava dados do cartão de seu cliente na instância do cliente. ```html
``` Depois você enviava o token ou fonte gerados para o seu servidor e fazia a cobrança em nome da conta conectada. #### curl ```bash curl https://api.stripe.com/v1/charges \ -u <>: \ -d "source"="{{TOKEN_ID}}" \ -d "description"="10 cucumbers from Roger\"s Farm" \ -d "amount"=2000 \ -d "currency"="usd" \ -d "application_fee_amount"=200 \ -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}" ``` ### Depois Adicione um botão de checkout ao site para chamar um endpoint do lado do servidor e criar uma [sessão do Checkout](https://docs.stripe.com/api/checkout/sessions/create.md). ```html Roger's Farm
``` A sessão do Checkout é a representação programática do que seu cliente vê ao ser redirecionado a um formulário de pagamento. Você pode configurá-la com opções como: - [Itens de linha](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items) a cobrar - Moedas a usar Inclua um `success_url` com o URL de uma página em seu site para a qual o cliente é redirecionado após concluir o pagamento. ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "line_items[0][price_data][currency]=usd" \ --data-urlencode "line_items[0][price_data][product_data][name]=Cucumbers from Roger's Farm" \ -d "line_items[0][price_data][unit_amount]=200" \ -d "line_items[0][quantity]=10" \ -d "payment_intent_data[application_fee_amount]=200" \ -d mode=payment \ --data-urlencode "success_url=https://example.com/success" ``` Depois de criar uma Sessão do Checkout, redirecione o cliente ao [URL](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-url) retornado na resposta. Se precisar processar produtos ou serviços comprados após o pagamento, consulte [Executar pagamentos no Checkout e em links de pagamento](https://docs.stripe.com/checkout/fulfillment.md). ## Salvar formas de pagamento para uso futuro Se você presta serviços que não cobram os clientes imediatamente, saiba como [configurar pagamentos futuros](https://docs.stripe.com/payments/save-and-reuse.md?platform=checkout). Você pode ter usado a versão antiga do Checkout para criar um token ou fonte no cliente, transferindo-o para seu servidor para salvá-lo para uso futuro. A versão atual do Checkout inverte esse fluxo. Antes, você cria a sessão no seu servidor e encaminha o cliente para o Checkout. Após a conclusão bem-sucedida, ele é encaminhado de volta para o seu aplicativo. ### Antes Na versão antiga do Checkout, você mostrava os dados da cobrança eram exibidos e coletava os dados do cartão. ```html
``` Em seguida, você enviava o token ou fonte gerado para o seu servidor para finalmente criar uma cobrança. #### curl ```bash curl https://api.stripe.com/v1/customers \ -u <>: \ -d "email"="customer@example.com" \ -d "source"="{{STRIPE_TOKEN}}" curl https://api.stripe.com/v1/charges \ -u <>: \ -d "customer"="{{CUSTOMER_ID}}" \ -d "description"="Cleaning service" \ -d "amount"="{{ORDER_AMOUNT}}" \ -d "currency"="usd" ``` ### Depois Adicione um botão de checkout ao site para chamar um endpoint do lado do servidor e criar uma [sessão do Checkout](https://docs.stripe.com/api/checkout/sessions/create.md). ```html Cleaning service
``` A sessão do Checkout é a representação programática do que seu cliente vê ao ser redirecionado a um formulário de pagamento. Você pode configurá-la com opções como: - [Itens de linha](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items) a cobrar - Moedas a usar Inclua um `success_url` com o URL de uma página em seu site para a qual o cliente é redirecionado após concluir a configuração de pagamento. ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d mode=setup \ -d currency=usd \ --data-urlencode "success_url=https://example.com/success?session_id={CHECKOUT_SESSION_ID}" ``` Depois de criar uma sessão do Checkout, redirecione o cliente ao [URL](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-url) retornado na resposta para receber os dados da forma de pagamento. O cliente é redirecionado para o `success_url` depois de concluir o fluxo. Quando estiver tudo pronto para receber um pagamento, [recupere o SetupIntent](https://docs.stripe.com/payments/checkout/save-and-reuse.md?payment-ui=stripe-hosted#retrieve-checkout-session) na sessão do Checkout e use-o para preparar a 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 [links de pagamento](https://docs.stripe.com/payment-links/create.md). Você pode ter usado a versão antiga do Checkout para criar um token ou fonte no cliente, transferindo-o para seu servidor para criar uma cobrança. ### Antes Na versão antiga do Checkout, você mostrava o valor e a descrição, e coletava os dados do cartão do cliente. ```html
``` Em seguida, você enviava o token ou fonte gerado para o seu servidor para criar um cliente e uma cobrança. #### curl ```bash curl https://api.stripe.com/v1/customers \ -u <>: \ -d "email"="{{STRIPE_EMAIL}}" \ -d "source"="{{STRIPE_TOKEN}}" curl https://api.stripe.com/v1/charges \ -u <>: \ -d "customer"="{{CUSTOMER_ID}}" \ -d "description"="T-shirt" \ -d "amount"=500 \ -d "currency"="usd" ``` ### Depois Crie um [Product](https://docs.stripe.com/api/products.md) e um [Price](https://docs.stripe.com/api/prices.md) para representar o item. O exemplo a seguir cria o Product em linha. Você também pode criar esses objetos no [Dashboard](https://dashboard.stripe.com/test/products). ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d currency=usd \ -d unit_amount=500 \ -d "product_data[name]=T-shirt" ``` Crie um [Payment Link](https://dashboard.stripe.com/payment-links/create) no Dashboard usando o Product e o Price. Após criar o link, clique no **botão “Comprar”** para configurar o design e gerar o código que você poderá copiar e colar no seu site. #### HTML ```html

Purchase your new kit

``` ## Assinaturas simples Se você oferece um serviço simples de assinaturas (como acesso mensal a um software), consulte o guia sobre [links de pagamento](https://docs.stripe.com/payment-links/create.md). Você pode ter usado a versão antiga do Checkout para criar um token ou fonte no cliente, transferindo-o para seu servidor para criar um cliente e uma assinatura. ### Antes Na versão antiga do Checkout, você mostrava os dados da assinatura e coletava os dados do cartão do cliente. ```html
``` Depois você enviava o token ou fonte gerado para o seu servidor a fim de criar o cliente e a assinatura. #### curl ```bash curl https://api.stripe.com/v1/customers \ -u <>: \ -d "email"="{{STRIPE_EMAIL}}" \ -d "source"="{{STRIPE_TOKEN}}" curl https://api.stripe.com/v1/subscriptions \ -u <>: \ -d "customer"="{{CUSTOMER_ID}}" \ -d "items[][price]"="{PRICE_ID}" \ -d "items[][quantity]"=1 ``` ### Depois Crie um [Product](https://docs.stripe.com/api/products.md) e um [Price](https://docs.stripe.com/api/prices.md) para representar a assinatura. O exemplo a seguir cria o Product em linha. Você também pode criar esses objetos no [Dashboard](https://dashboard.stripe.com/test/products). ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d currency=usd \ -d unit_amount=2000 \ -d "recurring[interval]=month" \ -d "product_data[name]=Gold Tier" ``` Crie um [Payment Link](https://dashboard.stripe.com/payment-links/create) no Dashboard usando o Product e o Price. Após criar o link, clique no **botão “Comprar”** para configurar o design e gerar o código que você poderá copiar e colar no seu site. #### HTML ```html

Purchase your new kit

``` ## Conversão de parâmetros A versão atual do Checkout aceita a maioria das funções da versão antiga do Checkout. No entanto, eles não compartilham a mesma API. A tabela a seguir mapeia os parâmetros e opções de configuração entre a versão antiga e a atual. Para obter uma lista completa das opções de configuração, consulte [Sessões do Checkout](https://docs.stripe.com/api/checkout/sessions.md). | Versão antiga | Versão atual | Dicas para integração | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `allowRememberMe` | Não aceita | Reutilize clientes existentes especificando o parâmetro `customer` quando criar uma [Checkout Session](https://docs.stripe.com/api/checkout/sessions/create.md). Você também pode habilitar o [Link](https://docs.stripe.com/payments/link/checkout-link.md) para que seus clientes possam salvar e reutilizar dados de pagamento com segurança. | | `amount` | Calculado automaticamente como a soma dos valores em todos os `line_items` | O valor total é a soma dos itens de linha enviados ao Checkout. | | `billingAddress` | `Session.billing_address_collection` | 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 o cliente decide encerrar o Checkout, ele fecha a aba do navegador. | | `currency` | `Session.currency` | | | `description` | `Session.line_items.description` ou `product.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` | `Session.customer_email` | Se você já sabe o e-mail do cliente, pode preenchê-lo com [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email) quando criar a Sessão do Checkout. | | `image` | **Marca do negócio**: carregue o logotipo ou ícone de sua empresa no Dashboard. **Imagens de produto**: especifique imagens para cada item de linha com `product.images`. | O Checkout usa imagens específicas para a [marca](https://docs.stripe.com/payments/checkout/customization/appearance.md#branding) 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` | Não é mais um parâmetro enviado para o Checkout | | | `locale` | `Session.locale` | É possível especificar um [local](https://docs.stripe.com/payments/checkout/custom-components.md#localization) compatível ao criar uma Checkout Session. | | `name` | `product.name` para preços especificados em `Session.line_items` | 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` | `submit_type` | O Checkout personaliza automaticamente o texto do botão, dependendo dos itens que serão vendidos. Para pagamentos únicos, use [submit_type](https://docs.stripe.com/payments/checkout/custom-components.md#submit-button) para personalizar o texto do botão. | | `shippingAddress` | `session.shipping_address_collection` | [Colete dados do endereço de entrega](https://docs.stripe.com/payments/collect-addresses.md?payment-ui=checkout) passando uma matriz de `allowed_countries` com os países onde você deseja fazer entregas. | | `token` ou `source` | `success_url` | 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 `success_url` para redirecionar o cliente após a conclusão do pagamento. | | `zipCode` | Coletado automaticamente pelo Checkout | O Checkout coleta automaticamente o código postal quando necessário para prevenção de fraudes ou obrigatório por lei. | ## See also - [Adicionar mais formas de pagamento](https://docs.stripe.com/payments/payment-methods/overview.md) - [Coletar endereços e números de telefone](https://docs.stripe.com/payments/collect-addresses.md)