# Configurar uma assinatura com o PayPal Saiba como criar e cobrar uma assinatura com o PayPal. # Página hospedada pela Stripe > This is a Página hospedada pela Stripe for when payments-ui-type is stripe-hosted. View the full page at https://docs.stripe.com/billing/subscriptions/paypal?payments-ui-type=stripe-hosted. Confira o [exemplo no GitHub](https://github.com/stripe-samples/checkout-single-subscription) ou explore a [demonstração](https://checkout.stripe.dev/checkout). Use este guia para configurar uma *assinatura* (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) usando o [PayPal](https://docs.stripe.com/payments/paypal.md) e o *Checkout* (A low-code payment integration that creates a customizable form for collecting payments. You can embed Checkout directly in your website, redirect customers to a Stripe-hosted payment page, or create a customized checkout page with Stripe Elements). Uma [sessão do Checkout](https://docs.stripe.com/api/checkout/sessions.md) representa os detalhes da intenção do cliente de fazer a compra. Crie uma sessão do Checkout quando um cliente quiser iniciar uma assinatura. Após redirecionar um cliente para uma sessão do Checkout, a Stripe apresenta um formulário de pagamento onde ele pode concluir a compra. Após a conclusão de uma compra, a Stripe redireciona o usuário de volta ao seu site. > #### Habilitar pagamentos recorrentes do PayPal > > A Stripe ativa automaticamente os pagamentos recorrentes para a maioria dos usuários quando eles [ativam pagamentos do PayPal](https://docs.stripe.com/payments/paypal/activate.md) no Stripe Dashboard. No entanto, devido às políticas do PayPal e às restrições regionais, talvez seja necessário que [habilitar](https://docs.stripe.com/payments/paypal/set-up-future-payments.md#enable-recurring-payments) manualmente os pagamentos recorrentes do PayPal no Dashboard. ## Configurar a Stripe [Lado do servidor] Primeiro, você precisa de uma conta Stripe. [Cadastre-se agora](https://dashboard.stripe.com/register). Use nossas bibliotecas oficiais para acessar a API da Stripe no seu aplicativo: #### Ruby ```bash # Available as a gem sudo gem install stripe ``` ```ruby # If you use bundler, you can add this line to your Gemfile gem 'stripe' ``` ## Criar produtos e preços recorrentes > A API Prices unifica a forma como as compras únicas e as assinaturas são modeladas na Stripe. As integrações existentes que não usam a API Prices ainda são [aceitas](https://support.stripe.com/questions/prices-api-and-existing-checkout-integrations). No entanto, alguns recursos do Checkout aceitam apenas o Prices. Consulte o [guia de migração](https://docs.stripe.com/payments/checkout/migrating-prices.md) para atualizar para a API Prices. Antes de usar o Checkout, você precisa criar um *produto* (Products represent what your business sells—whether that's a good or a service) e 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). Mercadorias físicas ou níveis de serviço diferentes devem ser representados por produtos. Cada produto pode ter um ou mais preços. Por exemplo, você pode criar um *produto* de software que tenha quatro *preços*: 10 USD/mês, 100 USD/ano, 9 EUR/mês e 90 EUR/ano. Isso permite alterar e adicionar preços sem precisar alterar os detalhes dos produtos correspondentes. Você pode criar um produto e preço [usando a API](https://docs.stripe.com/api/prices.md) ou usando [o Stripe Dashboard](https://dashboard.stripe.com/products). Quando o preço é determinado no checkout (por exemplo, o cliente define o valor da doação) ou você prefere não criar preços antecipadamente, é possível criar [preços em linha](https://docs.stripe.com/billing/subscriptions/paypal.md#creating-prices-inline) na criação da sessão do Checkout. #### Dashboard Antes de começar a configurar os produtos, verifique se você está em uma área restrita. Em seguida, defina as mercadorias e serviços que você planeja vender. Para criar um novo produto e preço: - Go to the [Products](https://dashboard.stripe.com/products) section in the Dashboard - Clique em **Adicionar produto** - Selecione “Recorrente” quando definir o preço - Configure o plano de preços Para cada produto recorrente, você pode definir vários planos de preços com parâmetros diferentes. Para cada preço, é gerado um ID que pode ser usado como referência durante o processo de checkout. > Produtos criados em área restrita podem ser copiados para o modo de produção, para que você não precise recriá-los. Na visualização de detalhes do Produto no Dashboard, clique em **Copy para o modo de produção** ( no canto superior direito. Você só pode fazer isso uma vez para cada produto criado em sandbox. Atualizações posteriores no produto de teste não são refletidas no produto em produção. #### API Para criar um [produto](https://docs.stripe.com/api/products.md) básico usando a API, somente o campo `name` é obrigatório. As propriedades `name`, `description` e `images` fornecidas aparecem para os clientes no Checkout. ```curl curl https://api.stripe.com/v1/products \ -u "<>:" \ -d "name=Blue banana" ``` Crie então um [preço](https://docs.stripe.com/api/prices.md) para definir o valor e a frequência da cobrança pelo produto. Você define o custo do produto, a moeda a ser usada e o intervalo de cobrança. #### curl ```bash curl https://api.stripe.com/v1/prices \ -u <>: \ -d "product"="{{ PRODUCT_ID }}" \ -d "unit_amount"=1000 \ -d "currency"="eur" \ -d "recurring[interval]=month" ``` O ID do preço é a referência do produto que você usa quando inicia o processo de pagamento no Checkout. ## Criar uma sessão do Checkout [Lado do cliente] [Lado do servidor] Adicione um botão de checkout ao seu site para chamar um endpoint do lado do servidor e criar uma Sessão do Checkout. ```html Checkout
``` ### Parâmetros da sessão do Checkout Consulte [Criar uma sessão do Checkout](https://docs.stripe.com/api/checkout/sessions/create.md) para ver a lista completa de parâmetros que você pode usar. Crie uma sessão do Checkout com o ID de um [preço](https://docs.stripe.com/api/prices.md) existente. Certifique-se de que o modo esteja definido como `subscription` e você passe pelo menos um preço recorrente. Você pode adicionar preços avulsos além de preços recorrentes. Depois de criar a sessão do Checkout, redirecione o cliente para o [URL](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-url) retornado na resposta. #### cURL ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"="paypal" \ -d "line_items[][price]"="{{PRICE_ID}}" \ -d "line_items[][quantity]"=1 \ -d "mode"="subscription" \ -d "success_url"="https://example.com/success?session_id={CHECKOUT_SESSION_ID}" \ ``` Quando o cliente finaliza um pagamento, é redirecionado para o `success_url`, uma página no seu site que informa ao cliente que o pagamento foi bem-sucedido. Disponibilize o ID da sessão na página de sucesso incluindo a variável de modelo `{CHECKOUT_SESSION_ID}` no `success_url` como no exemplo acima. As Sessões do Checkout expiram 24 horas após a criação por padrão. > Não confie apenas no redirecionamento para a `success_url` para detectar o início do pagamento, porque: > > - Usuários mal-intencionados podem acessar diretamente o `success_url` sem pagar e acessar seus produtos ou serviços. - Após um pagamento bem-sucedido, os clientes podem fechar a aba do navegador antes de serem redirecionados para a `success_url`. ## Confirmar a finalização do pagamento > Quando um comprador confirma uma assinatura na Stripe com PayPal, recebe um recibo da Stripe e outro do PayPal. Quando o cliente conclui um pagamento, é redirecionado para o URL especificado como `success_url`. Normalmente, é uma página no site que informa ao cliente que o pagamento foi bem-sucedido. Use o Dashboard, um *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) personalizado ou um plugin de terceiros para processar eventos pós-pagamento, como enviar um e-mail de confirmação de pedido ao cliente, registrar a venda em um banco de dados ou iniciar um fluxo de entrega. #### Dashboard Os pagamentos bem-sucedidos aparecem na [lista de pagamentos](https://dashboard.stripe.com/payments) do Dashboard. Quando você clica em um pagamento, a página de detalhes do pagamento é exibida. A seção **Resumo do checkout** contém dados de cobrança e a lista de itens comprados, que você pode usar para fazer a execução manual do pedido. ![Resumo do Checkout](https://b.stripecdn.com/docs-statics-srv/assets/source.16d3029596357c80a8efdbbfe106108a.png) > A Stripe ajuda você a acompanhar a entrada de pagamentos com o envio de notificações por e-mail sempre que um cliente efetua um. Use o Dashboard para [configurar notificações por e-mail](https://dashboard.stripe.com/settings/user). #### Webhooks [Configurar webhooks](https://docs.stripe.com/webhooks.md) para processar automaticamente eventos pós-pagamento. A forma mais rápida de desenvolver e testar webhooks localmente é com o [Stripe CLI](https://docs.stripe.com/stripe-cli.md). Após a instalação, você pode encaminhar eventos ao servidor: ```bash stripe listen --forward-to localhost:4242/webhook Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit) ``` Com um endpoint de webhook, o cliente é redirecionado para o `success_url` quando você [reconhece que recebeu o evento](https://docs.stripe.com/webhooks.md#acknowledge-events-immediately). Quando o endpoint estiver desconectado ou o evento não for reconhecido corretamente, o cliente será redirecionado para o `success_url` 10 segundos após o pagamento ter sido realizado. O exemplo de endpoint a seguir demonstra como reconhecer e processar eventos. #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. Stripe.api_key = '<>' # You can find your endpoint's secret in your webhook settings endpoint_secret = 'whsec_...' # Using Sinatra post '/webhook' do payload = request.body.read event = nil # Verify webhook signature and extract the event # See https://stripe.com/docs/webhooks#verify-events for more information. sig_header = request.env['HTTP_STRIPE_SIGNATURE'] begin event = Stripe::Webhook.construct_event( payload, sig_header, endpoint_secret ) rescue JSON::ParserError => e # Invalid payload status 400 return rescue Stripe::SignatureVerificationError => e # Invalid signature status 400 return end # Handle the checkout.session.completed event if event['type'] == 'checkout.session.completed' session = event['data']['object'] # Fulfill the purchase... handle_checkout_session(session) end status 200 end ``` Use plugins como o [Zapier](https://stripe.com/works-with/zapier) para automatizar a atualização dos seus sistemas de execução de compras com dados dos pagamentos da Stripe. Alguns exemplos de automação aceitas por plugins incluem: - Atualizar planilhas usadas para acompanhamento de pedidos em resposta a pagamentos efetivados - Atualizar sistemas de gerenciamento de inventário em resposta a pagamentos efetivados - Acionar notificações a equipes internas de atendimento ao cliente usando e-mail ou aplicativos de chat ## Testar a integração Teste a integração do PayPal com as [chaves de API de teste](https://docs.stripe.com/keys.md#test-live-modes) visualizando a página de redirecionamento. Para testar o caso de pagamento bem-sucedido, autentique o pagamento na página de redirecionamento. O PaymentIntent fará a transição de `requires_action` para `succeeded`. Para testar o que acontece quando a autenticação do usuário falha, use as chaves de API de teste e visualize a página de redirecionamento. Nessa página, clique em **Falhar pagamento de teste**. O PaymentIntent mudará de `requires_action` para `requires_payment_method`. ## Optional: Adicionar uma tarifa de configuração avulsa [Lado do servidor] Além de passar preços recorrentes, você pode adicionar preços avulsos no modo `subscription`. Esses preços somente estão na *fatura* (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) inicial criada pela assinatura. Esse recurso é útil para adicionar tarifas de configuração ou outras tarifas avulsas associadas a uma assinatura. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"="paypal" \ -d "line_items[0][price]"="{{RECURRING_PRICE_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?session_id={CHECKOUT_SESSION_ID}" ``` ## Optional: Criar preços e produtos em linha [Lado do servidor] Além de passar IDs de preços existentes, você pode definir o preço do item na criação da sessão do Checkout. Defina um [produto](https://docs.stripe.com/api/products.md) e crie uma sessão do Checkout passando o ID do produto em [price_data](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-price_data) com os dados de `unit_amount`, `currency` e `recurring`: #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"=paypal \-d line_items[0][price_data][unit_amount]=5000 \ -d line_items[0][price_data][currency]=eur\ -d line_items[0][price_data][product]="{{PRODUCT_ID}}" \ -d line_items[0][price_data][recurring][interval]=month \ -d line_items[0][quantity]=1 \ -d mode=subscription \ -d success_url="https://example.com/success?session_id={CHECKOUT_SESSION_ID}" \ ``` Se você também precisa criar produtos em linha, use [product_data](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-price_data-product_data): #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"=paypal \-d "line_items[][price_data][currency]"=eur\ -d "line_items[][price_data][product_data][name]"=T-shirt \ -d "line_items[][price_data][unit_amount]"=2000 \ -d "line_items[][quantity]"=1 \ -d "mode"="subscription" \ -d success_url="https://example.com/success?session_id={CHECKOUT_SESSION_ID}" \ ``` ## Optional: Clientes existentes [Lado do servidor] Se você já criou anteriormente um objeto Customer** para representar um cliente, use o[cliente](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer) argumento para passar o ID de Cliente ao criar uma sessão Checkout. Isso garante que todos os objetos criados durante a Sessão estejam associados ao objeto Customer correto. Quando você passa um ID de cliente, a Stripe também usa o e-mail armazenado no objeto Customer para preencher o campo de e-mail na página de checkout. Se o cliente trocar o e-mail na página de checkout, este será atualizado no objeto Customer quando o pagamento for concluído. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "customer"="{{CUSTOMER_ID}}" \ -d "payment_method_types[]"="paypal" \ -d "line_items[][price]"="{{PRICE_ID}}" \ -d "line_items[][quantity]"=1 \ -d "mode"="subscription" \ -d "success_url"="https://example.com/success" ``` ## Optional: Preencher dados do cliente [Lado do servidor] Se você já coletou o e-mail do cliente e quer preenchê-lo antecipadamente na sessão de checkout, passe [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email) ao criar uma sessão de checkout. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \-d customer_email="customer@example.com" \ -d "payment_method_types[]"=paypal \ -d "line_items[][price]"="{{PRICE_ID}}" \ -d "line_items[][quantity]"=1 \ -d mode=subscription \ -d success_url="https://example.com/success" \ ``` ## Optional: Gerenciar períodos de avaliação [Lado do servidor] É possível usar [trial_end](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-subscription_data-trial_end) ou [trial_period_days](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-subscription_data-trial_period_days) na sessão do Checkout para especificar a duração do período de avaliação. Neste exemplo, usamos `trial_period_days` para criar uma sessão do Checkout para uma assinatura com um período de avaliação de 30 dias. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"=paypal \ -d "line_items[][price]"="{{PRICE_ID}}" \ -d "line_items[][quantity]"=1 \-d "subscription_data[trial_period_days]"=30 \ -d mode=subscription \ -d success_url="https://example.com/success?session_id={CHECKOUT_SESSION_ID}" \ ``` O Checkout exibe as seguintes informações automaticamente para assinaturas com períodos de avaliação: - Período de avaliação - Frequência e valor das cobranças após o vencimento da avaliação Para mais informações sobre requisitos de conformidade, consulte os guias [Gerenciar requisitos de conformidade](https://docs.stripe.com/billing/subscriptions/trials/manage-trial-compliance.md) ou o [suporte](https://support.stripe.com/questions/2020-visa-trial-subscription-requirement-changes-guide). ## Optional: Alíquotas [Lado do servidor] Você pode especificar [alíquotas de impostos](https://docs.stripe.com/billing/taxes/tax-rates.md) (sobre vendas, IVA, GST e outros) nas sessões de checkout para aplicar impostos às *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). - Use alíquotas fixas quando você souber qual a alíquota exata que deve ser cobrada dos clientes antes do início do checkout (por exemplo, você vende apenas para clientes no Reino Unido e sempre cobra 20% de IVA). - Com a API *Prices* (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), você pode usar alíquotas dinâmicas quando precisar de mais dados do cliente (por exemplo, endereço de cobrança ou entrega) para determinar a alíquota a ser cobrada. As alíquotas dinâmicas podem ser atribuídas a regiões diferentes (por exemplo, uma alíquota de 20% de IVA para clientes no Reino Unido e uma alíquota de 7,25% sobre vendas para clientes na Califórnia). A Stripe tenta associar o local do cliente a uma dessas alíquotas. #### Alíquotas fixas Defina [subscription_data.default_tax_rates](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-subscription_data-default_tax_rates) para aplicar uma alíquota padrão a uma assinatura iniciada com o Checkout. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"=paypal \ -d "line_items[][price]"="{{PRICE_ID}}" \ -d "line_items[][quantity]"=1 \-d "subscription_data[default_tax_rates][]"="{{TAX_RATE_ID}}" \ -d mode=subscription \ -d success_url="https://example.com/success" \ ``` Você também pode especificar [line_items.tax_rates](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-tax_rates) ou [subscription_data.items.tax_rates](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-subscription_data-items-tax_rates) para aplicar alíquotas de imposto a planos ou itens de linha de fatura específicos. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"="paypal" \ -d "line_items[][price]"="{{PRICE_ID}}" \ -d "line_items[][quantity]"=1 \-d "line_items[][tax_rates][0]"="{{TAX_RATE_ID}}" \ -d "mode"="subscription" \ -d "success_url"="https://example.com/success" \ ``` #### Alíquotas dinâmicas Passe uma matriz de [alíquotas](https://docs.stripe.com/api/tax_rates/object.md) para [line_items.dynamic_tax_rates](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-dynamic_tax_rates). Cada alíquota deve ter um `country` (para os EUA, também um `state`) [aceito](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-dynamic_tax_rates). Esta lista associa alíquotas ao [endereço de entrega](https://docs.stripe.com/payments/collect-addresses.md), endereço de cobrança ou país do cliente. Para determinar a alíquota a ser cobrada, o endereço de entrega tem precedência sobre o endereço de cobrança. Quando você não coleta endereços de entrega ou cobrança, o país do cliente (e o código postal, se for o caso) é usado para determinar a alíquota. Se você não passou uma alíquota correspondente ao endereço de entrega, endereço de cobrança ou país do cliente, nenhuma alíquota é aplicada. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"="paypal" \ -d "line_items[][price]"="{{PRICE_ID}}" \ -d "line_items[][quantity]"=1 \-d "line_items[][dynamic_tax_rates][]"="{{FIRST_TAX_RATE_ID}}" \ -d "line_items[][dynamic_tax_rates][]"="{{SECOND_TAX_RATE_ID}}" \ -d "mode"="subscription" \ -d "success_url"="https://example.com/success" \ ``` > [subscription_data.default_tax_rates](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-subscription_data-default_tax_rates) e [line_items.tax_rates](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-tax_rates) não podem ser usados em combinação com [line_items.dynamic_tax_rates](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-dynamic_tax_rates). Você pode usar as exportações de dados da Stripe para preencher as declarações periódicas necessárias para o repasse. Acesse [Declarações e remessas fiscais](https://docs.stripe.com/billing/taxes/tax-rates.md#remittance) para obter mais informações. ## Optional: Adicionar cupons [Lado do servidor] Você pode aplicar [cupons](https://docs.stripe.com/billing/subscriptions/coupons.md) a assinaturas em uma sessão do Checkout configurando [descontos](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-discounts). Este cupom substitui qualquer cupom no cliente. Se você estiver criando uma assinatura com um [cliente existente](https://docs.stripe.com/billing/subscriptions/paypal.md#handling-existing-customers), qualquer cupom associado ao cliente é aplicado às *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) da assinatura. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"=paypal \ -d "line_items[][price]"="{{PRICE_ID}}" \ -d "line_items[][quantity]"=1 \-d "discounts[][coupon]"="{{COUPON_ID}}" \ -d "mode"="subscription" \ -d success_url="https://example.com/success" \ ``` ### Adicionar códigos de promoção voltados para o cliente Também é possível ativar [códigos promocionais](https://docs.stripe.com/billing/subscriptions/coupons.md#promotion-codes) resgatáveis pelo usuário utilizando o parâmetro [allow_promotion_codes](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-allow_promotion_codes) em sessões do Checkout. Com `allow_promotion_codes` ativado em uma sessão do Checkout, o Checkout inclui uma caixa de resgate de código de promoção para uso pelos clientes. Crie seus [cupons](https://docs.stripe.com/billing/subscriptions/coupons.md) e códigos promocionais no Dashboard ou na API para que seus clientes possam resgatá-los no Checkout. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"="paypal" \ -d "line_items[0][price_data][unit_amount]"=2000 \ -d "line_items[0][price_data][currency]"="eur" \ -d "line_items[0][price_data][product]={{PRODUCT_ID}}" \ -d "line_items[0][price_data][recurring][interval]=month" \ -d "line_items[0][quantity]"=1 \-d "allow_promotion_codes"="true" \ -d "mode"="subscription" \ -d "success_url"="https://example.com/success" \ ``` ## See also - [Personalizar sua integração](https://docs.stripe.com/payments/checkout/customization.md) - [Gerenciar assinaturas com o portal do cliente](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md?payment-ui=checkout&ui=stripe-hosted) # API Direct > This is a API Direct for when payments-ui-type is direct-api. View the full page at https://docs.stripe.com/billing/subscriptions/paypal?payments-ui-type=direct-api. Use este guia para configurar uma *assinatura* (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) usando [PayPal](https://docs.stripe.com/payments/paypal.md) como forma de pagamento. ## Before you begin - Para aceitar assinaturas do PayPal na Stripe, você deve [ativar pagamentos recorrentes do PayPal no Dashboard](https://docs.stripe.com/payments/paypal/set-up-future-payments.md?platform=web#enable-recurring-payments). - Esse recurso está disponível apenas em localizações específicas da empresa. [Reveja a localização das empresas para confirmar a elegibilidade](https://docs.stripe.com/payments/paypal.md). ## Criar produto e preço [Dashboard] [Produtos](https://docs.stripe.com/api/products.md) representam o item ou serviço que você está vendendo. [Preços](https://docs.stripe.com/api/prices.md) definem quanto e com que frequência você cobra por um produto. Você estabelece quanto custa o produto, qual moeda você aceita e se a cobrança é avulsa ou recorrente. Se você tiver apenas alguns produtos e preços, crie e gerencie-os no Dashboard. Este guia usa um serviço de banco de imagens como exemplo e cobra dos clientes uma assinatura mensal de 15 EUR. Para modelar isso: 1. Vá para a página [Produtos](https://dashboard.stripe.com/products?active=true) e clique em **Criar produto**. 1. Insira um **Nome** para o produto. Opcionalmente, você pode adicionar uma **Descrição** e fazer o upload de uma imagem do produto. 1. Selecione um **Código fiscal de produto**. Saiba mais sobre [códigos fiscais de produto](https://docs.stripe.com/tax/tax-codes.md). 1. Selecione **Recorrente**. Em seguida, insira **15** como preço e selecione **EUR** como moeda. 1. Escolha se deseja **Incluir imposto no preço**. Você pode usar o valor padrão das suas [configurações fiscais](https://dashboard.stripe.com/test/settings/tax) ou definir o valor manualmente. Neste exemplo, selecione **Automático**. 1. Em **Período de faturamento**, selecione **Mensal**. 1. Clique em **Mais opções de planos de preços**. Em seguida, selecione **Taxa fixa** como o modelo de preço para este exemplo. Saiba mais sobre [taxa fixa](https://docs.stripe.com/products-prices/pricing-models.md#flat-rate) e outros [modelos de planos de preços](https://docs.stripe.com/products-prices/pricing-models.md). 1. Adicione uma **Descrição de preço** interna e uma [Chave de pesquisa](https://docs.stripe.com/products-prices/manage-prices.md#lookup-keys) para organizar, consultar e atualizar preços específicos no futuro. 1. Clique em **Próximo**. Em seguida, clique em **Adicionar produto**. Depois de criar o produto e o preço, registre o ID do preço para utilizá-lo nas etapas subsequentes. A página de preços exibe o ID, que tem esta estrutura: `price_G0FvDp6vZvdwRZ`. ## Criar ou recuperar um Customer antes da configuração [Lado do servidor] Para reutilizar uma forma de pagamento PayPal para pagamentos futuros, vincule-a a um *Cliente* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments). Crie um objeto Customer quando um cliente abrir uma conta em sua empresa. Associar o ID do objeto Customer à sua própria representação interna de um cliente permitirá que você recupere e use posteriormente os dados da forma de pagamento armazenados. Se o cliente não criou uma conta, você pode criar um objeto Customer agora e associá-lo posteriormente à sua representação interna da conta do cliente. ```curl curl -X POST https://api.stripe.com/v1/customers \ -u "<>:" ``` ## Criar um SetupIntent [Lado do servidor] Um [SetupIntent](https://docs.stripe.com/api/setup_intents.md) é um objeto que representa sua intenção e acompanha as etapas de configuração da forma de pagamento do cliente para pagamentos futuros. Crie um [SetupIntent](https://docs.stripe.com/api/setup_intents.md) no servidor com [payment_method_types](https://docs.stripe.com/api/setup_intents/create.md#create_setup_intent-payment_method_types) definido como `paypal` e especifique o [id](https://docs.stripe.com/api/customers/object.md#customer_object-id) do *cliente* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments). ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "payment_method_types[]=paypal" \ -d "payment_method_data[type]=paypal" ``` O objeto SetupIntent contém um [client_secret](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-client_secret), uma chave única que você precisa passar para a Stripe no lado do cliente para redirecionar seu comprador para o PayPal e autorizar a instrução. ## Redirecionar o cliente [Lado do cliente] Quando um cliente tenta configurar sua conta PayPal para pagamentos futuros, recomendamos que você use o [Stripe.js](https://docs.stripe.com/js.md) para confirmar o SetupIntent. Stripe.js é a nossa biblioteca JavaScript básica para criar fluxos de pagamento. Ele processa automaticamente fluxos complexos, como o redirecionamento descrito abaixo, e facilita a ampliação da integração para incluir outras formas de pagamento no futuro. Para incluir o script Stripe.js na página de checkout, adicione-o ao head do arquivo HTML. ```html Checkout ``` Crie uma instância de Stripe.js com o JavaScript a seguir em sua página de checkout. ```javascript // Set your publishable key. Remember to change this to your live publishable key in production! // See your keys here: https://dashboard.stripe.com/apikeys const stripe = Stripe('<>', {} ); ``` Para confirmar a configuração no lado do cliente, passe o segredo do cliente no objeto SetupIntent criado na etapa 3. O segredo do cliente é diferente das suas chaves de API que autenticam solicitações da API da Stripe. Ainda assim, ele deve ser tratado com cuidado porque pode concluir a cobrança. Não o registre em logs, não o incorpore em URLs e não o exponha a ninguém além do cliente. ### Confirmar configuração do PayPal Para autorizar você a usar a conta PayPal para pagamentos futuros, o cliente será redirecionado para uma página de contrato de cobrança do PayPal, que precisará ser aprovada antes de ser redirecionado de volta ao seu site. Use [stripe.confirmPayPalSetup](https://docs.stripe.com/js/setup_intents/confirm_paypal_setup) para prosseguir da sua página para a conclusão da configuração. Adicione um `return_url` a esta função para indicar aonde a Stripe deve redirecionar o usuário depois que ele aprovar o contrato de faturamento no site do PayPal. ```javascript // Redirects away from the client const {error} = await stripe.confirmPayPalSetup( '{{SETUP_INTENT_CLIENT_SECRET}}', { return_url: 'https://example.com/setup/complete', mandate_data: { customer_acceptance: { type: 'online', online: { infer_from_client: true } } }, } ); if (error) { // Inform the customer that there was an error. } ``` Você pode encontrar o ID do pagador da forma de pagamento e o ID do contrato de cobrança no [Mandate](https://docs.stripe.com/api/mandates/.md) resultante, na propriedade [payment_method_details](https://docs.stripe.com/api/mandates/object.md#mandate_object-payment_method_details-paypal). O e-mail e o ID do pagador do comprador também podem ser encontrados na propriedade [paypal](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-paypal) do [PaymentMethod](https://docs.stripe.com/api/payment_methods.md). | Campo | Valor | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `payer_email` | O e-mail do pagador na conta PayPal dele. | | `payer_id` | Um ID único da conta PayPal do pagador. | | `billing_agreement_id` | O ID do contrato de faturamento (BAID) do PayPal. Um ID gerado pelo PayPal para representar o mandato entre a empresa e o cliente. | ## Monitorar webhooks [Lado do servidor] Use um método, como [webhooks](https://docs.stripe.com/payments/payment-intents/verifying-status.md#webhooks), para confirmar que o contrato de cobrança foi autorizado pelo cliente, em vez de esperar que o cliente volte à página de status do pagamento. Quando um cliente autoriza o contrato de cobrança, o SetupIntent emite o evento *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) [setup_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-setup_intent.succeeded). Se um cliente não autorizar o contrato de cobrança, o SetupIntent emitirá o evento de webhook [setup_intent.setup_failed](https://docs.stripe.com/api/events/types.md#event_types-setup_intent.setup_failed) e voltará ao status de `requires_payment_method`. Quando um cliente revoga o contrato de cobrança da sua conta PayPal, o [mandate.updated](https://docs.stripe.com/api/events/types.md#event_types-mandate.updated) é emitido. ## Criar a assinatura [Lado do servidor] Crie uma [assinatura](https://docs.stripe.com/api/subscriptions.md) com preço e cliente: ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d customer=cus_Gk0uVzT2M4xOKD \ -d default_payment_method=pm_1F0c9v2eZvKYlo2CJDeTrB4n \ -d "items[0][price]=price_F52b2UdntfQsfR" \ -d "expand[0]=latest_invoice.confirmation_secret" \ -d off_session=true ``` A criação de assinaturas cobra automaticamente os clientes porque a [forma de pagamento padrão](https://docs.stripe.com/api/customers/create.md#create_customer-invoice_settings-default_payment_method) está definida. Depois de um pagamento bem-sucedido, o status no [Stripe Dashboard](https://dashboard.stripe.com/test/subscriptions) muda para **Ativo**. O preço que você criou anteriormente determina as cobranças seguintes. ## Gerenciar o status da assinatura [Lado do cliente] Quando o pagamento inicial é bem-sucedido, o status da assinatura é `active` e nenhuma ação adicional é necessária. Quando os pagamentos falham, o status é alterado para o **Status da assinatura** configurado nas suas [configurações de cobrança automática](https://docs.stripe.com/invoicing/automatic-collection.md). Notifique o cliente após uma falha e [cobre-o com uma forma de pagamento diferente](https://docs.stripe.com/billing/subscriptions/overview.md#requires-payment-method). ## Atualizar uma assinatura [Lado do servidor] Quando você atualiza uma assinatura, é preciso especificar `off_session=true`. Caso contrário, qualquer novo pagamento exige um redirecionamento do usuário ao PayPal para confirmação. Por exemplo, se quiser alterar a quantidade de um item incluído na assinatura, você pode usar: ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d customer=cus_Gk0uVzT2M4xOKD \ -d default_payment_method=pm_1F0c9v2eZvKYlo2CJDeTrB4n \ -d "items[0][price]=price_F52b2UdntfQsfR" \ -d "items[0][quantity]=2" \ -d off_session=true ``` ## Testar a integração Teste a integração do PayPal com as [chaves de API de teste](https://docs.stripe.com/keys.md#test-live-modes) visualizando a página de redirecionamento. Para testar o caso de pagamento bem-sucedido, autentique o pagamento na página de redirecionamento. O PaymentIntent fará a transição de `requires_action` para `succeeded`. Para testar o que acontece quando a autenticação do usuário falha, use as chaves de API de teste e visualize a página de redirecionamento. Nessa página, clique em **Falhar pagamento de teste**. O PaymentIntent mudará de `requires_action` para `requires_payment_method`. ## Optional: Definir o período de cobrança Ao criar uma assinatura, ela define automaticamente o ciclo de cobrança por padrão. Por exemplo, se um cliente assina um plano mensal em 7 de setembro, ele será cobrado no dia 7 de cada mês subsequente. Algumas empresas preferem definir manualmente o ciclo de cobrança, de modo a cobrar todos os clientes ao mesmo tempo. O argumento [âncora do ciclo de cobrança](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-billing_cycle_anchor) permite que você faça isso. ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d billing_cycle_anchor=1611008505 ``` A definição manual do ciclo de cobrança gera cobra o cliente proporcionalmente pelo tempo decorrido da criação da assinatura até o primeiro dia do ciclo de cobrança. Se não quiser cobrar esse período dos clientes, defina o argumento [proration_behavior](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-proration_behavior) como `none`. Você também pode combinar a âncora do ciclo de cobrança com [períodos de avaliação](https://docs.stripe.com/billing/subscriptions/paypal.md#trial-periods) para oferecer acesso gratuito ao seu produto e depois cobrar um valor proporcional. ## Optional: Avaliações de assinaturas As avaliações oferecem acesso gratuito ao seu produto por um período. Usar avaliações gratuitas é diferente de definir [proration_behavior](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-proration_behavior) como `none`, porque você pode personalizar a duração do período gratuito. Passe um carimbo de data e hora em [fim do teste](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-trial_end) para definir o período do teste. ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d trial_end=1610403705 ``` Também é possível combinar uma [âncora de ciclo de faturamento](https://docs.stripe.com/billing/subscriptions/paypal.md#billing-cycle) com um período de teste gratuito. Por exemplo, digamos que seja 15 de setembro e você queira oferecer um teste gratuito de sete dias e começar o ciclo de cobrança normal em 1º de outubro. Você pode definir o teste gratuito para terminar em 22 de setembro e a âncora do ciclo de faturamento para 1º de outubro. Assim, o cliente ganha um teste de sete dias e depois paga um valor proporcional do fim do teste até 1º de outubro. Em 1º de outubro, você cobra o valor normal da assinatura pelo primeiro ciclo de faturamento completo. ## Optional: Remover uma conta PayPal salva Você pode usar a API [detach](https://docs.stripe.com/api/payment_methods/detach.md) para remover a conta PayPal salva de um cliente como forma de pagamento. Quando você desassocia uma forma de pagamento do PayPal, a [instrução](https://docs.stripe.com/api/mandates.md) é revogada e também invoca a API PayPal para cancelar o contrato de cobrança do PayPal associado. ```curl curl -X POST https://api.stripe.com/v1/payment_methods/{{PAYMENT_METHOD_ID}}/detach \ -u "<>:" ```