Checkout

` em seu formulário de pagamento. O Checkout é renderizado em um iframe que envia com segurança as informações de pagamento para a Stripe por meio de uma conexão HTTPS. Evite colocar o Checkout dentro de outro iframe porque algumas formas de pagamento exigem redirecionamento a outra página para confirmação do pagamento. ```javascript // Initialize Stripe.js const stripe = Stripe('<>'); initialize(); // Fetch Checkout Session and retrieve the client secret async function initialize() { const fetchClientSecret = async () => { const response = await fetch("/create-checkout-session", { method: "POST", }); const { clientSecret } = await response.json(); return clientSecret; }; // Initialize Checkout const checkout = await stripe.createEmbeddedCheckoutPage({ fetchClientSecret, }); // Mount Checkout checkout.mount('#checkout'); } ``` #### React #### Adicionar a Stripe ao aplicativo React Instale o [React Stripe.js](https://docs.stripe.com/sdks/stripejs-react.md) para manter a conformidade com o PCI, garantindo que os detalhes de pagamento sejam enviados diretamente a Stripe e nunca cheguem ao seu servidor. ```bash npm install --save @stripe/react-stripe-js @stripe/stripe-js ``` #### Carregar o Stripe.js Para configurar a biblioteca da Stripe, chame `loadStripe()` com sua chave da API publicável da Stripe. Crie um `EmbeddedCheckoutProvider`. Passe a `Promise` retornada para o provedor. #### Obter o segredo do cliente da Checkout Session Crie uma função assíncrona `fetchClientSecret` que faça uma solicitação ao servidor para [criar uma Checkout Session](https://docs.stripe.com/api/checkout/sessions/create.md) e recuperar o segredo do cliente. #### Inicializar o Checkout Para permitir que os componentes filhos acessem o serviço Stripe por meio do consumidor de Checkout incorporado, passe a promessa resultante de `loadStripe` e a função `fetchClientSecret` como `option` para o provedor de Checkout incorporado. ```jsx import * as React from 'react'; import {loadStripe} from '@stripe/stripe-js'; import { EmbeddedCheckoutProvider, EmbeddedCheckout } from '@stripe/react-stripe-js'; // Make sure to call `loadStripe` outside of a component's render to avoid // recreating the `Stripe` object on every render. const stripePromise = loadStripe('pk_test_123', { }); const App = ({fetchClientSecret}) => { const options = {fetchClientSecret}; return ( ) } ``` ## Exibir uma página de retorno Depois que o cliente tenta efetuar o pagamento, a Stripe o redireciona para uma página de retorno que você hospeda em seu site. Ao criar a Checkout Session, você especificou a URL da página de retorno no parâmetro [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-return_url). > Durante o pagamento, algumas formas de pagamento redirecionam o cliente para uma página intermediária, como uma página de autorização bancária. Quando o cliente conclui essa página, a Stripe o redireciona para a sua página de retorno. #### Crie um endpoint para recuperar uma Checkout Session Adicione um endpoint para recuperar o status de uma Checkout Session com o ID da Checkout Session na URL. #### Recuperar uma Checkout Session Para usar os detalhes da Checkout Session, faça imediatamente uma solicitação ao endpoint em seu servidor para [recuperar o status da Checkout Session](https://docs.stripe.com/api/checkout/sessions/retrieve.md) usando o ID da Checkout Session na URL assim que a página de retorno for carregada. #### Manipular a sessão Tratar o resultado estabelecido no status da sessão: - `complete`: o pagamento foi bem-sucedido. Use as informações da sessão do Checkout para renderizar uma página de sucesso. - `open`: o pagamento falhou ou foi cancelado. Remonte o Checkout para que seu cliente possa tentar novamente. ```js // Retrieve a Checkout Session // Use the session ID initialize(); async function initialize() { const queryString = window.location.search; const urlParams = new URLSearchParams(queryString); const sessionId = urlParams.get('session_id'); const response = await fetch(`/session-status?session_id=${sessionId}`); const session = await response.json(); // Handle the session according to its status if (session.status == 'open') { // Remount embedded Checkout window.location.replace('http://localhost:4242/checkout.html') } else if (session.status == 'complete') { document.getElementById('success').classList.remove('hidden'); document.getElementById('customer-email').textContent = session.customer_email; // Show success page // Optionally use session.payment_status or session.customer_email // to customize the success page } } ``` ```javascript // Add an endpoint to fetch the Checkout Session status app.get('/session_status', async (req, res) => { const session = await stripe.checkout.sessions.retrieve(req.query.session_id); const customer = await stripe.customers.retrieve(session.customer); res.send({ status: session.status, payment_status: session.payment_status, customer_email: customer.email }); }); ``` ## Optional: Configurar o portal de clientes Você pode configurar o *portal do cliente* para permitir que seus clientes gerenciem diretamente suas assinaturas e faturas existentes. Você pode configurar o portal no Dashboard. Para reduzir a rotatividade, você pode configurar o portal para permitir que os clientes atualizem suas formas de pagamento em caso de falha nos pagamentos. Para ajudar os clientes a encontrá-lo, adicione um botão em seu site para redirecionar para o portal do cliente e permitir que os clientes gerenciem suas assinaturas. Ao clicar nesse botão, o cliente é redirecionado para a página do portal do cliente hospedado pela Stripe. Saiba mais sobre o [portal do cliente ](https://docs.stripe.com/customer-management.md) e outras opções de gerenciamento de clientes. #### Criar uma sessão no portal Para adicionar um portal do cliente, defina um endpoint que [crie a sessão do portal do cliente](https://docs.stripe.com/api/customer_portal/sessions/create.md) para o front end chamar. O `CUSTOMER_ID` refere-se ao ID do cliente criado por uma Checkout Session que você salvou ao processar o Webhook `checkout.session.completed`. você também pode definir um link de redirecionamento padrão para o portal no Dashboard. Passe um valor opcional `return_url` para a página do seu site para a qual o cliente será redirecionado depois que terminar de gerenciar a assinatura: #### 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 = '<>' # This is the URL that users are redirected to after they're done # managing their billing. return_url = '{{DOMAIN_URL}}' # Exemplo: http://exemplo.com.br customer_id = '{{CUSTOMER_ID}}' # Exemplo: cus_GBV60HKsE0mb5v session = Stripe::BillingPortal::Session.create({ customer: customer_id, return_url: return_url, }) # Redirect to the URL for the session # redirect session.url, 303 ``` #### Enviar clientes ao portal de clientes No front end, adicione um botão à página em `success_url` que forneça um link para o portal do cliente: ```html Manage Billing ``` Após sair do portal do cliente, o cliente volta ao seu site em `return_url`. Continue a [monitorar eventos](https://docs.stripe.com/billing/subscriptions/webhooks.md) para monitorar o status da assinatura do cliente. Se você configurar o portal do cliente para permitir ações como o cancelamento de uma assinatura, certifique-se de monitorar [eventos adicionais](https://docs.stripe.com/customer-management/integrate-customer-portal.md#webhooks). ## Provisionar acesso Se a sua plataforma Connect utiliza [Contas configuradas pelo cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), utilize o nosso [guia](https://docs.stripe.com/connect/use-accounts-as-customers.md) para substituir as referências a `Cliente` e eventos no seu código pelas referências equivalentes da API Accounts v2. Quando a assinatura estiver ativa, dê ao usuário acesso ao seu serviço. Para fazer isso, ouça os eventos `customer.subscription.created`, `customer.subscription.updated` e `customer.subscription.deleted`. Esses eventos passam um objeto de `Assinaturas` que contém um campo `status` indicando se a assinatura está ativa, vencida ou cancelada. Consulte o [ciclo de vida da assinatura ](https://docs.stripe.com/billing/subscriptions/overview.md#subscription-lifecycle) para obter uma lista completa de status. Para gerenciar o acesso ao recurso de seu produto, saiba mais sobre [integrar direitos](https://docs.stripe.com/billing/entitlements.md). No seu gerenciador de webhooks: 1. Verifique o status da assinatura. Se estiver `active`, o usuário terá pago pelo seu produto. 1. Verifique o produto que o cliente assinou e conceda a ele acesso ao seu serviço. Ao verificar o produto em vez do preço, você pode alterar o preço ou o período de cobrança, conforme necessário. 1. Armazene o `product.id`, `subscription.id` e `subscription.status` no seu banco de dados junto com o `customer.id` que já salvou. Verifique esse registro quando determinar quais recursos precisam ser ativados para o usuário no seu aplicativo. O status da assinatura pode mudar a qualquer momento durante sua vida útil, mesmo que sua inscrição não faça nenhuma chamada direta para a Stripe. Por exemplo, uma renovação pode falhar devido a um cartão vencido, o que coloca a assinatura em um status vencido. Ou, se você implementar o [portal do cliente ](https://docs.stripe.com/customer-management.md), um usuário poderá cancelar a assinatura sem visitar diretamente a inscrição. A implementação correta do seu manipulador mantém o status da inscrição em sincronia com a Stripe. ## Teste a integração ### Testar formas de pagamento Use a tabela a seguir para testar diferentes formas de pagamento e cenários. | Forma de pagamento | Cenário | Como testar | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Débito automático BECS | O cliente paga com débito automático BECS. | Preencha o formulário usando o número da conta `900123456` e BSB `000000`. O PaymentIntent confirmado inicialmente passa para o status `processing`, depois passa para `succeeded` três minutos depois. | | Débito automático BECS | O pagamento do cliente falha com um código de erro `account_closed`. | Preencha o formulário usando o número da conta `111111113` e BSB `000000`. | | Cartão de crédito | O pagamento com cartão é bem-sucedido e não precisa de autenticação. | Preencha o formulário do cartão de crédito usando o número de cartão de crédito `4242 4242 4242 4242` com qualquer validade, CVC e código postal. | | Cartão de crédito | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número `4000 0025 0000 3155` com qualquer validade, CVC e código postal. | | Cartão de crédito | O cartão é recusado com um código de recusa como `insufficient_funds`. | Preencha o formulário do cartão de crédito usando o número `4000 0000 0000 9995` com qualquer validade, CVC e código postal. | | Débito automático SEPA | O cliente paga com débito automático SEPA. | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processing e, três minutos depois, para succeeded. | | Débito automático SEPA | O status do PaymentIntent do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`. | ### Monitorar eventos Configure Webhooks para ouvir os eventos de alteração de assinatura, como upgrades e cancelamentos. você pode visualizar [eventos de Webhook de assinatura](https://docs.stripe.com/billing/subscriptions/webhooks.md) no [Dashboard](https://dashboard.stripe.com/test/events) ou com o [Stripe CLI](https://docs.stripe.com/webhooks.md#test-webhook). Saiba mais sobre [testando sua integração de Faturamento](https://docs.stripe.com/billing/testing.md). #### Elements #### API Checkout Sessions #### Esforço de integração Complexity: 3/5 #### Tipo de integração Combine componentes de IU em um fluxo de pagamento personalizado #### Personalização da IU Personalização no nível de CSS com [Aparência da API](https://docs.stripe.com/elements/appearance-api.md) [Experimente](https://checkout.stripe.dev/) Crie um formulário de pagamento personalizado usando o [Stripe Elements](https://docs.stripe.com/payments/elements.md) e [API Payment Intents](https://docs.stripe.com/api/checkout/sessions.md) para vender *subscriptions* (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) de preço fixo. Veja como essa integração [se compara aos outros tipos de integração da Stripe](https://docs.stripe.com/payments/online-payments.md#compare-features-and-availability). A API Checkout Sessions oferece suporte integrado para cálculo de impostos, descontos, envio e conversão de moedas, reduzindo a quantidade de código personalizado que você precisa escrever. Esta é a abordagem recomendada para a maioria das integrações. Saiba mais sobre [quando usar Checkout Sessions em vez de PaymentIntents](https://docs.stripe.com/payments/checkout-sessions-and-payment-intents-comparison.md). Se você não quiser criar um formulário de pagamento personalizado, pode integrar-se com a versão hospedada do Checkout. Para uma versão completa desse guia de integração de ponta a ponta, veja o [Faturamento QuickStart](https://docs.stripe.com/billing/quickstart.md). Se você não estiver pronto para codificar uma integração, pode configurar assinaturas básicas [manualmente no Dashboard](https://docs.stripe.com/no-code/subscriptions.md). Você também pode usar o [Payment Links](https://docs.stripe.com/payment-links.md) para configurar assinaturas sem precisar escrever nenhum código. Saiba mais sobre como [projetar uma integração](https://docs.stripe.com/billing/subscriptions/design-an-integration.md) para entender as decisões que você precisa tomar e os recursos necessários. ## O que você vai criar Este guia ensina a: - Modelar seus negócios criando um catálogo de produtos. - Construir um processo de registro que cria um cliente. - Criar assinaturas e coletar dados de pagamento. - Testar e monitorar o status do pagamento e da assinatura. - Permitir que os clientes alterem o plano ou cancelem a assinatura. ### Definições de objetos de API | Recurso | Definição | | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Conta configurada como cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer) | Represents a customer in the Accounts v2 API who purchases a subscription. Configure an `Account` object as a customer and associate it with a subscription to make and track recurring charges and to manage the products that they subscribe to. For more information, see the [Use Accounts as customers guide](https://docs.stripe.com/connect/use-accounts-as-customers.md). | | [Cliente](https://docs.stripe.com/api/customers.md) | Represents a customer in the Customers API who purchases a subscription. Use the `Customer` object associated with a subscription to make and track recurring charges and to manage the products that they subscribe to. | | [Direito](https://docs.stripe.com/api/entitlements/active-entitlement.md) | Representa o acesso de um cliente a um recurso incluído em um produto de serviço que assina. Quando você cria uma assinatura para a compra recorrente de um produto por um cliente, um direito ativo é automaticamente criado para cada recurso associado a esse produto. Quando um cliente acessa seus serviços, use os direitos ativos para habilitar os recursos incluídos na assinatura. | | [Recurso](https://docs.stripe.com/api/entitlements/feature.md) | Representa uma função ou capacidade que seus clientes podem acessar quando assinam um produto de serviço. Você pode incluir recursos em um produto criando ProductFeatures. | | [Fatura](https://docs.stripe.com/api/invoices.md) | Uma declaração de valores devidos por um cliente que acompanha os status de pagamento desde o esboço até o pagamento (ou outro tipo de finalização). As assinaturas geram faturas automaticamente. | | [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) | Uma maneira de criar fluxos de pagamentos dinâmicos. Um PaymentIntent acompanha o ciclo de vida do fluxo de checkout de um cliente e aciona etapas adicionais de autenticação quando for exigido por mandatos regulatórios, regras personalizadas contra fraudes do Radar ou formas de pagamento baseadas em redirecionamento. As faturas criam PaymentIntents automaticamente. | | [PaymentMethod](https://docs.stripe.com/api/payment_methods.md) | A customer’s payment methods that they use to pay for your products. For example, you can store a credit card on a customer-configured `Account` or `Customer` object and use it to make recurring payments for that customer. Typically used with the Payment Intents or Setup Intents APIs. | | [Price](https://docs.stripe.com/api/prices.md) | Define o preço unitário, a moeda e o ciclo de faturamento de um produto. | | [Product](https://docs.stripe.com/api/products.md) | Um produto ou serviço que sua empresa vende. Um produto de serviço pode incluir um ou mais recursos. | | [ProductFeature](https://docs.stripe.com/api/product-feature.md) | Representa a inclusão de um único recurso em um único produto. Cada produto está associado a um ProductFeature para cada recurso que é incluído, e cada recurso é associado a um ProductFeature para cada produto que o inclui. | | [Subscription](https://docs.stripe.com/api/subscriptions.md) | Representa a compra recorrente agendada de um produto por um cliente. Use uma assinatura para coletar pagamentos e fornecer entregas repetidas ou acesso contínuo a um produto. | Aqui está um exemplo de como produtos, recursos e direitos funcionam juntos. Imagine que você deseja configurar um serviço de assinatura que oferece dois níveis: um produto padrão com funções básicas e um produto avançado que adiciona funções estendidas. 1. Você cria dois recursos: `basic_features` e `extended_features`. 1. Você cria dois produtos: `standard_product` e `advanced_product`. 1. Para o produto padrão, você cria uma ProductFeature que associa `basic_features` com `standard_product`. 1. Para o produto avançado, você cria duas ProductFeatures: uma que associa `basic_features` com `advanced_product` e outra que associa `extended_features` com `advanced_product`. Um cliente, `first_customer`, assina o produto padrão. Quando você cria a assinatura, a Stripe cria automaticamente um Entitlement que associa `first_customer` com `basic_features`. Outro cliente, `second_customer`, assina o produto avançado. Quando você cria a assinatura, a Stripe cria automaticamente dois Entitlements: um que associa `second_customer` a `basic_features` e outro que associa `second_customer` com `extended_features`. É possível determinar quais recursos fornecer para um cliente [recuperando seus direitos ativos ou escutando o evento Active Entitlement Summary](https://docs.stripe.com/billing/entitlements.md#entitlements). Você não precisa buscar as assinaturas, os produtos e os recursos dele. ## Configurar a Stripe Instale o cliente Stripe de sua escolha: #### 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' ``` Em seguida, instale o Stripe CLI. O CLI fornece testes de webhooks, e você pode executá-lo para fazer chamadas de API para a Stripe. Este guia mostra a você como usar o CLI para configurar um modelo de preços em uma seção posterior. Para obter opções de instalação adicionais, consulte [Comece a usar o Stripe CLI](https://docs.stripe.com/stripe-cli.md). ## Criar o modelo de preços [Stripe CLI ou Dashboard] [Modelos de planos de preços recorrentes](https://docs.stripe.com/products-prices/pricing-models.md) representam os produtos ou serviços que você vende, quanto custam, quais moedas você aceita para pagamentos e o período de serviço para assinaturas. Para montar o modelo de preços, crie [produtos](https://docs.stripe.com/api/products.md) (o que você vende) e [ preços](https://docs.stripe.com/api/prices.md) (quanto e com que frequência cobrar pelos seus produtos). Este exemplo utiliza um plano de preços de taxa fixa com duas opções de nível de serviço diferentes: básico e premium. Para cada opção de nível de serviço, você precisa criar um produto e um preço recorrente. Para adicionar uma cobrança pontual, como uma tarifa de abertura, crie um terceiro produto com um preço pontual. Cada produto fatura em intervalos mensais. O preço do produto básico é 5 USD. O preço do produto premium é 15 USD. Consulte o guia de [plano de preços de taxa fixa](https://docs.stripe.com/subscriptions/pricing-models/flat-rate-pricing.md) para ver um exemplo com três níveis. #### Dashboard Acesse a página [Adicionar um produto](https://dashboard.stripe.com/test/products/create) e crie dois produtos. Adicione um preço para cada produto, cada um com um período de faturamento mensal recorrente: - Produto premium: serviço premium com recursos extras - Preço: Tarifa fixa | 15 USD - Produto básico: serviço básico com recursos mínimos - Preço: Tarifa fixa | 5 USD Depois de criar os preços, registre o ID deles para utilizá-los em outras etapas. Os IDs de preço têm esta estrutura: `price_G0FvDp6vZvdwRZ`. Quando tudo estiver pronto, use o botão **Copiar para modo de produção**, no canto superior direito, para clonar seu produto de [uma área restrita para o modo de produção](https://docs.stripe.com/keys.md#test-live-modes). #### API Você pode usar a API para criar os [produtos](https://docs.stripe.com/api/products.md) e os [ preços](https://docs.stripe.com/api/prices.md). Criar o produto premium: ```curl curl https://api.stripe.com/v1/products \ -u "<>:" \ --data-urlencode "name=Billing Guide: Premium Service" \ -d "description=Premium service with extra features" ``` Criar o produto básico: ```curl curl https://api.stripe.com/v1/products \ -u "<>:" \ --data-urlencode "name=Billing Guide: Basic Service" \ -d "description=Basic service with minimum features" ``` Registre os IDs de cada produto. Eles têm esta estrutura: ```json { "id": "prod_H94k5odtwJXMtQ", "object": "product", "active": true, "attributes": [ ], "created": 1587577341, "description": "Premium service with extra features", "images": [ ], "livemode": false, "metadata": { }, "name": "Billing Guide: Premium Service", "statement_descriptor": null, "type": "service", "unit_label": null, "updated": 1587577341 } ``` Use os IDs de produto para criar um preço para cada produto. O número [unit_amount](https://docs.stripe.com/api/prices/object.md#price_object-unit_amount) está em centavos. Por exemplo, `1500` = 15 USD. Criar o preço premium: ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d product={{PREMIUM_PRODUCT_ID}} \ -d unit_amount=1500 \ -d currency=usd \ -d "recurring[interval]=month" ``` Criar o preço básico: ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d product={{BASIC_PRODUCT_ID}} \ -d unit_amount=500 \ -d currency=usd \ -d "recurring[interval]=month" ``` Registre os IDs de cada preço, para que possam ser usados em etapas subsequentes. Eles têm esta estrutura: ```json { "id": "price_HGd7M3DV3IMXkC", "object": "price", "product": "prod_HGd6W1VUqqXGvr", "type": "recurring", "currency": "usd", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "active": true, "billing_scheme": "per_unit", "created": 1589319695, "livemode": false, "lookup_key": null, "metadata": {}, "nickname": null, "unit_amount": 1500, "unit_amount_decimal": "1500", "tiers": null, "tiers_mode": null, "transform_quantity": null } ``` ## Criar o cliente [Cliente e servidor] Se a sua plataforma Connect utiliza [Contas configuradas pelo cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), utilize o nosso [guia](https://docs.stripe.com/connect/use-accounts-as-customers.md) para substituir as referências a `Cliente` e eventos no seu código pelas referências equivalentes da API Accounts v2. A Stripe precisa de um *Customer{% /glossary % para cada assinatura. No frontend da sua inscrição, recolha todas as informações necessárias dos seus usuários e passe para o backend.* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) Se for necessário coletar informações de endereço, o Address Element permite que você colete endereço de entrega ou de cobrança dos seus clientes. Para mais detalhes sobre esse componente, veja a página do [Address Element](https://docs.stripe.com/elements/address-element.md). ```html ``` ```javascript const emailInput = document.querySelector('#email'); fetch('/create-customer', { method: 'post', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ email: emailInput.value, }), }).then(r => r.json()); ``` No servidor, crie o objeto Customer da Stripe. > Certifique-se de armazenar o [ID do cliente](https://docs.stripe.com/api/customers/object.md#customer_object-id) para utilizá-lo ao iniciar uma sessão de checkout. ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d email={{CUSTOMER_EMAIL}} \ -d name={{CUSTOMER_NAME}} \ -d "shipping[address][city]=Brothers" \ -d "shipping[address][country]=US" \ -d "shipping[address][line1]=27 Fredrick Ave" \ -d "shipping[address][postal_code]=97712" \ -d "shipping[address][state]=CA" \ -d "shipping[name]={{CUSTOMER_NAME}}" \ -d "address[city]=Brothers" \ -d "address[country]=US" \ -d "address[line1]=27 Fredrick Ave" \ -d "address[postal_code]=97712" \ -d "address[state]=CA" ``` ## Criar uma sessão do Checkout [Servidor] No back-end de sua inscrição, defina um endpoint que [crie a sessão](https://docs.stripe.com/api/checkout/sessions/create.md) para ser chamada pelo front-end. você precisará da ID de preço da assinatura na qual o cliente está registrando-se - seu front end passa esse valor. Se você criou um preço único no [passo 2](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md#create-pricing-model), envie também essa ID de preço. Depois de criar uma Checkout Session, certifique-se de passar o [segredo do cliente ](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-client_secret) de volta para o cliente na resposta. > Você pode usar [lookup_keys](https://docs.stripe.com/products-prices/manage-prices.md#lookup-keys) para buscar preços em vez dos IDs de preço. Consulte a [inscrição de amostra](https://github.com/stripe-samples/subscription-use-cases/tree/main/fixed-price-subscriptions) para ver um exemplo. #### Ruby ```ruby require 'stripe' require 'sinatra' # This test secret API key is a placeholder. Don't include personal details in requests with this key. # To see your test secret API key embedded in code samples, sign in to your Stripe account. # You can also find your test secret API key at https://dashboard.stripe.com/test/apikeys. Stripe.api_key = '<>' Stripe.api_version = '2026-03-25.dahlia' set :static, true set :port, 4242 YOUR_DOMAIN = 'http://localhost:3000' post '/create-checkout-session' do content_type 'application/json' session = Stripe::Checkout::Session.create({ui_mode: 'elements', # Provide the customer ID of the customer you previously created customer: '{{CUSTOMER_ID}}', line_items: [{ # Provide the exact Price ID (for example, price_1234) of the product you want to sell price: '{{PRICE_ID}}', quantity: 1, }], mode: 'subscription', return_url: YOUR_DOMAIN + '/return?session_id={CHECKOUT_SESSION_ID}', }) { clientSecret: session.client_secret }.to_json end ``` No [Dashboard ](https://dashboard.stripe.com/settings/payment_methods), ative as formas de pagamento que você deseja aceitar de seus clientes. O Checkout aceita [várias formas de pagamento](https://docs.stripe.com/payments/payment-methods/payment-method-support.md#product-support). ## Inicializar o Checkout [Cliente] #### HTML + JS Chame [initCheckoutElementsSdk](https://docs.stripe.com/js/custom_checkout/init), passando o `clientSecret`. `initCheckoutElementsSdk` retorna um objeto [Checkout](https://docs.stripe.com/js/custom_checkout) que contém dados da Checkout Session e métodos para atualizá-lo. Leia o `total` e `lineItems` de [actions.getSession()](https://docs.stripe.com/js/custom_checkout/session), e exibi-os na sua IU. Isso permite ativar novos recursos com mínimas alterações no código. Por exemplo, somando [preços de moeda manual](https://docs.stripe.com/payments/custom/localize-prices/manual-currency-prices.md) não requer alterações na IU se você exibir o `total`. ```html

``` ```javascript const clientSecret = fetch('/create-checkout-session', {method: 'POST'}) .then((response) => response.json()) .then((json) => json.client_secret); const checkout = stripe.initCheckoutElementsSdk({clientSecret}); const loadActionsResult = await checkout.loadActions(); if (loadActionsResult.type === 'success') { const session = loadActionsResult.actions.getSession(); const checkoutContainer = document.getElementById('checkout-container'); checkoutContainer.append(JSON.stringify(session.lineItems, null, 2)); checkoutContainer.append(document.createElement('br')); checkoutContainer.append(`Total: ${session.total.total.amount}`); } ``` #### React Envolva seu aplicativo com o componente [CheckoutElementsProvider](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider), passando `clientSecret` e a instância `stripe`. ```jsx import React from 'react'; import {CheckoutElementsProvider} from '@stripe/react-stripe-js/checkout'; import CheckoutForm from './CheckoutForm'; const clientSecret = fetch('/create-checkout-session', {method: 'POST'}) .then((response) => response.json()) .then((json) => json.client_secret); const App = () => { return ( ); }; export default App; ``` Acesse o objeto do [Checkout](https://docs.stripe.com/js/custom_checkout) no seu componente do formulário de checkout usando o hook `useCheckout()`. O objeto do `Checkout` contém dados da sessão de checkout e métodos para atualizá-lo. Leia o `total` e `lineItems` do objeto do `Checkout` e exibi-lo na sua IU. Isso permite que você ative recursos com mudanças mínimas no código. Por exemplo, somando [preços de moeda manualmente](https://docs.stripe.com/payments/custom/localize-prices/manual-currency-prices.md) não requer alterações na IU se você exibir o `total`. ```jsx import React from 'react'; import {useCheckout} from '@stripe/react-stripe-js/checkout'; const CheckoutForm = () => {const checkoutState = useCheckout(); if (checkoutState.type === 'loading') { return (

); } if (checkoutState.type === 'error') { return (

Error: {checkoutState.error.message}

); } return ( ); }; ``` ## Colete dados de pagamento [Cliente] Colete dados de pagamento no cliente com o [Payment Element](https://docs.stripe.com/payments/payment-element.md). O Payment Element é um componente de IU que simplifica a coleta de dados de pagamento para diversas formas de pagamento. O Payment Element contém um iframe que envia dados de pagamento com segurança à Stripe por uma conexão HTTPS. Evite colocar o Payment Element dentro de outro iframe porque algumas formas de pagamento exigem o redirecionamento para outra página para confirmação do pagamento. Se você optar por usar um iframe e quiser aceitar Apple Pay ou Google Pay, o iframe deve ter o atributo [permitir](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-allowpaymentrequest) definido como igual a `"pagamento *"`. O endereço da página de Checkout deve começar com `https://` rather em vez de `http://` for para que sua integração funcione corretamente. Você pode testar sua integração sem usar HTTPS, mas lembre-se de [habilitá-lo](https://docs.stripe.com/security/guide.md#tls) quando estiver pronto para aceitar pagamentos em tempo real. #### HTML + JS Primeiro, crie um elemento DOM de contêiner para montar o [Payment Element](https://docs.stripe.com/payments/payment-element.md). Em seguida, crie uma instância do `Payment Element` usando [checkout.createPaymentElement](https://docs.stripe.com/js/custom_checkout/create_payment_element) e monte-a chamando [element.mount](https://docs.stripe.com/js/element/mount), fornecendo um seletor CSS ou o elemento DOM do contêiner. ```html

``` ```javascript const paymentElement = checkout.createPaymentElement(); paymentElement.mount('#payment-element'); ``` Veja as opções disponíveis na documentação da [Stripe.js](https://docs.stripe.com/js/custom_checkout/create_payment_element#custom_checkout_create_payment_element-options). Você pode [personalizar a aparência](https://docs.stripe.com/payments/checkout/customization/appearance.md) de todos os Elements passando [elementsOptions.appearance](https://docs.stripe.com/js/custom_checkout/init#custom_checkout_init-options-elementsOptions-appearance) ao inicializar o Checkout no frontend. #### React Monte o componente [Payment Element](https://docs.stripe.com/payments/payment-element.md) dentro do [CheckoutElementsProvider](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider). ```jsx import React from 'react';import {PaymentElement, useCheckout} from '@stripe/react-stripe-js/checkout'; const CheckoutForm = () => { const checkoutState = useCheckout(); if (checkoutState.type === 'loading') { return (

); } if (checkoutState.type === 'error') { return (

Error: {checkoutState.error.message}

); } return (

{JSON.stringify(checkoutState.checkout.lineItems, null, 2)} {/* A formatted total amount */} Total: {checkoutState.checkout.total.total.amount} ); }; export default CheckoutForm; ``` Veja as opções disponíveis na documentação da [Stripe.js](https://docs.stripe.com/js/custom_checkout/create_payment_element#custom_checkout_create_payment_element-options). Você pode [personalizar a aparência](https://docs.stripe.com/payments/checkout/customization/appearance.md) de todos os Elements passando [elementsOptions.appearance](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider#react_checkout_provider-options-elementsOptions-appearance) para o [CheckoutElementsProvider](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider). ## Envie o pagamento [Lado do cliente] #### HTML + JS Renderize um botão **Pagar** que chame a [confirmação](https://docs.stripe.com/js/custom_checkout/confirm) da instância `Checkout` para enviar o pagamento. ```html

``` ```js const checkout = stripe.initCheckoutElementsSdk({clientSecret}); checkout.on('change', (session) => { document.getElementById('pay-button').disabled = !session.canConfirm; }); const loadActionsResult = await checkout.loadActions(); if (loadActionsResult.type === 'success') { const {actions} = loadActionsResult; const button = document.getElementById('pay-button'); const errors = document.getElementById('confirm-errors'); button.addEventListener('click', () => { // Clear any validation errors errors.textContent = ''; actions.confirm().then((result) => { if (result.type === 'error') { errors.textContent = result.error.message; } }); }); } ``` #### React Renderize um botão **Pagar** que chame [confirm](https://docs.stripe.com/js/custom_checkout/confirm) do [useCheckout](https://docs.stripe.com/js/react_stripe_js/checkout/use_checkout) para submeter o pagamento. ```jsx import React from 'react'; import {useCheckout} from '@stripe/react-stripe-js/checkout'; const PayButton = () => { const checkoutState = useCheckout(); const [loading, setLoading] = React.useState(false); const [error, setError] = React.useState(null); if (checkoutState.type !== "success") { return null; } const handleClick = () => { setLoading(true);checkoutState.checkout.confirm().then((result) => { if (result.type === 'error') { setError(result.error) } setLoading(false); }) }; return (

{error &&

{error.message}

}

) }; export default PayButton; ``` ## Procuro por webhooks [Servidor] Para concluir a integração, você precisa processar *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) enviados pela Stripe. Esses eventos são acionados sempre que o status na Stripe muda, como assinaturas que criam novas faturas. No seu aplicativo, configure um manipulador HTTP para aceitar uma solicitação POST contendo o evento webhook e verifique a assinatura do evento: #### 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 = '<>' post '/webhook' do # You can use webhooks to receive information about asynchronous payment events. # For more about our webhook events check out https://stripe.com/docs/webhooks. webhook_secret = ENV['STRIPE_WEBHOOK_SECRET'] payload = request.body.read if !webhook_secret.empty? # Retrieve the event by verifying the signature using the raw body and secret if webhook signing is configured. sig_header = request.env['HTTP_STRIPE_SIGNATURE'] event = nil begin event = Stripe::Webhook.construct_event( payload, sig_header, webhook_secret ) rescue JSON::ParserError => e # Invalid payload status 400 return rescue Stripe::SignatureVerificationError => e # Invalid signature puts '⚠️ Webhook signature verification failed.' status 400 return end else data = JSON.parse(payload, symbolize_names: true) event = Stripe::Event.construct_from(data) end # Get the type of webhook event sent - used to check the status of PaymentIntents. event_type = event['type'] data = event['data'] data_object = data['object'] if event_type == 'invoice.paid' # Used to provision services after the trial has ended. # The status of the invoice will show up as paid. Store the status in your # database to reference when a user accesses your service to avoid hitting rate # limits. # puts data_object end if event_type == 'invoice.payment_failed' # If the payment fails or the customer doesn't have a valid payment method, # an invoice.payment_failed event is sent, the subscription becomes past_due. # Use this webhook to notify your user that their payment has # failed and to retrieve new card details. # puts data_object end if event_type == 'customer.subscription.deleted' # handle subscription canceled automatically based # upon your subscription settings. Or if the user cancels it. # puts data_object end content_type 'application/json' { status: 'success' }.to_json end ``` Durante o desenvolvimento, use a CLI da Stripe para [observar Webhooks e encaminhá-los para sua inscrição](https://docs.stripe.com/webhooks.md#test-webhook). Execute o seguinte em um novo terminal enquanto seu aplicativo de desenvolvimento estiver em execução: #### curl ```bash stripe listen --forward-to localhost:4242/webhook ``` Para produção, configure um URL de endpoint de webhook no Dashboard ou use a API [Webhook Endpoints](https://docs.stripe.com/api/webhook_endpoints.md). Você precisa ouvir alguns eventos para concluir as etapas restantes deste guia. Consulte [Eventos de assinatura](https://docs.stripe.com/billing/subscriptions/webhooks.md#events) para obter mais detalhes sobre Webhooks específicos de assinatura. ## Providenciar acesso ao seu serviço [Cliente e servidor] Agora que a assinatura está ativa, dê ao usuário acesso ao seu serviço. Para fazer isso, ouça os eventos `customer.subscription.created`, `customer.subscription.updated` e `customer.subscription.deleted`. Esses eventos passam um objeto de assinatura que contém um campo `status` indicando se a assinatura está ativa, vencida ou cancelada. Consulte [o ciclo de vida da assinatura](https://docs.stripe.com/billing/subscriptions/overview.md#subscription-lifecycle) para obter uma lista completa de status. No seu gerenciador de webhooks: 1. Verifique o status da assinatura. Se estiver `ativo`, então o usuário pagou pelo seu produto. 1. Confira o produto que o cliente assinou e conceda acesso ao serviço. Verificar o produto em vez do preço proporciona mais flexibilidade, caso seja necessário alterar os preços ou o período de faturamento. 1. Armazene o `product.id`, `subscription.id` e `subscription.status` no seu banco de dados junto com o `customer.id` que já salvou. Verifique esse registro quando determinar quais recursos precisam ser ativados para o usuário no seu aplicativo. O status de uma assinatura pode mudar a qualquer momento durante sua existência, mesmo que seu aplicativo não faça chamadas diretas para a Stripe. Por exemplo, uma renovação pode falhar devido a um cartão de crédito expirado, o que coloca a assinatura em um status de vencida. Ou, se você implementar o [portal do cliente](https://docs.stripe.com/customer-management.md), um usuário pode cancelar a assinatura sem acessar diretamente seu aplicativo. A implementação correta do manipulador mantém o status do seu aplicativo sincronizado com a Stripe. ## Cancelar a assinatura [Cliente e servidor] É comum permitir que os clientes cancelem suas assinaturas. Este exemplo adiciona uma opção de cancelamento à página de configurações da conta. ![Exemplo de interface de cancelamento de assinatura.](https://b.stripecdn.com/docs-statics-srv/assets/fixed-price-subscriptions-guide-account-settings.6559626ba4b434826a67abfea165e097.png) Configurações da conta com a capacidade de cancelar a assinatura ```javascript function cancelSubscription(subscriptionId) { return fetch('/cancel-subscription', { method: 'post', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ subscriptionId: subscriptionId, }), }) .then(response => { return response.json(); }) .then(cancelSubscriptionResponse => { // Display to the user that the subscription has been canceled. }); } ``` No back-end, configure um endpoint para ser chamado pelo front-end. #### 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 = '<>' post '/cancel-subscription' do content_type 'application/json' data = JSON.parse request.body.read deleted_subscription = Stripe::Subscription.cancel(data['subscriptionId']) deleted_subscription.to_json end ``` Seu aplicativo recebe um evento `customer.subscription.deleted`. Após o cancelamento da assinatura, atualize seu banco de dados para remover o ID da assinatura do Stripe previamente armazenado e restrinja o acesso ao seu serviço. Quando uma assinatura é cancelada, você não pode reativá-la. Em vez disso, recolha as informações de faturamento atualizadas do cliente, atualize as formas de pagamento padrão e crie uma nova assinatura com o registro de cliente existente. ## Teste a integração ### Testar formas de pagamento Use a tabela a seguir para testar diferentes formas de pagamento e cenários. | Forma de pagamento | Cenário | Como testar | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Débito automático BECS | O cliente paga com débito automático BECS. | Preencha o formulário usando o número da conta `900123456` e BSB `000000`. O PaymentIntent confirmado inicialmente passa para o status `processing`, depois passa para `succeeded` três minutos depois. | | Débito automático BECS | O pagamento do cliente falha com um código de erro `account_closed`. | Preencha o formulário usando o número da conta `111111113` e BSB `000000`. | | Cartão de crédito | O pagamento com cartão é bem-sucedido e não precisa de autenticação. | Preencha o formulário do cartão de crédito usando o número de cartão de crédito `4242 4242 4242 4242` com qualquer validade, CVC e código postal. | | Cartão de crédito | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número `4000 0025 0000 3155` com qualquer validade, CVC e código postal. | | Cartão de crédito | O cartão é recusado com um código de recusa como `insufficient_funds`. | Preencha o formulário do cartão de crédito usando o número `4000 0000 0000 9995` com qualquer validade, CVC e código postal. | | Débito automático SEPA | O cliente paga com débito automático SEPA. | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processing e, três minutos depois, para succeeded. | | Débito automático SEPA | O status do PaymentIntent do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`. | ### Monitorar eventos Configure Webhooks para ouvir os eventos de alteração de assinatura, como upgrades e cancelamentos. Saiba mais sobre os [Webhooks de assinatura ](https://docs.stripe.com/billing/subscriptions/webhooks.md) . você pode visualizar eventos no [Dashboard](https://dashboard.stripe.com/test/events) ou com o [Stripe CLI](https://docs.stripe.com/webhooks.md#test-webhook). Para obter mais detalhes, consulte [testando sua integração com o Billing](https://docs.stripe.com/billing/testing.md). ## Optional: Permita que os clientes alterem seus planos [Cliente e servidor] Para permitir que seus clientes alterem assinaturas, obtenha o ID do preço da opção para a qual desejam mudar. Em seguida, envie o ID do novo preço do front-end para um endpoint de back-end. Este exemplo também passa o ID da assinatura, mas é possível acessá-la no seu banco de dados para seu usuário conectado. ```javascript function updateSubscription(priceId, subscriptionId) { return fetch('/update-subscription', { method: 'post', headers: { 'Content-type': 'application/json', }, body: JSON.stringify({ subscriptionId: subscriptionId, newPriceId: priceId, }), }) .then(response => { return response.json(); }) .then(response => { return response; }); } ``` No back-end, defina o endpoint para a chamada do seu front-end, passando o ID da assinatura e o ID do novo preço. A assinatura agora é Premium, a US$ 15 por mês, em vez de Básica a US$ 5 por mês. #### 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 = '<>' post '/update-subscription' do content_type 'application/json' data = JSON.parse request.body.read subscription = Stripe::Subscription.retrieve(data['subscriptionId']) updated_subscription = Stripe::Subscription.update( data['subscriptionId'], cancel_at_period_end: false, items: [ { id: subscription.items.data[0].id, price: data['newPriceId'] } ] ) updated_subscription.to_json end ``` Seu aplicativo recebe um evento `customer.subscription.updated`. ## Optional: Prévia de uma alteração de preço [Cliente e servidor] Quando o cliente altera sua assinatura, geralmente há um ajuste no valor devido, conhecido como [pro rata](https://docs.stripe.com/billing/subscriptions/prorations.md). Você pode usar o endpoint [create preview invoice](https://docs.stripe.com/api/invoices/create_preview.md) para exibir o valor ajustado aos seus clientes. No front-end, envie os detalhes da fatura gerada para um endpoint do backend. ```javascript function createPreviewInvoice( customerId, subscriptionId, newPriceId, trialEndDate ) { return fetch('/create-preview-invoice', { method: 'post', headers: { 'Content-type': 'application/json', }, body: JSON.stringify({ customerId: customerId, subscriptionId: subscriptionId, newPriceId: newPriceId, }), }) .then(response => { return response.json(); }) .then((invoice) => { return invoice; }); } ``` No back-end, configure um endpoint para ser chamado pelo front-end. #### 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 = '<>' post '/create-preview-invoice' do content_type 'application/json' data = JSON.parse request.body.read subscription = Stripe::Subscription.retrieve(data['subscriptionId']) invoice = Stripe::Invoice.create_preview( customer: data['customerId'], subscription: data['subscriptionId'], subscription_details: { items: [ { id: subscription.items.data[0].id, deleted: true }, { price: data['newPriceId'], deleted: false } ] } ) invoice.to_json end ``` ## Optional: Exibir a forma de pagamento do cliente [Cliente e servidor] Exibir a bandeira e os últimos quatro dígitos do cartão do seu cliente informa qual cartão está sendo cobrado ou se é preciso atualizar a forma de pagamento. No front-end, envie o ID do método de pagamento para um endpoint de back-end que recupera os detalhes do método de pagamento. ```javascript function retrieveCustomerPaymentMethod(paymentMethodId) { return fetch('/retrieve-customer-payment-method', { method: 'post', headers: { 'Content-type': 'application/json', }, body: JSON.stringify({ paymentMethodId: paymentMethodId, }), }) .then((response) => { return response.json(); }) .then((response) => { return response; }); } ``` No back-end, configure um endpoint para ser chamado pelo front-end. #### 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 = '<>' post '/retrieve-customer-payment-method' do content_type 'application/json' data = JSON.parse request.body.read payment_method = Stripe::PaymentMethod.retrieve(data['paymentMethodId']) payment_method.to_json end ``` Exemplo de resposta: ```json { "id": "pm_1GcbHY2eZvKYlo2CoqlVxo42", "object": "payment_method", "billing_details": { "address": { "city": null, "country": null, "line1": null, "line2": null, "postal_code": null, "state": null }, "email": null, "name": null, "phone": null }, "card": { "brand": "visa", "checks": { "address_line1_check": null, "address_postal_code_check": null, "cvc_check": "pass" }, "country": "US", "exp_month": 8, "exp_year": 2021, "fingerprint": "Xt5EWLLDS7FJjR1c", "funding": "credit", "generated_from": null, "last4": "4242", "three_d_secure_usage": { "supported": true }, "wallet": null }, "created": 1588010536, "customer": "cus_HAxB7dVQxhoKLh", "livemode": false, "metadata": {}, "type": "card" } ``` > Recomendamos que você salve `paymentMethod.id` e `last4` no banco de dados (por exemplo, `paymentMethod.id` como `stripeCustomerPaymentMethodId` na coleção ou tabela `users`). Você também pode armazenar `exp_month`, `exp_year`, `fingerprint` e `billing_details` conforme necessário. Assim, você reduz o número de chamadas à Stripe para melhorar o desempenho e evitar possíveis limitações de fluxo. ## Divulgue a Stripe para seus clientes A Stripe coleta informações sobre interações do cliente com o Elements para fornecer serviços a você, evitar fraudes e melhorar os serviços. Isso inclui o uso de cookies e endereços IP para identificar quais Elements o cliente visualizou durante uma única sessão de checkout. Você é responsável por divulgar e obter todos os direitos e consentimentos necessários para que a Stripe use os dados dessas maneiras. Para saber mais, acesse nossa [central de privacidade](https://stripe.com/legal/privacy-center#as-a-business-user-what-notice-do-i-provide-to-my-end-customers-about-stripe). #### API Payment Intents #### Esforço de integração Complexity: 4/5 #### Tipo de integração Combine componentes de IU em um fluxo de pagamento personalizado #### Personalização da IU Personalização no nível de CSS com [Aparência da API](https://docs.stripe.com/elements/appearance-api.md) Se a sua plataforma Connect utiliza [Contas configuradas pelo cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), utilize o nosso [guia](https://docs.stripe.com/connect/use-accounts-as-customers.md) para substituir as referências a `Cliente` e eventos no seu código pelas referências equivalentes da API Accounts v2. Crie um formulário de pagamento personalizado usando o [Stripe Elements](https://docs.stripe.com/payments/elements.md) e [API Payment Intents](https://docs.stripe.com/api/payment_intents.md) para vender *subscriptions* (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) de preço fixo. Veja como essa integração [se compara aos outros tipos de integração da Stripe](https://docs.stripe.com/payments/online-payments.md#compare-features-and-availability). A API Payment Intents é uma API de nível inferior que você pode usar para criar seu próprio fluxo de checkout ou pagamentos, mas exige significativamente mais código e manutenção contínua. Recomendamos o [Payment Element com Checkout Sessions](https://docs.stripe.com/payments/quickstart-checkout-sessions.md) para a maioria das integrações porque abrange fluxos de pagamento semelhantes aos Payment Intents. Saiba mais sobre [quando usar Checkout Sessions em vez de Payment Intents](https://docs.stripe.com/payments/checkout-sessions-and-payment-intents-comparison.md). Se você não quiser criar um formulário de pagamento personalizado, pode integrar-se com a versão hospedada do Checkout. Para uma versão completa desse guia de integração de ponta a ponta, veja o [Faturamento QuickStart](https://docs.stripe.com/billing/quickstart.md). Se você não estiver pronto para codificar uma integração, pode configurar assinaturas básicas [manualmente no Dashboard](https://docs.stripe.com/no-code/subscriptions.md). Você também pode usar o [Payment Links](https://docs.stripe.com/payment-links.md) para configurar assinaturas sem precisar escrever nenhum código. Saiba mais sobre como [projetar uma integração](https://docs.stripe.com/billing/subscriptions/design-an-integration.md) para entender as decisões que você precisa tomar e os recursos necessários. ## O que você vai criar Este guia ensina a: - Criar um catálogo dos produtos. - Construir um processo de registro que cria um cliente. - Criar assinaturas e coletar dados de pagamento. - Testar e monitorar o status do pagamento e da assinatura. - Permitir que os clientes alterem o plano ou cancelem a assinatura. - Saiba como usar o [modo de faturamento flexível ](https://docs.stripe.com/billing/subscriptions/billing-mode.md) para acessar o comportamento de faturamento aprimorado e recursos adicionais. ## Como construir na Stripe [As Assinaturas](https://docs.stripe.com/api/subscriptions.md) simplificam o faturamento criando automaticamente *Invoices* e [PaymentIntents](https://docs.stripe.com/api/payment_intents.md) para você. Para criar e ativar uma assinatura, você precisa primeiro criar um *Product* para definir o que está vendendo e um *Price*, que determina o valor a ser cobrado e a frequência. você também precisa de um [Customer](https://docs.stripe.com/api/customers.md) para armazenar os *PaymentMethods* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) usados para fazer cada pagamento recorrente. #### Accounts v2 Um diagrama que ilustra objetos de cobrança comuns e suas relações (See full diagram at https://docs.stripe.com/billing/subscriptions/build-subscriptions) #### Customer v1 Um diagrama que ilustra objetos de cobrança comuns e suas relações (See full diagram at https://docs.stripe.com/billing/subscriptions/build-subscriptions) ### Definições de objetos de API | Recurso | Definição | | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Conta configurada como cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer) | Represents a customer in the Accounts v2 API who purchases a subscription. Configure an `Account` object as a customer and associate it with a subscription to make and track recurring charges and to manage the products that they subscribe to. For more information, see the [Use Accounts as customers guide](https://docs.stripe.com/connect/use-accounts-as-customers.md). | | [Cliente](https://docs.stripe.com/api/customers.md) | Represents a customer in the Customers API who purchases a subscription. Use the `Customer` object associated with a subscription to make and track recurring charges and to manage the products that they subscribe to. | | [Direito](https://docs.stripe.com/api/entitlements/active-entitlement.md) | Representa o acesso de um cliente a um recurso incluído em um produto de serviço que assina. Quando você cria uma assinatura para a compra recorrente de um produto por um cliente, um direito ativo é automaticamente criado para cada recurso associado a esse produto. Quando um cliente acessa seus serviços, use os direitos ativos para habilitar os recursos incluídos na assinatura. | | [Recurso](https://docs.stripe.com/api/entitlements/feature.md) | Representa uma função ou capacidade que seus clientes podem acessar quando assinam um produto de serviço. Você pode incluir recursos em um produto criando ProductFeatures. | | [Fatura](https://docs.stripe.com/api/invoices.md) | Uma declaração de valores devidos por um cliente que acompanha os status de pagamento desde o esboço até o pagamento (ou outro tipo de finalização). As assinaturas geram faturas automaticamente. | | [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) | Uma maneira de criar fluxos de pagamentos dinâmicos. Um PaymentIntent acompanha o ciclo de vida do fluxo de checkout de um cliente e aciona etapas adicionais de autenticação quando for exigido por mandatos regulatórios, regras personalizadas contra fraudes do Radar ou formas de pagamento baseadas em redirecionamento. As faturas criam PaymentIntents automaticamente. | | [PaymentMethod](https://docs.stripe.com/api/payment_methods.md) | A customer’s payment methods that they use to pay for your products. For example, you can store a credit card on a customer-configured `Account` or `Customer` object and use it to make recurring payments for that customer. Typically used with the Payment Intents or Setup Intents APIs. | | [Price](https://docs.stripe.com/api/prices.md) | Define o preço unitário, a moeda e o ciclo de faturamento de um produto. | | [Product](https://docs.stripe.com/api/products.md) | Um produto ou serviço que sua empresa vende. Um produto de serviço pode incluir um ou mais recursos. | | [ProductFeature](https://docs.stripe.com/api/product-feature.md) | Representa a inclusão de um único recurso em um único produto. Cada produto está associado a um ProductFeature para cada recurso que é incluído, e cada recurso é associado a um ProductFeature para cada produto que o inclui. | | [Subscription](https://docs.stripe.com/api/subscriptions.md) | Representa a compra recorrente agendada de um produto por um cliente. Use uma assinatura para coletar pagamentos e fornecer entregas repetidas ou acesso contínuo a um produto. | Aqui está um exemplo de como produtos, recursos e direitos funcionam juntos. Imagine que você deseja configurar um serviço de assinatura que oferece dois níveis: um produto padrão com funções básicas e um produto avançado que adiciona funções estendidas. 1. Você cria dois recursos: `basic_features` e `extended_features`. 1. Você cria dois produtos: `standard_product` e `advanced_product`. 1. Para o produto padrão, você cria uma ProductFeature que associa `basic_features` com `standard_product`. 1. Para o produto avançado, você cria duas ProductFeatures: uma que associa `basic_features` com `advanced_product` e outra que associa `extended_features` com `advanced_product`. Um cliente, `first_customer`, assina o produto padrão. Quando você cria a assinatura, a Stripe cria automaticamente um Entitlement que associa `first_customer` com `basic_features`. Outro cliente, `second_customer`, assina o produto avançado. Quando você cria a assinatura, a Stripe cria automaticamente dois Entitlements: um que associa `second_customer` a `basic_features` e outro que associa `second_customer` com `extended_features`. É possível determinar quais recursos fornecer para um cliente [recuperando seus direitos ativos ou escutando o evento Active Entitlement Summary](https://docs.stripe.com/billing/entitlements.md#entitlements). Você não precisa buscar as assinaturas, os produtos e os recursos dele. ## Configurar a Stripe Instale o cliente Stripe de sua escolha: #### 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' ``` Em seguida, instale a Stripe CLI. A CLI fornece testes de webhooks, e você pode executá-la para fazer chamadas de API para a Stripe. Este guia mostra a você como usar a CLI para configurar um modelo de preços em uma seção posterior. Para obter opções de instalação adicionais, consulte [Comece a usar o Stripe CLI](https://docs.stripe.com/stripe-cli.md). ## Criar o modelo de preços [Stripe CLI ou Dashboard] [Modelos de planos de preços recorrentes](https://docs.stripe.com/products-prices/pricing-models.md) representam os produtos ou serviços que você vende, quanto custam, quais moedas você aceita para pagamentos e o período de serviço para assinaturas. Para montar o modelo de preços, crie [produtos](https://docs.stripe.com/api/products.md) (o que você vende) e [ preços](https://docs.stripe.com/api/prices.md) (quanto e com que frequência cobrar pelos seus produtos). Este exemplo utiliza um plano de preços de taxa fixa com duas opções de nível de serviço diferentes: básico e premium. Para cada opção de nível de serviço, você precisa criar um produto e um preço recorrente. Para adicionar uma cobrança pontual, como uma tarifa de abertura, crie um terceiro produto com um preço pontual. Cada produto fatura em intervalos mensais. O preço do produto básico é 5 USD. O preço do produto premium é 15 USD. Consulte o guia de [plano de preços de taxa fixa](https://docs.stripe.com/subscriptions/pricing-models/flat-rate-pricing.md) para ver um exemplo com três níveis. #### Dashboard Acesse a página [Adicionar um produto](https://dashboard.stripe.com/test/products/create) e crie dois produtos. Adicione um preço para cada produto, cada um com um período de faturamento mensal recorrente: - Produto premium: serviço premium com recursos extras - Preço: Tarifa fixa | 15 USD - Produto básico: serviço básico com recursos mínimos - Preço: Tarifa fixa | 5 USD Depois de criar os preços, registre o ID deles para utilizá-los em outras etapas. Os IDs de preço têm esta estrutura: `price_G0FvDp6vZvdwRZ`. Quando tudo estiver pronto, use o botão **Copiar para modo de produção**, no canto superior direito, para clonar seu produto de [uma área restrita para o modo de produção](https://docs.stripe.com/keys.md#test-live-modes). #### API Você pode usar a API para criar os [produtos](https://docs.stripe.com/api/products.md) e os [ preços](https://docs.stripe.com/api/prices.md). Criar o produto premium: ```curl curl https://api.stripe.com/v1/products \ -u "<>:" \ --data-urlencode "name=Billing Guide: Premium Service" \ -d "description=Premium service with extra features" ``` Criar o produto básico: ```curl curl https://api.stripe.com/v1/products \ -u "<>:" \ --data-urlencode "name=Billing Guide: Basic Service" \ -d "description=Basic service with minimum features" ``` Registre os IDs de cada produto. Eles têm esta estrutura: ```json { "id": "prod_H94k5odtwJXMtQ", "object": "product", "active": true, "attributes": [ ], "created": 1587577341, "description": "Premium service with extra features", "images": [ ], "livemode": false, "metadata": { }, "name": "Billing Guide: Premium Service", "statement_descriptor": null, "type": "service", "unit_label": null, "updated": 1587577341 } ``` Use os IDs de produto para criar um preço para cada produto. O número [unit_amount](https://docs.stripe.com/api/prices/object.md#price_object-unit_amount) está em centavos. Por exemplo, `1500` = 15 USD. Criar o preço premium: ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d product={{PREMIUM_PRODUCT_ID}} \ -d unit_amount=1500 \ -d currency=usd \ -d "recurring[interval]=month" ``` Criar o preço básico: ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d product={{BASIC_PRODUCT_ID}} \ -d unit_amount=500 \ -d currency=usd \ -d "recurring[interval]=month" ``` Registre os IDs de cada preço, para que possam ser usados em etapas subsequentes. Eles têm esta estrutura: ```json { "id": "price_HGd7M3DV3IMXkC", "object": "price", "product": "prod_HGd6W1VUqqXGvr", "type": "recurring", "currency": "usd", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "active": true, "billing_scheme": "per_unit", "created": 1589319695, "livemode": false, "lookup_key": null, "metadata": {}, "nickname": null, "unit_amount": 1500, "unit_amount_decimal": "1500", "tiers": null, "tiers_mode": null, "transform_quantity": null } ``` ## Criar o cliente [Cliente e servidor] Se a sua plataforma Connect utiliza [Contas configuradas pelo cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), utilize o nosso [guia](https://docs.stripe.com/connect/use-accounts-as-customers.md) para substituir as referências a `Cliente` e eventos no seu código pelas referências equivalentes da API Accounts v2. A Stripe precisa de um *Customer{% /glossary % para cada assinatura. No frontend da sua inscrição, recolha todas as informações necessárias dos seus usuários e passe para o backend.* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) Se for necessário coletar informações de endereço, o Address Element permite que você colete endereço de entrega ou de cobrança dos seus clientes. Para mais detalhes sobre esse componente, veja a página do [Address Element](https://docs.stripe.com/elements/address-element.md). ```html ``` ```javascript const emailInput = document.querySelector('#email'); fetch('/create-customer', { method: 'post', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ email: emailInput.value, }), }).then(r => r.json()); ``` No servidor, crie o objeto Customer da Stripe. > Certifique-se de armazenar o [ID do cliente](https://docs.stripe.com/api/customers/object.md#customer_object-id) para utilizá-lo ao iniciar uma sessão de checkout. ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d email={{CUSTOMER_EMAIL}} \ -d name={{CUSTOMER_NAME}} \ -d "shipping[address][city]=Brothers" \ -d "shipping[address][country]=US" \ -d "shipping[address][line1]=27 Fredrick Ave" \ -d "shipping[address][postal_code]=97712" \ -d "shipping[address][state]=CA" \ -d "shipping[name]={{CUSTOMER_NAME}}" \ -d "address[city]=Brothers" \ -d "address[country]=US" \ -d "address[line1]=27 Fredrick Ave" \ -d "address[postal_code]=97712" \ -d "address[state]=CA" ``` ## Criar a assinatura [Cliente e servidor] > Se você quiser renderizar o Element Payment sem antes criar uma assinatura, consulte [Recolher detalhes de pagamento antes de criar uma Intenção](https://docs.stripe.com/payments/accept-a-payment-deferred.md?type=subscription). Permita que o cliente escolha um plano e, em seguida, crie a assinatura. No exemplo deste guia, o cliente escolhe entre o plano Básico e o plano Premium. No front-end, passe o ID do preço selecionado e o ID do registro do cliente para o back-end. ```javascript fetch('/create-subscription', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ priceId: priceId, customerId: customerId, }), }) ``` No back end, crie a assinatura com um status `incomplete` usando `payment_behavior=default_incomplete`. Em seguida, retorne o `client_secret` do primeiro [PaymentIntent](https://docs.stripe.com/payments/payment-intents.md) da assinatura para o front end para concluir o pagamento. Para fazer isso, expanda o [confirmation_secret](https://docs.stripe.com/api/invoices/object.md#invoice_object-confirmation_secret) na última fatura da assinatura. Para ativar o [comportamento aprimorado de assinatura](https://docs.stripe.com/billing/subscriptions/billing-mode.md) , defina `billing_mode[type]` como `flexible`. Você deve usar a versão da API Stripe [2025-06-30.basil](https://docs.stripe.com/changelog/basil.md#2025-06-30.basil) ou posterior. Defina [save_default_payment_method](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-payment_settings-save_default_payment_method) para `on_subscription` para salvar a forma de pagamento como padrão para uma assinatura quando o pagamento for bem-sucedido. Salvar um método de pagamento padrão aumenta a taxa de sucesso de futuros pagamentos de assinatura. The following example creates a `Subscription` and expands the `confirmation_secret` from its latest invoice in the response. That lets you pass the secret to the front end to confirm the payment. #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d payment_behavior=default_incomplete \ -d "payment_settings[save_default_payment_method]=on_subscription" \ -d "billing_mode[type]=flexible" \ -d "expand[0]=latest_invoice.confirmation_secret" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d payment_behavior=default_incomplete \ -d "payment_settings[save_default_payment_method]=on_subscription" \ -d "billing_mode[type]=flexible" \ -d "expand[0]=latest_invoice.confirmation_secret" ``` > Se você estiver usando um *multi-currency price* (A single Price object can support multiple currencies. Each purchase uses one of the supported currencies for the Price, depending on how you use the Price in your integration), use o parâmetro [currency](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-currency) para informar à assinatura qual das moedas aceitas deve ser usada. Se você omitir o parâmetro `currency`, a assinatura usará a moeda padrão. A assinatura agora está `inactive` e está aguardando pagamento. O exemplo de resposta abaixo destaca os campos mínimos a serem armazenados, mas você pode armazenar os campos que o seu aplicativo acessa com frequência. #### Accounts v2 ```json {"id": "sub_JgRjFjhKbtD2qz", "object": "subscription", "application_fee_percent": null, "automatic_tax": { "disabled_reason": null, "enabled": false, "liability": "null" }, "billing_cycle_anchor": 1623873347, "billing_cycle_anchor_config": null, "cancel_at": null, "cancel_at_period_end": false, "canceled_at": null, "cancellation_details": { "comment": null, "feedback": null, "reason": null }, "collection_method": "charge_automatically", "created": 1623873347, "currency": "usd","customer_account": identifier("customerAccount"), "days_until_due": null, "default_payment_method": null, "default_source": null, "default_tax_rates": [ ], "discounts": [], "ended_at": null, "invoice_customer_balance_settings": { "account_tax_ids": null, "issuer": { "type": "self" } }, "items": { "object": "list", "data": [ { "id": "si_JgRjmS4Ur1khEx", "object": "subscription_item", "created": 1623873347,"current_period_end": 1626465347, "current_period_start": 1623873347, "discounts": [], "metadata": { }, "plan": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "plan", "active": true, "amount": 2000, "amount_decimal": "2000", "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "tiers": null, "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "price": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "livemode": false, "lookup_key": null, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "tiers_mode": null, "transform_quantity": null, "type": "recurring", "unit_amount": 2000, "unit_amount_decimal": "2000" }, "quantity": 1, "subscription": "sub_JgRjFjhKbtD2qz", "tax_rates": [ ] } ], "has_more": false, "total_count": 1, "url": "/v1/subscription_items?subscription=sub_JgRjFjhKbtD2qz" }, "latest_invoice": { "id": "in_1J34pzGPZ1iASj5zB87qdBNZ", "object": "invoice", "account_country": "US", "account_name": "Angelina's Store", "account_tax_ids": null, "amount_due": 2000, "amount_overpaid": 0, "amount_paid": 0, "amount_remaining": 2000, "amount_shipping": 0, "attempt_count": 0, "attempted": false, "auto_advance": false, "automatic_tax": { "disabled_reason": null, "enabled": false, "liability": null, "status": null }, "automatically_finalizes_at": null, "billing_reason": "subscription_update", "collection_method": "charge_automatically", "created": 1623873347, "currency": "usd", "custom_fields": null, "customer_account": identifier("customerAccount"), "customer_address": null, "customer_email": "angelina@stripe.com", "customer_name": null, "customer_phone": null, "customer_shipping": { "address": { "city": "", "country": "US", "line1": "Berry", "line2": "", "postal_code": "", "state": "" }, "name": "", "phone": null }, "customer_tax_exempt": "none", "customer_tax_ids": [ ], "default_payment_method": null, "default_source": null, "default_tax_rates": [ ], "description": null, "discounts": [], "due_date": null, "effective_at": "1623873347", "ending_balance": 0, "footer": null, "from_invoice": null, "hosted_invoice_url": "https://invoice.stripe.com/i/acct_1By64KGPZ1iASj5z/invst_JgRjzIOILGeq2MKC9T0KtyXnD5udsLp", "invoice_pdf": "https://pay.stripe.com/invoice/acct_1By64KGPZ1iASj5z/invst_JgRjzIOILGeq2MKC9T0KtyXnD5udsLp/pdf", "last_finalization_error": null, "latest_revision": null, "lines": { "object": "list", "data": [ { "id": "il_1N2CjMBwKQ696a5NeOawRQP2", "object": "line_item", "amount": 2000, "currency": "usd", "description": "1 × Gold Special (at $20.00 / month)", "discount_amounts": [ ], "discountable": true, "discounts": [ ], "invoice": "in_1J34pzGPZ1iASj5zB87qdBNZ", "livemode": false, "metadata": { }, "parent": { "invoice_item_details": null, "subscription_item_details": { "invoice_item": null, "proration": false, "proration_details": { "credited_items": null }, "subscription": "sub_JgRjFjhKbtD2qz", "subscription_item": "si_JgRjmS4Ur1khEx" }, "type": "subscription_item_details" }, "period": { "end": 1626465347, "start": 1623873347 }, "plan": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "plan", "active": true, "amount": 2000, "amount_decimal": "2000", "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "tiers": null, "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "price": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "livemode": false, "lookup_key": null, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "tiers_mode": null, "transform_quantity": null, "type": "recurring", "unit_amount": 2000, "unit_amount_decimal": "2000" }, "quantity": 1, "taxes": [] } ], "has_more": false, "total_count": 1, "url": "/v1/invoices/in_1J34pzGPZ1iASj5zB87qdBNZ/lines" }, "livemode": false, "metadata": { }, "next_payment_attempt": null, "number": "C008FC2-0354", "on_behalf_of": null, "parent": { "quote_details": null, "subscription_details": { "metadata": {}, "pause_collection": null, "subscription": "sub_JgRjFjhKbtD2qz" } }, "payment_intent": { "id": "pi_1J34pzGPZ1iASj5zI2nOAaE6", "object": "payment_intent", "allowed_source_types": [ "card" ], "amount": 2000, "amount_capturable": 0, "amount_received": 0, "application": null, "application_fee_amount": null, "canceled_at": null, "cancellation_reason": null, "capture_method": "automatic", "charges": { "object": "list", "data": [ ], "has_more": false, "total_count": 0, "url": "/v1/charges?payment_intent=pi_1J34pzGPZ1iASj5zI2nOAaE6" }, "client_secret": "pi_1J34pzGPZ1iASj5zI2nOAaE6_secret_l7FN6ldFfXiFmJEumenJ2y2wu", "confirmation_method": "automatic", "created": 1623873347, "currency": "usd", "customer": "cus_CMqDWO2xODTZqt", "description": "Subscription creation", "invoice": "in_1J34pzGPZ1iASj5zB87qdBNZ", "last_payment_error": null, "livemode": false, "metadata": { }, "next_action": null, "next_source_action": null, "on_behalf_of": null, "payment_method": null, "payment_method_options": { "card": { "installments": null, "network": null, "request_three_d_secure": "automatic" } }, "payment_method_types": [ "card" ], "receipt_email": null, "review": null, "setup_future_usage": "off_session", "shipping": null, "source": "card_1By6iQGPZ1iASj5z7ijKBnXJ", "statement_descriptor": null, "statement_descriptor_suffix": null, "status": "requires_confirmation", "transfer_data": null, "transfer_group": null }, "payment_settings": { "payment_method_options": null, "payment_method_types": null, "save_default_payment_method": "on_subscription" }, "period_end": 1623873347, "period_start": 1623873347, "post_payment_credit_notes_amount": 0, "pre_payment_credit_notes_amount": 0, "receipt_number": null, "starting_balance": 0, "statement_descriptor": null, "status": "open", "status_transitions": { "finalized_at": 1623873347, "marked_uncollectible_at": null, "paid_at": null, "voided_at": null }, "subscription": "sub_JgRjFjhKbtD2qz", "subtotal": 2000, "tax": null, "tax_percent": null, "total": 2000, "total_discount_amounts": [], "total_tax_amounts": [], "transfer_data": null, "webhooks_delivered_at": 1623873347 }, "livemode": false, "metadata": { }, "next_pending_invoice_item_invoice": null, "pause_collection": null, "pending_invoice_item_interval": null, "pending_setup_intent": null, "pending_update": null, "plan": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "plan", "active": true, "amount": 2000, "amount_decimal": "2000", "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "tiers": null, "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "quantity": 1, "schedule": null, "start": 1623873347, "start_date": 1623873347, "status": "incomplete", "tax_percent": null, "transfer_data": null, "trial_end": null, "trial_start": null } ``` #### Customers v1 ```json {"id": "sub_JgRjFjhKbtD2qz", "object": "subscription", "application_fee_percent": null, "automatic_tax": { "disabled_reason": null, "enabled": false, "liability": "null" }, "billing_cycle_anchor": 1623873347, "billing_cycle_anchor_config": null, "cancel_at": null, "cancel_at_period_end": false, "canceled_at": null, "cancellation_details": { "comment": null, "feedback": null, "reason": null }, "collection_method": "charge_automatically", "created": 1623873347, "currency": "usd","customer": identifier("customer"), "days_until_due": null, "default_payment_method": null, "default_source": null, "default_tax_rates": [ ], "discounts": [], "ended_at": null, "invoice_customer_balance_settings": { "account_tax_ids": null, "issuer": { "type": "self" } }, "items": { "object": "list", "data": [ { "id": "si_JgRjmS4Ur1khEx", "object": "subscription_item", "created": 1623873347,"current_period_end": 1626465347, "current_period_start": 1623873347, "discounts": [], "metadata": { }, "plan": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "plan", "active": true, "amount": 2000, "amount_decimal": "2000", "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "tiers": null, "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "price": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "livemode": false, "lookup_key": null, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "tiers_mode": null, "transform_quantity": null, "type": "recurring", "unit_amount": 2000, "unit_amount_decimal": "2000" }, "quantity": 1, "subscription": "sub_JgRjFjhKbtD2qz", "tax_rates": [ ] } ], "has_more": false, "total_count": 1, "url": "/v1/subscription_items?subscription=sub_JgRjFjhKbtD2qz" }, "latest_invoice": { "id": "in_1J34pzGPZ1iASj5zB87qdBNZ", "object": "invoice", "account_country": "US", "account_name": "Angelina's Store", "account_tax_ids": null, "amount_due": 2000, "amount_overpaid": 0, "amount_paid": 0, "amount_remaining": 2000, "amount_shipping": 0, "attempt_count": 0, "attempted": false, "auto_advance": false, "automatic_tax": { "disabled_reason": null, "enabled": false, "liability": null, "status": null }, "automatically_finalizes_at": null, "billing_reason": "subscription_update", "collection_method": "charge_automatically", "created": 1623873347, "currency": "usd", "custom_fields": null, "customer": identifier("customer"), "customer_address": null, "customer_email": "angelina@stripe.com", "customer_name": null, "customer_phone": null, "customer_shipping": { "address": { "city": "", "country": "US", "line1": "Berry", "line2": "", "postal_code": "", "state": "" }, "name": "", "phone": null }, "customer_tax_exempt": "none", "customer_tax_ids": [ ], "default_payment_method": null, "default_source": null, "default_tax_rates": [ ], "description": null, "discounts": [], "due_date": null, "effective_at": "1623873347", "ending_balance": 0, "footer": null, "from_invoice": null, "hosted_invoice_url": "https://invoice.stripe.com/i/acct_1By64KGPZ1iASj5z/invst_JgRjzIOILGeq2MKC9T0KtyXnD5udsLp", "invoice_pdf": "https://pay.stripe.com/invoice/acct_1By64KGPZ1iASj5z/invst_JgRjzIOILGeq2MKC9T0KtyXnD5udsLp/pdf", "last_finalization_error": null, "latest_revision": null, "lines": { "object": "list", "data": [ { "id": "il_1N2CjMBwKQ696a5NeOawRQP2", "object": "line_item", "amount": 2000, "currency": "usd", "description": "1 × Gold Special (at $20.00 / month)", "discount_amounts": [ ], "discountable": true, "discounts": [ ], "invoice": "in_1J34pzGPZ1iASj5zB87qdBNZ", "livemode": false, "metadata": { }, "parent": { "invoice_item_details": null, "subscription_item_details": { "invoice_item": null, "proration": false, "proration_details": { "credited_items": null }, "subscription": "sub_JgRjFjhKbtD2qz", "subscription_item": "si_JgRjmS4Ur1khEx" }, "type": "subscription_item_details" }, "period": { "end": 1626465347, "start": 1623873347 }, "plan": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "plan", "active": true, "amount": 2000, "amount_decimal": "2000", "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "tiers": null, "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "price": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "livemode": false, "lookup_key": null, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "tiers_mode": null, "transform_quantity": null, "type": "recurring", "unit_amount": 2000, "unit_amount_decimal": "2000" }, "quantity": 1, "taxes": [] } ], "has_more": false, "total_count": 1, "url": "/v1/invoices/in_1J34pzGPZ1iASj5zB87qdBNZ/lines" }, "livemode": false, "metadata": { }, "next_payment_attempt": null, "number": "C008FC2-0354", "on_behalf_of": null, "parent": { "quote_details": null, "subscription_details": { "metadata": {}, "pause_collection": null, "subscription": "sub_JgRjFjhKbtD2qz" } }, "payment_intent": { "id": "pi_1J34pzGPZ1iASj5zI2nOAaE6", "object": "payment_intent", "allowed_source_types": [ "card" ], "amount": 2000, "amount_capturable": 0, "amount_received": 0, "application": null, "application_fee_amount": null, "canceled_at": null, "cancellation_reason": null, "capture_method": "automatic", "charges": { "object": "list", "data": [ ], "has_more": false, "total_count": 0, "url": "/v1/charges?payment_intent=pi_1J34pzGPZ1iASj5zI2nOAaE6" }, "client_secret": "pi_1J34pzGPZ1iASj5zI2nOAaE6_secret_l7FN6ldFfXiFmJEumenJ2y2wu", "confirmation_method": "automatic", "created": 1623873347, "currency": "usd", "customer": "cus_CMqDWO2xODTZqt", "description": "Subscription creation", "invoice": "in_1J34pzGPZ1iASj5zB87qdBNZ", "last_payment_error": null, "livemode": false, "metadata": { }, "next_action": null, "next_source_action": null, "on_behalf_of": null, "payment_method": null, "payment_method_options": { "card": { "installments": null, "network": null, "request_three_d_secure": "automatic" } }, "payment_method_types": [ "card" ], "receipt_email": null, "review": null, "setup_future_usage": "off_session", "shipping": null, "source": "card_1By6iQGPZ1iASj5z7ijKBnXJ", "statement_descriptor": null, "statement_descriptor_suffix": null, "status": "requires_confirmation", "transfer_data": null, "transfer_group": null }, "payment_settings": { "payment_method_options": null, "payment_method_types": null, "save_default_payment_method": "on_subscription" }, "period_end": 1623873347, "period_start": 1623873347, "post_payment_credit_notes_amount": 0, "pre_payment_credit_notes_amount": 0, "receipt_number": null, "starting_balance": 0, "statement_descriptor": null, "status": "open", "status_transitions": { "finalized_at": 1623873347, "marked_uncollectible_at": null, "paid_at": null, "voided_at": null }, "subscription": "sub_JgRjFjhKbtD2qz", "subtotal": 2000, "tax": null, "tax_percent": null, "total": 2000, "total_discount_amounts": [], "total_tax_amounts": [], "transfer_data": null, "webhooks_delivered_at": 1623873347 }, "livemode": false, "metadata": { }, "next_pending_invoice_item_invoice": null, "pause_collection": null, "pending_invoice_item_interval": null, "pending_setup_intent": null, "pending_update": null, "plan": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "plan", "active": true, "amount": 2000, "amount_decimal": "2000", "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "tiers": null, "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "quantity": 1, "schedule": null, "start": 1623873347, "start_date": 1623873347, "status": "incomplete", "tax_percent": null, "transfer_data": null, "trial_end": null, "trial_start": null } ``` ## Colete dados de pagamento [Cliente] Use o [Stripe Elements](https://docs.stripe.com/payments/elements.md) para recolher os detalhes do pagamento e ativar a assinatura. você pode personalizar o Elements para que corresponda à aparência de sua inscrição. O [Payment Element](https://docs.stripe.com/payments/payment-element.md) oferece suporte a [Link](https://docs.stripe.com/payments/link.md), cartões de crédito, débitos automáticos SEPA e débitos automáticos BECS para assinaturas. Você pode exibir as formas de pagamento habilitadas e coletar com segurança os dados de pagamento com base na seleção do seu cliente. ### Configurar o Stripe Elements O Payment Element está automaticamente disponível como um recurso do Stripe.js. Inclua o script Stripe.js em sua página de pagamento adicionando-o ao `head` do arquivo HTML. Sempre carregue o Stripe.js diretamente de js.stripe.com para manter a conformidade com PCI. Não inclua o script em um pacote nem hospede pessoalmente uma cópia dele. ```html Checkout ``` Crie uma instância da Stripe com o seguinte JavaScript na página de pagamentos: ```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('<>'); ``` ### Adicione o Payment Element à sua página O Payment Element precisa de um lugar para residir na sua página de pagamentos. Crie um node DOM vazio (contêiner) com um ID único no seu formulário de pagamento. ```html ``` Depois que o formulário for carregado, crie uma instância do Payment Element e monte-o no nódulo DOM do contêiner. Quando [criou a assinatura](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md#create-subscription), você passou o valor `client_secret` para o front end. Passe esse valor como uma opção quando você criar uma instância de Elements. ```javascript const options = { clientSecret: '{{CLIENT_SECRET}}', // Fully customizable with appearance API. appearance: {/*...*/}, }; // Set up Stripe.js and Elements to use in the payment form, passing the client secret obtained in step 5 const elements = stripe.elements(options); const paymentElementOptions = { layout: "tabs", }; // Create and mount the Payment Element const paymentElement = elements.create('payment', paymentElementOptions); paymentElement.mount('#payment-element'); ``` O Payment Element renderiza um formulário dinâmico que permite que o cliente selecione uma forma de pagamento. O formulário recolhe automaticamente todos os detalhes de pagamento necessários para a forma de pagamento selecionada. #### Configurações opcionais do Payment Element Como opção, você pode fazer o seguinte: - Personalize o Payment Element para que corresponda ao design do seu site, passando o [objeto de aparência](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-appearance) para `options` ao criar uma instância do Elements. - Configure a interface do Apple Pay para retornar um [token de comerciante ](https://docs.stripe.com/apple-pay/merchant-tokens.md?pay-element=web-pe) para aceitar pagamentos recorrentes, recarga automática e diferidos. ### Finalizar pagamento Use `stripe.confirmPayment` para concluir o pagamento usando os detalhes do Stripe Elements e ativar a assinatura. Isso cria um PaymentMethod, confirma o primeiro PaymentIntent da assinatura incompleta e faz uma cobrança. Se *Strong Customer Authentication* (SCA) for necessária para o pagamento, o Payment Element tratará o processo de autenticação antes de confirmar o PaymentIntent. Forneça um [return_url](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-return_url) para indicar para onde o Stripe redireciona o usuário depois que ele conclui o pagamento. O usuário pode ser redirecionado primeiro para um site intermediário, como uma página de autorização bancária, antes de ser redirecionado para o `return_url`. Os pagamentos com cartão redirecionam imediatamente para o `return_url` quando o pagamento é bem-sucedido. ```javascript const form = document.getElementById('payment-form'); form.addEventListener('submit', async (event) => { event.preventDefault(); const {error} = await stripe.confirmPayment({ //`Elements` instance that was used to create the Payment Element elements, confirmParams: { return_url: "https://example.com/order/123/complete", } }); if (error) { // This point is reached only if there's an immediate error when // confirming the payment. Show an error to your customer (for example, payment // details incomplete) const messageContainer = document.querySelector('#error-message'); messageContainer.textContent = error.message; } else { // Your customer redirects to your `return_url`. For some payment // methods, such as iDEAL, your customer redirects to an intermediate // site first to authorize the payment, and then redirects to the `return_url`. } }); ``` Quando o cliente envia um pagamento, a Stripe o redireciona para o `return_url` e inclui os parâmetros de consulta de URL a seguir. A página de retorno pode usá-los para obter o status do PaymentIntent e exibir o status do pagamento para o cliente. Ao especificar o `return_url`, você também pode anexar seus próprios parâmetros de consulta para uso na página de retorno. | Parâmetro | Descrição | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `payment_intent` | O identificador único do `PaymentIntent`. | | `payment_intent_client_secret` | O [segredo do cliente](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) do objeto `PaymentIntent`. Para integrações de assinaturas, esse client_secret também é exposto no objeto `Invoice` por meio de [`confirmation_secret`](https://docs.stripe.com/api/invoices/object.md#invoice_object-confirmation_secret) | Quando o cliente é redirecionado para o seu site, você pode usar o `payment_intent_client_secret` para consultar o PaymentIntent e exibir o status da transação ao cliente. > Se você tiver ferramentas que monitoram a sessão do navegador do cliente, pode precisar adicionar o domínio `stripe.com` à lista de exclusão dos indicadores. Os redirecionamentos fazem com que algumas ferramentas criem sessões, o que evita que você acompanhe a sessão completa. Use um dos parâmetros da consulta para recuperar o PaymentIntent. Inspecione o status [do PaymentIntent](https://docs.stripe.com/payments/paymentintents/lifecycle.md) para decidir o que mostrar aos seus clientes. você também pode anexar seus próprios parâmetros de consulta ao fornecer o `return_url`, que persiste durante o processo de redirecionamento. ```javascript // Initialize Stripe.js using your publishable key const stripe = Stripe('<>'); // Retrieve the "payment_intent_client_secret" query parameter appended to // your return_url by Stripe.js const clientSecret = new URLSearchParams(window.location.search).get( 'payment_intent_client_secret' ); // Retrieve the PaymentIntent stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => { const message = document.querySelector('#message') // Inspect the PaymentIntent `status` to indicate the status of the payment // to your customer. // // Some payment methods [immediately succeed or fail][0] upon // confirmation, while others first enter a `processing` status. // // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification switch (paymentIntent.status) { case 'succeeded': message.innerText = 'Success! Payment received.'; break; case 'processing': message.innerText = "Payment processing. We'll update you when payment is received."; break; case 'requires_payment_method': message.innerText = 'Payment failed. Please try another payment method.'; // Redirect your user back to your payment page to attempt collecting // payment again break; default: message.innerText = 'Something went wrong.'; break; } }); ``` ## Procuro por webhooks [Servidor] Para concluir a integração, você precisa processar os *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) enviados pela Stripe. Esses eventos são acionados sempre que o status na Stripe muda, como assinaturas que criam novas faturas. No seu aplicativo, configure um manipulador HTTP para aceitar uma solicitação POST contendo o evento webhook e verifique a assinatura do evento: #### 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 = '<>' post '/webhook' do # You can use webhooks to receive information about asynchronous payment events. # For more about our webhook events, see https://stripe.com/docs/webhooks. webhook_secret = ENV['STRIPE_WEBHOOK_SECRET'] payload = request.body.read if !webhook_secret.empty? # Retrieve the event by verifying the signature using the raw body and secret if webhook signing is configured. sig_header = request.env['HTTP_STRIPE_SIGNATURE'] event = nil begin event = Stripe::Webhook.construct_event( payload, sig_header, webhook_secret ) rescue JSON::ParserError => e # Invalid payload status 400 return rescue Stripe::SignatureVerificationError => e # Invalid signature puts '⚠️ Webhook signature verification failed.' status 400 return end else data = JSON.parse(payload, symbolize_names: true) event = Stripe::Event.construct_from(data) end # Get the type of webhook event sent - used to check the status of PaymentIntents. event_type = event['type'] data = event['data'] data_object = data['object'] if event_type == 'invoice.paid' # Used to provision services after the trial has ended. # The status of the invoice shows up as paid. Store the status in your # database to reference when a user accesses your service to avoid hitting rate # limits. # puts data_object end if event_type == 'invoice.payment_failed' # If the payment fails or the customer doesn't have a valid payment method, # an invoice.payment_failed event is sent and the subscription becomes past_due. # Use this webhook to notify your user that their payment has # failed and to retrieve new card details. # puts data_object end if event_type == 'customer.subscription.deleted' # handle subscription canceled automatically based # upon your subscription settings. Or if the user cancels it. # puts data_object end content_type 'application/json' { status: 'success' }.to_json end ``` Durante o desenvolvimento, use a CLI da Stripe para [observar Webhooks e encaminhá-los para sua inscrição](https://docs.stripe.com/webhooks.md#test-webhook). Execute o seguinte em um novo terminal enquanto seu aplicativo de desenvolvimento estiver em execução: #### curl ```bash stripe listen --forward-to localhost:4242/webhook ``` Para produção, configure um endpoint de Webhook no [Workbench](https://docs.stripe.com/workbench.md), ou use o [Webhook Endpoints API](https://docs.stripe.com/api/webhook_endpoints.md). Ouça alguns eventos para concluir as etapas restantes deste guia. Consulte [Eventos de assinatura](https://docs.stripe.com/billing/subscriptions/webhooks.md#events) para obter mais detalhes sobre Webhooks específicos de assinatura. ## Providenciar acesso ao seu serviço [Cliente e servidor] Agora que a assinatura está ativa, conceda acesso ao seu serviço para o usuário. Para isso, escute os `customer.subscription.created`, `customer.subscription.updated`, e `customer.subscription.deleted`. Esses eventos enviam um objeto de `Assinatura` que contém um campo `status`, indicando se a assinatura está ativa, vencida, ou cancelada. Consulte [o ciclo de vida da assinatura](https://docs.stripe.com/billing/subscriptions/overview.md#subscription-lifecycle) para ver a lista completa de status. No seu gerenciador de webhooks: 1. Verifique o status da assinatura. Se estiver `active`, o usuário terá pago pelo seu produto. 1. Confira o produto que o cliente assinou e conceda acesso ao serviço. Verificar o produto em vez do preço proporciona mais flexibilidade, caso seja necessário alterar os preços ou o período de faturamento. 1. Armazene o `product.id`, `subscription.id` e `subscription.status` no seu banco de dados junto com o `customer.id` que já salvou. Verifique esse registro quando determinar quais recursos precisam ser ativados para o usuário no seu aplicativo. O status da assinatura pode mudar a qualquer momento durante seu ciclo de vida, mesmo que sua aplicação não faça chamadas diretamente para a Stripe. Por exemplo, uma renovação pode falhar por causa de um cartão de crédito expirado, o que coloca a assinatura em status`vencido`. Ou, se você implementar [portal do cliente](https://docs.stripe.com/customer-management.md), um usuário pode cancelar a assinatura sem acessar diretamente a sua aplicação. Implementar corretamente o seu handler mantém o status da sua aplicação sincronizado com a Stripe. ## Cancelar a assinatura [Cliente e servidor] Você pode permitir que os clientes cancelem suas assinaturas. O exemplo abaixo adiciona uma opção de cancelamento à página de configurações da conta. ![Exemplo de interface de cancelamento de assinatura](https://b.stripecdn.com/docs-statics-srv/assets/fixed-price-subscriptions-guide-account-settings.6559626ba4b434826a67abfea165e097.png) Configurações da conta com a capacidade de cancelar a assinatura ```javascript function cancelSubscription(subscriptionId) { return fetch('/cancel-subscription', { method: 'post', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ subscriptionId: subscriptionId, }), }) .then(response => { return response.json(); }) .then(cancelSubscriptionResponse => { // Display to the user that the subscription has been canceled. }); } ``` No back-end, configure um endpoint para ser chamado pelo front-end. #### 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 = '<>' post '/cancel-subscription' do content_type 'application/json' data = JSON.parse request.body.read deleted_subscription = Stripe::Subscription.cancel(data['subscriptionId']) deleted_subscription.to_json end ``` Seu aplicativo recebe um evento `customer.subscription.deleted`. Após o cancelamento da assinatura, remova do banco de dados o ID de assinatura da Stripe que você armazenou anteriormente e limite o acesso ao seu serviço. Depois de serem canceladas, as assinaturas não podem ser reativadas. Obtenha dados de faturamento atualizados do seu cliente, atualize a forma de pagamento padrão e crie uma nova assinatura com o registro de cliente existente. ## Teste a integração ### Testar formas de pagamento Use a tabela a seguir para testar diferentes formas de pagamento e cenários. | Forma de pagamento | Cenário | Como testar | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Débito automático BECS | O cliente paga com débito automático BECS. | Preencha o formulário usando o número da conta `900123456` e BSB `000000`. O PaymentIntent confirmado inicialmente passa para o status `processing`, depois passa para `succeeded` três minutos depois. | | Débito automático BECS | O pagamento do cliente falha com um código de erro `account_closed`. | Preencha o formulário usando o número da conta `111111113` e BSB `000000`. | | Cartão de crédito | O pagamento com cartão é bem-sucedido e não precisa de autenticação. | Preencha o formulário do cartão de crédito usando o número de cartão de crédito `4242 4242 4242 4242` com qualquer validade, CVC e código postal. | | Cartão de crédito | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número `4000 0025 0000 3155` com qualquer validade, CVC e código postal. | | Cartão de crédito | O cartão é recusado com um código de recusa como `insufficient_funds`. | Preencha o formulário do cartão de crédito usando o número `4000 0000 0000 9995` com qualquer validade, CVC e código postal. | | Débito automático SEPA | O cliente paga com débito automático SEPA. | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processing e, três minutos depois, para succeeded. | | Débito automático SEPA | O status do PaymentIntent do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`. | ### Monitorar eventos Configure Webhooks para ouvir os eventos de alteração de assinatura, como upgrades e cancelamentos. Saiba mais sobre os [Webhooks de assinatura ](https://docs.stripe.com/billing/subscriptions/webhooks.md) . você pode visualizar eventos no [Dashboard](https://dashboard.stripe.com/test/events) ou com o [Stripe CLI](https://docs.stripe.com/webhooks.md#test-webhook). Para obter mais detalhes, consulte [testando sua integração com o Billing](https://docs.stripe.com/billing/testing.md). ## Optional: Permita que os clientes alterem seus planos [Cliente e servidor] Para permitir que seus clientes alterem a assinatura, recolha a ID de preço da opção para a qual desejam mudar. Em seguida, envie o novo ID de preço do front-end para um endpoint de back-end. O exemplo abaixo também passa o ID da assinatura, mas você pode recuperá-lo do seu banco de dados para o usuário logado. ```javascript function updateSubscription(priceId, subscriptionId) { return fetch('/update-subscription', { method: 'post', headers: { 'Content-type': 'application/json', }, body: JSON.stringify({ subscriptionId: subscriptionId, newPriceId: priceId, }), }) .then(response => { return response.json(); }) .then(response => { return response; }); } ``` No back-end, defina o endpoint para o front-end chamar, passando o ID da assinatura e o novo ID do preço. A assinatura agora é Premium a 15 USD por mês, em vez de Basic a 5 USD por mês. #### 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 = '<>' post '/update-subscription' do content_type 'application/json' data = JSON.parse request.body.read subscription = Stripe::Subscription.retrieve(data['subscriptionId']) updated_subscription = Stripe::Subscription.update( data['subscriptionId'], cancel_at_period_end: false, items: [ { id: subscription.items.data[0].id, price: data['newPriceId'] } ] ) updated_subscription.to_json end ``` Seu aplicativo recebe um evento `customer.subscription.updated`. ## Optional: Prévia de uma alteração de preço [Cliente e servidor] Quando o cliente altera sua assinatura, geralmente há um ajuste no valor devido, conhecido como [pro rata](https://docs.stripe.com/billing/subscriptions/prorations.md). Você pode usar o endpoint [create preview invoice](https://docs.stripe.com/api/invoices/create_preview.md) para exibir o valor ajustado aos seus clientes. No frontend, envie os detalhes de `create preview invoice` para um endpoint do backend. ```javascript function createPreviewInvoice( customerId, subscriptionId, newPriceId, trialEndDate ) { return fetch('/create-preview-invoice', { method: 'post', headers: { 'Content-type': 'application/json', }, body: JSON.stringify({ customerId: customerId, subscriptionId: subscriptionId, newPriceId: newPriceId, }), }) .then(response => { return response.json(); }) .then((invoice) => { return invoice; }); } ``` No back-end, configure um endpoint para ser chamado pelo front-end. #### 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 = '<>' post '/create-preview-invoice' do content_type 'application/json' data = JSON.parse request.body.read subscription = Stripe::Subscription.retrieve(data['subscriptionId']) invoice = Stripe::Invoice.create_preview( customer: data['customerId'], subscription: data['subscriptionId'], subscription_details: { items: [ { id: subscription.items.data[0].id, deleted: true }, { price: data['newPriceId'], deleted: false } ] } ) invoice.to_json end ``` ## Optional: Exibir a forma de pagamento do cliente [Cliente e servidor] Exibir a bandeira e os últimos quatro dígitos do cartão do seu cliente informa qual cartão está sendo cobrado ou se é preciso atualizar a forma de pagamento. No front-end, envie o ID do método de pagamento para um endpoint de back-end que recupera os detalhes do método de pagamento. ```javascript function retrieveCustomerPaymentMethod(paymentMethodId) { return fetch('/retrieve-customer-payment-method', { method: 'post', headers: { 'Content-type': 'application/json', }, body: JSON.stringify({ paymentMethodId: paymentMethodId, }), }) .then((response) => { return response.json(); }) .then((response) => { return response; }); } ``` No back-end, configure um endpoint para ser chamado pelo front-end. #### 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 = '<>' post '/retrieve-customer-payment-method' do content_type 'application/json' data = JSON.parse request.body.read payment_method = Stripe::PaymentMethod.retrieve(data['paymentMethodId']) payment_method.to_json end ``` Exemplo de resposta: ```json { "id": "pm_1GcbHY2eZvKYlo2CoqlVxo42", "object": "payment_method", "billing_details": { "address": { "city": null, "country": null, "line1": null, "line2": null, "postal_code": null, "state": null }, "email": null, "name": null, "phone": null }, "card": { "brand": "visa", "checks": { "address_line1_check": null, "address_postal_code_check": null, "cvc_check": "pass" }, "country": "US", "exp_month": 8, "exp_year": 2021, "fingerprint": "Xt5EWLLDS7FJjR1c", "funding": "credit", "generated_from": null, "last4": "4242", "three_d_secure_usage": { "supported": true }, "wallet": null }, "created": 1588010536, "customer": "cus_HAxB7dVQxhoKLh", "livemode": false, "metadata": {}, "type": "card" } ``` > Recomendamos que você salve `paymentMethod.id` e `last4` no banco de dados (por exemplo, `paymentMethod.id` como `stripeCustomerPaymentMethodId` na coleção ou tabela `users`). Você também pode armazenar `exp_month`, `exp_year`, `fingerprint` e `billing_details` conforme necessário. Assim, você reduz o número de chamadas à Stripe para melhorar o desempenho e evitar possíveis limitações de fluxo. ## Divulgue a Stripe para seus clientes A Stripe coleta informações sobre interações do cliente com o Elements para fornecer serviços a você, evitar fraudes e melhorar os serviços. Isso inclui o uso de cookies e endereços IP para identificar quais Elements o cliente visualizou durante uma única sessão de checkout. Você é responsável por divulgar e obter todos os direitos e consentimentos necessários para que a Stripe use os dados dessas maneiras. Para saber mais, acesse nossa [central de privacidade](https://stripe.com/legal/privacy-center#as-a-business-user-what-notice-do-i-provide-to-my-end-customers-about-stripe). #### Dispositivos móveis #### iOS Aprenda a vender *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) com preço fixo. Você usará o [Elemento de Pagamento Móvel](https://docs.stripe.com/payments/accept-a-payment.md) para criar um formulário de pagamento personalizado que você pode integrar ao seu aplicativo. ![Página de assinatura com preço fixo com o Mobile Payment Element](https://b.stripecdn.com/docs-statics-srv/assets/fixed-price-collect-payment-details-mobile.b11cdc8fa8952d753238df4df3375fa6.png) > Se você vende produtos ou serviços digitais consumidos no seu aplicativo (por exemplo, assinaturas, moedas de jogos, níveis de jogos, acesso a conteúdo premium ou desbloqueio de uma versão completa), use as APIs de compra no aplicativo da Apple. Essa regra tem algumas exceções, incluindo serviços pessoais individuais e [aplicativos baseados em regiões específicas](https://support.stripe.com/questions/changes-to-mobile-app-store-rules). Consulte as [diretrizes de revisão da App Store](https://developer.apple.com/app-store/review/guidelines/#payments) para obter mais informações. ## Crie sua assinatura Este guia ensina a: - Modelar seus negócios criando um catálogo de produtos. - Crie um processo de registro para adicionar clientes. - Criar assinaturas e coletar dados de pagamento. - Teste e monitore o status de pagamentos e assinaturas. - Permitir que os clientes alterem o plano ou cancelem a assinatura. - Saiba como usar o [modo de faturamento flexíve](https://docs.stripe.com/billing/subscriptions/billing-mode.md) para acessar o comportamento de faturamento aprimorado e recursos adicionais. ## Como modelar na Stripe [Subscriptions](https://docs.stripe.com/api/subscriptions.md) (assinaturas) simplificam seu faturamento ao criar automaticamente *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 [PaymentIntents](https://docs.stripe.com/api/payment_intents.md) para você. Para criar e ativar uma assinatura, primeiro você precisa criar um *Produto* (Products represent what your business sells—whether that's a good or a service) para modelar o que está sendo vendido 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), que determina o intervalo e o valor a cobrar. Você também precisa de um [Customer](https://docs.stripe.com/api/customers.md) (Cliente) para armazenar *PaymentMethods* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) usados para realizar cada pagamento recorrente. #### Accounts v2 Um diagrama que ilustra objetos de cobrança comuns e suas relações (See full diagram at https://docs.stripe.com/billing/subscriptions/build-subscriptions) #### Customer v1 Um diagrama que ilustra objetos de cobrança comuns e suas relações (See full diagram at https://docs.stripe.com/billing/subscriptions/build-subscriptions) ### Definições de objetos de API | Recurso | Definição | | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Conta configurada como cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer) | Represents a customer in the Accounts v2 API who purchases a subscription. Configure an `Account` object as a customer and associate it with a subscription to make and track recurring charges and to manage the products that they subscribe to. For more information, see the [Use Accounts as customers guide](https://docs.stripe.com/connect/use-accounts-as-customers.md). | | [Cliente](https://docs.stripe.com/api/customers.md) | Represents a customer in the Customers API who purchases a subscription. Use the `Customer` object associated with a subscription to make and track recurring charges and to manage the products that they subscribe to. | | [Direito](https://docs.stripe.com/api/entitlements/active-entitlement.md) | Representa o acesso de um cliente a um recurso incluído em um produto de serviço que assina. Quando você cria uma assinatura para a compra recorrente de um produto por um cliente, um direito ativo é automaticamente criado para cada recurso associado a esse produto. Quando um cliente acessa seus serviços, use os direitos ativos para habilitar os recursos incluídos na assinatura. | | [Recurso](https://docs.stripe.com/api/entitlements/feature.md) | Representa uma função ou capacidade que seus clientes podem acessar quando assinam um produto de serviço. Você pode incluir recursos em um produto criando ProductFeatures. | | [Fatura](https://docs.stripe.com/api/invoices.md) | Uma declaração de valores devidos por um cliente que acompanha os status de pagamento desde o esboço até o pagamento (ou outro tipo de finalização). As assinaturas geram faturas automaticamente. | | [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) | Uma maneira de criar fluxos de pagamentos dinâmicos. Um PaymentIntent acompanha o ciclo de vida do fluxo de checkout de um cliente e aciona etapas adicionais de autenticação quando for exigido por mandatos regulatórios, regras personalizadas contra fraudes do Radar ou formas de pagamento baseadas em redirecionamento. As faturas criam PaymentIntents automaticamente. | | [PaymentMethod](https://docs.stripe.com/api/payment_methods.md) | A customer’s payment methods that they use to pay for your products. For example, you can store a credit card on a customer-configured `Account` or `Customer` object and use it to make recurring payments for that customer. Typically used with the Payment Intents or Setup Intents APIs. | | [Price](https://docs.stripe.com/api/prices.md) | Define o preço unitário, a moeda e o ciclo de faturamento de um produto. | | [Product](https://docs.stripe.com/api/products.md) | Um produto ou serviço que sua empresa vende. Um produto de serviço pode incluir um ou mais recursos. | | [ProductFeature](https://docs.stripe.com/api/product-feature.md) | Representa a inclusão de um único recurso em um único produto. Cada produto está associado a um ProductFeature para cada recurso que é incluído, e cada recurso é associado a um ProductFeature para cada produto que o inclui. | | [Subscription](https://docs.stripe.com/api/subscriptions.md) | Representa a compra recorrente agendada de um produto por um cliente. Use uma assinatura para coletar pagamentos e fornecer entregas repetidas ou acesso contínuo a um produto. | Aqui está um exemplo de como produtos, recursos e direitos funcionam juntos. Imagine que você deseja configurar um serviço de assinatura que oferece dois níveis: um produto padrão com funções básicas e um produto avançado que adiciona funções estendidas. 1. Você cria dois recursos: `basic_features` e `extended_features`. 1. Você cria dois produtos: `standard_product` e `advanced_product`. 1. Para o produto padrão, você cria uma ProductFeature que associa `basic_features` com `standard_product`. 1. Para o produto avançado, você cria duas ProductFeatures: uma que associa `basic_features` com `advanced_product` e outra que associa `extended_features` com `advanced_product`. Um cliente, `first_customer`, assina o produto padrão. Quando você cria a assinatura, a Stripe cria automaticamente um Entitlement que associa `first_customer` com `basic_features`. Outro cliente, `second_customer`, assina o produto avançado. Quando você cria a assinatura, a Stripe cria automaticamente dois Entitlements: um que associa `second_customer` a `basic_features` e outro que associa `second_customer` com `extended_features`. É possível determinar quais recursos fornecer para um cliente [recuperando seus direitos ativos ou escutando o evento Active Entitlement Summary](https://docs.stripe.com/billing/entitlements.md#entitlements). Você não precisa buscar as assinaturas, os produtos e os recursos dele. ## Configurar a Stripe O [SDK da Stripe para iOS](https://github.com/stripe/stripe-ios) é de código aberto, [totalmente documentado](https://stripe.dev/stripe-ios/index.html) e compatível com aplicativos que aceitam iOS 13 ou versões mais recentes. #### Gerenciador de pacotes Swift Para instalar o SDK, siga estas etapas: 1. No Xcode, selecione **Arquivo** > **Adicionar dependências de pacote…** e insira `https://github.com/stripe/stripe-ios-spm` como URL do repositório. 1. Selecione o número da última versão da nossa [página de lançamentos](https://github.com/stripe/stripe-ios/releases). 1. Adicione o produto **StripePaymentSheet** ao [alvo do seu aplicativo](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app). #### CocoaPods 1. Se ainda não o fez, instale a versão mais recente do [CocoaPods](https://guides.cocoapods.org/using/getting-started.html). 1. Se não tiver um [Podfile](https://guides.cocoapods.org/syntax/podfile.html), execute o seguinte comando para criar um: ```bash pod init ``` 1. Adicione esta linha ao seu `Podfile`: ```podfile pod 'StripePaymentSheet' ``` 1. Execute o seguinte comando: ```bash pod install ``` 1. Não se esqueça de usar o arquivo `.xcworkspace` para abrir seu projeto em Xcode, em vez do arquivo `.xcodeproj`, daqui em diante. 1. No futuro, para atualizar para a versão mais recente do SDK, execute: ```bash pod update StripePaymentSheet ``` #### Carthage 1. Se ainda não o fez, instale a versão mais recente do [Carthage](https://github.com/Carthage/Carthage#installing-carthage). 1. Adicione esta linha ao seu `Cartfile`: ```cartfile github "stripe/stripe-ios" ``` 1. Siga as [instruções de instalação do Carthage](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos). Certifique-se de integrar todas as estruturas necessárias listadas [here](https://github.com/stripe/stripe-ios/tree/master/StripePaymentSheet/README.md#manual-linking). 1. No futuro, para atualizar para a versão mais recente do SDK, execute o seguinte comando: ```bash carthage update stripe-ios --platform ios ``` #### Estrutura manual 1. Vá até a nossa [página de lançamentos do GitHub](https://github.com/stripe/stripe-ios/releases/latest) e baixe e descompacte o **Stripe.xcframework.zip**. 1. Arraste **StripePaymentSheet.xcframework** até a seção **Embedded Binaries** das configurações **General** no seu projeto Xcode. Certifique-se de selecionar **Copy items if needed**. 1. Repita a etapa 2 para todas as estruturas necessárias listadas [here](https://github.com/stripe/stripe-ios/tree/master/StripePaymentSheet/README.md#manual-linking). 1. No futuro, para atualizar para a versão mais recente do nosso SDK, repita as etapas 1 a 3. > Para obter mais informações sobre a versão mais recente e as versões anteriores do SDK, consulte a página [Lançamentos](https://github.com/stripe/stripe-ios/releases) no GitHub. Para receber notificações quando um novo lançamento for publicado, [assista aos lançamentos](https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository#watching-releases-for-a-repository) do repositório. Configure o SDK com sua [chave publicável da Stripe](https://dashboard.stripe.com/test/apikeys) na inicialização do aplicativo. Isso permite que seu aplicativo faça solicitações à API da Stripe . #### Swift ```swift import UIKitimportStripePaymentSheet @main class AppDelegate: UIResponder, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {StripeAPI.defaultPublishableKey = "<>" // do any other necessary launch configuration return true } } ``` > Use suas [chaves de teste](https://docs.stripe.com/keys.md#obtain-api-keys) enquanto testa e desenvolve, e suas chaves de [modo de produção](https://docs.stripe.com/keys.md#test-live-modes) quando publicar seu aplicativo. Em seguida, instale o Stripe CLI. O CLI fornece testes de webhooks, e você pode executá-lo para fazer chamadas de API para a Stripe. Este guia mostra a você como usar o CLI para configurar um modelo de preços em uma seção posterior. Para obter opções de instalação adicionais, consulte [Comece a usar o Stripe CLI](https://docs.stripe.com/stripe-cli.md). ## Criar o modelo de preços [Stripe CLI ou Dashboard] [Modelos de planos de preços recorrentes](https://docs.stripe.com/products-prices/pricing-models.md) representam os produtos ou serviços que você vende, quanto custam, quais moedas você aceita para pagamentos e o período de serviço para assinaturas. Para montar o modelo de preços, crie [produtos](https://docs.stripe.com/api/products.md) (o que você vende) e [ preços](https://docs.stripe.com/api/prices.md) (quanto e com que frequência cobrar pelos seus produtos). Este exemplo utiliza um plano de preços de taxa fixa com duas opções de nível de serviço diferentes: básico e premium. Para cada opção de nível de serviço, você precisa criar um produto e um preço recorrente. Para adicionar uma cobrança pontual, como uma tarifa de abertura, crie um terceiro produto com um preço pontual. Cada produto fatura em intervalos mensais. O preço do produto básico é 5 USD. O preço do produto premium é 15 USD. Consulte o guia de [plano de preços de taxa fixa](https://docs.stripe.com/subscriptions/pricing-models/flat-rate-pricing.md) para ver um exemplo com três níveis. #### Dashboard Acesse a página [Adicionar um produto](https://dashboard.stripe.com/test/products/create) e crie dois produtos. Adicione um preço para cada produto, cada um com um período de faturamento mensal recorrente: - Produto premium: serviço premium com recursos extras - Preço: Tarifa fixa | 15 USD - Produto básico: serviço básico com recursos mínimos - Preço: Tarifa fixa | 5 USD Depois de criar os preços, registre o ID deles para utilizá-los em outras etapas. Os IDs de preço têm esta estrutura: `price_G0FvDp6vZvdwRZ`. Quando tudo estiver pronto, use o botão **Copiar para modo de produção**, no canto superior direito, para clonar seu produto de [uma área restrita para o modo de produção](https://docs.stripe.com/keys.md#test-live-modes). #### API Você pode usar a API para criar os [produtos](https://docs.stripe.com/api/products.md) e os [ preços](https://docs.stripe.com/api/prices.md). Criar o produto premium: ```curl curl https://api.stripe.com/v1/products \ -u "<>:" \ --data-urlencode "name=Billing Guide: Premium Service" \ -d "description=Premium service with extra features" ``` Criar o produto básico: ```curl curl https://api.stripe.com/v1/products \ -u "<>:" \ --data-urlencode "name=Billing Guide: Basic Service" \ -d "description=Basic service with minimum features" ``` Registre os IDs de cada produto. Eles têm esta estrutura: ```json { "id": "prod_H94k5odtwJXMtQ", "object": "product", "active": true, "attributes": [ ], "created": 1587577341, "description": "Premium service with extra features", "images": [ ], "livemode": false, "metadata": { }, "name": "Billing Guide: Premium Service", "statement_descriptor": null, "type": "service", "unit_label": null, "updated": 1587577341 } ``` Use os IDs de produto para criar um preço para cada produto. O número [unit_amount](https://docs.stripe.com/api/prices/object.md#price_object-unit_amount) está em centavos. Por exemplo, `1500` = 15 USD. Criar o preço premium: ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d product={{PREMIUM_PRODUCT_ID}} \ -d unit_amount=1500 \ -d currency=usd \ -d "recurring[interval]=month" ``` Criar o preço básico: ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d product={{BASIC_PRODUCT_ID}} \ -d unit_amount=500 \ -d currency=usd \ -d "recurring[interval]=month" ``` Registre os IDs de cada preço, para que possam ser usados em etapas subsequentes. Eles têm esta estrutura: ```json { "id": "price_HGd7M3DV3IMXkC", "object": "price", "product": "prod_HGd6W1VUqqXGvr", "type": "recurring", "currency": "usd", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "active": true, "billing_scheme": "per_unit", "created": 1589319695, "livemode": false, "lookup_key": null, "metadata": {}, "nickname": null, "unit_amount": 1500, "unit_amount_decimal": "1500", "tiers": null, "tiers_mode": null, "transform_quantity": null } ``` ## Criar o cliente [Cliente e servidor] A Stripe precisa de um *customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) para cada assinatura. No frontend do seu aplicativo, colete todas as informações necessárias dos seus usuários e passe-as ao backend. > #### Comparar referências de Customers v1 e Accounts v2 > > Se a sua plataforma Connect utiliza [Contas configuradas pelo cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), utilize o nosso [guia](https://docs.stripe.com/connect/use-accounts-as-customers.md) para substituir as referências a `Cliente` e eventos no seu código pelas referências equivalentes da API Accounts v2. Se precisar coletar detalhes de endereço, o Address Element permite coletar um endereço de entrega ou cobrança para seus clientes. Saiba mais o Address Element na página [Address Element](https://docs.stripe.com/elements/address-element.md). ```swift struct RegisterView: View { @State var email = "" var body: some View { VStack { TextField(text: $email) { Text("Email") } Button { Task { var request = URLRequest(url: URL(string: "http://localhost:4242/create-customer")!) request.httpMethod = "POST" request.setValue("application/json", forHTTPHeaderField: "Content-Type") request.httpBody = try! JSONEncoder().encode(["email": email]) let (data, _) = try! await URLSession.shared.data(for: request) let responseJSON = try! JSONSerialization.jsonObject(with: data) as! [String: Any] // Return the customer ID here print(responseJSON["customer"]) } } label: { Text("Submit") } } } } ``` No servidor, crie o objeto do cliente Stripe. ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d email={{CUSTOMER_EMAIL}} \ -d name={{CUSTOMER_NAME}} \ -d "shipping[address][city]=Brothers" \ -d "shipping[address][country]=US" \ -d "shipping[address][line1]=27 Fredrick Ave" \ -d "shipping[address][postal_code]=97712" \ -d "shipping[address][state]=CA" \ -d "shipping[name]={{CUSTOMER_NAME}}" \ -d "address[city]=Brothers" \ -d "address[country]=US" \ -d "address[line1]=27 Fredrick Ave" \ -d "address[postal_code]=97712" \ -d "address[state]=CA" ``` ## Criar a assinatura [Cliente e servidor] > Se quiser renderizar o Payment Element antes de criar uma assinatura, consulte [Coletar dados de pagamento antes de criar um Intent](https://docs.stripe.com/payments/accept-a-payment-deferred.md?type=subscription). Permita que seu novo cliente escolha um plano e crie a assinatura. Neste guia, ele escolhe Básico ou Premium. No seu aplicativo, passe o ID do preço selecionado e o ID do registro do cliente ao back-end. ```swift func createSubscription(priceId: String, customerId: String) async -> SubscriptionsResponse { var request = URLRequest(url: URL(string: "http://localhost:4242/create-subscription")!) request.httpMethod = "POST" request.setValue("application/json", forHTTPHeaderField: "Content-Type") request.httpBody = try! JSONEncoder().encode(["customerId": customerId, "priceId": priceId]) let (responseData, _) = try! await URLSession.shared.data(for: request) // SubscriptionsResponse is a Decodable struct conforming to the expected response from your backend. // It should include the client_secret, as discussed below. let subscriptionsResponse = try! JSONDecoder().decode(SubscriptionsResponse.self, from: responseData) return subscriptionsResponse } ``` No back-end, crie a assinatura com status `incomplete` usando `payment_behavior=default_incomplete`. Em seguida, retorne o `client_secret` do primeiro [Payment Intent](https://docs.stripe.com/payments/payment-intents.md) da assinatura ao frontend para concluir o pagamento expandindo o [`confirmation_secret`](https://docs.stripe.com/api/invoices/object.md#invoice_object-confirmation_secret) na última fatura da assinatura. Para habilitar [comportamento de assinatura aprimorado](https://docs.stripe.com/billing/subscriptions/billing-mode.md), defina `billing_mode[type]` como `flexible`. Você deve usar a versão [2025-06-30.basil](https://docs.stripe.com/changelog/basil.md#2025-06-30.basil) ou posterior da API da Stripe. Defina [save_default_payment_method](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-payment_settings-save_default_payment_method) como `on_subscription` para salvar a forma de pagamento como o padrão para uma assinatura quando um pagamento for bem-sucedido. Salvar uma forma de pagamento padrão aumenta o sucesso de futuros pagamentos de assinatura. The following example creates a `Subscription` and expands the `confirmation_secret` from its latest invoice in the response. That lets you pass the secret to the front end to confirm the payment. #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d payment_behavior=default_incomplete \ -d "payment_settings[save_default_payment_method]=on_subscription" \ -d "billing_mode[type]=flexible" \ -d "expand[0]=latest_invoice.confirmation_secret" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d payment_behavior=default_incomplete \ -d "payment_settings[save_default_payment_method]=on_subscription" \ -d "billing_mode[type]=flexible" \ -d "expand[0]=latest_invoice.confirmation_secret" ``` > Se estiver usando um *preço multimoeda* (A single Price object can support multiple currencies. Each purchase uses one of the supported currencies for the Price, depending on how you use the Price in your integration), use o parâmetro [currency](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-currency) para informar à assinatura qual das moedas do preço deve ser usada. (Se você omitir o parâmetro `currency`, a Assinatura usará a moeda padrão do preço.) A assinatura agora está `inativa` e aguardando pagamento. A resposta de exemplo a seguir destaca os campos mínimos a serem armazenados, mas você pode armazenar o que sua inscrição acessa com frequência. #### Accounts v2 ```json {"id": "sub_JgRjFjhKbtD2qz", "object": "subscription", "application_fee_percent": null, "automatic_tax": { "disabled_reason": null, "enabled": false, "liability": "null" }, "billing_cycle_anchor": 1623873347, "billing_cycle_anchor_config": null, "cancel_at": null, "cancel_at_period_end": false, "canceled_at": null, "cancellation_details": { "comment": null, "feedback": null, "reason": null }, "collection_method": "charge_automatically", "created": 1623873347, "currency": "usd","customer_account": identifier("customerAccount"), "days_until_due": null, "default_payment_method": null, "default_source": null, "default_tax_rates": [ ], "discounts": [], "ended_at": null, "invoice_customer_balance_settings": { "account_tax_ids": null, "issuer": { "type": "self" } }, "items": { "object": "list", "data": [ { "id": "si_JgRjmS4Ur1khEx", "object": "subscription_item", "created": 1623873347,"current_period_end": 1626465347, "current_period_start": 1623873347, "discounts": [], "metadata": { }, "plan": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "plan", "active": true, "amount": 2000, "amount_decimal": "2000", "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "tiers": null, "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "price": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "livemode": false, "lookup_key": null, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "tiers_mode": null, "transform_quantity": null, "type": "recurring", "unit_amount": 2000, "unit_amount_decimal": "2000" }, "quantity": 1, "subscription": "sub_JgRjFjhKbtD2qz", "tax_rates": [ ] } ], "has_more": false, "total_count": 1, "url": "/v1/subscription_items?subscription=sub_JgRjFjhKbtD2qz" }, "latest_invoice": { "id": "in_1J34pzGPZ1iASj5zB87qdBNZ", "object": "invoice", "account_country": "US", "account_name": "Angelina's Store", "account_tax_ids": null, "amount_due": 2000, "amount_overpaid": 0, "amount_paid": 0, "amount_remaining": 2000, "amount_shipping": 0, "attempt_count": 0, "attempted": false, "auto_advance": false, "automatic_tax": { "disabled_reason": null, "enabled": false, "liability": null, "status": null }, "automatically_finalizes_at": null, "billing_reason": "subscription_update", "collection_method": "charge_automatically", "created": 1623873347, "currency": "usd", "custom_fields": null, "customer_account": identifier("customerAccount"), "customer_address": null, "customer_email": "angelina@stripe.com", "customer_name": null, "customer_phone": null, "customer_shipping": { "address": { "city": "", "country": "US", "line1": "Berry", "line2": "", "postal_code": "", "state": "" }, "name": "", "phone": null }, "customer_tax_exempt": "none", "customer_tax_ids": [ ], "default_payment_method": null, "default_source": null, "default_tax_rates": [ ], "description": null, "discounts": [], "due_date": null, "effective_at": "1623873347", "ending_balance": 0, "footer": null, "from_invoice": null, "hosted_invoice_url": "https://invoice.stripe.com/i/acct_1By64KGPZ1iASj5z/invst_JgRjzIOILGeq2MKC9T0KtyXnD5udsLp", "invoice_pdf": "https://pay.stripe.com/invoice/acct_1By64KGPZ1iASj5z/invst_JgRjzIOILGeq2MKC9T0KtyXnD5udsLp/pdf", "last_finalization_error": null, "latest_revision": null, "lines": { "object": "list", "data": [ { "id": "il_1N2CjMBwKQ696a5NeOawRQP2", "object": "line_item", "amount": 2000, "currency": "usd", "description": "1 × Gold Special (at $20.00 / month)", "discount_amounts": [ ], "discountable": true, "discounts": [ ], "invoice": "in_1J34pzGPZ1iASj5zB87qdBNZ", "livemode": false, "metadata": { }, "parent": { "invoice_item_details": null, "subscription_item_details": { "invoice_item": null, "proration": false, "proration_details": { "credited_items": null }, "subscription": "sub_JgRjFjhKbtD2qz", "subscription_item": "si_JgRjmS4Ur1khEx" }, "type": "subscription_item_details" }, "period": { "end": 1626465347, "start": 1623873347 }, "plan": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "plan", "active": true, "amount": 2000, "amount_decimal": "2000", "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "tiers": null, "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "price": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "livemode": false, "lookup_key": null, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "tiers_mode": null, "transform_quantity": null, "type": "recurring", "unit_amount": 2000, "unit_amount_decimal": "2000" }, "quantity": 1, "taxes": [] } ], "has_more": false, "total_count": 1, "url": "/v1/invoices/in_1J34pzGPZ1iASj5zB87qdBNZ/lines" }, "livemode": false, "metadata": { }, "next_payment_attempt": null, "number": "C008FC2-0354", "on_behalf_of": null, "parent": { "quote_details": null, "subscription_details": { "metadata": {}, "pause_collection": null, "subscription": "sub_JgRjFjhKbtD2qz" } }, "payment_intent": { "id": "pi_1J34pzGPZ1iASj5zI2nOAaE6", "object": "payment_intent", "allowed_source_types": [ "card" ], "amount": 2000, "amount_capturable": 0, "amount_received": 0, "application": null, "application_fee_amount": null, "canceled_at": null, "cancellation_reason": null, "capture_method": "automatic", "charges": { "object": "list", "data": [ ], "has_more": false, "total_count": 0, "url": "/v1/charges?payment_intent=pi_1J34pzGPZ1iASj5zI2nOAaE6" }, "client_secret": "pi_1J34pzGPZ1iASj5zI2nOAaE6_secret_l7FN6ldFfXiFmJEumenJ2y2wu", "confirmation_method": "automatic", "created": 1623873347, "currency": "usd", "customer": "cus_CMqDWO2xODTZqt", "description": "Subscription creation", "invoice": "in_1J34pzGPZ1iASj5zB87qdBNZ", "last_payment_error": null, "livemode": false, "metadata": { }, "next_action": null, "next_source_action": null, "on_behalf_of": null, "payment_method": null, "payment_method_options": { "card": { "installments": null, "network": null, "request_three_d_secure": "automatic" } }, "payment_method_types": [ "card" ], "receipt_email": null, "review": null, "setup_future_usage": "off_session", "shipping": null, "source": "card_1By6iQGPZ1iASj5z7ijKBnXJ", "statement_descriptor": null, "statement_descriptor_suffix": null, "status": "requires_confirmation", "transfer_data": null, "transfer_group": null }, "payment_settings": { "payment_method_options": null, "payment_method_types": null, "save_default_payment_method": "on_subscription" }, "period_end": 1623873347, "period_start": 1623873347, "post_payment_credit_notes_amount": 0, "pre_payment_credit_notes_amount": 0, "receipt_number": null, "starting_balance": 0, "statement_descriptor": null, "status": "open", "status_transitions": { "finalized_at": 1623873347, "marked_uncollectible_at": null, "paid_at": null, "voided_at": null }, "subscription": "sub_JgRjFjhKbtD2qz", "subtotal": 2000, "tax": null, "tax_percent": null, "total": 2000, "total_discount_amounts": [], "total_tax_amounts": [], "transfer_data": null, "webhooks_delivered_at": 1623873347 }, "livemode": false, "metadata": { }, "next_pending_invoice_item_invoice": null, "pause_collection": null, "pending_invoice_item_interval": null, "pending_setup_intent": null, "pending_update": null, "plan": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "plan", "active": true, "amount": 2000, "amount_decimal": "2000", "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "tiers": null, "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "quantity": 1, "schedule": null, "start": 1623873347, "start_date": 1623873347, "status": "incomplete", "tax_percent": null, "transfer_data": null, "trial_end": null, "trial_start": null } ``` #### Customers v1 ```json {"id": "sub_JgRjFjhKbtD2qz", "object": "subscription", "application_fee_percent": null, "automatic_tax": { "disabled_reason": null, "enabled": false, "liability": "null" }, "billing_cycle_anchor": 1623873347, "billing_cycle_anchor_config": null, "cancel_at": null, "cancel_at_period_end": false, "canceled_at": null, "cancellation_details": { "comment": null, "feedback": null, "reason": null }, "collection_method": "charge_automatically", "created": 1623873347, "currency": "usd","customer": identifier("customer"), "days_until_due": null, "default_payment_method": null, "default_source": null, "default_tax_rates": [ ], "discounts": [], "ended_at": null, "invoice_customer_balance_settings": { "account_tax_ids": null, "issuer": { "type": "self" } }, "items": { "object": "list", "data": [ { "id": "si_JgRjmS4Ur1khEx", "object": "subscription_item", "created": 1623873347,"current_period_end": 1626465347, "current_period_start": 1623873347, "discounts": [], "metadata": { }, "plan": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "plan", "active": true, "amount": 2000, "amount_decimal": "2000", "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "tiers": null, "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "price": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "livemode": false, "lookup_key": null, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "tiers_mode": null, "transform_quantity": null, "type": "recurring", "unit_amount": 2000, "unit_amount_decimal": "2000" }, "quantity": 1, "subscription": "sub_JgRjFjhKbtD2qz", "tax_rates": [ ] } ], "has_more": false, "total_count": 1, "url": "/v1/subscription_items?subscription=sub_JgRjFjhKbtD2qz" }, "latest_invoice": { "id": "in_1J34pzGPZ1iASj5zB87qdBNZ", "object": "invoice", "account_country": "US", "account_name": "Angelina's Store", "account_tax_ids": null, "amount_due": 2000, "amount_overpaid": 0, "amount_paid": 0, "amount_remaining": 2000, "amount_shipping": 0, "attempt_count": 0, "attempted": false, "auto_advance": false, "automatic_tax": { "disabled_reason": null, "enabled": false, "liability": null, "status": null }, "automatically_finalizes_at": null, "billing_reason": "subscription_update", "collection_method": "charge_automatically", "created": 1623873347, "currency": "usd", "custom_fields": null, "customer": identifier("customer"), "customer_address": null, "customer_email": "angelina@stripe.com", "customer_name": null, "customer_phone": null, "customer_shipping": { "address": { "city": "", "country": "US", "line1": "Berry", "line2": "", "postal_code": "", "state": "" }, "name": "", "phone": null }, "customer_tax_exempt": "none", "customer_tax_ids": [ ], "default_payment_method": null, "default_source": null, "default_tax_rates": [ ], "description": null, "discounts": [], "due_date": null, "effective_at": "1623873347", "ending_balance": 0, "footer": null, "from_invoice": null, "hosted_invoice_url": "https://invoice.stripe.com/i/acct_1By64KGPZ1iASj5z/invst_JgRjzIOILGeq2MKC9T0KtyXnD5udsLp", "invoice_pdf": "https://pay.stripe.com/invoice/acct_1By64KGPZ1iASj5z/invst_JgRjzIOILGeq2MKC9T0KtyXnD5udsLp/pdf", "last_finalization_error": null, "latest_revision": null, "lines": { "object": "list", "data": [ { "id": "il_1N2CjMBwKQ696a5NeOawRQP2", "object": "line_item", "amount": 2000, "currency": "usd", "description": "1 × Gold Special (at $20.00 / month)", "discount_amounts": [ ], "discountable": true, "discounts": [ ], "invoice": "in_1J34pzGPZ1iASj5zB87qdBNZ", "livemode": false, "metadata": { }, "parent": { "invoice_item_details": null, "subscription_item_details": { "invoice_item": null, "proration": false, "proration_details": { "credited_items": null }, "subscription": "sub_JgRjFjhKbtD2qz", "subscription_item": "si_JgRjmS4Ur1khEx" }, "type": "subscription_item_details" }, "period": { "end": 1626465347, "start": 1623873347 }, "plan": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "plan", "active": true, "amount": 2000, "amount_decimal": "2000", "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "tiers": null, "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "price": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "livemode": false, "lookup_key": null, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "tiers_mode": null, "transform_quantity": null, "type": "recurring", "unit_amount": 2000, "unit_amount_decimal": "2000" }, "quantity": 1, "taxes": [] } ], "has_more": false, "total_count": 1, "url": "/v1/invoices/in_1J34pzGPZ1iASj5zB87qdBNZ/lines" }, "livemode": false, "metadata": { }, "next_payment_attempt": null, "number": "C008FC2-0354", "on_behalf_of": null, "parent": { "quote_details": null, "subscription_details": { "metadata": {}, "pause_collection": null, "subscription": "sub_JgRjFjhKbtD2qz" } }, "payment_intent": { "id": "pi_1J34pzGPZ1iASj5zI2nOAaE6", "object": "payment_intent", "allowed_source_types": [ "card" ], "amount": 2000, "amount_capturable": 0, "amount_received": 0, "application": null, "application_fee_amount": null, "canceled_at": null, "cancellation_reason": null, "capture_method": "automatic", "charges": { "object": "list", "data": [ ], "has_more": false, "total_count": 0, "url": "/v1/charges?payment_intent=pi_1J34pzGPZ1iASj5zI2nOAaE6" }, "client_secret": "pi_1J34pzGPZ1iASj5zI2nOAaE6_secret_l7FN6ldFfXiFmJEumenJ2y2wu", "confirmation_method": "automatic", "created": 1623873347, "currency": "usd", "customer": "cus_CMqDWO2xODTZqt", "description": "Subscription creation", "invoice": "in_1J34pzGPZ1iASj5zB87qdBNZ", "last_payment_error": null, "livemode": false, "metadata": { }, "next_action": null, "next_source_action": null, "on_behalf_of": null, "payment_method": null, "payment_method_options": { "card": { "installments": null, "network": null, "request_three_d_secure": "automatic" } }, "payment_method_types": [ "card" ], "receipt_email": null, "review": null, "setup_future_usage": "off_session", "shipping": null, "source": "card_1By6iQGPZ1iASj5z7ijKBnXJ", "statement_descriptor": null, "statement_descriptor_suffix": null, "status": "requires_confirmation", "transfer_data": null, "transfer_group": null }, "payment_settings": { "payment_method_options": null, "payment_method_types": null, "save_default_payment_method": "on_subscription" }, "period_end": 1623873347, "period_start": 1623873347, "post_payment_credit_notes_amount": 0, "pre_payment_credit_notes_amount": 0, "receipt_number": null, "starting_balance": 0, "statement_descriptor": null, "status": "open", "status_transitions": { "finalized_at": 1623873347, "marked_uncollectible_at": null, "paid_at": null, "voided_at": null }, "subscription": "sub_JgRjFjhKbtD2qz", "subtotal": 2000, "tax": null, "tax_percent": null, "total": 2000, "total_discount_amounts": [], "total_tax_amounts": [], "transfer_data": null, "webhooks_delivered_at": 1623873347 }, "livemode": false, "metadata": { }, "next_pending_invoice_item_invoice": null, "pause_collection": null, "pending_invoice_item_interval": null, "pending_setup_intent": null, "pending_update": null, "plan": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "plan", "active": true, "amount": 2000, "amount_decimal": "2000", "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "tiers": null, "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "quantity": 1, "schedule": null, "start": 1623873347, "start_date": 1623873347, "status": "incomplete", "tax_percent": null, "transfer_data": null, "trial_end": null, "trial_start": null } ``` ### Atualize seu servidor endpoint Adicione a criação de chave efêmera ao endpoint de assinatura e retorne-a na resposta: #### Ruby ```ruby ephemeral_key = Stripe::EphemeralKey.create( {customer: customer_id}, {stripe_version: '2025-06-30.basil'} ) { subscriptionId: subscription.id, clientSecret: subscription.latest_invoice.confirmation_secret.client_secret, ephemeralKey: ephemeral_key.secret, customerId: customer_id, }.to_json ``` ### Atualize seu modelo de resposta ```swift struct SubscriptionsResponse: Decodable { let subscriptionId: String let clientSecret: String let ephemeralKey: String let customerId: String } ``` ### Passe a configuração do cliente para o PaymentSheet Adicione o seguinte ao configurar o PaymentSheet: ```swift config.customer = .init(id: customerId, ephemeralKeySecret: ephemeralKey) ``` ## Colete dados de pagamento [Cliente] Use o [Payment Sheet](https://docs.stripe.com/payments/mobile/payment-sheet.md) para recolher os detalhes do pagamento e ativar a assinatura. Você pode personalizar o Elements para combinar com a aparência do seu aplicativo. O Payment Sheet coleta com segurança todos os detalhes de pagamento necessários para uma ampla variedade de métodos de pagamento. Saiba mais sobre os [métodos de pagamento compatíveis](https://docs.stripe.com/payments/payment-methods/payment-method-support.md#product-support) com o Payment Sheet e as assinaturas. ### Adicionar o Payment Element ao seu aplicativo > Esta etapa mostra uma maneira de começar, mas você pode usar qualquer [integração de pagamentos no aplicativo](https://docs.stripe.com/payments/mobile.md). Inicialize e apresente o Mobile Payment Element usando a classe PaymentSheet. ```swift struct SubscribeView: View { let paymentSheet: PaymentSheet @State var isPaymentSheetPresented = false init(clientSecret: String) { var config = PaymentSheet.Configuration() // Set `allowsDelayedPaymentMethods` to true if your business handles // delayed notification payment methods like US bank accounts. config.allowsDelayedPaymentMethods = true config.primaryButtonLabel = "Subscribe for $15/month" self.paymentSheet = PaymentSheet(paymentIntentClientSecret: clientSecret, configuration: config) } var body: some View { Button { isPaymentSheetPresented = true } label: { Text("Subscribe") }.paymentSheet(isPresented: $isPaymentSheetPresented, paymentSheet: paymentSheet) { result in switch result { case .completed: // Handle completion case .canceled: break case .failed(let error): // Handle error } } } } ``` O Mobile Payment Element renderiza uma planilha que permite ao cliente selecionar uma forma de pagamento. O formulário coleta automaticamente todos os dados de pagamento necessários da forma de pagamento selecionada. Configurar `allowsDelayedPaymentMethods` como verdadeiro permite formas de pagamento de [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification) como contas bancárias dos EUA. Para essas formas de pagamento, o status final do pagamento não é conhecido quando o `PaymentSheet` é concluído, sendo efetivado ou não posteriormente. Se você aceitar esses tipos de formas de pagamento, informe o cliente que seu pedido está confirmado e somente processe o pedido (por exemplo, fazendo o envio do produto) quando o pagamento for bem-sucedido. Você pode personalizar o Payment Element para combinar com o design do seu app usando a propriedade [`appearance`](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=ios) do objeto `PaymentSheet.Configuration`. ### Confirmar pagamento O Mobile Payment Element cria um PaymentMethod e confirma o primeiro PaymentIntent da assinatura incompleta, resultando em uma cobrança. Se a *Autenticação forte de cliente* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase) (SCA) for necessária para o pagamento, o Payment Element gerenciará o processo de autenticação antes de confirmar o PaymentIntent. ## Configurar um URL de retorno [Lado do cliente] O cliente pode sair do seu aplicativo para autenticar (por exemplo, no Safari ou no aplicativo bancário). Para permitir que eles voltem ao seu aplicativo após a autenticação, [configure um esquema de URL personalizado](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) e configure seu aplicativo delegado para encaminhar o URL ao SDK. A Stripe não aceita [links universais](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content). #### SceneDelegate #### Swift ```swift // This method handles opening custom URL schemes (for example, "your-app://stripe-redirect") func scene(_ scene: UIScene, openURLContexts URLContexts: Set) { guard let url = URLContexts.first?.url else { return } let stripeHandled = StripeAPI.handleURLCallback(with: url) if (!stripeHandled) { // This was not a Stripe url – handle the URL normally as you would } } ``` #### AppDelegate #### Swift ```swift // This method handles opening custom URL schemes (for example, "your-app://stripe-redirect") func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool { let stripeHandled = StripeAPI.handleURLCallback(with: url) if (stripeHandled) { return true } else { // This was not a Stripe url – handle the URL normally as you would } return false } ``` #### SwiftUI #### Swift ```swift @main struct MyApp: App { var body: some Scene { WindowGroup { Text("Hello, world!").onOpenURL { incomingURL in let stripeHandled = StripeAPI.handleURLCallback(with: incomingURL) if (!stripeHandled) { // This was not a Stripe url – handle the URL normally as you would } } } } } ``` Além disso, defina o [returnURL](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:6Stripe12PaymentSheetC13ConfigurationV9returnURLSSSgvp) no seu objeto [PaymentSheet.Configuration](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html) para o URL do seu aplicativo. ```swift var configuration = PaymentSheet.Configuration() configuration.returnURL = "your-app://stripe-redirect" ``` ## Optional: Ativar Apple Pay ### Solicitar um ID de comerciante da Apple Obtenha um ID de comerciante da Apple [solicitando um novo identificador](https://developer.apple.com/account/resources/identifiers/add/merchant) no site de desenvolvedores da Apple. Preencha o formulário com descrição e identificador. A descrição é para seu controle e pode ser modificada no futuro. A Stripe recomenda que você use o nome do aplicativo como identificador (por exemplo, `merchant.com.{{YOUR_APP_NAME}}`). ### Criar um certificado Apple Pay Crie um certificado para criptografia de dados de pagamento pelo aplicativo. Vá até [Configurações de certificado do iOS](https://dashboard.stripe.com/settings/ios_certificates) no Dashboard, clique em **Adicionar novo aplicativo** e siga o guia. Baixe um arquivo de solicitação de assinatura de certificado (CSR) para obter um certificado seguro da Apple que permite usar o Apple Pay. Um arquivo CSR deve ser usado para emitir exatamente um certificado. Se você trocar seu ID de comerciante da Apple, acesse as [Configurações de certificado do iOS](https://dashboard.stripe.com/settings/ios_certificates) no Dashboard para obter um novo CSR e certificado. ### Integrar com Xcode Adicione as funções do Apple Pay ao aplicativo. No Xcode, abra as configurações do projeto, clique na guia **Signing & Capabilities** e adicione o recurso **Apple Pay**. Talvez seja necessário fazer login na sua conta de desenvolvedor. Selecione o ID de comerciante criado anteriormente e o aplicativo já pode aceitar Apple Pay. ![](https://b.stripecdn.com/docs-statics-srv/assets/xcode.a701d4c1922d19985e9c614a6f105bf1.png) Habilitar o recurso Apple Pay no Xcode ### Adicionar Apple Pay #### Pagamentos recorrentes Para adicionar Apple Pay à PaymentSheet, defina [applePay](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:6Stripe12PaymentSheetC13ConfigurationV8applePayAC05ApplefD0VSgvp) após inicializar `PaymentSheet.Configuration` com seu ID de comerciante Apple e o [código de país da sua empresa](https://dashboard.stripe.com/settings/account). De acordo com as [diretrizes da Apple](https://developer.apple.com/design/human-interface-guidelines/apple-pay#Supporting-subscriptions) para pagamentos recorrentes, você também precisará definir atributos adicionais no `PKPaymentRequest`. Adicione um gerenciador em [ApplePayConfiguration.paymentRequestHandlers](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/applepayconfiguration/handlers/paymentrequesthandler) para configurar [PKPaymentRequest.paymentSummaryItems](https://developer.apple.com/documentation/passkit/pkpaymentrequest/1619231-paymentsummaryitems) com o valor que você pretende cobrar (por exemplo, 9,95 USD por mês). Você também pode adotar [tokens de comerciante](https://developer.apple.com/apple-pay/merchant-tokens/) definindo as propriedades `recurringPaymentRequest` ou `automaticReloadPaymentRequest` no `PKPaymentRequest`. Para saber mais sobre como usar pagamentos recorrentes com o Apple Pay, consulte a [documentação do PassKit da Apple](https://developer.apple.com/documentation/passkit/pkpaymentrequest). #### iOS (Swift) ```swift let customHandlers = PaymentSheet.ApplePayConfiguration.Handlers( paymentRequestHandler: { request in // PKRecurringPaymentSummaryItem is available on iOS 15 or later if #available(iOS 15.0, *) { let billing = PKRecurringPaymentSummaryItem(label: "My Subscription", amount: NSDecimalNumber(string: "59.99")) // Payment starts today billing.startDate = Date() // Payment ends in one year billing.endDate = Date().addingTimeInterval(60 * 60 * 24 * 365) // Pay once a month. billing.intervalUnit = .month billing.intervalCount = 1 // recurringPaymentRequest is only available on iOS 16 or later if #available(iOS 16.0, *) { request.recurringPaymentRequest = PKRecurringPaymentRequest(paymentDescription: "Recurring", regularBilling: billing, managementURL: URL(string: "https://my-backend.example.com/customer-portal")!) request.recurringPaymentRequest?.billingAgreement = "You'll be billed $59.99 every month for the next 12 months. To cancel at any time, go to Account and click 'Cancel Membership.'" } request.paymentSummaryItems = [billing] request.currencyCode = "USD" } else { // On older iOS versions, set alternative summary items. request.paymentSummaryItems = [PKPaymentSummaryItem(label: "Monthly plan starting July 1, 2022", amount: NSDecimalNumber(string: "59.99"), type: .final)] } return request } ) var configuration = PaymentSheet.Configuration() configuration.applePay = .init(merchantId: "merchant.com.your_app_name", merchantCountryCode: "US", customHandlers: customHandlers) ``` ### Rastreamento de pedidos Para adicionar informações de [rastreamento de pedidos](https://developer.apple.com/design/human-interface-guidelines/technologies/wallet/designing-order-tracking) no iOS 16 ou posterior, configure um [authorizationResultHandler](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/applepayconfiguration/handlers/authorizationresulthandler) em seu `PaymentSheet.ApplePayConfiguration.Handlers`. A Stripe invoca sua implementação após a conclusão do pagamento, mas antes que o iOS descarte a descrição Apple Pay. Na sua implementação de `authorizationResultHandler`, obtenha os detalhes do pedido a partir do seu servidor para o pedido concluído. Adicione esses detalhes ao [PKPaymentAuthorizationResult](https://developer.apple.com/documentation/passkit/pkpaymentauthorizationresult) fornecido e retorne o resultado modificado. Para saber mais sobre o rastreamento de pedidos, consulte a [documentação de pedidos da carteira da Apple](https://developer.apple.com/documentation/walletorders). #### iOS (Swift) ```swift let customHandlers = PaymentSheet.ApplePayConfiguration.Handlers( authorizationResultHandler: { result in do { // Fetch the order details from your service let myOrderDetails = try await MyAPIClient.shared.fetchOrderDetails(orderID: orderID) result.orderDetails = PKPaymentOrderDetails( orderTypeIdentifier: myOrderDetails.orderTypeIdentifier, // "com.myapp.order" orderIdentifier: myOrderDetails.orderIdentifier, // "ABC123-AAAA-1111" webServiceURL: myOrderDetails.webServiceURL, // "https://my-backend.example.com/apple-order-tracking-backend" authenticationToken: myOrderDetails.authenticationToken) // "abc123" // Return your modified PKPaymentAuthorizationResult return result } catch { return PKPaymentAuthorizationResult(status: .failure, errors: [error]) } } ) var configuration = PaymentSheet.Configuration() configuration.applePay = .init(merchantId: "merchant.com.your_app_name", merchantCountryCode: "US", customHandlers: customHandlers) ``` ## Ouvir webhooks [Servidor] Para concluir a integração, é preciso processar os *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) enviados pela Stripe. Os eventos são acionados sempre que o estado dentro da Stripe muda, como assinaturas criando novas faturas. Em seu aplicativo, configure um gerenciador de HTTP para aceitar uma solicitação POST contendo o evento de webhook e verifique a assinatura do evento: #### 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 = '<>' post '/webhook' do # You can use webhooks to receive information about asynchronous payment events. # For more about our webhook events check out https://stripe.com/docs/webhooks. webhook_secret = ENV['STRIPE_WEBHOOK_SECRET'] payload = request.body.read if !webhook_secret.empty? # Retrieve the event by verifying the signature using the raw body and secret if webhook signing is configured. sig_header = request.env['HTTP_STRIPE_SIGNATURE'] event = nil begin event = Stripe::Webhook.construct_event( payload, sig_header, webhook_secret ) rescue JSON::ParserError => e # Invalid payload status 400 return rescue Stripe::SignatureVerificationError => e # Invalid signature puts '⚠️ Webhook signature verification failed.' status 400 return end else data = JSON.parse(payload, symbolize_names: true) event = Stripe::Event.construct_from(data) end # Get the type of webhook event sent - used to check the status of PaymentIntents. event_type = event['type'] data = event['data'] data_object = data['object'] if event_type == 'invoice.paid' # Used to provision services after the trial has ended. # The status of the invoice will show up as paid. Store the status in your # database to reference when a user accesses your service to avoid hitting rate # limits. # puts data_object end if event_type == 'invoice.payment_failed' # If the payment fails or the customer does not have a valid payment method, # an invoice.payment_failed event is sent, the subscription becomes past_due. # Use this webhook to notify your user that their payment has # failed and to retrieve new card details. # puts data_object end if event_type == 'customer.subscription.deleted' # handle subscription canceled automatically based # upon your subscription settings. Or if the user cancels it. # puts data_object end content_type 'application/json' { status: 'success' }.to_json end ``` Durante o desenvolvimento, use o Stripe CLI para [observar webhooks e encaminhá-los ao seu aplicativo](https://docs.stripe.com/webhooks.md#test-webhook). Execute o seguinte em um novo terminal enquanto seu aplicativo de desenvolvimento está sendo executado: #### curl ```bash stripe listen --forward-to localhost:4242/webhook ``` Para produção, configure um URL de endpoint de webhook no Dashboard ou use o [Webhook Endpoints API](https://docs.stripe.com/api/webhook_endpoints.md). Você precisa ouvir alguns eventos para concluir as etapas restantes deste guia. Consulte [Eventos de assinatura](https://docs.stripe.com/billing/subscriptions/webhooks.md#events) para obter mais detalhes sobre webhooks específicos de assinatura. ## Providenciar acesso ao seu serviço [Cliente e servidor] Agora que a assinatura está ativa, dê ao usuário acesso ao seu serviço. Para fazer isso, ouça os eventos `customer.subscription.created`, `customer.subscription.updated` e `customer.subscription.deleted`. Esses eventos passam um objeto de assinatura que contém um campo `status` indicando se a assinatura está ativa, vencida ou cancelada. Consulte [o ciclo de vida da assinatura](https://docs.stripe.com/billing/subscriptions/overview.md#subscription-lifecycle) para obter uma lista completa de status. No seu gerenciador de webhooks: 1. Verifique o status da assinatura. Se estiver `ativo`, então o usuário pagou pelo seu produto. 1. Confira o produto que o cliente assinou e conceda acesso ao serviço. Verificar o produto em vez do preço proporciona mais flexibilidade, caso seja necessário alterar os preços ou o intervalo de faturamento. 1. Armazene o `product.id`, `subscription.id` e `subscription.status` no seu banco de dados junto com o `customer.id` que já salvou. Verifique esse registro quando determinar quais recursos precisam ser ativados para o usuário no seu aplicativo. O estado de uma assinatura pode mudar a qualquer momento durante seu ciclo de vida, mesmo que sua aplicação não faça nenhuma chamada diretamente para a Stripe. Por exemplo, uma renovação pode falhar devido a um cartão de crédito expirado, o que coloca a assinatura em estado vencido. Ou, se você implementar o [portal do cliente](https://docs.stripe.com/customer-management.md), um usuário pode cancelar sua assinatura sem acessar diretamente sua aplicação. Implementar corretamente seu manipulador mantém o estado da sua aplicação sincronizado com a Stripe. ## Cancelar a assinatura [Cliente e servidor] É comum permitir que os clientes cancelem suas assinaturas. Este exemplo adiciona uma opção de cancelamento à página de configurações da conta. O exemplo coleta o ID da assinatura no front-end, mas o seu aplicativo pode obter essas informações do seu banco de dados para seu usuário conectado. ![Exemplo de interface de cancelamento de assinatura.](https://b.stripecdn.com/docs-statics-srv/assets/fixed-price-subscriptions-guide-account-settings.6559626ba4b434826a67abfea165e097.png) Configurações da conta com a capacidade de cancelar a assinatura ```swift func cancelSubscription() async { var request = URLRequest(url: URL(string: "http://localhost:4242/cancel-subscription")!) request.httpMethod = "POST" request.setValue("application/json", forHTTPHeaderField: "Content-Type") request.httpBody = try! JSONEncoder().encode(["subscriptionId": subscription.id]) let (subscriptionResponse, _) = try! await URLSession.shared.data(for: request) // Update the state to show the subscription has been cancelled } ``` No back-end, defina o endpoint para a chamada do seu aplicativo. #### 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 = '<>' post '/cancel-subscription' do content_type 'application/json' data = JSON.parse request.body.read deleted_subscription = Stripe::Subscription.cancel(data['subscriptionId']) deleted_subscription.to_json end ``` Seu back-end recebe um evento `customer.subscription.deleted`. Após o cancelamento da assinatura, remova do banco de dados o ID de assinatura da Stripe que você armazenou anteriormente e limite o acesso ao seu serviço. Depois de serem canceladas, as assinaturas não podem ser reativadas. Obtenha dados de faturamento atualizados do seu cliente, atualize a forma de pagamento padrão e crie uma nova assinatura com o registro de cliente existente. ## Teste a integração ### Testar formas de pagamento Use a tabela a seguir para testar diferentes formas de pagamento e cenários. | Forma de pagamento | Cenário | Como testar | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Débito automático BECS | O cliente paga com débito automático BECS. | Preencha o formulário usando o número da conta `900123456` e BSB `000000`. O PaymentIntent confirmado inicialmente passa para o status `processing`, depois passa para `succeeded` três minutos depois. | | Débito automático BECS | O pagamento do cliente falha com um código de erro `account_closed`. | Preencha o formulário usando o número da conta `111111113` e BSB `000000`. | | Cartão de crédito | O pagamento com cartão é bem-sucedido e não precisa de autenticação. | Preencha o formulário do cartão de crédito usando o número de cartão de crédito `4242 4242 4242 4242` com qualquer validade, CVC e código postal. | | Cartão de crédito | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número `4000 0025 0000 3155` com qualquer validade, CVC e código postal. | | Cartão de crédito | O cartão é recusado com um código de recusa como `insufficient_funds`. | Preencha o formulário do cartão de crédito usando o número `4000 0000 0000 9995` com qualquer validade, CVC e código postal. | | Débito automático SEPA | O cliente paga com débito automático SEPA. | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processing e, três minutos depois, para succeeded. | | Débito automático SEPA | O status do PaymentIntent do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`. | ### Monitorar eventos Configure webhooks para ouvir eventos de alteração de assinatura, como atualizações e cancelamentos. Saiba mais sobre [webhooks de assinatura](https://docs.stripe.com/billing/subscriptions/webhooks.md). É possível visualizar eventos no [Dashboard](https://dashboard.stripe.com/test/events) ou com a [Stripe CLI](https://docs.stripe.com/webhooks.md#test-webhook). Saiba mais em [testar sua integração com o Billing](https://docs.stripe.com/billing/testing.md). ## Optional: Permita que os clientes alterem seus planos [Cliente e servidor] Para permitir que seus clientes alterem assinaturas, obtenha o ID do preço da opção para a qual desejam mudar. Em seguida, envie o ID do novo preço do aplicativo para um endpoint de back-end. Este exemplo também passa o ID da assinatura, mas é possível acessá-lo no seu banco de dados para seu usuário conectado. ```swift func updateSubscription(priceId: String, subscriptionId: String) async -> SubscriptionsResponse { var request = URLRequest(url: URL(string: "http://localhost:4242/update-subscription")!) request.httpMethod = "POST" request.setValue("application/json", forHTTPHeaderField: "Content-Type") request.httpBody = try! JSONEncoder().encode(["subscriptionId": subscriptionId, "priceId": priceId]) let (responseData, _) = try! await URLSession.shared.data(for: request) // SubscriptionsResponse is a Decodable struct conforming to the expected response from your backend let subscriptionsResponse = try! JSONDecoder().decode(SubscriptionsResponse.self, from: responseData) return subscriptionsResponse } ``` No back-end, defina o endpoint para a chamada do seu front-end, passando o ID da assinatura e o ID do novo preço. A assinatura agora é Premium, a US$ 15 por mês, em vez de Básica, a US$ 5 por mês. #### 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 = '<>' post '/update-subscription' do content_type 'application/json' data = JSON.parse request.body.read subscription = Stripe::Subscription.retrieve(data['subscriptionId']) updated_subscription = Stripe::Subscription.update( data['subscriptionId'], cancel_at_period_end: false, items: [ { id: subscription.items.data[0].id, price: data['newPriceId'] } ] ) updated_subscription.to_json end ``` Seu aplicativo recebe um evento `customer.subscription.updated`. ## Optional: Prévia de uma alteração de preço [Cliente e servidor] Quando seu cliente altera a assinatura, normalmente há um ajuste no valor devido, conhecido como [cobrança proporcional](https://docs.stripe.com/billing/subscriptions/prorations.md). Você pode usar o [endpoint de criação de prévia de fatura](https://docs.stripe.com/api/invoices/create_preview.md) para exibir o valor ajustado aos clientes. No aplicativo, passe os detalhes da prévia da fatura para um endpoint de back-end. ```swift func createPreviewInvoice(customerId: String, subscriptionId: String, newPriceId: String) async -> InvoiceResponse { var request = URLRequest(url: URL(string: "http://localhost:4242/create-preview-invoice")!) request.httpMethod = "POST" request.setValue("application/json", forHTTPHeaderField: "Content-Type") request.httpBody = try! JSONEncoder().encode(["subscriptionId": subscriptionId, "customerId": customerId, "newPriceId": newPriceId]) let (responseData, _) = try! await URLSession.shared.data(for: request) // Invoice is a Decodable struct conforming to the expected response from your backend let invoiceResponse = try! JSONDecoder().decode(InvoiceResponse.self, from: responseData) return invoiceResponse } ``` No back-end, defina o endpoint para a chamada do seu front-end. #### 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 = '<>' post '/create-preview-invoice' do content_type 'application/json' data = JSON.parse request.body.read subscription = Stripe::Subscription.retrieve(data['subscriptionId']) invoice = Stripe::Invoice.create_preview( customer: data['customerId'], subscription: data['subscriptionId'], subscription_details: { items: [ { id: subscription.items.data[0].id, deleted: true }, { price: data['newPriceId'], deleted: false } ] } ) invoice.to_json end ``` ## Optional: Exibir a forma de pagamento do cliente [Cliente e servidor] Exibir a bandeira e os últimos quatro dígitos do cartão do seu cliente informa qual cartão está sendo cobrado ou se é preciso atualizar a forma de pagamento. No front-end, envie o ID da forma de pagamento para um endpoint de back-end que recupera os detalhes da forma de pagamento. ```swift func retrieveCustomerPaymentMethod(paymentMethodId: String) async -> PaymentMethodResponse { var request = URLRequest(url: URL(string: "http://localhost:4242/retrieve-customer-payment-method")!) request.httpMethod = "POST" request.setValue("application/json", forHTTPHeaderField: "Content-Type") request.httpBody = try! JSONEncoder().encode(["paymentMethodId": paymentMethodId]) let (responseData, _) = try! await URLSession.shared.data(for: request) // PaymentMethodResponse is a Decodable struct conforming to the expected response from your backend let paymentMethodResponse = try! JSONDecoder().decode(PaymentMethodResponse.self, from: responseData) return paymentMethodResponse } ``` No back-end, defina o endpoint para a chamada do seu aplicativo. #### 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 = '<>' post '/retrieve-customer-payment-method' do content_type 'application/json' data = JSON.parse request.body.read payment_method = Stripe::PaymentMethod.retrieve(data['paymentMethodId']) payment_method.to_json end ``` Exemplo de resposta: ```json { "id": "pm_1GcbHY2eZvKYlo2CoqlVxo42", "object": "payment_method", "billing_details": { "address": { "city": null, "country": null, "line1": null, "line2": null, "postal_code": null, "state": null }, "email": null, "name": null, "phone": null }, "card": { "brand": "visa", "checks": { "address_line1_check": null, "address_postal_code_check": null, "cvc_check": "pass" }, "country": "US", "exp_month": 8, "exp_year": 2021, "fingerprint": "Xt5EWLLDS7FJjR1c", "funding": "credit", "generated_from": null, "last4": "4242", "three_d_secure_usage": { "supported": true }, "wallet": null }, "created": 1588010536, "customer": "cus_HAxB7dVQxhoKLh", "livemode": false, "metadata": {}, "type": "card" } ``` > Recomendamos que você salve o `paymentMethod.id` e `last4` no seu banco de dados (por exemplo, `paymentMethod.id` como `stripeCustomerPaymentMethodId` na sua coleção ou tabela `users`. Você também pode armazenar `exp_month`, `exp_year`, `fingerprint` e `billing_details` conforme necessário. Isso é para limitar o número de chamadas que você faz para a Stripe, tanto para eficiência de desempenho quanto para evitar possíveis limitações de taxa. ## Divulgue a Stripe para seus clientes A Stripe coleta informações sobre interações do cliente com o Elements para fornecer serviços a você, evitar fraudes e melhorar os serviços. Isso inclui o uso de cookies e endereços IP para identificar quais Elements o cliente visualizou durante uma única sessão de checkout. Você é responsável por divulgar e obter todos os direitos e consentimentos necessários para que a Stripe use os dados dessas maneiras. Para saber mais, acesse nossa [central de privacidade](https://stripe.com/legal/privacy-center#as-a-business-user-what-notice-do-i-provide-to-my-end-customers-about-stripe). #### Android Aprenda a vender *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) com preço fixo. Você usará o [Elemento de Pagamento Móvel](https://docs.stripe.com/payments/accept-a-payment.md) para criar um formulário de pagamento personalizado que você pode integrar ao seu aplicativo. ![Página de assinatura com preço fixo com o Mobile Payment Element](https://b.stripecdn.com/docs-statics-srv/assets/fixed-price-collect-payment-details-mobile.b11cdc8fa8952d753238df4df3375fa6.png) > Se você vende produtos ou serviços digitais consumidos no seu aplicativo (por exemplo, assinaturas, moedas de jogos, níveis de jogos, acesso a conteúdo premium ou desbloqueio de uma versão completa), use as APIs de compra no aplicativo da Apple. Essa regra tem algumas exceções, incluindo serviços pessoais individuais e [aplicativos baseados em regiões específicas](https://support.stripe.com/questions/changes-to-mobile-app-store-rules). Consulte as [diretrizes de revisão da App Store](https://developer.apple.com/app-store/review/guidelines/#payments) para obter mais informações. ## Crie sua assinatura Este guia ensina a: - Modelar seus negócios criando um catálogo de produtos. - Crie um processo de registro para adicionar clientes. - Criar assinaturas e coletar dados de pagamento. - Teste e monitore o status de pagamentos e assinaturas. - Permitir que os clientes alterem o plano ou cancelem a assinatura. - Saiba como usar o [modo de faturamento flexíve](https://docs.stripe.com/billing/subscriptions/billing-mode.md) para acessar o comportamento de faturamento aprimorado e recursos adicionais. ## Como modelar na Stripe [Subscriptions](https://docs.stripe.com/api/subscriptions.md) (assinaturas) simplificam seu faturamento ao criar automaticamente *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 [PaymentIntents](https://docs.stripe.com/api/payment_intents.md) para você. Para criar e ativar uma assinatura, primeiro você precisa criar um *Produto* (Products represent what your business sells—whether that's a good or a service) para modelar o que está sendo vendido 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), que determina o intervalo e o valor a cobrar. Você também precisa de um [Customer](https://docs.stripe.com/api/customers.md) (Cliente) para armazenar *PaymentMethods* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) usados para realizar cada pagamento recorrente. #### Accounts v2 Um diagrama que ilustra objetos de cobrança comuns e suas relações (See full diagram at https://docs.stripe.com/billing/subscriptions/build-subscriptions) #### Customer v1 Um diagrama que ilustra objetos de cobrança comuns e suas relações (See full diagram at https://docs.stripe.com/billing/subscriptions/build-subscriptions) ### Definições de objetos de API | Recurso | Definição | | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Conta configurada como cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer) | Represents a customer in the Accounts v2 API who purchases a subscription. Configure an `Account` object as a customer and associate it with a subscription to make and track recurring charges and to manage the products that they subscribe to. For more information, see the [Use Accounts as customers guide](https://docs.stripe.com/connect/use-accounts-as-customers.md). | | [Cliente](https://docs.stripe.com/api/customers.md) | Represents a customer in the Customers API who purchases a subscription. Use the `Customer` object associated with a subscription to make and track recurring charges and to manage the products that they subscribe to. | | [Direito](https://docs.stripe.com/api/entitlements/active-entitlement.md) | Representa o acesso de um cliente a um recurso incluído em um produto de serviço que assina. Quando você cria uma assinatura para a compra recorrente de um produto por um cliente, um direito ativo é automaticamente criado para cada recurso associado a esse produto. Quando um cliente acessa seus serviços, use os direitos ativos para habilitar os recursos incluídos na assinatura. | | [Recurso](https://docs.stripe.com/api/entitlements/feature.md) | Representa uma função ou capacidade que seus clientes podem acessar quando assinam um produto de serviço. Você pode incluir recursos em um produto criando ProductFeatures. | | [Fatura](https://docs.stripe.com/api/invoices.md) | Uma declaração de valores devidos por um cliente que acompanha os status de pagamento desde o esboço até o pagamento (ou outro tipo de finalização). As assinaturas geram faturas automaticamente. | | [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) | Uma maneira de criar fluxos de pagamentos dinâmicos. Um PaymentIntent acompanha o ciclo de vida do fluxo de checkout de um cliente e aciona etapas adicionais de autenticação quando for exigido por mandatos regulatórios, regras personalizadas contra fraudes do Radar ou formas de pagamento baseadas em redirecionamento. As faturas criam PaymentIntents automaticamente. | | [PaymentMethod](https://docs.stripe.com/api/payment_methods.md) | A customer’s payment methods that they use to pay for your products. For example, you can store a credit card on a customer-configured `Account` or `Customer` object and use it to make recurring payments for that customer. Typically used with the Payment Intents or Setup Intents APIs. | | [Price](https://docs.stripe.com/api/prices.md) | Define o preço unitário, a moeda e o ciclo de faturamento de um produto. | | [Product](https://docs.stripe.com/api/products.md) | Um produto ou serviço que sua empresa vende. Um produto de serviço pode incluir um ou mais recursos. | | [ProductFeature](https://docs.stripe.com/api/product-feature.md) | Representa a inclusão de um único recurso em um único produto. Cada produto está associado a um ProductFeature para cada recurso que é incluído, e cada recurso é associado a um ProductFeature para cada produto que o inclui. | | [Subscription](https://docs.stripe.com/api/subscriptions.md) | Representa a compra recorrente agendada de um produto por um cliente. Use uma assinatura para coletar pagamentos e fornecer entregas repetidas ou acesso contínuo a um produto. | Aqui está um exemplo de como produtos, recursos e direitos funcionam juntos. Imagine que você deseja configurar um serviço de assinatura que oferece dois níveis: um produto padrão com funções básicas e um produto avançado que adiciona funções estendidas. 1. Você cria dois recursos: `basic_features` e `extended_features`. 1. Você cria dois produtos: `standard_product` e `advanced_product`. 1. Para o produto padrão, você cria uma ProductFeature que associa `basic_features` com `standard_product`. 1. Para o produto avançado, você cria duas ProductFeatures: uma que associa `basic_features` com `advanced_product` e outra que associa `extended_features` com `advanced_product`. Um cliente, `first_customer`, assina o produto padrão. Quando você cria a assinatura, a Stripe cria automaticamente um Entitlement que associa `first_customer` com `basic_features`. Outro cliente, `second_customer`, assina o produto avançado. Quando você cria a assinatura, a Stripe cria automaticamente dois Entitlements: um que associa `second_customer` a `basic_features` e outro que associa `second_customer` com `extended_features`. É possível determinar quais recursos fornecer para um cliente [recuperando seus direitos ativos ou escutando o evento Active Entitlement Summary](https://docs.stripe.com/billing/entitlements.md#entitlements). Você não precisa buscar as assinaturas, os produtos e os recursos dele. ## Configurar a Stripe O [SDK da Stripe para Android](https://github.com/stripe/stripe-android) é de código aberto e [totalmente documentado](https://stripe.dev/stripe-android/). Para instalar o SDK, adicione `stripe-android` ao bloco `dependencies` do arquivo [app/build.gradle](https://developer.android.com/studio/build/dependencies): #### Kotlin ```kotlin plugins { id("com.android.application") } android { ... } dependencies { // ... // Stripe Android SDK implementation("com.stripe:stripe-android:23.2.0") // Include the financial connections SDK to support US bank account as a payment method implementation("com.stripe:financial-connections:23.2.0") } ``` > Veja mais informações sobre o último lançamento de SDK e as versões anteriores na página [Lançamentos](https://github.com/stripe/stripe-android/releases) no GitHub. Para receber notificações quando um novo lançamento for publicado, [assista aos lançamentos do repositório](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository). Configure o SDK com sua [chave publicável](https://dashboard.stripe.com/apikeys) da Stripe, de modo que seja possível fazer solicitações à API Stripe, como em sua subcategoria `Application`: #### Kotlin ```kotlin import com.stripe.android.PaymentConfiguration class MyApp : Application() { override fun onCreate() { super.onCreate() PaymentConfiguration.init( applicationContext, "<>" ) } } ``` > Use suas [chaves de teste](https://docs.stripe.com/keys.md#obtain-api-keys) enquanto testa e desenvolve, e suas chaves de [modo de produção](https://docs.stripe.com/keys.md#test-live-modes) quando publicar seu aplicativo. Em seguida, instale o Stripe CLI. O CLI fornece testes de webhooks, e você pode executá-lo para fazer chamadas de API para a Stripe. Este guia mostra a você como usar o CLI para configurar um modelo de preços em uma seção posterior. Para obter opções de instalação adicionais, consulte [Comece a usar o Stripe CLI](https://docs.stripe.com/stripe-cli.md). ## Criar o modelo de preços [Stripe CLI ou Dashboard] [Modelos de planos de preços recorrentes](https://docs.stripe.com/products-prices/pricing-models.md) representam os produtos ou serviços que você vende, quanto custam, quais moedas você aceita para pagamentos e o período de serviço para assinaturas. Para montar o modelo de preços, crie [produtos](https://docs.stripe.com/api/products.md) (o que você vende) e [ preços](https://docs.stripe.com/api/prices.md) (quanto e com que frequência cobrar pelos seus produtos). Este exemplo utiliza um plano de preços de taxa fixa com duas opções de nível de serviço diferentes: básico e premium. Para cada opção de nível de serviço, você precisa criar um produto e um preço recorrente. Para adicionar uma cobrança pontual, como uma tarifa de abertura, crie um terceiro produto com um preço pontual. Cada produto fatura em intervalos mensais. O preço do produto básico é 5 USD. O preço do produto premium é 15 USD. Consulte o guia de [plano de preços de taxa fixa](https://docs.stripe.com/subscriptions/pricing-models/flat-rate-pricing.md) para ver um exemplo com três níveis. #### Dashboard Acesse a página [Adicionar um produto](https://dashboard.stripe.com/test/products/create) e crie dois produtos. Adicione um preço para cada produto, cada um com um período de faturamento mensal recorrente: - Produto premium: serviço premium com recursos extras - Preço: Tarifa fixa | 15 USD - Produto básico: serviço básico com recursos mínimos - Preço: Tarifa fixa | 5 USD Depois de criar os preços, registre o ID deles para utilizá-los em outras etapas. Os IDs de preço têm esta estrutura: `price_G0FvDp6vZvdwRZ`. Quando tudo estiver pronto, use o botão **Copiar para modo de produção**, no canto superior direito, para clonar seu produto de [uma área restrita para o modo de produção](https://docs.stripe.com/keys.md#test-live-modes). #### API Você pode usar a API para criar os [produtos](https://docs.stripe.com/api/products.md) e os [ preços](https://docs.stripe.com/api/prices.md). Criar o produto premium: ```curl curl https://api.stripe.com/v1/products \ -u "<>:" \ --data-urlencode "name=Billing Guide: Premium Service" \ -d "description=Premium service with extra features" ``` Criar o produto básico: ```curl curl https://api.stripe.com/v1/products \ -u "<>:" \ --data-urlencode "name=Billing Guide: Basic Service" \ -d "description=Basic service with minimum features" ``` Registre os IDs de cada produto. Eles têm esta estrutura: ```json { "id": "prod_H94k5odtwJXMtQ", "object": "product", "active": true, "attributes": [ ], "created": 1587577341, "description": "Premium service with extra features", "images": [ ], "livemode": false, "metadata": { }, "name": "Billing Guide: Premium Service", "statement_descriptor": null, "type": "service", "unit_label": null, "updated": 1587577341 } ``` Use os IDs de produto para criar um preço para cada produto. O número [unit_amount](https://docs.stripe.com/api/prices/object.md#price_object-unit_amount) está em centavos. Por exemplo, `1500` = 15 USD. Criar o preço premium: ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d product={{PREMIUM_PRODUCT_ID}} \ -d unit_amount=1500 \ -d currency=usd \ -d "recurring[interval]=month" ``` Criar o preço básico: ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d product={{BASIC_PRODUCT_ID}} \ -d unit_amount=500 \ -d currency=usd \ -d "recurring[interval]=month" ``` Registre os IDs de cada preço, para que possam ser usados em etapas subsequentes. Eles têm esta estrutura: ```json { "id": "price_HGd7M3DV3IMXkC", "object": "price", "product": "prod_HGd6W1VUqqXGvr", "type": "recurring", "currency": "usd", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "active": true, "billing_scheme": "per_unit", "created": 1589319695, "livemode": false, "lookup_key": null, "metadata": {}, "nickname": null, "unit_amount": 1500, "unit_amount_decimal": "1500", "tiers": null, "tiers_mode": null, "transform_quantity": null } ``` ## Criar o cliente [Cliente e servidor] A Stripe precisa de um *customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) para cada assinatura. No frontend do seu aplicativo, colete todas as informações necessárias dos seus usuários e passe-as ao backend. > #### Comparar referências de Customers v1 e Accounts v2 > > Se a sua plataforma Connect utiliza [Contas configuradas pelo cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), utilize o nosso [guia](https://docs.stripe.com/connect/use-accounts-as-customers.md) para substituir as referências a `Cliente` e eventos no seu código pelas referências equivalentes da API Accounts v2. Talvez você queira usar uma biblioteca de rede para enviar solicitações de rede ao seu back-end. Este documento usa [okhttp](https://square.github.io/okhttp/), mas você pode usar qualquer biblioteca que funcione melhor em seu projeto. ```groovy dependencies { ... implementation "com.squareup.okhttp3:okhttp:4.12.0" } ``` Se precisar coletar detalhes de endereço, o Address Element permite coletar um endereço de entrega ou cobrança para seus clientes. Saiba mais o Address Element na página [Address Element](https://docs.stripe.com/elements/address-element.md). ```kotlin import androidx.compose.foundation.layout.Column import androidx.compose.material3.Button import androidx.compose.material3.OutlinedTextField import androidx.compose.material3.Text import androidx.compose.runtime.Composable import androidx.compose.runtime.getValue import androidx.compose.runtime.mutableStateOf import androidx.compose.runtime.remember import androidx.compose.runtime.setValue import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import okhttp3.MediaType.Companion.toMediaType import okhttp3.OkHttpClient import okhttp3.Request import okhttp3.RequestBody.Companion.toRequestBody import org.json.JSONObject @Composable fun RegisterView() { var email by remember { mutableStateOf("") } Column { OutlinedTextField(value = email, label = { Text(text = "Email") }, onValueChange = { email = it }) Button(onClick = { val body = JSONObject().put("email", email).toString() .toRequestBody("application/json".toMediaType()) val request = Request.Builder().url("http://10.0.2.2:4567/create-customer").post(body).build() CoroutineScope(Dispatchers.IO).launch { OkHttpClient().newCall(request).execute().use { response -> if (response.isSuccessful) { println(JSONObject(response.body!!.string()).get("customer")) } } } }) { Text(text = "Submit") } } } ``` No servidor, crie o objeto do cliente Stripe. ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d email={{CUSTOMER_EMAIL}} \ -d name={{CUSTOMER_NAME}} \ -d "shipping[address][city]=Brothers" \ -d "shipping[address][country]=US" \ -d "shipping[address][line1]=27 Fredrick Ave" \ -d "shipping[address][postal_code]=97712" \ -d "shipping[address][state]=CA" \ -d "shipping[name]={{CUSTOMER_NAME}}" \ -d "address[city]=Brothers" \ -d "address[country]=US" \ -d "address[line1]=27 Fredrick Ave" \ -d "address[postal_code]=97712" \ -d "address[state]=CA" ``` ## Criar a assinatura [Cliente e servidor] > Se quiser renderizar o Payment Element antes de criar uma assinatura, consulte [Coletar dados de pagamento antes de criar um Intent](https://docs.stripe.com/payments/accept-a-payment-deferred.md?type=subscription). Permita que seu novo cliente escolha um plano e crie a assinatura. Neste guia, ele escolhe Básico ou Premium. No seu aplicativo, passe o ID do preço selecionado e o ID do registro do cliente ao back-end. ```kotlin import okhttp3.MediaType.Companion.toMediaType import okhttp3.OkHttpClient import okhttp3.Request import okhttp3.RequestBody.Companion.toRequestBody import org.json.JSONObject fun createSubscription(priceId: String, customerId: String): SubscriptionResponse? { val body = JSONObject() .put("priceId", priceId) .put("customerId", customerId).toString() .toRequestBody("application/json".toMediaType()) val request = Request.Builder().url("http://10.0.2.2:4567/create-subscription").post(body).build() OkHttpClient().newCall(request).execute().use { response -> if (response.isSuccessful) { // SubscriptionsResponse is data class conforming to the expected response from your backend. // It should include the client_secret, as discussed below. return Gson().fromJson(response.body!!.string(), SubscriptionResponse::class.java) } } return null } ``` No back-end, crie a assinatura com status `incomplete` usando `payment_behavior=default_incomplete`. Em seguida, retorne o `client_secret` do primeiro [Payment Intent](https://docs.stripe.com/payments/payment-intents.md) da assinatura ao frontend para concluir o pagamento expandindo o [`confirmation_secret`](https://docs.stripe.com/api/invoices/object.md#invoice_object-confirmation_secret) na última fatura da assinatura. Para habilitar [comportamento de assinatura aprimorado](https://docs.stripe.com/billing/subscriptions/billing-mode.md), defina `billing_mode[type]` como `flexible`. Você deve usar a versão [2025-06-30.basil](https://docs.stripe.com/changelog/basil.md#2025-06-30.basil) ou posterior da API da Stripe. Defina [save_default_payment_method](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-payment_settings-save_default_payment_method) como `on_subscription` para salvar a forma de pagamento como o padrão para uma assinatura quando um pagamento for bem-sucedido. Salvar uma forma de pagamento padrão aumenta o sucesso de futuros pagamentos de assinatura. The following example creates a `Subscription` and expands the `confirmation_secret` from its latest invoice in the response. That lets you pass the secret to the front end to confirm the payment. #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d payment_behavior=default_incomplete \ -d "payment_settings[save_default_payment_method]=on_subscription" \ -d "billing_mode[type]=flexible" \ -d "expand[0]=latest_invoice.confirmation_secret" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d payment_behavior=default_incomplete \ -d "payment_settings[save_default_payment_method]=on_subscription" \ -d "billing_mode[type]=flexible" \ -d "expand[0]=latest_invoice.confirmation_secret" ``` > Se estiver usando um *preço multimoeda* (A single Price object can support multiple currencies. Each purchase uses one of the supported currencies for the Price, depending on how you use the Price in your integration), use o parâmetro [currency](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-currency) para informar à assinatura qual das moedas do preço deve ser usada. (Se você omitir o parâmetro `currency`, a Assinatura usará a moeda padrão do preço.) A assinatura agora está `inativa` e aguardando pagamento. A resposta de exemplo a seguir destaca os campos mínimos a serem armazenados, mas você pode armazenar o que sua inscrição acessa com frequência. #### Accounts v2 ```json {"id": "sub_JgRjFjhKbtD2qz", "object": "subscription", "application_fee_percent": null, "automatic_tax": { "disabled_reason": null, "enabled": false, "liability": "null" }, "billing_cycle_anchor": 1623873347, "billing_cycle_anchor_config": null, "cancel_at": null, "cancel_at_period_end": false, "canceled_at": null, "cancellation_details": { "comment": null, "feedback": null, "reason": null }, "collection_method": "charge_automatically", "created": 1623873347, "currency": "usd","customer_account": identifier("customerAccount"), "days_until_due": null, "default_payment_method": null, "default_source": null, "default_tax_rates": [ ], "discounts": [], "ended_at": null, "invoice_customer_balance_settings": { "account_tax_ids": null, "issuer": { "type": "self" } }, "items": { "object": "list", "data": [ { "id": "si_JgRjmS4Ur1khEx", "object": "subscription_item", "created": 1623873347,"current_period_end": 1626465347, "current_period_start": 1623873347, "discounts": [], "metadata": { }, "plan": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "plan", "active": true, "amount": 2000, "amount_decimal": "2000", "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "tiers": null, "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "price": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "livemode": false, "lookup_key": null, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "tiers_mode": null, "transform_quantity": null, "type": "recurring", "unit_amount": 2000, "unit_amount_decimal": "2000" }, "quantity": 1, "subscription": "sub_JgRjFjhKbtD2qz", "tax_rates": [ ] } ], "has_more": false, "total_count": 1, "url": "/v1/subscription_items?subscription=sub_JgRjFjhKbtD2qz" }, "latest_invoice": { "id": "in_1J34pzGPZ1iASj5zB87qdBNZ", "object": "invoice", "account_country": "US", "account_name": "Angelina's Store", "account_tax_ids": null, "amount_due": 2000, "amount_overpaid": 0, "amount_paid": 0, "amount_remaining": 2000, "amount_shipping": 0, "attempt_count": 0, "attempted": false, "auto_advance": false, "automatic_tax": { "disabled_reason": null, "enabled": false, "liability": null, "status": null }, "automatically_finalizes_at": null, "billing_reason": "subscription_update", "collection_method": "charge_automatically", "created": 1623873347, "currency": "usd", "custom_fields": null, "customer_account": identifier("customerAccount"), "customer_address": null, "customer_email": "angelina@stripe.com", "customer_name": null, "customer_phone": null, "customer_shipping": { "address": { "city": "", "country": "US", "line1": "Berry", "line2": "", "postal_code": "", "state": "" }, "name": "", "phone": null }, "customer_tax_exempt": "none", "customer_tax_ids": [ ], "default_payment_method": null, "default_source": null, "default_tax_rates": [ ], "description": null, "discounts": [], "due_date": null, "effective_at": "1623873347", "ending_balance": 0, "footer": null, "from_invoice": null, "hosted_invoice_url": "https://invoice.stripe.com/i/acct_1By64KGPZ1iASj5z/invst_JgRjzIOILGeq2MKC9T0KtyXnD5udsLp", "invoice_pdf": "https://pay.stripe.com/invoice/acct_1By64KGPZ1iASj5z/invst_JgRjzIOILGeq2MKC9T0KtyXnD5udsLp/pdf", "last_finalization_error": null, "latest_revision": null, "lines": { "object": "list", "data": [ { "id": "il_1N2CjMBwKQ696a5NeOawRQP2", "object": "line_item", "amount": 2000, "currency": "usd", "description": "1 × Gold Special (at $20.00 / month)", "discount_amounts": [ ], "discountable": true, "discounts": [ ], "invoice": "in_1J34pzGPZ1iASj5zB87qdBNZ", "livemode": false, "metadata": { }, "parent": { "invoice_item_details": null, "subscription_item_details": { "invoice_item": null, "proration": false, "proration_details": { "credited_items": null }, "subscription": "sub_JgRjFjhKbtD2qz", "subscription_item": "si_JgRjmS4Ur1khEx" }, "type": "subscription_item_details" }, "period": { "end": 1626465347, "start": 1623873347 }, "plan": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "plan", "active": true, "amount": 2000, "amount_decimal": "2000", "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "tiers": null, "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "price": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "livemode": false, "lookup_key": null, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "tiers_mode": null, "transform_quantity": null, "type": "recurring", "unit_amount": 2000, "unit_amount_decimal": "2000" }, "quantity": 1, "taxes": [] } ], "has_more": false, "total_count": 1, "url": "/v1/invoices/in_1J34pzGPZ1iASj5zB87qdBNZ/lines" }, "livemode": false, "metadata": { }, "next_payment_attempt": null, "number": "C008FC2-0354", "on_behalf_of": null, "parent": { "quote_details": null, "subscription_details": { "metadata": {}, "pause_collection": null, "subscription": "sub_JgRjFjhKbtD2qz" } }, "payment_intent": { "id": "pi_1J34pzGPZ1iASj5zI2nOAaE6", "object": "payment_intent", "allowed_source_types": [ "card" ], "amount": 2000, "amount_capturable": 0, "amount_received": 0, "application": null, "application_fee_amount": null, "canceled_at": null, "cancellation_reason": null, "capture_method": "automatic", "charges": { "object": "list", "data": [ ], "has_more": false, "total_count": 0, "url": "/v1/charges?payment_intent=pi_1J34pzGPZ1iASj5zI2nOAaE6" }, "client_secret": "pi_1J34pzGPZ1iASj5zI2nOAaE6_secret_l7FN6ldFfXiFmJEumenJ2y2wu", "confirmation_method": "automatic", "created": 1623873347, "currency": "usd", "customer": "cus_CMqDWO2xODTZqt", "description": "Subscription creation", "invoice": "in_1J34pzGPZ1iASj5zB87qdBNZ", "last_payment_error": null, "livemode": false, "metadata": { }, "next_action": null, "next_source_action": null, "on_behalf_of": null, "payment_method": null, "payment_method_options": { "card": { "installments": null, "network": null, "request_three_d_secure": "automatic" } }, "payment_method_types": [ "card" ], "receipt_email": null, "review": null, "setup_future_usage": "off_session", "shipping": null, "source": "card_1By6iQGPZ1iASj5z7ijKBnXJ", "statement_descriptor": null, "statement_descriptor_suffix": null, "status": "requires_confirmation", "transfer_data": null, "transfer_group": null }, "payment_settings": { "payment_method_options": null, "payment_method_types": null, "save_default_payment_method": "on_subscription" }, "period_end": 1623873347, "period_start": 1623873347, "post_payment_credit_notes_amount": 0, "pre_payment_credit_notes_amount": 0, "receipt_number": null, "starting_balance": 0, "statement_descriptor": null, "status": "open", "status_transitions": { "finalized_at": 1623873347, "marked_uncollectible_at": null, "paid_at": null, "voided_at": null }, "subscription": "sub_JgRjFjhKbtD2qz", "subtotal": 2000, "tax": null, "tax_percent": null, "total": 2000, "total_discount_amounts": [], "total_tax_amounts": [], "transfer_data": null, "webhooks_delivered_at": 1623873347 }, "livemode": false, "metadata": { }, "next_pending_invoice_item_invoice": null, "pause_collection": null, "pending_invoice_item_interval": null, "pending_setup_intent": null, "pending_update": null, "plan": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "plan", "active": true, "amount": 2000, "amount_decimal": "2000", "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "tiers": null, "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "quantity": 1, "schedule": null, "start": 1623873347, "start_date": 1623873347, "status": "incomplete", "tax_percent": null, "transfer_data": null, "trial_end": null, "trial_start": null } ``` #### Customers v1 ```json {"id": "sub_JgRjFjhKbtD2qz", "object": "subscription", "application_fee_percent": null, "automatic_tax": { "disabled_reason": null, "enabled": false, "liability": "null" }, "billing_cycle_anchor": 1623873347, "billing_cycle_anchor_config": null, "cancel_at": null, "cancel_at_period_end": false, "canceled_at": null, "cancellation_details": { "comment": null, "feedback": null, "reason": null }, "collection_method": "charge_automatically", "created": 1623873347, "currency": "usd","customer": identifier("customer"), "days_until_due": null, "default_payment_method": null, "default_source": null, "default_tax_rates": [ ], "discounts": [], "ended_at": null, "invoice_customer_balance_settings": { "account_tax_ids": null, "issuer": { "type": "self" } }, "items": { "object": "list", "data": [ { "id": "si_JgRjmS4Ur1khEx", "object": "subscription_item", "created": 1623873347,"current_period_end": 1626465347, "current_period_start": 1623873347, "discounts": [], "metadata": { }, "plan": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "plan", "active": true, "amount": 2000, "amount_decimal": "2000", "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "tiers": null, "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "price": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "livemode": false, "lookup_key": null, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "tiers_mode": null, "transform_quantity": null, "type": "recurring", "unit_amount": 2000, "unit_amount_decimal": "2000" }, "quantity": 1, "subscription": "sub_JgRjFjhKbtD2qz", "tax_rates": [ ] } ], "has_more": false, "total_count": 1, "url": "/v1/subscription_items?subscription=sub_JgRjFjhKbtD2qz" }, "latest_invoice": { "id": "in_1J34pzGPZ1iASj5zB87qdBNZ", "object": "invoice", "account_country": "US", "account_name": "Angelina's Store", "account_tax_ids": null, "amount_due": 2000, "amount_overpaid": 0, "amount_paid": 0, "amount_remaining": 2000, "amount_shipping": 0, "attempt_count": 0, "attempted": false, "auto_advance": false, "automatic_tax": { "disabled_reason": null, "enabled": false, "liability": null, "status": null }, "automatically_finalizes_at": null, "billing_reason": "subscription_update", "collection_method": "charge_automatically", "created": 1623873347, "currency": "usd", "custom_fields": null, "customer": identifier("customer"), "customer_address": null, "customer_email": "angelina@stripe.com", "customer_name": null, "customer_phone": null, "customer_shipping": { "address": { "city": "", "country": "US", "line1": "Berry", "line2": "", "postal_code": "", "state": "" }, "name": "", "phone": null }, "customer_tax_exempt": "none", "customer_tax_ids": [ ], "default_payment_method": null, "default_source": null, "default_tax_rates": [ ], "description": null, "discounts": [], "due_date": null, "effective_at": "1623873347", "ending_balance": 0, "footer": null, "from_invoice": null, "hosted_invoice_url": "https://invoice.stripe.com/i/acct_1By64KGPZ1iASj5z/invst_JgRjzIOILGeq2MKC9T0KtyXnD5udsLp", "invoice_pdf": "https://pay.stripe.com/invoice/acct_1By64KGPZ1iASj5z/invst_JgRjzIOILGeq2MKC9T0KtyXnD5udsLp/pdf", "last_finalization_error": null, "latest_revision": null, "lines": { "object": "list", "data": [ { "id": "il_1N2CjMBwKQ696a5NeOawRQP2", "object": "line_item", "amount": 2000, "currency": "usd", "description": "1 × Gold Special (at $20.00 / month)", "discount_amounts": [ ], "discountable": true, "discounts": [ ], "invoice": "in_1J34pzGPZ1iASj5zB87qdBNZ", "livemode": false, "metadata": { }, "parent": { "invoice_item_details": null, "subscription_item_details": { "invoice_item": null, "proration": false, "proration_details": { "credited_items": null }, "subscription": "sub_JgRjFjhKbtD2qz", "subscription_item": "si_JgRjmS4Ur1khEx" }, "type": "subscription_item_details" }, "period": { "end": 1626465347, "start": 1623873347 }, "plan": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "plan", "active": true, "amount": 2000, "amount_decimal": "2000", "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "tiers": null, "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "price": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "livemode": false, "lookup_key": null, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "tiers_mode": null, "transform_quantity": null, "type": "recurring", "unit_amount": 2000, "unit_amount_decimal": "2000" }, "quantity": 1, "taxes": [] } ], "has_more": false, "total_count": 1, "url": "/v1/invoices/in_1J34pzGPZ1iASj5zB87qdBNZ/lines" }, "livemode": false, "metadata": { }, "next_payment_attempt": null, "number": "C008FC2-0354", "on_behalf_of": null, "parent": { "quote_details": null, "subscription_details": { "metadata": {}, "pause_collection": null, "subscription": "sub_JgRjFjhKbtD2qz" } }, "payment_intent": { "id": "pi_1J34pzGPZ1iASj5zI2nOAaE6", "object": "payment_intent", "allowed_source_types": [ "card" ], "amount": 2000, "amount_capturable": 0, "amount_received": 0, "application": null, "application_fee_amount": null, "canceled_at": null, "cancellation_reason": null, "capture_method": "automatic", "charges": { "object": "list", "data": [ ], "has_more": false, "total_count": 0, "url": "/v1/charges?payment_intent=pi_1J34pzGPZ1iASj5zI2nOAaE6" }, "client_secret": "pi_1J34pzGPZ1iASj5zI2nOAaE6_secret_l7FN6ldFfXiFmJEumenJ2y2wu", "confirmation_method": "automatic", "created": 1623873347, "currency": "usd", "customer": "cus_CMqDWO2xODTZqt", "description": "Subscription creation", "invoice": "in_1J34pzGPZ1iASj5zB87qdBNZ", "last_payment_error": null, "livemode": false, "metadata": { }, "next_action": null, "next_source_action": null, "on_behalf_of": null, "payment_method": null, "payment_method_options": { "card": { "installments": null, "network": null, "request_three_d_secure": "automatic" } }, "payment_method_types": [ "card" ], "receipt_email": null, "review": null, "setup_future_usage": "off_session", "shipping": null, "source": "card_1By6iQGPZ1iASj5z7ijKBnXJ", "statement_descriptor": null, "statement_descriptor_suffix": null, "status": "requires_confirmation", "transfer_data": null, "transfer_group": null }, "payment_settings": { "payment_method_options": null, "payment_method_types": null, "save_default_payment_method": "on_subscription" }, "period_end": 1623873347, "period_start": 1623873347, "post_payment_credit_notes_amount": 0, "pre_payment_credit_notes_amount": 0, "receipt_number": null, "starting_balance": 0, "statement_descriptor": null, "status": "open", "status_transitions": { "finalized_at": 1623873347, "marked_uncollectible_at": null, "paid_at": null, "voided_at": null }, "subscription": "sub_JgRjFjhKbtD2qz", "subtotal": 2000, "tax": null, "tax_percent": null, "total": 2000, "total_discount_amounts": [], "total_tax_amounts": [], "transfer_data": null, "webhooks_delivered_at": 1623873347 }, "livemode": false, "metadata": { }, "next_pending_invoice_item_invoice": null, "pause_collection": null, "pending_invoice_item_interval": null, "pending_setup_intent": null, "pending_update": null, "plan": { "id": "price_1J32RfGPZ1iASj5zHHp57z7C", "object": "plan", "active": true, "amount": 2000, "amount_decimal": "2000", "billing_scheme": "per_unit", "created": 1623864151, "currency": "usd", "interval": "month", "interval_count": 1, "livemode": false, "metadata": { }, "nickname": null, "product": "prod_JgPF5xnq7qBun3", "tiers": null, "tiers_mode": null, "transform_usage": null, "trial_period_days": null, "usage_type": "licensed" }, "quantity": 1, "schedule": null, "start": 1623873347, "start_date": 1623873347, "status": "incomplete", "tax_percent": null, "transfer_data": null, "trial_end": null, "trial_start": null } ``` ### Atualize seu servidor endpoint Adicione a criação de chave efêmera ao endpoint de assinatura e retorne-a na resposta: #### Ruby ```ruby ephemeral_key = Stripe::EphemeralKey.create( {customer: customer_id}, {stripe_version: '2025-06-30.basil'} ) { subscriptionId: subscription.id, clientSecret: subscription.latest_invoice.confirmation_secret.client_secret, ephemeralKey: ephemeral_key.secret, customerId: customer_id, }.to_json ``` ### Atualize seu modelo de resposta ```kotlin data class SubscriptionsResponse( val subscriptionId: String, val clientSecret: String, val ephemeralKey: String, val customerId: String ) ``` ### Passe a configuração do cliente para o PaymentSheet Adicione o seguinte ao configurar o PaymentSheet: ```kotlin PaymentSheet.Configuration( primaryButtonLabel = "Subscribe for $15/month", merchantDisplayName = "My merchant name", customer = PaymentSheet.CustomerConfiguration( id = customerId, ephemeralKeySecret = ephemeralKey ) ) ``` ## Colete dados de pagamento [Cliente] Use o [Payment Sheet](https://docs.stripe.com/payments/mobile/payment-sheet.md) para recolher os detalhes do pagamento e ativar a assinatura. Você pode personalizar o Elements para combinar com a aparência do seu aplicativo. O Payment Sheet coleta com segurança todos os detalhes de pagamento necessários para uma ampla variedade de métodos de pagamento. Saiba mais sobre os [métodos de pagamento compatíveis](https://docs.stripe.com/payments/payment-methods/payment-method-support.md#product-support) com o Payment Sheet e as assinaturas. ### Adicionar o Payment Element ao seu aplicativo > Esta etapa mostra uma maneira de começar, mas você pode usar qualquer [integração de pagamentos no aplicativo](https://docs.stripe.com/payments/mobile.md). Inicialize e apresente o Mobile Payment Element usando a classe PaymentSheet. ```kotlin import androidx.compose.material3.Button import androidx.compose.material3.Text import androidx.compose.runtime.Composable import com.stripe.android.paymentsheet.PaymentSheet import com.stripe.android.paymentsheet.PaymentSheetResult import com.stripe.android.paymentsheet.rememberPaymentSheet @Composable fun SubscribeView(clientSecret: String) { val paymentSheet = rememberPaymentSheet(::onPaymentSheetResult) Button(onClick = { paymentSheet.presentWithPaymentIntent( clientSecret, PaymentSheet.Configuration( primaryButtonLabel = "Subscribe for $15/month", merchantDisplayName = "My merchant name", // Set `allowsDelayedPaymentMethods` to true if your business handles // delayed notification payment methods like US bank accounts. allowsDelayedPaymentMethods = true ) ) }) { Text(text = "Subscribe") } } fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) { when (paymentSheetResult) { is PaymentSheetResult.Canceled -> { print("Canceled") } is PaymentSheetResult.Failed -> { print("Error: ${paymentSheetResult.error}") } is PaymentSheetResult.Completed -> { // Display for example, an order confirmation screen print("Completed") } } } ``` O Mobile Payment Element renderiza uma planilha que permite ao cliente selecionar uma forma de pagamento. O formulário coleta automaticamente todos os dados de pagamento necessários da forma de pagamento selecionada. Configurar `allowsDelayedPaymentMethods` como verdadeiro permite formas de pagamento de [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification) como contas bancárias dos EUA. Para essas formas de pagamento, o status final do pagamento não é conhecido quando o `PaymentSheet` é concluído, sendo efetivado ou não posteriormente. Se você aceitar esses tipos de formas de pagamento, informe o cliente que seu pedido está confirmado e somente processe o pedido (por exemplo, fazendo o envio do produto) quando o pagamento for bem-sucedido. Você pode personalizar o Payment Element para combinar com o design do seu app usando a propriedade [`appearance`](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=ios) do objeto `PaymentSheet.Configuration`. ### Confirmar pagamento O Mobile Payment Element cria um PaymentMethod e confirma o primeiro PaymentIntent da assinatura incompleta, resultando em uma cobrança. Se a *Autenticação forte de cliente* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase) (SCA) for necessária para o pagamento, o Payment Element gerenciará o processo de autenticação antes de confirmar o PaymentIntent. ## Ouvir webhooks [Servidor] Para concluir a integração, é preciso processar os *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) enviados pela Stripe. Os eventos são acionados sempre que o estado dentro da Stripe muda, como assinaturas criando novas faturas. Em seu aplicativo, configure um gerenciador de HTTP para aceitar uma solicitação POST contendo o evento de webhook e verifique a assinatura do evento: #### 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 = '<>' post '/webhook' do # You can use webhooks to receive information about asynchronous payment events. # For more about our webhook events check out https://stripe.com/docs/webhooks. webhook_secret = ENV['STRIPE_WEBHOOK_SECRET'] payload = request.body.read if !webhook_secret.empty? # Retrieve the event by verifying the signature using the raw body and secret if webhook signing is configured. sig_header = request.env['HTTP_STRIPE_SIGNATURE'] event = nil begin event = Stripe::Webhook.construct_event( payload, sig_header, webhook_secret ) rescue JSON::ParserError => e # Invalid payload status 400 return rescue Stripe::SignatureVerificationError => e # Invalid signature puts '⚠️ Webhook signature verification failed.' status 400 return end else data = JSON.parse(payload, symbolize_names: true) event = Stripe::Event.construct_from(data) end # Get the type of webhook event sent - used to check the status of PaymentIntents. event_type = event['type'] data = event['data'] data_object = data['object'] if event_type == 'invoice.paid' # Used to provision services after the trial has ended. # The status of the invoice will show up as paid. Store the status in your # database to reference when a user accesses your service to avoid hitting rate # limits. # puts data_object end if event_type == 'invoice.payment_failed' # If the payment fails or the customer does not have a valid payment method, # an invoice.payment_failed event is sent, the subscription becomes past_due. # Use this webhook to notify your user that their payment has # failed and to retrieve new card details. # puts data_object end if event_type == 'customer.subscription.deleted' # handle subscription canceled automatically based # upon your subscription settings. Or if the user cancels it. # puts data_object end content_type 'application/json' { status: 'success' }.to_json end ``` Durante o desenvolvimento, use o Stripe CLI para [observar webhooks e encaminhá-los ao seu aplicativo](https://docs.stripe.com/webhooks.md#test-webhook). Execute o seguinte em um novo terminal enquanto seu aplicativo de desenvolvimento está sendo executado: #### curl ```bash stripe listen --forward-to localhost:4242/webhook ``` Para produção, configure um URL de endpoint de webhook no Dashboard ou use o [Webhook Endpoints API](https://docs.stripe.com/api/webhook_endpoints.md). Você precisa ouvir alguns eventos para concluir as etapas restantes deste guia. Consulte [Eventos de assinatura](https://docs.stripe.com/billing/subscriptions/webhooks.md#events) para obter mais detalhes sobre webhooks específicos de assinatura. ## Providenciar acesso ao seu serviço [Cliente e servidor] Agora que a assinatura está ativa, dê ao usuário acesso ao seu serviço. Para fazer isso, ouça os eventos `customer.subscription.created`, `customer.subscription.updated` e `customer.subscription.deleted`. Esses eventos passam um objeto de assinatura que contém um campo `status` indicando se a assinatura está ativa, vencida ou cancelada. Consulte [o ciclo de vida da assinatura](https://docs.stripe.com/billing/subscriptions/overview.md#subscription-lifecycle) para obter uma lista completa de status. No seu gerenciador de webhooks: 1. Verifique o status da assinatura. Se estiver `ativo`, então o usuário pagou pelo seu produto. 1. Confira o produto que o cliente assinou e conceda acesso ao serviço. Verificar o produto em vez do preço proporciona mais flexibilidade, caso seja necessário alterar os preços ou o intervalo de faturamento. 1. Armazene o `product.id`, `subscription.id` e `subscription.status` no seu banco de dados junto com o `customer.id` que já salvou. Verifique esse registro quando determinar quais recursos precisam ser ativados para o usuário no seu aplicativo. O estado de uma assinatura pode mudar a qualquer momento durante seu ciclo de vida, mesmo que sua aplicação não faça nenhuma chamada diretamente para a Stripe. Por exemplo, uma renovação pode falhar devido a um cartão de crédito expirado, o que coloca a assinatura em estado vencido. Ou, se você implementar o [portal do cliente](https://docs.stripe.com/customer-management.md), um usuário pode cancelar sua assinatura sem acessar diretamente sua aplicação. Implementar corretamente seu manipulador mantém o estado da sua aplicação sincronizado com a Stripe. ## Cancelar a assinatura [Cliente e servidor] É comum permitir que os clientes cancelem suas assinaturas. Este exemplo adiciona uma opção de cancelamento à página de configurações da conta. O exemplo coleta o ID da assinatura no front-end, mas o seu aplicativo pode obter essas informações do seu banco de dados para seu usuário conectado. ![Exemplo de interface de cancelamento de assinatura.](https://b.stripecdn.com/docs-statics-srv/assets/fixed-price-subscriptions-guide-account-settings.6559626ba4b434826a67abfea165e097.png) Configurações da conta com a capacidade de cancelar a assinatura ```kotlin fun cancelSubscription(subscriptionId: String): SubscriptionResponse? { val body = JSONObject().put("subscriptionId", subscriptionId).toString() .toRequestBody("application/json".toMediaType()) val request = Request.Builder().url("http://10.0.2.2:4567/cancel-subscription").post(body).build() OkHttpClient().newCall(request).execute().use { response -> if (response.isSuccessful) { return Gson().fromJson(response.body!!.string(), SubscriptionResponse::class.java) } } return null } ``` No back-end, defina o endpoint para a chamada do seu aplicativo. #### 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 = '<>' post '/cancel-subscription' do content_type 'application/json' data = JSON.parse request.body.read deleted_subscription = Stripe::Subscription.cancel(data['subscriptionId']) deleted_subscription.to_json end ``` Seu back-end recebe um evento `customer.subscription.deleted`. Após o cancelamento da assinatura, remova do banco de dados o ID de assinatura da Stripe que você armazenou anteriormente e limite o acesso ao seu serviço. Depois de serem canceladas, as assinaturas não podem ser reativadas. Obtenha dados de faturamento atualizados do seu cliente, atualize a forma de pagamento padrão e crie uma nova assinatura com o registro de cliente existente. ## Teste a integração ### Testar formas de pagamento Use a tabela a seguir para testar diferentes formas de pagamento e cenários. | Forma de pagamento | Cenário | Como testar | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Débito automático BECS | O cliente paga com débito automático BECS. | Preencha o formulário usando o número da conta `900123456` e BSB `000000`. O PaymentIntent confirmado inicialmente passa para o status `processing`, depois passa para `succeeded` três minutos depois. | | Débito automático BECS | O pagamento do cliente falha com um código de erro `account_closed`. | Preencha o formulário usando o número da conta `111111113` e BSB `000000`. | | Cartão de crédito | O pagamento com cartão é bem-sucedido e não precisa de autenticação. | Preencha o formulário do cartão de crédito usando o número de cartão de crédito `4242 4242 4242 4242` com qualquer validade, CVC e código postal. | | Cartão de crédito | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número `4000 0025 0000 3155` com qualquer validade, CVC e código postal. | | Cartão de crédito | O cartão é recusado com um código de recusa como `insufficient_funds`. | Preencha o formulário do cartão de crédito usando o número `4000 0000 0000 9995` com qualquer validade, CVC e código postal. | | Débito automático SEPA | O cliente paga com débito automático SEPA. | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processing e, três minutos depois, para succeeded. | | Débito automático SEPA | O status do PaymentIntent do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`. | ### Monitorar eventos Configure webhooks para ouvir eventos de alteração de assinatura, como atualizações e cancelamentos. Saiba mais sobre [webhooks de assinatura](https://docs.stripe.com/billing/subscriptions/webhooks.md). É possível visualizar eventos no [Dashboard](https://dashboard.stripe.com/test/events) ou com a [Stripe CLI](https://docs.stripe.com/webhooks.md#test-webhook). Saiba mais em [testar sua integração com o Billing](https://docs.stripe.com/billing/testing.md). ## Optional: Permita que os clientes alterem seus planos [Cliente e servidor] Para permitir que seus clientes alterem assinaturas, obtenha o ID do preço da opção para a qual desejam mudar. Em seguida, envie o ID do novo preço do aplicativo para um endpoint de back-end. Este exemplo também passa o ID da assinatura, mas é possível acessá-lo no seu banco de dados para seu usuário conectado. ```kotlin fun updateSubscription(subscriptionId: String, priceId: String): SubscriptionResponse? { val body = JSONObject() .put("priceId", priceId) .put("subscriptionId", subscriptionId).toString() .toRequestBody("application/json".toMediaType()) val request = Request.Builder().url("http://10.0.2.2:4567/update-subscription").post(body).build() OkHttpClient().newCall(request).execute().use { response -> if (response.isSuccessful) { // It should include the client_secret, as discussed below. return Gson().fromJson(response.body!!.string(), SubscriptionResponse::class.java) } } return null } ``` No back-end, defina o endpoint para a chamada do seu front-end, passando o ID da assinatura e o ID do novo preço. A assinatura agora é Premium, a US$ 15 por mês, em vez de Básica, a US$ 5 por mês. #### 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 = '<>' post '/update-subscription' do content_type 'application/json' data = JSON.parse request.body.read subscription = Stripe::Subscription.retrieve(data['subscriptionId']) updated_subscription = Stripe::Subscription.update( data['subscriptionId'], cancel_at_period_end: false, items: [ { id: subscription.items.data[0].id, price: data['newPriceId'] } ] ) updated_subscription.to_json end ``` Seu aplicativo recebe um evento `customer.subscription.updated`. ## Optional: Prévia de uma alteração de preço [Cliente e servidor] Quando seu cliente altera a assinatura, normalmente há um ajuste no valor devido, conhecido como [cobrança proporcional](https://docs.stripe.com/billing/subscriptions/prorations.md). Você pode usar o [endpoint de criação de prévia de fatura](https://docs.stripe.com/api/invoices/create_preview.md) para exibir o valor ajustado aos clientes. No aplicativo, passe os detalhes da prévia da fatura para um endpoint de back-end. ```kotlin fun createPreviewInvoice( subscriptionId: String, priceId: String, newPriceId: String ): InvoiceResponse? { val body = JSONObject() .put("priceId", priceId) .put("subscriptionId", subscriptionId) .put("newPriceId", newPriceId).toString() .toRequestBody("application/json".toMediaType()) val request = Request.Builder().url("http://10.0.2.2:4567/create-preview-invoice").post(body).build() OkHttpClient().newCall(request).execute().use { response -> if (response.isSuccessful) { // InvoiceResponse is a data class conforming to the expected response from your backend return Gson().fromJson(response.body!!.string(), InvoiceResponse::class.java) } } return null } ``` No back-end, defina o endpoint para a chamada do seu front-end. #### 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 = '<>' post '/create-preview-invoice' do content_type 'application/json' data = JSON.parse request.body.read subscription = Stripe::Subscription.retrieve(data['subscriptionId']) invoice = Stripe::Invoice.create_preview( customer: data['customerId'], subscription: data['subscriptionId'], subscription_details: { items: [ { id: subscription.items.data[0].id, deleted: true }, { price: data['newPriceId'], deleted: false } ] } ) invoice.to_json end ``` ## Optional: Exibir a forma de pagamento do cliente [Cliente e servidor] Exibir a bandeira e os últimos quatro dígitos do cartão do seu cliente informa qual cartão está sendo cobrado ou se é preciso atualizar a forma de pagamento. No front-end, envie o ID da forma de pagamento para um endpoint de back-end que recupera os detalhes da forma de pagamento. ```kotlin fun retrieveCustomerPaymentMethod(paymentMethodId: String): PaymentMethodResponse? { val body = JSONObject() .put("paymentMethodId", paymentMethodId).toString() .toRequestBody("application/json".toMediaType()) val request = Request.Builder().url("http://10.0.2.2:4567/retrieve-customer-payment-method").post(body) .build() OkHttpClient().newCall(request).execute().use { response -> if (response.isSuccessful) { // PaymentMethodResponse is a data class conforming to the expected response from your backend return Gson().fromJson(response.body!!.string(), PaymentMethodResponse::class.java) } } return null } ``` No back-end, defina o endpoint para a chamada do seu aplicativo. #### 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 = '<>' post '/retrieve-customer-payment-method' do content_type 'application/json' data = JSON.parse request.body.read payment_method = Stripe::PaymentMethod.retrieve(data['paymentMethodId']) payment_method.to_json end ``` Exemplo de resposta: ```json { "id": "pm_1GcbHY2eZvKYlo2CoqlVxo42", "object": "payment_method", "billing_details": { "address": { "city": null, "country": null, "line1": null, "line2": null, "postal_code": null, "state": null }, "email": null, "name": null, "phone": null }, "card": { "brand": "visa", "checks": { "address_line1_check": null, "address_postal_code_check": null, "cvc_check": "pass" }, "country": "US", "exp_month": 8, "exp_year": 2021, "fingerprint": "Xt5EWLLDS7FJjR1c", "funding": "credit", "generated_from": null, "last4": "4242", "three_d_secure_usage": { "supported": true }, "wallet": null }, "created": 1588010536, "customer": "cus_HAxB7dVQxhoKLh", "livemode": false, "metadata": {}, "type": "card" } ``` > Recomendamos que você salve o `paymentMethod.id` e `last4` no seu banco de dados (por exemplo, `paymentMethod.id` como `stripeCustomerPaymentMethodId` na sua coleção ou tabela `users`. Você também pode armazenar `exp_month`, `exp_year`, `fingerprint` e `billing_details` conforme necessário. Isso é para limitar o número de chamadas que você faz para a Stripe, tanto para eficiência de desempenho quanto para evitar possíveis limitações de taxa. ## Divulgue a Stripe para seus clientes A Stripe coleta informações sobre interações do cliente com o Elements para fornecer serviços a você, evitar fraudes e melhorar os serviços. Isso inclui o uso de cookies e endereços IP para identificar quais Elements o cliente visualizou durante uma única sessão de checkout. Você é responsável por divulgar e obter todos os direitos e consentimentos necessários para que a Stripe use os dados dessas maneiras. Para saber mais, acesse nossa [central de privacidade](https://stripe.com/legal/privacy-center#as-a-business-user-what-notice-do-i-provide-to-my-end-customers-about-stripe). #### React Native Aprenda a vender *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) com preço fixo. Você usará o [Elemento de Pagamento Móvel](https://docs.stripe.com/payments/accept-a-payment.md) para criar um formulário de pagamento personalizado que você pode integrar ao seu aplicativo. ![Página de assinatura com preço fixo com o Mobile Payment Element](https://b.stripecdn.com/docs-statics-srv/assets/fixed-price-collect-payment-details-mobile.b11cdc8fa8952d753238df4df3375fa6.png) > Se você vende produtos ou serviços digitais consumidos no seu aplicativo (por exemplo, assinaturas, moedas de jogos, níveis de jogos, acesso a conteúdo premium ou desbloqueio de uma versão completa), use as APIs de compra no aplicativo da Apple. Essa regra tem algumas exceções, incluindo serviços pessoais individuais e [aplicativos baseados em regiões específicas](https://support.stripe.com/questions/changes-to-mobile-app-store-rules). Consulte as [diretrizes de revisão da App Store](https://developer.apple.com/app-store/review/guidelines/#payments) para obter mais informações. ## Crie sua assinatura Este guia ensina a: - Modelar seus negócios criando um catálogo de produtos. - Crie um processo de registro para adicionar clientes. - Criar assinaturas e coletar dados de pagamento. - Teste e monitore o status de pagamentos e assinaturas. - Permitir que os clientes alterem o plano ou cancelem a assinatura. - Saiba como usar o [modo de faturamento flexíve](https://docs.stripe.com/billing/subscriptions/billing-mode.md) para acessar o comportamento de faturamento aprimorado e recursos adicionais. ## Como modelar na Stripe [Subscriptions](https://docs.stripe.com/api/subscriptions.md) (assinaturas) simplificam seu faturamento ao criar automaticamente *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 [PaymentIntents](https://docs.stripe.com/api/payment_intents.md) para você. Para criar e ativar uma assinatura, primeiro você precisa criar um *Produto* (Products represent what your business sells—whether that's a good or a service) para modelar o que está sendo vendido 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), que determina o intervalo e o valor a cobrar. Você também precisa de um [Customer](https://docs.stripe.com/api/customers.md) (Cliente) para armazenar *PaymentMethods* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) usados para realizar cada pagamento recorrente. #### Accounts v2 Um diagrama que ilustra objetos de cobrança comuns e suas relações (See full diagram at https://docs.stripe.com/billing/subscriptions/build-subscriptions) #### Customer v1 Um diagrama que ilustra objetos de cobrança comuns e suas relações (See full diagram at https://docs.stripe.com/billing/subscriptions/build-subscriptions) ### Definições de objetos de API | Recurso | Definição | | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Conta configurada como cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer) | Represents a customer in the Accounts v2 API who purchases a subscription. Configure an `Account` object as a customer and associate it with a subscription to make and track recurring charges and to manage the products that they subscribe to. For more information, see the [Use Accounts as customers guide](https://docs.stripe.com/connect/use-accounts-as-customers.md). | | [Cliente](https://docs.stripe.com/api/customers.md) | Represents a customer in the Customers API who purchases a subscription. Use the `Customer` object associated with a subscription to make and track recurring charges and to manage the products that they subscribe to. | | [Direito](https://docs.stripe.com/api/entitlements/active-entitlement.md) | Representa o acesso de um cliente a um recurso incluído em um produto de serviço que assina. Quando você cria uma assinatura para a compra recorrente de um produto por um cliente, um direito ativo é automaticamente criado para cada recurso associado a esse produto. Quando um cliente acessa seus serviços, use os direitos ativos para habilitar os recursos incluídos na assinatura. | | [Recurso](https://docs.stripe.com/api/entitlements/feature.md) | Representa uma função ou capacidade que seus clientes podem acessar quando assinam um produto de serviço. Você pode incluir recursos em um produto criando ProductFeatures. | | [Fatura](https://docs.stripe.com/api/invoices.md) | Uma declaração de valores devidos por um cliente que acompanha os status de pagamento desde o esboço até o pagamento (ou outro tipo de finalização). As assinaturas geram faturas automaticamente. | | [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) | Uma maneira de criar fluxos de pagamentos dinâmicos. Um PaymentIntent acompanha o ciclo de vida do fluxo de checkout de um cliente e aciona etapas adicionais de autenticação quando for exigido por mandatos regulatórios, regras personalizadas contra fraudes do Radar ou formas de pagamento baseadas em redirecionamento. As faturas criam PaymentIntents automaticamente. | | [PaymentMethod](https://docs.stripe.com/api/payment_methods.md) | A customer’s payment methods that they use to pay for your products. For example, you can store a credit card on a customer-configured `Account` or `Customer` object and use it to make recurring payments for that customer. Typically used with the Payment Intents or Setup Intents APIs. | | [Price](https://docs.stripe.com/api/prices.md) | Define o preço unitário, a moeda e o ciclo de faturamento de um produto. | | [Product](https://docs.stripe.com/api/products.md) | Um produto ou serviço que sua empresa vende. Um produto de serviço pode incluir um ou mais recursos. | | [ProductFeature](https://docs.stripe.com/api/product-feature.md) | Representa a inclusão de um único recurso em um único produto. Cada produto está associado a um ProductFeature para cada recurso que é incluído, e cada recurso é associado a um ProductFeature para cada produto que o inclui. | | [Subscription](https://docs.stripe.com/api/subscriptions.md) | Representa a compra recorrente agendada de um produto por um cliente. Use uma assinatura para coletar pagamentos e fornecer entregas repetidas ou acesso contínuo a um produto. | Aqui está um exemplo de como produtos, recursos e direitos funcionam juntos. Imagine que você deseja configurar um serviço de assinatura que oferece dois níveis: um produto padrão com funções básicas e um produto avançado que adiciona funções estendidas. 1. Você cria dois recursos: `basic_features` e `extended_features`. 1. Você cria dois produtos: `standard_product` e `advanced_product`. 1. Para o produto padrão, você cria uma ProductFeature que associa `basic_features` com `standard_product`. 1. Para o produto avançado, você cria duas ProductFeatures: uma que associa `basic_features` com `advanced_product` e outra que associa `extended_features` com `advanced_product`. Um cliente, `first_customer`, assina o produto padrão. Quando você cria a assinatura, a Stripe cria automaticamente um Entitlement que associa `first_customer` com `basic_features`. Outro cliente, `second_customer`, assina o produto avançado. Quando você cria a assinatura, a Stripe cria automaticamente dois Entitlements: um que associa `second_customer` a `basic_features` e outro que associa `second_customer` com `extended_features`. É possível determinar quais recursos fornecer para um cliente [recuperando seus direitos ativos ou escutando o evento Active Entitlement Summary](https://docs.stripe.com/billing/entitlements.md#entitlements). Você não precisa buscar as assinaturas, os produtos e os recursos dele. ## Configurar a Stripe O [SDK do React Native](https://github.com/stripe/stripe-react-native) é de código aberto e totalmente documentado. Internamente, utiliza as SDKs de [iOS nativo](https://github.com/stripe/stripe-ios) e [Android](https://github.com/stripe/stripe-android). Para instalar o SDK do React Native da Stripe, execute um dos seguintes comandos no diretório do seu projeto (dependendo de qual gerenciador de pacotes você usa): #### yarn ```bash yarn add @stripe/stripe-react-native ``` #### npm ```bash npm install @stripe/stripe-react-native ``` Em seguida, instale algumas outras dependências necessárias: - Para iOS, vá para o diretório **ios** e execute `pod install` para garantir a instalação das dependências nativas necessárias. - Para Android, não há mais dependências para instalar. > Recomendamos seguir o [guia oficial do TypeScript](https://reactnative.dev/docs/typescript#adding-typescript-to-an-existing-project) para adicionar suporte ao TypeScript. ### Inicialização da Stripe Para inicializar a Stripe no aplicativo React Native, insira sua tela de pagamento com o componente `StripeProvider` ou use o método de inicialização `initStripe`. Somente a [chave da API publicável](https://docs.stripe.com/keys.md#obtain-api-keys) em `publishableKey` é necessária. O exemplo a seguir mostra como inicializar a Stripe usando o componente `StripeProvider`. ```jsx import { useState, useEffect } from 'react'; import { StripeProvider } from '@stripe/stripe-react-native'; function App() { const [publishableKey, setPublishableKey] = useState(''); const fetchPublishableKey = async () => { const key = await fetchKey(); // fetch key from your server here setPublishableKey(key); }; useEffect(() => { fetchPublishableKey(); }, []); return ( {/* Your app code here */} ); } ``` > Use suas [chaves de API de teste](https://docs.stripe.com/keys.md#obtain-api-keys) enquanto testa e desenvolve, e as chaves de [modo de produção](https://docs.stripe.com/keys.md#test-live-modes) quando publica seu aplicativo. Em seguida, instale o Stripe CLI. O CLI fornece testes de webhooks, e você pode executá-lo para fazer chamadas de API para a Stripe. Este guia mostra a você como usar o CLI para configurar um modelo de preços em uma seção posterior. Para obter opções de instalação adicionais, consulte [Comece a usar o Stripe CLI](https://docs.stripe.com/stripe-cli.md). ## Criar o modelo de preços [Stripe CLI ou Dashboard] [Modelos de planos de preços recorrentes](https://docs.stripe.com/products-prices/pricing-models.md) representam os produtos ou serviços que você vende, quanto custam, quais moedas você aceita para pagamentos e o período de serviço para assinaturas. Para montar o modelo de preços, crie [produtos](https://docs.stripe.com/api/products.md) (o que você vende) e [ preços](https://docs.stripe.com/api/prices.md) (quanto e com que frequência cobrar pelos seus produtos). Este exemplo utiliza um plano de preços de taxa fixa com duas opções de nível de serviço diferentes: básico e premium. Para cada opção de nível de serviço, você precisa criar um produto e um preço recorrente. Para adicionar uma cobrança pontual, como uma tarifa de abertura, crie um terceiro produto com um preço pontual. Cada produto fatura em intervalos mensais. O preço do produto básico é 5 USD. O preço do produto premium é 15 USD. Consulte o guia de [plano de preços de taxa fixa](https://docs.stripe.com/subscriptions/pricing-models/flat-rate-pricing.md) para ver um exemplo com três níveis. #### Dashboard Acesse a página [Adicionar um produto](https://dashboard.stripe.com/test/products/create) e crie dois produtos. Adicione um preço para cada produto, cada um com um período de faturamento mensal recorrente: - Produto premium: serviço premium com recursos extras - Preço: Tarifa fixa | 15 USD - Produto básico: serviço básico com recursos mínimos - Preço: Tarifa fixa | 5 USD Depois de criar os preços, registre o ID deles para utilizá-los em outras etapas. Os IDs de preço têm esta estrutura: `price_G0FvDp6vZvdwRZ`. Quando tudo estiver pronto, use o botão **Copiar para modo de produção**, no canto superior direito, para clonar seu produto de [uma área restrita para o modo de produção](https://docs.stripe.com/keys.md#test-live-modes). #### API Você pode usar a API para criar os [produtos](https://docs.stripe.com/api/products.md) e os [ preços](https://docs.stripe.com/api/prices.md). Criar o produto premium: ```curl curl https://api.stripe.com/v1/products \ -u "<>:" \ --data-urlencode "name=Billing Guide: Premium Service" \ -d "description=Premium service with extra features" ``` Criar o produto básico: ```curl curl https://api.stripe.com/v1/products \ -u "<>:" \ --data-urlencode "name=Billing Guide: Basic Service" \ -d "description=Basic service with minimum features" ``` Registre os IDs de cada produto. Eles têm esta estrutura: ```json { "id": "prod_H94k5odtwJXMtQ", "object": "product", "active": true, "attributes": [ ], "created": 1587577341, "description": "Premium service with extra features", "images": [ ], "livemode": false, "metadata": { }, "name": "Billing Guide: Premium Service", "statement_descriptor": null, "type": "service", "unit_label": null, "updated": 1587577341 } ``` Use os IDs de produto para criar um preço para cada produto. O número [unit_amount](https://docs.stripe.com/api/prices/object.md#price_object-unit_amount) está em centavos. Por exemplo, `1500` = 15 USD. Criar o preço premium: ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d product={{PREMIUM_PRODUCT_ID}} \ -d unit_amount=1500 \ -d currency=usd \ -d "recurring[interval]=month" ``` Criar o preço básico: ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d product={{BASIC_PRODUCT_ID}} \ -d unit_amount=500 \ -d currency=usd \ -d "recurring[interval]=month" ``` Registre os IDs de cada preço, para que possam ser usados em etapas subsequentes. Eles têm esta estrutura: ```json { "id": "price_HGd7M3DV3IMXkC", "object": "price", "product": "prod_HGd6W1VUqqXGvr", "type": "recurring", "currency": "usd", "recurring": { "interval": "month", "interval_count": 1, "trial_period_days": null, "usage_type": "licensed" }, "active": true, "billing_scheme": "per_unit", "created": 1589319695, "livemode": false, "lookup_key": null, "metadata": {}, "nickname": null, "unit_amount": 1500, "unit_amount_decimal": "1500", "tiers": null, "tiers_mode": null, "transform_quantity": null } ``` ## Criar o cliente [Cliente e servidor] A Stripe precisa de um *customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) para cada assinatura. No frontend do seu aplicativo, colete todas as informações necessárias dos seus usuários e passe-as ao backend. > #### Comparar referências de Customers v1 e Accounts v2 > > Se a sua plataforma Connect utiliza [Contas configuradas pelo cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), utilize o nosso [guia](https://docs.stripe.com/connect/use-accounts-as-customers.md) para substituir as referências a `Cliente` e eventos no seu código pelas referências equivalentes da API Accounts v2. Se precisar coletar detalhes de endereço, o Address Element permite coletar um endereço de entrega ou cobrança para seus clientes. Saiba mais o Address Element na página [Address Element](https://docs.stripe.com/elements/address-element.md). ```javascript import React from 'react'; import {View, TextInput, StyleSheet, Button, Platform} from 'react-native'; function RegisterView() { const [email, setEmail] = React.useState(''); const createCustomer = async () => { const apiEndpoint = Platform.OS === 'ios' ? 'http://localhost:4242' : 'http://10.0.2.2:4567'; const response = await fetch(`${apiEndpoint}/create-customer`, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ email: email, }), }); if (response.status === 200) { const customer = await response.json(); console.log(customer); } }; return (