Guia de migração de preços para o Checkout

A API Prices 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 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.
• Aplicar alíquotas fiscais dinâmicas a assinaturas e pagamentos avulsos.

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 formam uma entidade nova e básica da Stripe que funciona em assinaturas, faturas e no Checkout. Cada preço fica vinculado a um único produto, 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 e, geralmente, um preço.
• modo 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 com a API ou o Dashboard.

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 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 ou defina os dados do produto dinamicamente, com price_data.product_data. O exemplo a seguir demonstra o fluxo de criação de um item avulso.

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -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" \
  -d cancel_url="https://example.com/cancel"

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 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 preço com a API Prices ou pelo Dashboard. Será preciso usar o 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 https://api.stripe.com/v1/products \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -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 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d product="{{PRODUCT_ID}}" \
  -d unit_amount=2000 \
  -d currency=usd

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "line_items[0][price]"="{{PRICE_ID}}" \
  -d mode=payment \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Assinaturas

As integrações para pagamentos recorrentes foram alteradas da seguinte forma:

• Todos os itens são passados em um só campo line_items, em vez de em subscription_data.items.
• modo 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 https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "subscription_data[items][][plan]"="{{PRICE_OR_PLAN_ID}}" \
  -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" \
  -d cancel_url="https://example.com/cancel"

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 para saber como os antigos campos line_items aparecem na nova integração. Você pode criar um produto e preço pela API Prices ou pelo Stripe Dashboard. Você também pode criar o item avulso em linha. O exemplo a seguir usa uma ID de preço existente:

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "subscription_data[items][][plan]"="{{PLAN_ID}}" \
  -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" \
  -d cancel_url="https://example.com/cancel"

Mudanças nos objetos de resposta

Em vez de listar itens com display_items, o objeto da Sessão do Checkout usa line_items. O campo line_items não renderiza por padrão como display_items, mas você pode incluí-lo com expand ao criar a Sessão do Checkout:

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -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 "cancel_url"="https://example.com/cancel" \
  -d "expand[]"="line_items"

Mudanças no webhook

Como line_items pode ser incluído, a resposta do webhook 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 https://api.stripe.com/v1/checkout/sessions/{{CHECKOUT_SESSION_ID}}/line_items \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:

Para obter mais detalhes, consulte a execução de pedidos com o Checkout.