# Guia de migração de preços para o Checkout Saiba como atualizar sua integração para usar preços no Stripe Checkout. A [API Prices](https://docs.stripe.com/api/prices.md) cria recursos e gera flexibilidade para suas cobranças aos clientes. Esta nova integração oferece: - Um modelo mais unificado 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 em linha, cada item agora é um *preço*. - Capacidade de renderizar imagens de produtos em itens recorrentes. - Criar um catálogo reutilizável de produtos e preços em vez de itens de linha avulsos. - Criar preços em linha 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). - Aplicar alíquotas fiscais dinâmicas a [assinaturas](https://docs.stripe.com/billing/taxes/collect-taxes.md?tax-calculation=tax-rates#adding-tax-rates-to-checkout) e [pagamentos avulsos](https://docs.stripe.com/payments/checkout/taxes.md). Não quer migrar? Você pode continuar usando sua integração atual, mas os novos recursos não são compatíveis. Você pode usar qualquer novo plano ou preço recorrente que criar no parâmetro `plan` das chamadas de API existentes. ## Visão geral de produtos e preç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) formam uma entidade nova e básica da Stripe que funciona em 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 no Checkout. Cada preço fica vinculado a um único *produto* (Products represent what your business sells—whether that's a good or a service), e cada produto pode ter diversos preços. Diferentes mercadorias ou níveis de um serviço podem ser representados por produtos. Os preços desse produto devem ser representados pela entidade preços. Os preços definem o preço inicial, a moeda e, no caso de produtos recorrentes, o ciclo de faturamento. Dessa forma, você pode alterar ou acrescentar preços sem mudar os detalhes do produto vendido. Por exemplo, você pode ter um só preço, em categoria “ouro”, de US$ 10/mês, US$ 100/ano, € 9/mês e € 90/ano. Ou talvez você venda uma camiseta azul, que custa US$ 20 e € 15. ## 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 esta nova integração, você pode [criar um catálogo de produtos e preços](https://docs.stripe.com/payments/accept-a-payment.md) logo no início, sem precisar definir valor, moeda e nome, sempre que criar uma sessão do 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 configuração avulsa, crie o produto e o preço representando a tarifa avulsa antes de criar a Sessão do Checkout. Consulte a [tabela de mapeamento](https://docs.stripe.com/payments/checkout/migrating-prices.md#mapping-table-server-one-time) para saber como os antigos campos `line_items` aparecem na nova integração. Você pode criar um produto e preço pela [API Prices](https://docs.stripe.com/api/prices.md) ou pelo [Stripe Dashboard](https://dashboard.stripe.com/products). Você também pode [criar o item avulso em linha](https://docs.stripe.com/payments/checkout/migrating-prices.md#server-side-code-for-inline-items). O exemplo a seguir usa uma 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` já não lista os itens por padrão. O objeto de resposta menor permite que você receba os webhooks do Checkout mais rápido. Você pode recuperar itens com o novo endpoint de `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).