# Crie uma integração de assinaturas

Crie e gerencie assinaturas para aceitar pagamentos recorrentes.

## Comece aqui: instale skills de agente

A Stripe recomenda usar skills oficiais para integrar com a API seguindo práticas recomendadas. Siga as instruções abaixo para saber como.

**Dica: use curl em vez de ferramentas Fetch.** Skills são arquivos markdown detalhados de 10 KB a 20 KB. Ferramentas Fetch fazem um resumo deles. `curl -sL` garante o conteúdo completo.

**Usando `npx skills`**: verifique se `npx` está instalado no sistema. Se `npx` estiver disponível, execute `npx skills add https://docs.stripe.com --list` para listar os skills disponíveis e, depois, execute `npx skills add https://docs.stripe.com --yes --skill <skill-name> <--skill other-skills>` para instalar skills individuais.

**Se `npx skills` não estiver disponível**: é possível usar curl para buscar o índice de skills disponíveis, o que eles fazem e seus arquivos em `https://docs.stripe.com/.well-known/skills/index.json`. Para baixar um skill e os arquivos relacionados, use curl para baixá-los de `https://docs.stripe.com/.well-known/skills/<filepath>`.

Para este artigo, recomendamos usar estes skills: `stripe-best-practices`

#### Checkout

#### Página hospedada pela Stripe

# Página hospedada

> This is a Página hospedada for when platform is web and ui is stripe-hosted. View the full page at https://docs.stripe.com/billing/subscriptions/build-subscriptions?platform=web&ui=stripe-hosted.

#### Esforço de integração
Complexity: 2/5
#### Personalização da IU
Personalização limitada
- 20 fontes predefinidas
- 3 raios de borda predefinidos
- Cores do fundo e das bordas personalizadas
- Logotipo personalizado

#### Tipo de integração

Use páginas hospedadas pré-construídas para recolher pagamentos e gerenciar suas *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).

[Tente ](https://checkout.stripe.dev/)

## O que você vai criar

Este guia descreve como vender assinaturas mensais de preço fixo usando o [Stripe Checkout](https://docs.stripe.com/payments/checkout.md).

Este guia ensina a:

- Modelar seus negócios criando um catálogo de produtos.
- Adicionar uma sessão do Checkout ao seu site, com um botão e páginas de confirmação e cancelamento.
- Monitorar os eventos de assinatura e dar acesso ao seu serviço.
- Configurar o [portal do cliente](https://docs.stripe.com/customer-management.md)
- Adicionar uma sessão do portal do cliente ao seu site, com botão e redirecionamento.
- Permitir que os clientes gerenciem a assinatura no portal.
- 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.

Se você não estiver pronto para codificar uma integração, poderá configurar assinaturas básicas [manualmente no Dashboard](https://docs.stripe.com/no-code/subscriptions.md) ou usar [Links de pagamento](https://docs.stripe.com/payment-links.md) para configurar assinaturas sem escrever nenhum código.

Saiba mais sobre [projetando uma integração](https://docs.stripe.com/billing/subscriptions/design-an-integration.md) para entender as decisões e os recursos necessários para uma integração completa.

Após a conclusão da integração, você pode ampliá-la para:

- Exibir [tributos](https://docs.stripe.com/payments/checkout/taxes.md)
- Aplicar [descontos](https://docs.stripe.com/billing/subscriptions/coupons.md#using-coupons-in-checkout)
- Ofereça aos clientes um [período de teste gratuito](https://docs.stripe.com/billing/subscriptions/trials.md)
- Adicionar [formas de pagamento](https://docs.stripe.com/payments/payment-methods/integration-options.md)
- Integrar a [página da fatura hospedada ](https://docs.stripe.com/invoicing/hosted-invoice-page.md)
- Use o Checkout no [modo de configuração ](https://docs.stripe.com/payments/save-and-reuse.md)
- Configurar [cobrança por uso](https://docs.stripe.com/products-prices/pricing-models.md#usage-based-pricing), [níveis de preços](https://docs.stripe.com/products-prices/pricing-models.md#tiered-pricing) e [preços baseados no uso](https://docs.stripe.com/products-prices/pricing-models.md#usage-based-pricing)
- Gerencie [pro rata](https://docs.stripe.com/billing/subscriptions/prorations.md)
- [Permitir que os clientes assinem vários produtos](https://docs.stripe.com/billing/subscriptions/quantities.md#multiple-product-sub)
- Integre os [direitos](https://docs.stripe.com/billing/entitlements.md) para gerenciar o acesso aos recursos de seu produto

## Configurar a Stripe

Instale o Stripe client 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'
```

Opcionalmente, instale a CLI da Stripe. A CLI fornece o teste [Webhook](https://docs.stripe.com/webhooks.md#test-webhook), e você pode executá-la para criar seus produtos e preços.
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 [Dashboard ou Stripe CLI]

[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 "<<YOUR_SECRET_KEY>>:" \
  --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 "<<YOUR_SECRET_KEY>>:" \
  --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 "<<YOUR_SECRET_KEY>>:" \
  -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 "<<YOUR_SECRET_KEY>>:" \
  -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
}
```

Se você oferece vários períodos de cobrança, use o Checkout para fazer [upsell](https://docs.stripe.com/payments/checkout/upsells.md) aos clientes em períodos de cobrança mais longos e recolher mais receita antecipadamente.

Para outros modelos de preços, consulte [Exemplos de faturamento](https://docs.stripe.com/products-prices/pricing-models.md).

## Criar uma sessão do Checkout [Cliente e servidor]

Adicione um botão de checkout ao seu site para chamar um endpoint do lado do servidor e criar uma Sessão de Checkout.

```html
<html>
  <head>
    <title>Checkout</title>
  </head>
  <body>
    <form action="/create-checkout-session" method="POST">
      <!-- Note: If using PHP set the action to /create-checkout-session.php -->

      <input type="hidden" name="priceId" value="price_G0FvDp6vZvdwRZ" />
      <button type="submit">Checkout</button>
    </form>
  </body>
</html>
```

No backend 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 frontend. você precisa desses valores:

- O ID do preço da assinatura ao qual o cliente está se registrando. Seu front-end passa esse valor
- Seu `success_url`, que é uma página do seu site para a qual o Checkout retorna o cliente depois que ele conclui o pagamento

Opcionalmente, você pode:

- Configure uma [âncora de ciclo de faturamento](https://docs.stripe.com/billing/subscriptions/billing-cycle.md) para sua assinatura nessa chamada.
- Use um [texto personalizado](https://docs.stripe.com/payments/checkout/custom-components.md?platform=web&payment-ui=stripe-hosted#customize-text) para incluir seus termos da assinatura e cancelamento, além de um link para que seus clientes possam atualizar ou cancelar suas assinaturas. Recomendamos configurar [lembretes e notificações por e-mail](https://docs.stripe.com/invoicing/send-email.md#email-configuration) para seus assinantes.

Se você criou um preço único no [passo 2](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md#create-pricing-model), passe também esse ID de preço. Depois de criar uma Checkout Session, redirecione o cliente para [URL ](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-url) retornada na resposta.

Você pode ativar um comportamento de assinatura mais preciso e previsível ao criar uma Checkout Session definindo o [modo de faturamento ](https://docs.stripe.com/billing/subscriptions/billing-mode.md) type como `flexible`. Você deve usar a versão da API da Stripe [2025-06-30.basil](https://docs.stripe.com/changelog/basil.md#2025-06-30.basil) ou posterior.

> Você pode usar [lookup_keys](https://docs.stripe.com/products-prices/manage-prices.md#lookup-keys) para buscar preços em vez de IDs de preços. Consulte como exemplo o [aplicativo de amostra ](https://github.com/stripe-samples/subscription-use-cases/tree/main/fixed-price-subscriptions).

#### 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

# The price ID passed from the front end.
#   price_id = params['priceId']
price_id = '{{PRICE_ID}}'

session = client.v1.checkout.sessions.create({
  success_url: 'https://example.com/success.html?session_id={CHECKOUT_SESSION_ID}',
  mode: 'subscription',
  line_items: [{
    # For usage-based billing, don't pass quantity
    quantity: 1,
    price: price_id
  }],
  subscription_data: {
    billing_mode: { type: 'flexible' }
  }
})

# Redirect to the URL returned on the session
#   redirect session.url, 303
```

Este exemplo personaliza o `success_url` acrescentando o ID da sessão. Saiba mais sobre [como personalizar sua página de sucesso](https://docs.stripe.com/payments/checkout/custom-success-page.md).

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).

## Provisionar e monitorar assinaturas [Servidor]

Após a assinatura ser bem-sucedida, o cliente retornará ao seu site em `success_url`, que inicia um `checkout.session.completed` *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests). Ao receber um evento `checkout.session.completed`, use [entitlements](https://docs.stripe.com/billing/entitlements.md)(/billing/entitlements) para provisionar a assinatura. Continue provisionando mensalmente (se a cobrança for mensal) conforme você receber eventos `invoice.paid`. Se receber um evento `invoice.payment_failed`, notifique seu cliente e o direcione ao portal do cliente para atualizar sua forma de pagamento.

Para determinar a próxima etapa da lógica do seu sistema, verifique o tipo de evento e analise a carga útil de [cada objeto de evento ](https://docs.stripe.com/api/events/object.md) , como `invoice.paid`. Armazene os objetos de evento `subscription.id` e `customer.id` em seu banco de dados para verificação.

Para fins de teste, você pode monitorar eventos na guia [Events](https://dashboard.stripe.com/workbench/events) do [Workbench](https://docs.stripe.com/workbench.md). Para produção, configure um endpoint Webhook e assine os tipos de eventos apropriados. Se você não souber sua chave `STRIPE_WEBHOOK_SECRET`, acesse a visualização de detalhes do destino na guia [Webhooks](https://dashboard.stripe.com/workbench/webhooks) do Workbench para visualizá-la.

#### 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/webhook' do
  webhook_secret = '{{STRIPE_WEBHOOK_SECRET}}' # Exemplo: whsec_c7681Dm
  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
  event_type = event['type']
  data = event['data']
  data_object = data['object']

  case event_type
  when 'checkout.session.completed'
    # Payment is successful and the subscription is created.
    # You should provision the subscription and save the customer ID to your database.
  when 'invoice.paid'
    # Continue to provision the subscription as payments continue to be made.
    # Store the status in your database and check when a user accesses your service.
    # This approach helps you avoid hitting rate limits.
  when 'invoice.payment_failed'
    # The payment failed or the customer doesn't have a valid payment method.
    # The subscription becomes past_due. Notify your customer and send them to the
    # customer portal to update their payment information.
  else
    puts "Unhandled event type: \#{event.type}"
  end

  status 200
end
```

Mínimo de tipos de evento a serem monitorados:

| Nome do evento               | Descrição                                                                                                |
| ---------------------------- | -------------------------------------------------------------------------------------------------------- |
| `checkout.session.completed` | Enviado quando um cliente conclui com êxito a sessão de Checkout, informando você sobre uma nova compra. |
| `invoice.paid`               | Enviado a cada período de cobrança quando um pagamento for efetivado.                                    |
| `invoice.payment_failed`     | Enviado a cada período de cobrança se houver um problema com a forma de pagamento do seu cliente.        |

Para obter ainda mais eventos para monitorar, consulte [. Webhooks de assinatura](https://docs.stripe.com/billing/subscriptions/webhooks.md).

## Configurar o portal de clientes [Dashboard]

O [portal do cliente ](https://docs.stripe.com/customer-management.md) permite que seus clientes gerenciem diretamente suas assinaturas e faturas existentes.

Use o [Dashboard](https://dashboard.stripe.com/test/settings/billing/portal) para configurar o portal. No mínimo, certifique-se de [configurar o portal](https://docs.stripe.com/customer-management.md) para que os clientes possam atualizar suas formas de pagamento.

## Criar uma sessão no portal [Servidor]

Definir um endpoint que [crie a sessão do portal do cliente](https://docs.stripe.com/api/customer_portal/sessions/create.md) para o seu frontend chamar. O `CUSTOMER_ID` refere-se ao ID do cliente criado por uma Checkout Session que você salvou ao processar o evento `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:

#### Accounts v2

#### 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_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_account_id = '{{CUSTOMER_ACCOUNT_ID}}' # Exemplo: acct_GBV60HKsE0mb5v

session = Stripe::BillingPortal::Session.create({
  customer_account: customer_account_id,
  return_url: return_url,
})

# Redirect to the URL for the session
#   redirect session.url, 303
```

#### Customers v1

#### 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_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 = client.v1.billing_portal.sessions.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 [Cliente]

No seu front-end, adicione um botão à página `success_url` que fornece um link para o portal de clientes:

```html
<html>
  <head>
    <title>Manage Billing</title>
  </head>
  <body>
    <form action="/customer-portal" method="POST">
      <!-- Note: If using PHP set the action to /customer-portal.php -->
      <button type="submit">Manage Billing</button>
    </form>
  </body>
</html>
```

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, [monitore eventos adicionais](https://docs.stripe.com/customer-management/integrate-customer-portal.md#webhooks).

## 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).

## See also

- [Oferecer aos clientes um período de teste gratuito](https://docs.stripe.com/billing/subscriptions/trials.md)
- [Aplicar descontos](https://docs.stripe.com/billing/subscriptions/coupons.md#using-coupons-in-checkout)
- [Gerencie pro rata](https://docs.stripe.com/billing/subscriptions/prorations.md)
- [Integrar direitos para gerenciar o acesso aos recursos de seu produto](https://docs.stripe.com/billing/entitlements.md)


#### Formulário integrado

# Página integrada

> This is a Página integrada for when platform is web and ui is embedded-form. View the full page at https://docs.stripe.com/billing/subscriptions/build-subscriptions?platform=web&ui=embedded-form.

#### Esforço de integração
Complexity: 2/5
#### Personalização da IU

Personalize a aparência

#### Tipo de integração

Use formulários integrados pré-criados para recolher pagamentos e gerenciar *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).

## Configure o servidor

### Configurar a Stripe

Instale o Stripe client 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'
```

### Criar um produto e preço

[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 "<<YOUR_SECRET_KEY>>:" \
  --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 "<<YOUR_SECRET_KEY>>:" \
  --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 "<<YOUR_SECRET_KEY>>:" \
  -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 "<<YOUR_SECRET_KEY>>:" \
  -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
}
```

Se você oferece vários períodos de cobrança, use o Checkout para fazer [upsell](https://docs.stripe.com/payments/checkout/upsells.md) aos clientes em períodos de cobrança mais longos e recolher mais receita antecipadamente.

Para outros modelos de preços, consulte [Exemplos de faturamento](https://docs.stripe.com/products-prices/pricing-models.md).

### Criar uma sessão do Checkout

Adicione um endpoint em seu servidor que crie uma *Checkout Session*.

Quando você criar a [Checkout Session ](https://docs.stripe.com/api/checkout/sessions/create.md) , passe os seguintes parâmetros:

- para usar a forma de pagamento da embedded_page, defina [ui_mode](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-ui_mode) como `embedded`.
- Para criar assinaturas quando o cliente fizer checkout, defina o [modo ](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode) para `subscription`.
- Para definir a página para a qual o cliente retorna após a conclusão do pagamento ou a tentativa de pagamento, especifique uma [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-return_url). Inclua a variável de modelo `{CHECKOUT_SESSION_ID}` na URL. O Checkout substitui a variável pela ID da sessão de checkout antes de redirecionar o cliente. você cria e hospeda a página de retorno em seu site.
- Para incluir os termos de assinatura e cancelamento, além de um link para que seus clientes possam atualizar ou cancelar a assinatura, use, opcionalmente, um [texto personalizado](https://docs.stripe.com/payments/checkout/custom-components.md?ui=embedded-form#customize-payment-method-reuse-agreement-and-subscription-terms). Recomendamos configurar [lembretes e notificações por e-mail](https://docs.stripe.com/invoicing/send-email.md#email-configuration) para seus assinantes.

Para montar o Checkout, use o `client_secret` da Checkout Session retornado na resposta.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=subscription \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/checkout/return?session_id={CHECKOUT_SESSION_ID}"
```

## Criar sua página de assinatura [Cliente]

### Montar o Checkout

#### HTML + JS

#### Carregar o Stripe.js

Use o *Stripe.js* (Use Stripe.js’ APIs to tokenize customer information, collect sensitive card data, and accept payments with browser payment APIs) para manter a *conformidade com o PCI* (Any party involved in processing, transmitting, or storing credit card data must comply with the rules specified in the Payment Card Industry (PCI) Data Security Standards. PCI compliance is a shared responsibility and applies to both Stripe and your business), garantindo que os dados de pagamento sejam enviados diretamente para a Stripe e nunca passem pelo servidor. Sempre carregue o Stripe.js de js.stripe.com para manter a conformidade. Não inclua o script em um pacote nem o hospede.

#### Defina o formulário de pagamentos

Para recolher com segurança as informações do cliente, crie um espaço reservado vazio `div`. A Stripe insere um iframe no `div`.

O Checkout está disponível como parte do [Stripe.js](https://docs.stripe.com/js.md)(/js). Inclua o script Stripe.js na sua página, adicionando-o ao cabeçalho do arquivo HTML. Em seguida, crie um nódulo DOM vazio (contêiner) para usar na montagem.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Accept a payment</title>
    <meta name="description" content="A demo of a payment on Stripe" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="stylesheet" href="style.css" /><!-- Add the Stripe.js script here -->
    <script src="https://js.stripe.com/dahlia/stripe.js"></script>
    <script src="checkout.js" defer></script>
  </head><body>
    <!-- Display a payment form -->
      <div id="checkout">
        <!-- Checkout inserts the payment form here -->
      </div>
  </body>
</html>
```

#### Inicializar o Stripe.js

Inicialize o Stripe.js com sua chave de API publicável.

#### 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

Inicialize o Checkout com sua função `fetchClientSecret` e monte-a no espaço reservado `<div>` 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('<<YOUR_PUBLISHABLE_KEY>>');

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 (
    <EmbeddedCheckoutProvider
      stripe={stripePromise}
      options={options}
    >
      <EmbeddedCheckout />
    </EmbeddedCheckoutProvider>
  )
}
```

## 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
  }
}
```

#### Accounts v2

```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_account = await stripe.v2.core.accounts(session.customer_account);

  res.send({
    status: session.status,
    payment_status: session.payment_status,
    customer_email: customer_account.contact_email
  });
});
```

#### Customers v1

```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. Inclua o ID do cliente criado pela 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:

#### Accounts v2

#### 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_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_account_id = '{{CUSTOMER_ACCOUNT_ID}}' # Exemplo: acct_GBV60HKsE0mb5v

session = Stripe::BillingPortal::Session.create({
  customer_account: customer_account_id,
  return_url: return_url,
})

# Redirect to the URL for the session
#   redirect session.url, 303
```

#### Customers v1

#### 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_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 = client.v1.billing_portal.sessions.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
<html>
  <head>
    <title>Manage Billing</title>
  </head>
  <body>
    <form action="/customer-portal" method="POST">
      <!-- Note: If using PHP set the action to /customer-portal.php -->
      <button type="submit">Manage Billing</button>
    </form>
  </body>
</html>
```

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

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 `product.id`, `subscription.id` e `subscription.status` no seu banco de dados, junto com `customer_account.id` ou `customer.id`, que você já salvou. Verifique esse registro ao determinar quais recursos ativar 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) | Representa um cliente na API Accounts v2 que adquire uma assinatura. Configure um objeto `Account` como cliente e associe-o a uma assinatura para realizar e acompanhar cobranças recorrentes e gerenciar os produtos aos quais ele assina. Para mais informações, consulte o [guia Usar Accounts como clientes](https://docs.stripe.com/connect/use-accounts-as-customers.md).              |
| [Cliente](https://docs.stripe.com/api/customers.md)                                                                                | Representa um cliente na API Customers que adquire uma assinatura. Use o objeto `Customer` associado a uma assinatura para realizar e acompanhar cobranças recorrentes e gerenciar os produtos aos quais ele assina.                                                                                                                                                                         |
| [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)                                                                    | As formas de pagamento de um cliente que ele utiliza para pagar pelos seus produtos. Por exemplo, você pode armazenar um cartão de crédito em um objeto `Account` ou `Customer` configurado pelo cliente e utilizá-lo para realizar pagamentos recorrentes para esse cliente. Normalmente usado com a API Payment Intents ou API Setup Intents.                                              |
| [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 "<<YOUR_SECRET_KEY>>:" \
  --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 "<<YOUR_SECRET_KEY>>:" \
  --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 "<<YOUR_SECRET_KEY>>:" \
  -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 "<<YOUR_SECRET_KEY>>:" \
  -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 cliente para cada assinatura. No front-end do seu aplicativo, colete as informações necessárias dos seus usuários e envie-as para o backend.

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
<form id="signup-form">
  <label>
    Email
    <input id="email" type="email" placeholder="Email address" value="test@example.com" required />
  </label>

  <button type="submit">
    Register
  </button>
</form>
```

```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 um objeto para representar o cliente. Pode ser um objeto `Account` configurado pelo cliente ou um objeto `Customer`. Salve o ID do objeto para usar na Checkout Session.

> #### Use a API Accounts v2 para representar clientes
> 
> A API Accounts v2 está geralmente disponível para usuários do Connect e em prévia pública para outros usuários da Stripe. Se faz parte da prévia de Accounts v2, é necessário [especificar uma versão de prévia](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning) no seu código.
> 
> Para solicitar acesso à prévia de Accounts v2, 
> 
> Para a maioria dos casos de uso, recomendamos [modelar seus clientes como objetos Account configurados pelo cliente](https://docs.stripe.com/connect/use-accounts-as-customers.md), em vez de usar objetos [Customer](https://docs.stripe.com/api/customers.md).

#### Accounts v2

```curl
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "contact_email": "jenny.rosen@example.com",
    "display_name": "Jenny Rosen",
    "identity": {
        "individual": {
            "given_name": "Jenny Rosen",
            "address": {
                "city": "San Francisco",
                "country": "US",
                "line1": "123 Main Street",
                "postal_code": "94605",
                "state": "CA"
            }
        }
    },
    "configuration": {
        "customer": {
            "capabilities": {
                "automatic_indirect_tax": {
                    "requested": true
                }
            },
            "shipping": {
                "address": {
                    "city": "San Francisco",
                    "country": "US",
                    "line1": "123 Main Street",
                    "postal_code": "94605",
                    "state": "CA"
                }
            }
        }
    },
    "include": [
        "configuration.customer",
        "identity"
    ]
  }'
```

#### Clientes v1

```curl
curl https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "email=jenny.rosen@example.com" \
  -d "name=Jenny Rosen" \
  -d "shipping[address][city]=San Francisco" \
  -d "shipping[address][country]=US" \
  -d "shipping[address][line1]=123 Main Street" \
  -d "shipping[address][postal_code]=9460" \
  -d "shipping[address][state]=CA" \
  -d "shipping[name]=Jenny Rosen" \
  -d "address[city]=San Francisco" \
  -d "address[country]=US" \
  -d "address[line1]=123 Main Street" \
  -d "address[postal_code]=9460" \
  -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.

#### Accounts v2

#### 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.
# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
Stripe.api_key = '<<YOUR_SECRET_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 Account ID of the account you previously created
    customer_account: '{{CUSTOMER_ACCOUNT_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

```

#### Customers v1

#### 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.
# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>', stripe_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 = client.v1.checkout.sessions.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
<div id="checkout-container"></div>
```

```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 (
    <CheckoutElementsProvider
      stripe={stripe}options={{clientSecret}}
    >
      <CheckoutForm />
    </CheckoutElementsProvider>
  );
};

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 (
      <div>Loading...</div>
    );
  }

  if (checkoutState.type === 'error') {
    return (
      <div>Error: {checkoutState.error.message}</div>
    );
  }

  return (
    <form>{JSON.stringify(checkoutState.checkout.lineItems, null, 2)}
      {/* A formatted total amount */}
      Total: {checkoutState.checkout.total.total.amount}
    </form>
  );
};
```

## 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
<div id="payment-element"></div>
```

```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 (
      <div>Loading...</div>
    );
  }

  if (checkoutState.type === 'error') {
    return (
      <div>Error: {checkoutState.error.message}</div>
    );
  }

  return (
    <form>

      {JSON.stringify(checkoutState.checkout.lineItems, null, 2)}
      {/* A formatted total amount */}
      Total: {checkoutState.checkout.total.total.amount}
<PaymentElement options={{layout: 'accordion'}}/>
    </form>
  );
};

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
<button id="pay-button">Pay</button>
<div id="confirm-errors"></div>
```

```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 (
    <div>
      <button disabled={!checkoutState.checkout.canConfirm || loading} onClick={handleClick}>
        Pay
      </button>
      {error && <div>{error.message}</div>}
    </div>
  )
};

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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_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 `product.id`, `subscription.id` e `subscription.status` no seu banco de dados, junto com `customer_account.id` ou `customer.id`, que você já salvou. Verifique esse registro ao determinar quais recursos ativar 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/cancel-subscription' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  deleted_subscription = client.v1.subscriptions.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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/update-subscription' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  subscription = client.v1.subscriptions.retrieve(data['subscriptionId'])

  updated_subscription =
    client.v1.subscriptions.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.

#### Accounts v2

```javascript
function createPreviewInvoice(
  customerAccountId,
  subscriptionId,
  newPriceId,
  trialEndDate
) {
  return fetch('/create-preview-invoice', {
    method: 'post',
    headers: {
      'Content-type': 'application/json',
    },
    body: JSON.stringify({
      customerAccountId: customerAccountId,
      subscriptionId: subscriptionId,
      newPriceId: newPriceId,
    }),
  })
    .then(response => {
      return response.json();
    })
    .then((invoice) => {
      return invoice;
    });
}
```

#### Customers v1

```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.

#### Accounts v2

#### 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_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_account: data['customerAccountId'],
      subscription: data['subscriptionId'],
      subscription_details: {
        items: [
          { id: subscription.items.data[0].id, deleted: true },
          { price: data['newPriceId'], deleted: false }
        ]
      }
    )

  invoice.to_json
end
```

#### Customers v1

#### 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/create-preview-invoice' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  subscription = client.v1.subscriptions.retrieve(data['subscriptionId'])

  invoice =
    client.v1.invoices.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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/retrieve-customer-payment-method' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  payment_method = client.v1.payment_methods.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)

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 seu faturamento criando 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 definir o que está vendendo 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 valor a ser cobrado e a frequência da cobrança. Você também precisa de um objeto `Account` configurado pelo cliente ou de um objeto `Customer` 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) | Representa um cliente na API Accounts v2 que adquire uma assinatura. Configure um objeto `Account` como cliente e associe-o a uma assinatura para realizar e acompanhar cobranças recorrentes e gerenciar os produtos aos quais ele assina. Para mais informações, consulte o [guia Usar Accounts como clientes](https://docs.stripe.com/connect/use-accounts-as-customers.md).              |
| [Cliente](https://docs.stripe.com/api/customers.md)                                                                                | Representa um cliente na API Customers que adquire uma assinatura. Use o objeto `Customer` associado a uma assinatura para realizar e acompanhar cobranças recorrentes e gerenciar os produtos aos quais ele assina.                                                                                                                                                                         |
| [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)                                                                    | As formas de pagamento de um cliente que ele utiliza para pagar pelos seus produtos. Por exemplo, você pode armazenar um cartão de crédito em um objeto `Account` ou `Customer` configurado pelo cliente e utilizá-lo para realizar pagamentos recorrentes para esse cliente. Normalmente usado com a API Payment Intents ou API Setup Intents.                                              |
| [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 "<<YOUR_SECRET_KEY>>:" \
  --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 "<<YOUR_SECRET_KEY>>:" \
  --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 "<<YOUR_SECRET_KEY>>:" \
  -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 "<<YOUR_SECRET_KEY>>:" \
  -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 cliente para cada assinatura. No front-end do seu aplicativo, colete as informações necessárias dos seus usuários e envie-as para o backend.

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
<form id="signup-form">
  <label>
    Email
    <input id="email" type="email" placeholder="Email address" value="test@example.com" required />
  </label>

  <button type="submit">
    Register
  </button>
</form>
```

```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 um objeto para representar o cliente. Pode ser um objeto `Account` configurado pelo cliente ou um objeto `Customer`. Salve o ID do objeto para usar na Checkout Session.

> #### Use a API Accounts v2 para representar clientes
> 
> A API Accounts v2 está geralmente disponível para usuários do Connect e em prévia pública para outros usuários da Stripe. Se faz parte da prévia de Accounts v2, é necessário [especificar uma versão de prévia](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning) no seu código.
> 
> Para solicitar acesso à prévia de Accounts v2, 
> 
> Para a maioria dos casos de uso, recomendamos [modelar seus clientes como objetos Account configurados pelo cliente](https://docs.stripe.com/connect/use-accounts-as-customers.md), em vez de usar objetos [Customer](https://docs.stripe.com/api/customers.md).

#### Accounts v2

```curl
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "contact_email": "jenny.rosen@example.com",
    "display_name": "Jenny Rosen",
    "identity": {
        "individual": {
            "given_name": "Jenny Rosen",
            "address": {
                "city": "San Francisco",
                "country": "US",
                "line1": "123 Main Street",
                "postal_code": "94605",
                "state": "CA"
            }
        }
    },
    "configuration": {
        "customer": {
            "capabilities": {
                "automatic_indirect_tax": {
                    "requested": true
                }
            },
            "shipping": {
                "address": {
                    "city": "San Francisco",
                    "country": "US",
                    "line1": "123 Main Street",
                    "postal_code": "94605",
                    "state": "CA"
                }
            }
        }
    },
    "include": [
        "configuration.customer",
        "identity"
    ]
  }'
```

#### Clientes v1

```curl
curl https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "email=jenny.rosen@example.com" \
  -d "name=Jenny Rosen" \
  -d "shipping[address][city]=San Francisco" \
  -d "shipping[address][country]=US" \
  -d "shipping[address][line1]=123 Main Street" \
  -d "shipping[address][postal_code]=9460" \
  -d "shipping[address][state]=CA" \
  -d "shipping[name]=Jenny Rosen" \
  -d "address[city]=San Francisco" \
  -d "address[country]=US" \
  -d "address[line1]=123 Main Street" \
  -d "address[postal_code]=9460" \
  -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.

#### Accounts v2

```javascript
fetch('/create-subscription', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    priceId: priceId,
    customerAccountId: customerAccountId,
  }),
})
```

#### Customers v1

```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.

O exemplo a seguir cria uma `Assinatura` e expande o `confirmation_secret` da sua fatura mais recente na resposta. Isso permite enviar o segredo para o front-end para confirmar o pagamento.

#### Contas v2

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -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"
```

#### Clientes v1

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -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.

#### Contas 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
}
```

#### Clientes 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
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/dahlia/stripe.js"></script>
</head>
<body>
  <!-- content here -->
</body>
```

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('<<YOUR_PUBLISHABLE_KEY>>');
```

### 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
<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Subscribe</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>
```

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('<<YOUR_PUBLISHABLE_KEY>>');

// 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_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 `product.id`, `subscription.id` e `subscription.status` no seu banco de dados, junto com `customer_account.id` ou `customer.id`, que você já salvou. Verifique esse registro ao determinar quais recursos ativar 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/cancel-subscription' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  deleted_subscription = client.v1.subscriptions.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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/update-subscription' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  subscription = client.v1.subscriptions.retrieve(data['subscriptionId'])

  updated_subscription =
    client.v1.subscriptions.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.

#### Accounts v2

```javascript
function createPreviewInvoice(
  customerAccountId,
  subscriptionId,
  newPriceId,
  trialEndDate
) {
  return fetch('/create-preview-invoice', {
    method: 'post',
    headers: {
      'Content-type': 'application/json',
    },
    body: JSON.stringify({
      customerAccountId: customerAccountId,
      subscriptionId: subscriptionId,
      newPriceId: newPriceId,
    }),
  })
    .then(response => {
      return response.json();
    })
    .then((invoice) => {
      return invoice;
    });
}
```

#### Customers v1

```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.

#### Accounts v2

#### 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_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_account: data['customerAccountId'],
      subscription: data['subscriptionId'],
      subscription_details: {
        items: [
          { id: subscription.items.data[0].id, deleted: true },
          { price: data['newPriceId'], deleted: false }
        ]
      }
    )

  invoice.to_json
end
```

#### Customers v1

#### 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/create-preview-invoice' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  subscription = client.v1.subscriptions.retrieve(data['subscriptionId'])

  invoice =
    client.v1.invoices.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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/retrieve-customer-payment-method' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  payment_method = client.v1.payment_methods.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

[As assinaturas](https://docs.stripe.com/api/subscriptions.md) simplificam seu faturamento criando 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 objeto `Account` configurado pelo cliente ou de um objeto `Customer` 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) | Representa um cliente na API Accounts v2 que adquire uma assinatura. Configure um objeto `Account` como cliente e associe-o a uma assinatura para realizar e acompanhar cobranças recorrentes e gerenciar os produtos aos quais ele assina. Para mais informações, consulte o [guia Usar Accounts como clientes](https://docs.stripe.com/connect/use-accounts-as-customers.md).              |
| [Cliente](https://docs.stripe.com/api/customers.md)                                                                                | Representa um cliente na API Customers que adquire uma assinatura. Use o objeto `Customer` associado a uma assinatura para realizar e acompanhar cobranças recorrentes e gerenciar os produtos aos quais ele assina.                                                                                                                                                                         |
| [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)                                                                    | As formas de pagamento de um cliente que ele utiliza para pagar pelos seus produtos. Por exemplo, você pode armazenar um cartão de crédito em um objeto `Account` ou `Customer` configurado pelo cliente e utilizá-lo para realizar pagamentos recorrentes para esse cliente. Normalmente usado com a API Payment Intents ou API Setup Intents.                                              |
| [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 = "<<YOUR_PUBLISHABLE_KEY>>"
        // 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 "<<YOUR_SECRET_KEY>>:" \
  --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 "<<YOUR_SECRET_KEY>>:" \
  --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 "<<YOUR_SECRET_KEY>>:" \
  -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 "<<YOUR_SECRET_KEY>>:" \
  -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 cliente para cada assinatura. No front-end do seu aplicativo, colete as informações necessárias dos seus usuários e envie-as para o backend.

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.

> #### Use a API Accounts v2 para representar clientes
> 
> A API Accounts v2 está geralmente disponível para usuários do Connect e em prévia pública para outros usuários da Stripe. Se faz parte da prévia de Accounts v2, é necessário [especificar uma versão de prévia](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning) no seu código.
> 
> Para solicitar acesso à prévia de Accounts v2, 
> 
> Para a maioria dos casos de uso, recomendamos [modelar seus clientes como objetos Account configurados pelo cliente](https://docs.stripe.com/connect/use-accounts-as-customers.md), em vez de usar objetos [Customer](https://docs.stripe.com/api/customers.md).

#### Accounts v2

```curl
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "contact_email": "jenny.rosen@example.com",
    "display_name": "Jenny Rosen",
    "identity": {
        "individual": {
            "given_name": "Jenny Rosen",
            "address": {
                "city": "San Francisco",
                "country": "US",
                "line1": "123 Main Street",
                "postal_code": "94605",
                "state": "CA"
            }
        }
    },
    "configuration": {
        "customer": {
            "capabilities": {
                "automatic_indirect_tax": {
                    "requested": true
                }
            },
            "shipping": {
                "address": {
                    "city": "San Francisco",
                    "country": "US",
                    "line1": "123 Main Street",
                    "postal_code": "94605",
                    "state": "CA"
                }
            }
        }
    },
    "include": [
        "configuration.customer",
        "identity"
    ]
  }'
```

#### Clientes v1

```curl
curl https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "email=jenny.rosen@example.com" \
  -d "name=Jenny Rosen" \
  -d "shipping[address][city]=San Francisco" \
  -d "shipping[address][country]=US" \
  -d "shipping[address][line1]=123 Main Street" \
  -d "shipping[address][postal_code]=9460" \
  -d "shipping[address][state]=CA" \
  -d "shipping[name]=Jenny Rosen" \
  -d "address[city]=San Francisco" \
  -d "address[country]=US" \
  -d "address[line1]=123 Main Street" \
  -d "address[postal_code]=9460" \
  -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.

#### Accounts v2

```swift
func createSubscription(priceId: String, customerAccountId: 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(["customerAccountId": customerAccountId, "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
}
```

#### Customers v1

```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.

O exemplo a seguir cria uma `Assinatura` e expande o `confirmation_secret` da sua fatura mais recente na resposta. Isso permite enviar o segredo para o front-end para confirmar o pagamento.

#### Contas v2

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -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"
```

#### Clientes v1

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -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.

#### Contas 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
}
```

#### Clientes 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:

#### Accounts v2

#### Ruby

```ruby
ephemeral_key = Stripe::EphemeralKey.create(
  {customer_account: customer_account_id},
  {stripe_version: '2026-03-25.dahlia'}
)

{
  subscriptionId: subscription.id,
  clientSecret: subscription.latest_invoice.confirmation_secret.client_secret,
  ephemeralKey: ephemeral_key.secret,
  customerAccountId: customer_account_id,
}.to_json
```

#### Customers v1

#### Ruby

```ruby
ephemeral_key = client.v1.ephemeral_keys.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

#### Accounts v2

```swift
struct SubscriptionsResponse: Decodable {
    let subscriptionId: String
    let clientSecret: String
    let ephemeralKey: String
    let customerAccountId: String
}
```

#### Customers v1

```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

#### Accounts v2

Adicione o seguinte ao configurar o PaymentSheet:

```swift
config.customerAccount = .init(id: customerAccountId, ephemeralKeySecret: ephemeralKey)
```

#### Customers v1

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<UIOpenURLContext>) {
    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&nbsp;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&nbsp;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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/cancel-subscription' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  deleted_subscription = client.v1.subscriptions.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$&nbsp;15 por mês, em vez de Básica, a US$&nbsp;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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/update-subscription' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  subscription = client.v1.subscriptions.retrieve(data['subscriptionId'])

  updated_subscription =
    client.v1.subscriptions.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.

#### Accounts v2

#### 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_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_account: data['customerAccountId'],
      subscription: data['subscriptionId'],
      subscription_details: {
        items: [
          { id: subscription.items.data[0].id, deleted: true },
          { price: data['newPriceId'], deleted: false }
        ]
      }
    )

  invoice.to_json
end
```

#### Customers v1

#### 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/create-preview-invoice' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  subscription = client.v1.subscriptions.retrieve(data['subscriptionId'])

  invoice =
    client.v1.invoices.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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/retrieve-customer-payment-method' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  payment_method = client.v1.payment_methods.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

[As assinaturas](https://docs.stripe.com/api/subscriptions.md) simplificam seu faturamento criando 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 objeto `Account` configurado pelo cliente ou de um objeto `Customer` 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) | Representa um cliente na API Accounts v2 que adquire uma assinatura. Configure um objeto `Account` como cliente e associe-o a uma assinatura para realizar e acompanhar cobranças recorrentes e gerenciar os produtos aos quais ele assina. Para mais informações, consulte o [guia Usar Accounts como clientes](https://docs.stripe.com/connect/use-accounts-as-customers.md).              |
| [Cliente](https://docs.stripe.com/api/customers.md)                                                                                | Representa um cliente na API Customers que adquire uma assinatura. Use o objeto `Customer` associado a uma assinatura para realizar e acompanhar cobranças recorrentes e gerenciar os produtos aos quais ele assina.                                                                                                                                                                         |
| [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)                                                                    | As formas de pagamento de um cliente que ele utiliza para pagar pelos seus produtos. Por exemplo, você pode armazenar um cartão de crédito em um objeto `Account` ou `Customer` configurado pelo cliente e utilizá-lo para realizar pagamentos recorrentes para esse cliente. Normalmente usado com a API Payment Intents ou API Setup Intents.                                              |
| [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.3.0")
  // Include the financial connections SDK to support US bank account as a payment method
  implementation("com.stripe:financial-connections:23.3.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,
            "<<YOUR_PUBLISHABLE_KEY>>"
        )
    }
}
```

> 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 "<<YOUR_SECRET_KEY>>:" \
  --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 "<<YOUR_SECRET_KEY>>:" \
  --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 "<<YOUR_SECRET_KEY>>:" \
  -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 "<<YOUR_SECRET_KEY>>:" \
  -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 cliente para cada assinatura. No front-end do seu aplicativo, colete as informações necessárias dos seus usuários e envie-as para o backend.

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.

> #### Use a API Accounts v2 para representar clientes
> 
> A API Accounts v2 está geralmente disponível para usuários do Connect e em prévia pública para outros usuários da Stripe. Se faz parte da prévia de Accounts v2, é necessário [especificar uma versão de prévia](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning) no seu código.
> 
> Para solicitar acesso à prévia de Accounts v2, 
> 
> Para a maioria dos casos de uso, recomendamos [modelar seus clientes como objetos Account configurados pelo cliente](https://docs.stripe.com/connect/use-accounts-as-customers.md), em vez de usar objetos [Customer](https://docs.stripe.com/api/customers.md).

#### Accounts v2

```curl
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "contact_email": "jenny.rosen@example.com",
    "display_name": "Jenny Rosen",
    "identity": {
        "individual": {
            "given_name": "Jenny Rosen",
            "address": {
                "city": "San Francisco",
                "country": "US",
                "line1": "123 Main Street",
                "postal_code": "94605",
                "state": "CA"
            }
        }
    },
    "configuration": {
        "customer": {
            "capabilities": {
                "automatic_indirect_tax": {
                    "requested": true
                }
            },
            "shipping": {
                "address": {
                    "city": "San Francisco",
                    "country": "US",
                    "line1": "123 Main Street",
                    "postal_code": "94605",
                    "state": "CA"
                }
            }
        }
    },
    "include": [
        "configuration.customer",
        "identity"
    ]
  }'
```

#### Clientes v1

```curl
curl https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "email=jenny.rosen@example.com" \
  -d "name=Jenny Rosen" \
  -d "shipping[address][city]=San Francisco" \
  -d "shipping[address][country]=US" \
  -d "shipping[address][line1]=123 Main Street" \
  -d "shipping[address][postal_code]=9460" \
  -d "shipping[address][state]=CA" \
  -d "shipping[name]=Jenny Rosen" \
  -d "address[city]=San Francisco" \
  -d "address[country]=US" \
  -d "address[line1]=123 Main Street" \
  -d "address[postal_code]=9460" \
  -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.

#### Accounts v2

```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, customerAccountId: String): SubscriptionResponse? {
    val body = JSONObject()
        .put("priceId", priceId)
        .put("customerAccountId", customerAccountId).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
}
```

#### Customers v1

```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.

O exemplo a seguir cria uma `Assinatura` e expande o `confirmation_secret` da sua fatura mais recente na resposta. Isso permite enviar o segredo para o front-end para confirmar o pagamento.

#### Contas v2

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -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"
```

#### Clientes v1

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -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.

#### Contas 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
}
```

#### Clientes 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:

#### Accounts v2

#### Ruby

```ruby
ephemeral_key = Stripe::EphemeralKey.create(
  {customer_account: customer_account_id},
  {stripe_version: '2026-03-25.dahlia'}
)

{
  subscriptionId: subscription.id,
  clientSecret: subscription.latest_invoice.confirmation_secret.client_secret,
  ephemeralKey: ephemeral_key.secret,
  customerAccountId: customer_account_id,
}.to_json
```

#### Customers v1

#### Ruby

```ruby
ephemeral_key = client.v1.ephemeral_keys.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

#### Accounts v2

```kotlin
data class SubscriptionsResponse(
    val subscriptionId: String,
    val clientSecret: String,
    val ephemeralKey: String,
    val customerAccountId: String
)
```

#### Customers v1

```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

#### Accounts v2

Adicione o seguinte ao configurar o PaymentSheet:

```kotlin
PaymentSheet.Configuration(
    primaryButtonLabel = "Subscribe for $15/month",
    merchantDisplayName = "My merchant name",
    customerAccount = PaymentSheet.CustomerConfiguration(
        id = customerAccountId,
        ephemeralKeySecret = ephemeralKey
    )
)
```

#### Customers v1

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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/cancel-subscription' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  deleted_subscription = client.v1.subscriptions.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$&nbsp;15 por mês, em vez de Básica, a US$&nbsp;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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/update-subscription' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  subscription = client.v1.subscriptions.retrieve(data['subscriptionId'])

  updated_subscription =
    client.v1.subscriptions.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.

#### Accounts v2

#### 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_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_account: data['customerAccountId'],
      subscription: data['subscriptionId'],
      subscription_details: {
        items: [
          { id: subscription.items.data[0].id, deleted: true },
          { price: data['newPriceId'], deleted: false }
        ]
      }
    )

  invoice.to_json
end
```

#### Customers v1

#### 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/create-preview-invoice' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  subscription = client.v1.subscriptions.retrieve(data['subscriptionId'])

  invoice =
    client.v1.invoices.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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/retrieve-customer-payment-method' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  payment_method = client.v1.payment_methods.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

[As assinaturas](https://docs.stripe.com/api/subscriptions.md) simplificam seu faturamento criando 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 objeto `Account` configurado pelo cliente ou de um objeto `Customer` 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) | Representa um cliente na API Accounts v2 que adquire uma assinatura. Configure um objeto `Account` como cliente e associe-o a uma assinatura para realizar e acompanhar cobranças recorrentes e gerenciar os produtos aos quais ele assina. Para mais informações, consulte o [guia Usar Accounts como clientes](https://docs.stripe.com/connect/use-accounts-as-customers.md).              |
| [Cliente](https://docs.stripe.com/api/customers.md)                                                                                | Representa um cliente na API Customers que adquire uma assinatura. Use o objeto `Customer` associado a uma assinatura para realizar e acompanhar cobranças recorrentes e gerenciar os produtos aos quais ele assina.                                                                                                                                                                         |
| [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)                                                                    | As formas de pagamento de um cliente que ele utiliza para pagar pelos seus produtos. Por exemplo, você pode armazenar um cartão de crédito em um objeto `Account` ou `Customer` configurado pelo cliente e utilizá-lo para realizar pagamentos recorrentes para esse cliente. Normalmente usado com a API Payment Intents ou API Setup Intents.                                              |
| [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 (
    <StripeProvider
      publishableKey={publishableKey}
      merchantIdentifier="merchant.identifier" // required for Apple Pay
      urlScheme="your-url-scheme" // required for 3D Secure and bank redirects
    >
      {/* Your app code here */}
    </StripeProvider>
  );
}
```

> 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 "<<YOUR_SECRET_KEY>>:" \
  --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 "<<YOUR_SECRET_KEY>>:" \
  --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 "<<YOUR_SECRET_KEY>>:" \
  -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 "<<YOUR_SECRET_KEY>>:" \
  -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 cliente para cada assinatura. No front-end do seu aplicativo, colete as informações necessárias dos seus usuários e envie-as para o backend.

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 (
    <View>
      <TextInput
        style={styles.input}
        placeholder="Email"
        value={email}
        onChangeText={setEmail}
      />
      <Button
        title="Register"
        onPress={async () => {
          await createCustomer();
        }}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  input: {
    height: 40,
    margin: 12,
    borderWidth: 1,
    padding: 10,
  },
});

export default RegisterView;
```

No servidor, crie o objeto do cliente Stripe.

> #### Use a API Accounts v2 para representar clientes
> 
> A API Accounts v2 está geralmente disponível para usuários do Connect e em prévia pública para outros usuários da Stripe. Se faz parte da prévia de Accounts v2, é necessário [especificar uma versão de prévia](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning) no seu código.
> 
> Para solicitar acesso à prévia de Accounts v2, 
> 
> Para a maioria dos casos de uso, recomendamos [modelar seus clientes como objetos Account configurados pelo cliente](https://docs.stripe.com/connect/use-accounts-as-customers.md), em vez de usar objetos [Customer](https://docs.stripe.com/api/customers.md).

#### Accounts v2

```curl
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "contact_email": "jenny.rosen@example.com",
    "display_name": "Jenny Rosen",
    "identity": {
        "individual": {
            "given_name": "Jenny Rosen",
            "address": {
                "city": "San Francisco",
                "country": "US",
                "line1": "123 Main Street",
                "postal_code": "94605",
                "state": "CA"
            }
        }
    },
    "configuration": {
        "customer": {
            "capabilities": {
                "automatic_indirect_tax": {
                    "requested": true
                }
            },
            "shipping": {
                "address": {
                    "city": "San Francisco",
                    "country": "US",
                    "line1": "123 Main Street",
                    "postal_code": "94605",
                    "state": "CA"
                }
            }
        }
    },
    "include": [
        "configuration.customer",
        "identity"
    ]
  }'
```

#### Clientes v1

```curl
curl https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "email=jenny.rosen@example.com" \
  -d "name=Jenny Rosen" \
  -d "shipping[address][city]=San Francisco" \
  -d "shipping[address][country]=US" \
  -d "shipping[address][line1]=123 Main Street" \
  -d "shipping[address][postal_code]=9460" \
  -d "shipping[address][state]=CA" \
  -d "shipping[name]=Jenny Rosen" \
  -d "address[city]=San Francisco" \
  -d "address[country]=US" \
  -d "address[line1]=123 Main Street" \
  -d "address[postal_code]=9460" \
  -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.

#### Accounts v2

```javascript
const createSubscription = async (priceId, customerAccountId) => {
  const apiEndpoint =
    Platform.OS === 'ios' ? 'http://localhost:4242' : 'http://10.0.2.2:4567';
  const response = await fetch(`${apiEndpoint}/create-subscription`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      priceId: priceId,
      customerAccountId: customerAccountId,
    }),
  });
  if (response.status === 200) {
    const subscription = await response.json();
    return subscription;
  }
};
```

#### Customers v1

```javascript
const createSubscription = async (priceId, customerId) => {
  const apiEndpoint =
    Platform.OS === 'ios' ? 'http://localhost:4242' : 'http://10.0.2.2:4567';
  const response = await fetch(`${apiEndpoint}/create-subscription`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      priceId: priceId,
      customerId: customerId,
    }),
  });
  if (response.status === 200) {
    const subscription = await response.json();
    return subscription;
  }
};
```

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.

O exemplo a seguir cria uma `Assinatura` e expande o `confirmation_secret` da sua fatura mais recente na resposta. Isso permite enviar o segredo para o front-end para confirmar o pagamento.

#### Contas v2

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -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"
```

#### Clientes v1

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -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.

#### Contas 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
}
```

#### Clientes 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:

#### Accounts v2

#### Ruby

```ruby
ephemeral_key = Stripe::EphemeralKey.create(
  {customer_account: customer_account_id},
  {stripe_version: '2026-03-25.dahlia'}
)

{
  subscriptionId: subscription.id,
  clientSecret: subscription.latest_invoice.confirmation_secret.client_secret,
  ephemeralKey: ephemeral_key.secret,
  customerAccountId: customer_account_id,
}.to_json
```

#### Customers v1

#### Ruby

```ruby
ephemeral_key = client.v1.ephemeral_keys.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

#### Accounts v2

```typescript
interface SubscriptionsResponse {
  subscriptionId: string;
  clientSecret: string;
  ephemeralKey: string;
  customerAccountId: string;
}
```

#### Customers v1

```typescript
interface SubscriptionsResponse {
  subscriptionId: string;
  clientSecret: string;
  ephemeralKey: string;
  customerId: string;
}
```

### Passe a configuração do cliente para o PaymentSheet

#### Accounts v2

Adicione os seguintes parâmetros ao inicializar o PaymentSheet:

```javascript
await initPaymentSheet({
  paymentIntentClientSecret: clientSecret,
  customerAccountId: customerAccountId,
  customerEphemeralKeySecret: ephemeralKey,
  // ... other parameters
});
```

#### Customers v1

Adicione os seguintes parâmetros ao inicializar o PaymentSheet:

```javascript
await initPaymentSheet({
  paymentIntentClientSecret: clientSecret,
  customerId: customerId,
  customerEphemeralKeySecret: ephemeralKey,
  // ... other parameters
});
```

## 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.

```javascript
import React from 'react';
import {useStripe, PaymentSheetError} from '@stripe/stripe-react-native';
import {View, Button} from 'react-native';

function SubscribeView({clientSecret}) {
  const {initPaymentSheet, presentPaymentSheet} = useStripe();

  React.useEffect(() => {
    const initializePaymentSheet = async () => {
      const {error} = await initPaymentSheet({
        paymentIntentClientSecret: clientSecret,
        returnURL: 'stripe-example://payment-sheet',
        // Set `allowsDelayedPaymentMethods` to true if your business handles
        // delayed notification payment methods like US bank accounts.
        allowsDelayedPaymentMethods: true,
      });
      if (error) {
        // Handle error
      }
    };

    initializePaymentSheet();
  }, [clientSecret, initPaymentSheet]);

  return (
    <View>
      <Button
        title="Subscribe"
        onPress={async () => {
          const {error} = await presentPaymentSheet();
          if (error) {
            if (error.code === PaymentSheetError.Failed) {
              // Handle failed
            } else if (error.code === PaymentSheetError.Canceled) {
              // Handle canceled
            }
          } else {
            // Payment succeeded
          }
        }}
      />
    </View>
  );
}

export default SubscribeView;
```

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 (somente iOS) [Lado do cliente]

Quando um cliente sair do seu aplicativo (por exemplo, para fazer a autenticação no Safari ou no aplicativo do banco), forneça uma opção para que ele retorne automaticamente ao seu aplicativo. Muitos tipos de formas de pagamento *exigem* um URL de retorno. Se você não fornecer um, não poderemos apresentar formas de pagamento que exijam um URL de retorno aos seus usuários, mesmo que você os habilite.

Para fornecer um URL de retorno:

1. [Cadastre](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app#Register-your-URL-scheme) um URL personalizado. Links universais não são aceitos.
1. [Configurar](https://reactnative.dev/docs/linking) seu URL personalizado.
1. Configure seu componente-raiz para encaminhar o URL ao SDK da Stripe, conforme mostrado abaixo.

> Se estiver usando a Expo, [defina seu esquema](https://docs.expo.io/guides/linking/#in-a-standalone-app) no arquivo `app.json`.

```jsx
import { useEffect, useCallback } from 'react';
import { Linking } from 'react-native';
import { useStripe } from '@stripe/stripe-react-native';

export default function MyApp() {
  const { handleURLCallback } = useStripe();

  const handleDeepLink = useCallback(
    async (url: string | null) => {
      if (url) {
        const stripeHandled = await handleURLCallback(url);
        if (stripeHandled) {
          // This was a Stripe URL - you can return or add extra handling here as you see fit
        } else {
          // This was NOT a Stripe URL – handle as you normally would
        }
      }
    },
    [handleURLCallback]
  );

  useEffect(() => {
    const getUrlAsync = async () => {
      const initialUrl = await Linking.getInitialURL();
      handleDeepLink(initialUrl);
    };

    getUrlAsync();

    const deepLinkListener = Linking.addEventListener(
      'url',
      (event: { url: string }) => {
        handleDeepLink(event.url);
      }
    );

    return () => deepLinkListener.remove();
  }, [handleDeepLink]);

  return (
    <View>
      <AwesomeAppComponent />
    </View>
  );
}
```

Além disso, defina o `returnURL` quando chamar o método `initPaymentSheet`:

```js
await initPaymentSheet({
  ...
  returnURL: 'your-app://stripe-redirect',
  ...
});
```

Para obter mais informações sobre esquemas de URL nativos, consulte a documentação do [Android](https://developer.android.com/training/app-links/deep-linking) e do [iOS](https://developer.apple.com/documentation/xcode/allowing_apps_and_websites_to_link_to_your_content/defining_a_custom_url_scheme_for_your_app).

## 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 do 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

Quando você chamar `initPaymentSheet`, passe um [ApplePayParams](https://stripe.dev/stripe-react-native/api-reference/modules/PaymentSheet.html#ApplePayParams) com `merchantCountryCode` definido como o código de país da sua empresa.

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 deve definir um `cardItems` que inclua um [RecurringCartSummaryItem](https://stripe.dev/stripe-react-native/api-reference/modules/ApplePay.html#RecurringCartSummaryItem) com o valor que pretende cobrar (por exemplo, “59,95 USD por mês”).

Você também pode adotar [tokens de comerciante](https://developer.apple.com/apple-pay/merchant-tokens/) definindo a `request` com seu `type` definido como `PaymentRequestType.Recurring`

Para saber como usar pagamentos recorrentes com Apple Pay, consulte a [documentação do PassKit da Apple](https://developer.apple.com/documentation/passkit/pkpaymentrequest).

#### iOS (React Native)

```javascript
const initializePaymentSheet = async () => {
  const recurringSummaryItem = {
    label: 'My Subscription',
    amount: '59.99',
    paymentType: 'Recurring',
    intervalCount: 1,
    intervalUnit: 'month',
    // Payment starts today
    startDate: new Date().getTime() / 1000,

    // Payment ends in one year
    endDate: new Date().getTime() / 1000 + 60 * 60 * 24 * 365,
  };

  const {error} = await initPaymentSheet({
    // ...
    applePay: {
      merchantCountryCode: 'US',
      cartItems: [recurringSummaryItem],
      request: {
        type: PaymentRequestType.Recurring,
        description: 'Recurring',
        managementUrl: 'https://my-backend.example.com/customer-portal',
        billing: recurringSummaryItem,
        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.'",
      },
    },
  });
};
```

### Rastreamento de pedidos

Para adicionar informações de [rastreamento de pedido](https://developer.apple.com/design/human-interface-guidelines/technologies/wallet/designing-order-tracking) no iOS 16 ou mais recente, configure uma função de retorno de chamada `setOrderTracking`. A Stripe chama sua implementação após a conclusão do pagamento, mas antes que o iOS ignore a descrição de compra do Apple Pay.

Na implementação da função de retorno de chamada `setOrderTracking`, obtenha os detalhes do pedido concluído no seu servidor e passe esses dados à função de `completion` informada.

Para saber mais sobre rastreamento de pedidos, consulte a [documentação de pedidos da carteira da Apple](https://developer.apple.com/documentation/walletorders).

#### iOS (React Native)

```javascript
await initPaymentSheet({
  // ...
  applePay: {
    // ...
    setOrderTracking: async complete => {
      const apiEndpoint =
        Platform.OS === 'ios'
          ? 'http://localhost:4242'
          : 'http://10.0.2.2:4567';
      const response = await fetch(
        `${apiEndpoint}/retrieve-order?orderId=${orderId}`,
        {
          method: 'GET',
          headers: {
            'Content-Type': 'application/json',
          },
        },
      );
      if (response.status === 200) {
        const orderDetails = await response.json();
        // orderDetails should include orderIdentifier, orderTypeIdentifier,
        // authenticationToken and webServiceUrl
        complete(orderDetails);
      }
    },
  },
});
```

## 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_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

```javascript
const cancelSubscription = async subscriptionId => {
  const apiEndpoint =
    Platform.OS === 'ios' ? 'http://localhost:4242' : 'http://10.0.2.2:4567';
  const response = await fetch(`${apiEndpoint}/cancel-subscription`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      subscriptionId: subscriptionId,
    }),
  });
  if (response.status === 200) {
    const subscription = await response.json();
    return subscription;
  }
};
```

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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/cancel-subscription' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  deleted_subscription = client.v1.subscriptions.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.

```javascript
const updateSubscription = async (subscriptionId, priceId) => {
  const apiEndpoint =
    Platform.OS === 'ios' ? 'http://localhost:4242' : 'http://10.0.2.2:4567';
  const response = await fetch(`${apiEndpoint}/update-subscription`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      subscriptionId: subscriptionId,
      newPriceId: priceId,
    }),
  });
  if (response.status === 200) {
    const subscription = await response.json();
    return subscription;
  }
};
```

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$&nbsp;15 por mês, em vez de Básica, a US$&nbsp;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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/update-subscription' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  subscription = client.v1.subscriptions.retrieve(data['subscriptionId'])

  updated_subscription =
    client.v1.subscriptions.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.

```javascript
const createPreviewInvoice = async (subscriptionId, priceId, newPriceId) => {
  const apiEndpoint =
    Platform.OS === 'ios' ? 'http://localhost:4242' : 'http://10.0.2.2:4567';
  const response = await fetch(`${apiEndpoint}/create-preview-invoice`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      subscriptionId: subscriptionId,
      priceId: priceId,
      newPriceId: newPriceId,
    }),
  });
  if (response.status === 200) {
    const invoice = await response.json();
    return invoice;
  }
};
```

No back-end, defina o endpoint para a chamada do seu front-end.

#### Accounts v2

#### 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_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_account: data['customerAccountId'],
      subscription: data['subscriptionId'],
      subscription_details: {
        items: [
          { id: subscription.items.data[0].id, deleted: true },
          { price: data['newPriceId'], deleted: false }
        ]
      }
    )

  invoice.to_json
end
```

#### Customers v1

#### 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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/create-preview-invoice' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  subscription = client.v1.subscriptions.retrieve(data['subscriptionId'])

  invoice =
    client.v1.invoices.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.

```javascript
const retrieveCustomerPaymentMethod = async paymentMethodId => {
  const apiEndpoint =
    Platform.OS === 'ios' ? 'http://localhost:4242' : 'http://10.0.2.2:4567';
  const response = await fetch(
    `${apiEndpoint}/retrieve-customer-payment-method`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        paymentMethodId: paymentMethodId,
      }),
    },
  );
  if (response.status === 200) {
    const paymentMethod = await response.json();
    return paymentMethod;
  }
};
```

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.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/retrieve-customer-payment-method' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  payment_method = client.v1.payment_methods.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).