# Guia de migração de preços para o Checkout Saiba como atualizar sua integração para usar preços no Stripe Checkout. A integração com a [API Prices](https://docs.stripe.com/api/prices.md) inclui: - Modelagem unificada para itens do Checkout: em vez de planos, *SKUs* (SKUs (Stock Keeping Units) represent a specific Product variation, taking into account any combination of attributes and cost (for instance, size, color, currency, cost)) e itens de linha inline, cada item é um *preço*. - Capacidade de renderizar imagens de produtos em itens recorrentes. - A capacidade de criar um catálogo reutilizável de produtos e preços, em vez de itens de linha de uso único. - A capacidade de criar preços inline para *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). - Alíquotas de imposto dinâmicas para [assinaturas](https://docs.stripe.com/billing/taxes/collect-taxes.md?tax-calculation=tax-rates#adding-tax-rates-to-checkout) e [pagamentos únicos](https://docs.stripe.com/payments/checkout/taxes.md). Se não quiser migrar, você pode continuar usando a integração atual, mas não adicionaremos novos recursos. Você pode usar quaisquer novos planos ou preços recorrentes que criar no parâmetro `plan` das suas chamadas de API existentes. ## Visão geral de produtos e preços Os *Preços* (Prices define how much and how often to charge for products. This includes how much the product costs, what currency to use, and the interval if the price is for subscriptions) são uma entidade central na Stripe que funciona com assinaturas, *faturas* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) e o Checkout. Cada preço está vinculado a um único *Produto* (Products represent what your business sells—whether that's a good or a service), e cada produto pode ter vários preços. Diferentes bens físicos ou níveis de serviço são representados por produtos. Os preços definem o preço base, a moeda e (para produtos recorrentes) o ciclo de faturamento. Isso permite alterar e adicionar preços sem precisar mudar os detalhes do que você oferece. Por exemplo, você pode ter um único produto “gold” com preços de US$ 10,00 por mês, US$ 100,00 por ano, € 9,00 por mês e € 90,00 por ano. Ou você pode ter uma camiseta azul com preços de US$ 20,00 e € 15,00. ## Pagamentos avulsos As integrações para pagamentos avulsos foram alteradas da seguinte forma: - Em vez de itens de linha específicos (ou seja, nome, valor e moeda), a criação de uma Sessão do Checkout exige um *produto* (Products represent what your business sells—whether that's a good or a service) e, geralmente, um *preço* (Prices define how much and how often to charge for products. This includes how much the product costs, what currency to use, and the interval if the price is for subscriptions). - [modo](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode) passou a ser obrigatório. O código do lado do cliente continua igual. ### Tabela de mapeamento Em vez de definir cada campo em `line_items`, o Checkout usa os objetos de produto e preço correspondentes para definir o nome, descrição, valor, moeda e imagens. Você pode [criar produtos e preços](https://docs.stripe.com/payments/accept-a-payment.md) com a API ou o Dashboard. | Sem preços | Com preços | | --- | --- | | `line_items.name` | `product.name` | | `line_items.description` | `product.description` | | `line_items.amount` | - `price.unit_amount` - `price_data.unit_amount` (se definido quando a Sessão do Checkout for criada) | | `line_items.currency` | - `price.currency` - `price_data.currency` (se definido quando a Sessão do Checkout for criada) | | `line_items.images` | `product.images` (exibe a primeira imagem enviada) | ### Código do lado do servidor para itens em linha Antes, só era possível criar itens para uso avulso em linha. Com o sistema de preços, você pode continuar configurando seus itens em linha, mas também pode definir preços dinamicamente com [price_data](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-price_data) ao criar a Sessão do Checkout. Ao criar a Sessão do Checkout com `price_data`, indique um ID de produto existente com [price_data.product](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-price_data-product) ou defina os dados do produto dinamicamente, com [price_data.product_data](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-price_data-product_data). O exemplo a seguir demonstra o fluxo de criação de um item avulso. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "line_items[0][quantity]"=1 \ -d "line_items[0][price_data][unit_amount]"=2000 \ -d "line_items[0][price_data][product_data][name]"=T-shirt \ -d "line_items[0][price_data][product_data][description]"="Comfortable cotton t-shirt" \ -d "line_items[0][price_data][product_data][images][]"="https://example.com/t-shirt.png" \ -d "line_items[0][price_data][currency]"=usd \ -d mode=payment \ -d success_url="https://example.com/success" \ ``` ### Código do lado do servidor para preços avulsos Com essa integração, você pode [criar um catálogo de produtos e preços](https://docs.stripe.com/payments/accept-a-payment.md) antecipadamente, em vez de precisar definir o valor, a moeda e o nome cada vez que criar uma Sessão de Checkout. Você pode criar um produto e um preço com a [API Prices](https://docs.stripe.com/api/prices.md) ou pelo [Dashboard](https://dashboard.stripe.com/products). Será preciso usar a ID do preço para criar a Sessão do Checkout. O exemplo a seguir mostra como criar um produto e um preço pela API: #### curl ```bash curl https://api.stripe.com/v1/products \ -u<>: \ -d name=T-shirt \ -d description="Comfortable cotton t-shirt" \ -d "images[]"="https://example.com/t-shirt.png" curl https://api.stripe.com/v1/prices \ -u<>: \ -d product="{{PRODUCT_ID}}" \ -d unit_amount=2000 \ -d currency=usd curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "line_items[0][quantity]"=1 \ -d "line_items[0][price]"="{{PRICE_ID}}" \ -d mode=payment \ -d success_url="https://example.com/success" \ ``` ## Assinaturas As integrações para pagamentos recorrentes foram alteradas da seguinte forma: - Todos os itens são passados em um só campo [line_items](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items), em vez de em `subscription_data.items`. - [modo](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode) agora é obrigatório. Defina `mode=subscription` se houver itens recorrentes na sessão. O código do lado do cliente continua igual. Planos existentes podem ser usados sempre que forem aceitos preços recorrentes. ### Código do lado do servidor com planos Veja um exemplo de antes e depois da Sessão do Checkout com uma avaliação gratuita em um plano existente, que pode ser usado também com um preço. O plano agora é passado para `line_items` em vez de `subscription_data.items`. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "line_items[0][price]"="{{PRICE_OR_PLAN_ID}}" \ -d "line_items[0][quantity]"=1 \ -d mode=subscription \ -d success_url="https://example.com/success" \ ``` ### O código do lado do servidor para preços recorrentes com tarifa de configuração Se você tiver planos recorrentes com uma tarifa de abertura única, crie o produto e o preço que representam a tarifa única antes de criar a Sessão de Checkout. Consulte a [tabela de mapeamento](https://docs.stripe.com/payments/checkout/migrating-prices.md#mapping-table-server-one-time) para saber como os campos de `line_items` se mapeiam para essa integração. Você pode criar um produto e preço pela [API Prices](https://docs.stripe.com/api/prices.md) ou pelo [Dashboard da Stripe](https://dashboard.stripe.com/products). Você também pode [criar o item único de forma inline](https://docs.stripe.com/payments/checkout/migrating-prices.md#server-side-code-for-inline-items). O exemplo a seguir usa um ID de preço existente: #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "line_items[0][price]"="{{PRICE_OR_PLAN_ID}}" \ -d "line_items[0][quantity]"=1 \ -d "line_items[1][price]"="{{ONE_TIME_PRICE_ID}}" \ -d "line_items[1][quantity]"=1 \ -d mode=subscription \ -d success_url="https://example.com/success" \ ``` ## Mudanças nos objetos de resposta Em vez de listar os itens com `display_items`, o objeto Checkout Session usa `line_items`. O campo `line_items` não é renderizado por padrão como o `display_items`, mas você pode incluí-lo usando [expand](https://docs.stripe.com/api/expanding_objects.md) ao criar uma sessão de checkout: #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"="card" \ -d "mode"="payment" \ -d "line_items[0][price]"="{{PRICE_ID}}" \ -d "line_items[0][quantity]"=1 \ -d "success_url"="https://example.com/success" \ -d "expand[]"="line_items" ``` ## Mudanças no webhook Como `line_items` pode ser incluído, a resposta do *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) `checkout.session.completed` não lista os itens por padrão. O objeto de resposta menor permite que você receba seus webhooks do Checkout com mais rapidez. Você pode recuperar itens com o endpoint `line_items`: #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions/{{CHECKOUT_SESSION_ID}}/line_items \ -u <>: ``` Para obter mais detalhes, consulte a [execução de pedidos com o Checkout](https://docs.stripe.com/checkout/fulfillment.md).