# Criar assinaturas com o Stripe Billing Com o Connect, você pode criar assinaturas para seus clientes ou contas conectadas. Para saber mais sobre o *Connect* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients), confira a [visão geral](https://docs.stripe.com/connect.md). Baseamos as transações de *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) nos [preços do Stripe Billing](https://stripe.com/billing/pricing) Empresas de software como serviço (SaaS) e de marketplace usam o Stripe Connect para direcionar pagamentos entre si, clientes e contas conectadas. Você pode usar o Connect para direcionar pagamentos ou *repasses* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit) e usar o Stripe Billing para apoiar seu modelo de receitas recorrentes. ## Casos de uso Você pode criar [assinaturas](https://docs.stripe.com/billing/subscriptions/overview.md) para conectar contas, o que apoia várias abordagens para coletar pagamentos. Também é possível criar assinaturas para seus clientes de contas conectadas usando cobranças diretas ou cobranças de destino, para que seus clientes finais façam transações diretamente com a sua plataforma, e para cobrar uma tarifa das suas contas conectadas por usar sua plataforma. (See full diagram at https://docs.stripe.com/connect/subscriptions) ```text [customer] --> [platform] [customer] --> [account] [account] --> [platform] ``` Os seguintes casos de uso descrevem como usar o Stripe Billing para criar assinaturas de clientes finais para contas conectadas, para faturar clientes finais da plataforma e para faturar contas conectadas. | Caso de uso | Descrição | | --- | --- | | [Crie assinaturas do cliente final para a conta conectada](https://docs.stripe.com/connect/subscriptions.md#customer-connected-account) | Crie assinaturas para clientes finais para suas contas conectadas, o que apoia várias abordagens para coletar pagamentos. Neste exemplo, [Prices](https://docs.stripe.com/api/prices.md) residem na conta conectada. | | [Criar assinaturas para faturar plataforma e clientes](https://docs.stripe.com/connect/subscriptions.md#customer-platform) | Marketplaces podem oferecer assinaturas de associação diretamente sem envolver sua conta conectada. Neste exemplo, [Prices](https://docs.stripe.com/api/prices.md) residem na conta conectada. | | [Criar assinaturas para faturar contas conectadas](https://docs.stripe.com/connect/subscriptions.md#connected-account-platform) | Plataformas podem criar assinaturas para suas contas conectadas. Neste exemplo, [Prices](https://docs.stripe.com/api/prices.md) residem na plataforma. | ### Restrições O uso de assinaturas com o Connect tem as seguintes restrições: - Sua plataforma não pode atualizar ou cancelar uma assinatura que outra plataforma criou. - Sua plataforma não pode adicionar um `application_fee_amount` a uma fatura que não criou, nem a uma fatura que contenha itens de fatura que a plataforma não criou. - Somente contas conectadas com acesso integral ao Stripe Dashboard podem gerenciar as assinaturas de seus clientes. Para outras contas conectadas, a plataforma precisa gerenciar as assinaturas dos clientes. - As assinaturas não são canceladas automaticamente quando você se desconecta da plataforma. Você deve cancelar a assinatura após a desconexão. Você pode usar [webhooks para monitorar atividade da conta conectada](https://docs.stripe.com/connect/webhooks.md). ## Criar assinaturas do cliente final para a conta conectada Se estiver construindo uma plataforma, você pode criar assinaturas para os clientes da sua conta conectada, opcionalmente cobrando uma tarifa por pagamento para a sua plataforma. (See full diagram at https://docs.stripe.com/connect/subscriptions) ```text [customer] --> [account] [account] --> [platform] ``` Este exemplo cria uma plataforma de publicação online que permite aos clientes assinar seus autores favoritos e pagar uma tarifa mensal a eles para receber publicações de blog premium de cada autor. ## Before you begin Antes de poder criar assinaturas para seus clientes ou contas conectadas, você deve: 1. Crie uma conta conectada para cada pessoa que recebe dinheiro na sua plataforma. Siga a [configuração de conta SaaS](https://docs.stripe.com/connect/saas/tasks/create.md) para direct charges ou a [configuração de conta de marketplace](https://docs.stripe.com/connect/marketplace/tasks/create.md) para destination charges. No nosso exemplo de publicação online, uma conta conectada representa um autor. 2. Criar um modelo de preços. Para esse exemplo, criamos um [modelo de preço](https://docs.stripe.com/products-prices/pricing-models.md#flat-rate) de taxa fixa para cobrar uma tarifa dos clientes de forma recorrente, mas preços por usuário e por uso também são aceitos. 3. Crie um [cliente com a forma de pagamento desejada](https://docs.stripe.com/billing/customer.md#manage-customers) para cada pessoa que assinar uma conta conectada. Em nosso exemplo de publicação online, você cria um cliente para cada máquina que assina um autor. ### Escolha um modelo de cobrança e liquidação de fundos Você pode usar Direct Charges ou Destination Charges para dividir o pagamento de um cliente entre a conta conectada e a sua plataforma. Antes de criar uma assinatura, escolha onde criar cobranças e qual conta é o *merchant of record* (The legal entity responsible for facilitating the sale of products to a customer that handles any applicable regulations and liabilities, including sales taxes. In a Connect integration, it can be the platform or a connected account). O *merchant of record* (The legal entity responsible for facilitating the sale of products to a customer that handles any applicable regulations and liabilities, including sales taxes. In a Connect integration, it can be the platform or a connected account) determina a descrição no extrato e os dados da empresa que se aplicam ao pagamento. | Modelo | Cobrança criada em | *merchant of record* (The legal entity responsible for facilitating the sale of products to a customer that handles any applicable regulations and liabilities, including sales taxes. In a Connect integration, it can be the platform or a connected account) | Escolha quando | | --- | --- | --- | --- | | Direct Charge | Conta conectada | Conta conectada | Os clientes fazem transações diretamente com a conta conectada e veem a descrição no extrato. | | Destination Charges sem `on_behalf_of` | Plataforma | Plataforma | Os clientes fazem transações com a sua plataforma e veem a sua descrição no extrato. | | [Destination Charges com on_behalf_of](https://docs.stripe.com/connect/subscriptions.md#on-behalf-of) | Plataforma | Conta conectada | Os clientes fazem transações com a conta conectada por meio da sua plataforma e veem a descrição no extrato da conta conectada e os dados aplicáveis da empresa. | No nosso exemplo de publicação online, as Direct Charges significam que as máquinas interagem com os autores diretamente e veem o nome do autor na descrição no extrato, não o nome da sua plataforma. Os reembolsos e os estornos debitam do saldo da conta conectada. A responsabilidade pelas tarifas e pelos saldos negativos depende das configurações da sua conta. As cobranças diretas são recomendadas para contas conectadas com acesso ao Stripe Dashboard completo, o que inclui contas Standard. No mesmo exemplo de publicação online usando Destination Charges, a Stripe cobra do saldo da sua plataforma as tarifas, os reembolsos e os estornos, quer você defina `on_behalf_of` ou não. Defina `on_behalf_of` para designar o autor ou a plataforma como *merchant of record* (The legal entity responsible for facilitating the sale of products to a customer that handles any applicable regulations and liabilities, including sales taxes. In a Connect integration, it can be the platform or a connected account). As cobranças de destino são recomendadas para contas conectadas com acesso ao Dashboard Express ou contas conectadas sem acesso a um Dashboard hospedado pela Stripe, o que inclui contas Express e Custom. Para obter mais informações sobre os diferentes tipos de cobranças do Connect, consulte [Tipos de cobrança](https://docs.stripe.com/connect/charges.md#types). ### Usar Direct Charges para criar uma assinatura Para criar uma assinatura com [Charges](https://docs.stripe.com/api/charges/object.md) associadas à conta conectada, [crie assinatura](https://docs.stripe.com/api.md#create_subscription) estando [autenticado como a conta conectada](https://docs.stripe.com/connect/authentication.md#stripe-account-header). Certifique-se de definir o cliente com uma forma de pagamento padrão e o [Preço](https://docs.stripe.com/api/prices.md) na conta conectada. Para usar um cliente sem uma forma de pagamento padrão, defina `payment_behavior: "default_incomplete"`. Saiba mais sobre o [comportamento de pagamento](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-payment_behavior). Expanda o `latest_invoice.confirmation_secret` para incluir o Payment Element, que você precisa para confirmar o pagamento. Saiba mais sobre [Payment Elements](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md?payment-ui=elements&api-integration=paymentintents#add-the-payment-element-to-your-page). Para um exemplo completo de como implementar uma inscrição de assinatura e um fluxo de pagamento no seu aplicativo, consulte o guia [Integração de assinaturas](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md). #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "expand[0]=latest_invoice.confirmation_secret" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "expand[0]=latest_invoice.confirmation_secret" ``` Opcionalmente, você pode [especificar uma porcentagem do valor da fatura para recolher como tarifa da plataforma](https://docs.stripe.com/connect/subscriptions.md#collect-fees). ### Usar cobranças de destino para criar uma assinatura Para criar uma assinatura com [Charges](https://docs.stripe.com/api/charges/object.md) associadas à plataforma e criar automaticamente transferências para uma conta conectada, fazer uma chamada [criar assinatura](https://docs.stripe.com/api.md#create_subscription) enquanto fornece o ID da conta conectada como o [valor](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-transfer_data) de `transfer_data[destination]`. Para uma conta conectada do Accounts v2, as Destination Charges exigem a configuração `recipient` com uma funcionalidade `stripe_balance.stripe_transfers` ativa. Expanda o `latest_invoice.confirmation_secret` para incluir o Payment Element, que você precisa para confirmar o pagamento. Saiba mais sobre [Payment Elements](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md?payment-ui=elements&api-integration=paymentintents#add-the-payment-element-to-your-page). Opcionalmente, você pode [especificar uma porcentagem do valor da fatura para recolher como tarifa da plataforma](https://docs.stripe.com/connect/subscriptions.md#collect-fees). #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "expand[0]=latest_invoice.confirmation_secret" \ -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "expand[0]=latest_invoice.confirmation_secret" \ -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}" ``` ### Transforme a conta conectada o *merchant of record* (The legal entity responsible for facilitating the sale of products to a customer that handles any applicable regulations and liabilities, including sales taxes. In a Connect integration, it can be the platform or a connected account) com on_behalf_of Defina `on_behalf_of` com o ID da conta conectada ao criar ou atualizar uma assinatura para tornar essa conta o *merchant of record* (The legal entity responsible for facilitating the sale of products to a customer that handles any applicable regulations and liabilities, including sales taxes. In a Connect integration, it can be the platform or a connected account). Para Destination Charges, a omissão de `on_behalf_of` torna a sua plataforma o *merchant of record* (The legal entity responsible for facilitating the sale of products to a customer that handles any applicable regulations and liabilities, including sales taxes. In a Connect integration, it can be the platform or a connected account). Ao definir `on_behalf_of`: - As cobranças são liquidadas no país e na moeda de liquidação da conta conectada usando a estrutura de tarifas do respectivo país. - A descrição no extrato da conta conectada aparece no extrato do cartão de crédito do cliente. Se a conta conectada estiver em um país diferente da sua plataforma, o endereço e o número de telefone dela também aparecerão. - As configurações de atraso de repasse da conta conectada determinam quanto tempo leva para que os fundos da cobrança fiquem disponíveis para repasse. - Os recursos hospedados, incluindo recibos por e-mail, faturas e o portal do cliente, podem usar a marca da conta conectada. A conta conectada deve ter uma [funcionalidade de pagamentos](https://docs.stripe.com/connect/account-capabilities.md#payment-methods), como `card_payments`. Se a conta conectada usar Accounts v2, ela também deverá ter a configuração `merchant`; caso contrário, os pagamentos falharão. Para Destination Charges ou cobranças e transferências separadas, a conta conectada do Accounts v2 também precisa da configuração `recipient` com uma funcionalidade `stripe_balance.stripe_transfers` ativa. Contas sob o [Contrato de Serviços do beneficiário](https://docs.stripe.com/connect/service-agreement-types.md#recipient) não podem solicitar funcionalidades de pagamentos e não podem usar `on_behalf_of`. Para obter mais detalhes, consulte [Cobrar em nome de uma conta conectada](https://docs.stripe.com/connect/charges.md#on_behalf_of), [cobranças e transferências separadas](https://docs.stripe.com/connect/separate-charges-and-transfers.md#settlement-merchant) e [configurações de marca](https://docs.stripe.com/api/accounts/object.md#account_object-settings-branding) da conta conectada. Configure a responsabilidade fiscal do Stripe Tax e o emissor da fatura separadamente com `automatic_tax[liability]` e `invoice_settings[issuer]`. Consulte [Stripe Tax com o Connect](https://docs.stripe.com/tax/connect.md) para determinar a responsabilidade fiscal e [configurar o Billing para a responsabilidade fiscal da conta conectada](https://docs.stripe.com/tax/tax-for-platforms.md#billing). #### Crie Destination Charges com on_behalf_of Crie a assinatura na plataforma com `on_behalf_of` e `transfer_data[destination]` definidos com o ID da conta conectada. Esse exemplo também inclui um `application_fee_percent` opcional: #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "on_behalf_of={{CONNECTEDACCOUNT_ID}}" \ -d application_fee_percent=10 \ -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "on_behalf_of={{CONNECTEDACCOUNT_ID}}" \ -d application_fee_percent=10 \ -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" ``` #### Crie cobranças e transferências separadas com on_behalf_of Para [cobranças e transferências separadas](https://docs.stripe.com/connect/separate-charges-and-transfers.md), crie a assinatura na plataforma com `on_behalf_of`, sem um cabeçalho `Stripe-Account`. Esse exemplo não transfere fundos automaticamente. Crie transferências separadamente para enviar fundos para a conta conectada. #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "on_behalf_of={{CONNECTEDACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "on_behalf_of={{CONNECTEDACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" ``` ### Etapas adicionais antes de você criar uma assinatura Para criar Destination Charges, defina o cliente e o preço na conta da plataforma. Você precisa ter criado uma conta conectada na plataforma. O cliente precisa existir na conta da plataforma. A sua plataforma é o *merchant of record* (The legal entity responsible for facilitating the sale of products to a customer that handles any applicable regulations and liabilities, including sales taxes. In a Connect integration, it can be the platform or a connected account), a menos que você defina `on_behalf_of` com o ID da conta conectada. ## Criar assinaturas para cobrar plataforma e clientes Você pode usar o Stripe Billing para criar assinaturas para os seus clientes finais para fazer transações diretamente com sua plataforma sem envolver suas contas conectadas. (See full diagram at https://docs.stripe.com/connect/subscriptions) ```text [customer] --> [platform] [account] ``` Este exemplo cria um marketplace que permite aos clientes fazer pedidos de entregas de restaurantes sob demanda. Esse marketplace oferece aos clientes uma assinatura mensal premium que os isenta de taxas de entrega. Os clientes que assinam a oferta premium pagam o marketplace diretamente e não assinam nenhum serviço de entrega ou restaurante específico. ## Before you begin Antes de você criar assinaturas para os clientes, é preciso: 1. Criar um modelo de preços. Para esse exemplo, criamos um [modelo de preço](https://docs.stripe.com/products-prices/pricing-models.md#flat-rate) de taxa fixa para cobrar uma tarifa dos clientes de forma recorrente, mas preços por usuário e por uso também são aceitos. 2. Criar um registro de [cliente](https://docs.stripe.com/billing/customer.md#manage-customers) para cada cliente que desejar faturar. Também é possível criar uma [conta conectada](https://docs.stripe.com/connect/marketplace/tasks/create.md) para cada usuário que recebe dinheiro do seu marketplace. No nosso exemplo de entrega sob demanda de restaurantes, uma conta conectada é um restaurante ou um serviço de entrega. No entanto, essa etapa não é necessária para que os clientes assinem o seu marketplace diretamente. ### Criar uma assinatura Para criar uma assinatura na qual sua plataforma recebe os fundos, sem qualquer dinheiro indo para as contas conectadas, siga o [Guia de assinaturas](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md) para criar uma assinatura com o Stripe Billing. ### Criar cobranças e transferências separadas Se quiser fazer posteriormente uma transferência manual de parte dos fundos que sua plataforma recebe para suas contas conectadas, use [cobranças e transferências separadas](https://docs.stripe.com/connect/separate-charges-and-transfers.md) para repassar fundos para uma ou mais contas conectadas. No nosso exemplo de entrega sob demanda de restaurantes, você pode usar cobranças e transferências separadas para repassar uma tarifa de afiliado para um motorista de entrega ou restaurante que encaminha um cliente para assinar o serviço de entrega premium. ## Criar assinaturas para cobrar contas conectadas Você pode usar o Stripe Billing para criar assinaturas para cobrar uma tarifa de suas contas conectadas por usar sua plataforma. (See full diagram at https://docs.stripe.com/connect/subscriptions) ```text [account] --> [platform] [customer] ``` Este exemplo cria uma plataforma de software de gerenciamento de academias que permite às academias pagar uma tarifa mensal para usar o software para gerenciar o cronograma e a marcação de aulas. As academias pagam a tarifa de assinatura, não os usuários da academia. O software de gerenciamento de academias também facilita pagamentos avulsos entre o usuário e a academia por cada aula em que o usuário estiver inscrito. A assinatura mensal é entre a conta conectada e a plataforma, não envolvendo o usuário da academia na transação. No diagrama acima, a academia é a conta conectada e o usuário da academia é o consumidor final. ## Before you begin Antes de criar assinaturas para suas contas conectadas, você precisa: 1. Criar um modelo de preços. Para esse exemplo, criamos um [modelo de preço](https://docs.stripe.com/products-prices/pricing-models.md#flat-rate) de taxa fixa para cobrar uma tarifa dos clientes de forma recorrente, mas preços por usuário e por uso também são aceitos. 2. Crie um cliente na plataforma com a forma de pagamento desejada para cada conta conectada que você deseja faturar. No exemplo do software de gestão de academias, você cria um cliente para cada academia: ### Crie um objeto Customer ou conta configurada pelo cliente para representar a conta conectada #### Accounts v2 Para representar cada academia, você precisa criar um objeto Account com `customer` e `merchant` como [configurações](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration). A configuração `customer` permite que a plataforma recolha pagamentos recorrentes da conta, e a configuração `merchant` permite que a conta recolha pagamentos dos seus próprios clientes. Crie apenas uma conta para representar cada pessoa jurídica, em vez de criar uma conta separada para cada proprietário, gerente ou operador da empresa. #### Customers v1 Para criar uma assinatura para a conta conectada que pague uma tarifa recorrente à plataforma, você precisa criar um objeto [Customer](https://docs.stripe.com/api/customers/create.md) para representar a conta conectada. O objeto Account permite que a conta conectada receba pagamentos de seus clientes, mas a plataforma não pode usá-lo para receber pagamentos recorrentes da conta conectada. Crie apenas um cliente para representar cada pessoa jurídica, em vez de criar um cliente para representar cada proprietário, gerente ou operador da empresa. ### Criar uma assinatura para a conta conectada Para criar uma assinatura em que sua plataforma receba os fundos das suas contas conectadas, siga o [Guia de assinaturas](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md) para criar uma assinatura com o Stripe Billing. Passe a conta ou o objeto Customer que representa a conta conectada no parâmetro `customer_account` ou `customer`. ## Habilite sua integração para receber notificações de evento A Stripe cria notificações de evento quando alterações ocorrem em sua conta, como quando um pagamento recorrente é bem-sucedido ou quando um repasse falha. Para receber essas notificações e usá-las para automatizar sua integração, configure um endpoint de *webhook* (A configurable endpoint that executes when it receives certain event notifications from an event destination). Por exemplo, você pode provisionar acesso ao seu serviço ao receber o evento `invoice.paid`. ### Notificações de eventos para integrações do Connect e de assinaturas Estas são as notificações de evento usadas pelas integrações do Connect. #### Accounts v2 | Evento | tipo data.object | Descrição | | --- | --- | --- | | `v2.core.account.closed` | `v2.core.account` | Ocorre quando uma conta conectada é encerrada, inclusive quando uma conta Express é encerrada pelo próprio titular por meio do Dashboard Express. Você pode usar esse evento para acionar a limpeza no seu servidor. Disponível para contas conectadas com acesso ao Dashboard da Stripe. | | - `v2.core.account[configuration.customer].capability_status_updated` - `v2.core.account[configuration.merchant].capability_status_updated` - `v2.core.account[configuration.recipient].capability_status_updated` | `v2.core.account` | Ocorre quando uma capacidade pertencente à configuração correspondente é atualizada. | | `v2.core.account.updated` | `v2.core.account` | Ocorre quando uma das seguintes propriedades de `Account` é atualizada: - `display_name` - `contact_email` - `metadata` - `applied_configurations` - `dashboard` | | `balance.available` | `balance` | Ocorre quando o seu saldo da Stripe é atualizado (por exemplo, quando [fundos que você adicionou da sua conta bancária](https://docs.stripe.com/connect/top-ups.md) ficam disponíveis para repasse à sua conta conectada). | | `payment_intent.succeeded` | `payment_intent` | Ocorre quando uma intenção de pagamento resulta em uma cobrança bem-sucedida. Disponível para todos os pagamentos, incluindo cobranças de [destino](https://docs.stripe.com/connect/destination-charges.md) e [diretas](https://docs.stripe.com/connect/direct-charges.md). | | `payout.failed` | `payout` | Ocorre quando [um repasse falha](https://docs.stripe.com/connect/manage-connected-account-payouts.md#webhooks). Quando um repasse falha, a conta externa envolvida é desativada, e nenhum repasse automático ou manual pode ser processado até que a conta externa seja atualizada. | | `v2.core.account_person.updated` | `v2.core.account_person` | Ocorre quando uma `Person` associada à `Account` é atualizada. Se você [usa a API Persons para gerenciar requisitos](https://docs.stripe.com/connect/handling-api-verification.md#verification-process), escute esse evento para monitorar alterações de requisitos e status de indivíduos. Disponível para contas conectadas controladas pela sua plataforma. | #### Accounts v1 | Evento | tipo data.object | Descrição | | --- | --- | --- | | `account.application.deauthorized` | `application` | Ocorre quando uma conta conectada se desconecta da sua plataforma. Você pode usá-lo para acionar a limpeza em seu servidor. Disponível para contas conectadas com acesso ao Stripe Dashboard, que inclui [contas Standard](https://docs.stripe.com/connect/standard-accounts.md). | | `account.external_account.updated` | Uma conta externa, como `card` ou `bank_account` | Ocorre quando [uma conta bancária ou cartão de débito vinculado a uma conta conectada é atualizado](https://docs.stripe.com/connect/payouts-bank-accounts.md), o que pode afetar os repasses. Disponível para contas conectadas controladas pela sua plataforma, o que inclui contas Custom e Express, e contas Standard com [controles de plataforma](https://docs.stripe.com/connect/platform-controls-for-stripe-dashboard-accounts.md) habilitados. | | `account.updated` | `account` | Permite monitorar alterações nos requisitos e mudanças de status das contas conectadas. Disponível para todas as contas conectadas. | | `balance.available` | `balance` | Ocorre quando o seu saldo da Stripe é atualizado. Por exemplo, quando [fundos que você adicionou da sua conta bancária](https://docs.stripe.com/connect/top-ups.md) ficam disponíveis para repasse à sua conta conectada. | | `payment_intent.succeeded` | `payment_intent` | Ocorre quando uma intenção de pagamento resulta em uma cobrança bem-sucedida. Disponível para todos os pagamentos, incluindo cobranças de [destino](https://docs.stripe.com/connect/destination-charges.md) e [diretas](https://docs.stripe.com/connect/direct-charges.md). | | `payout.failed` | `payout` | Ocorre quando [um repasse falha](https://docs.stripe.com/connect/manage-connected-account-payouts.md#webhooks). Quando um repasse falha, a conta externa envolvida é desativada, e nenhum repasse automático ou manual pode ser processado até que a conta externa seja atualizada. | | `person.updated` | `person` | Ocorre quando uma `Person` associada à `Account` é atualizada. Se você [usa a API Persons para gerenciar requisitos](https://docs.stripe.com/connect/handling-api-verification.md#verification-process), escute esse evento para monitorar alterações de requisitos e status de indivíduos. Disponível para contas conectadas controladas pela sua plataforma, o que inclui contas Custom e Express, e contas Standard com [controles de plataforma](https://docs.stripe.com/connect/platform-controls-for-stripe-dashboard-accounts.md) habilitados. | Estas são as notificações de evento usadas pelas integrações de assinaturas. > A API Accounts v2 está disponível para o público em geral para usuários do Connect e em versão prévia pública para outros usuários da Stripe. > > Independentemente de você usar objetos [Accounts v2](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md) ou objetos [Customer](https://docs.stripe.com/api/customers.md) para representar clientes, use os eventos `customer.subscription` para monitorar eventos de assinatura. | Evento | Descrição | | --- | --- | | `v2.core.account.created` | Enviado quando uma [Account v2](https://docs.stripe.com/api/v2/core/accounts/object.md) é devidamente criada. | | `customer.created` | Enviado quando um [Customer](https://docs.stripe.com/api/customers/object.md) é criado. | | `customer.subscription.created` | Enviado quando a assinatura é criada. O `status` da assinatura poderá ser `incomplete` se a autenticação do cliente for necessária para concluir o pagamento ou se você definir `payment_behavior` como [default_incomplete](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-payment_behavior). | | `customer.subscription.deleted` | Enviado quando a assinatura do cliente termina. | | `customer.subscription.paused` | Enviado quando o `status` de uma assinatura muda para `paused`. Por exemplo, isso é enviado quando você [configura](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-trial_settings-end_behavior-missing_payment_method) uma assinatura para ser pausada quando um [período de teste gratuito termina sem uma forma de pagamento](https://docs.stripe.com/billing/subscriptions/trials/free-trials.md#create-free-trials-without-payment). O faturamento não ocorrerá até que a assinatura [seja retomada](https://docs.stripe.com/api/subscriptions/resume.md). Esse evento não será enviado se você [pausar a cobrança do pagamento](https://docs.stripe.com/billing/subscriptions/pause-payment.md), pois as faturas continuam sendo criadas durante esse período. | | `customer.subscription.resumed` | Enviado quando você retoma uma assinatura que estava anteriormente com o status `suspenso`. Isso não se aplica quando você [retoma a cobrança de pagamentos](https://docs.stripe.com/billing/subscriptions/pause-payment.md#unpausing). | | `customer.subscription.trial_will_end` | Enviado 3 dias antes de o [período de teste terminar](https://docs.stripe.com/billing/subscriptions/trials.md). Se o período de teste for inferior a 3 dias, este evento será acionado. | | `customer.subscription.updated` | Enviado quando uma assinatura inicia ou é [alterada](https://docs.stripe.com/billing/subscriptions/change.md). Por exemplo, o evento é acionado ao renovar uma assinatura, adicionar cupons, aplicar descontos, incluir itens de fatura ou alterar planos. | | `entitlements.active_entitlement_summary.updated` | Enviado quando os direitos ativos de um cliente são atualizados. Quando receber esse evento, você pode provisionar ou cancelar o acesso aos recursos do produto. Leia mais sobre [integração com direitos](https://docs.stripe.com/billing/entitlements.md). | | `invoice.created` | Enviado quando uma fatura é criada para uma assinatura nova ou em renovação. Se a Stripe não receber uma resposta positiva para `invoice.created`, a finalização de todas as faturas com [cobrança automática](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection.md) será adiada por até 72 horas. Leia mais sobre a [finalização de faturas](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized). - Responda à notificação enviando uma solicitação para a API [finalizar uma fatura](https://docs.stripe.com/api/invoices/finalize.md). | | `invoice.finalized` | Enviado quando uma fatura é finalizada e está pronta para pagamento. - Você pode enviar a fatura ao cliente. Para saber mais, consulte [finalização de faturas](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized). - Dependendo da configuração, cobraremos automaticamente a forma de pagamento padrão ou tentaremos fazer a cobrança. Para saber mais, consulte [e-mails após a finalização](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#emails). | | `invoice.finalization_failed` | A fatura não pôde ser finalizada. Saiba mais sobre [como lidar com falhas na finalização de faturas](https://docs.stripe.com/tax/customer-locations.md#finalizing-invoices-with-finalization-failures) e [sobre a finalização de faturas](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized). - Inspecione o [last_finalization_error](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error) da fatura para determinar a causa do erro. - Se você estiver usando o Stripe Tax, verifique o campo [automatic_tax](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error) do objeto `Invoice`. - Se `automatic_tax[status]=requires_location_inputs`, a fatura não será finalizada e os pagamentos não poderão ser coletados. Notifique seu cliente e colete a [localização do cliente](https://docs.stripe.com/tax/customer-locations.md) necessária. - Se `automatic_tax[status]=failed`, tente a solicitação outra vez mais tarde. | | `invoice.paid` | Enviado quando a fatura é paga. Você pode provisionar acesso ao produto quando recebe este evento e `status` é `active`. | | `invoice.payment_action_required` | Enviado quando a fatura exige autenticação do cliente. Saiba como gerenciar a assinatura quando a fatura [exigir ação](https://docs.stripe.com/billing/subscriptions/overview.md#requires-action). | | `invoice.payment_failed` | Um pagamento de uma fatura falhou. Consulte [Como lidar com falhas de pagamento](https://docs.stripe.com/billing/subscriptions/webhooks.md#payment-failures) para saber mais sobre os status do PaymentIntent e da assinatura. Você pode tomar várias medidas possíveis: - Avise o cliente. - Defina suas [configurações de assinatura](https://dashboard.stripe.com/settings/billing/automatic) no Dashboard para ativar o [Smart Retries](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md) e outros recursos de recuperação de receitas. - Se você usa PaymentIntents, colete os novos dados de pagamento e [confirme o PaymentIntent](https://docs.stripe.com/api/payment_intents/confirm.md). - Atualize a [forma de pagamento padrão](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-default_payment_method) na assinatura. | | `invoice.upcoming` | Enviado alguns dias antes da renovação da assinatura. O número de dias é baseado no número definido para **Próximos eventos de renovação** no [Dashboard](https://dashboard.stripe.com/settings/billing/automatic). Para assinaturas existentes, a alteração do número de dias entra em vigor no próximo período de cobrança. Se necessário, você ainda pode adicionar [outros itens de fatura](https://docs.stripe.com/billing/invoices/subscription.md#adding-upcoming-invoice-items). | | `invoice.updated` | Enviado quando um pagamento é bem-sucedido ou falha. Se o pagamento for bem-sucedido, o atributo `paid` será definido como `true`, e `status` será `paid`. Se o pagamento falhar, `paid` será definido como `false`, e `status` permanecerá `open`. As falhas de pagamento também acionam um evento `invoice.payment_failed`. | | `payment_intent.created` | Enviado quando um [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) é criado. | | `payment_intent.succeeded` | Enviado quando um PaymentIntent conclui um pagamento. | | `subscription_schedule.aborted` | Enviado quando um cronograma de assinatura é cancelado porque o pagamento inadimplente encerrou a assinatura relacionada. | | `subscription_schedule.canceled` | Enviado quando um cronograma de assinatura é cancelado, o que também cancela qualquer assinatura associada ativa. | | `subscription_schedule.completed` | Enviado quando todas as [fases](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md#subscription-schedule-phases) de um cronograma de assinatura são concluídas. | | `subscription_schedule.created` | Enviado quando um novo cronograma de assinatura é criado. | | `subscription_schedule.expiring` | Enviado 7 dias antes da data de vencimento de um cronograma de assinatura. | | `subscription_schedule.released` | Enviado quando um cronograma de assinatura é [lançado](https://docs.stripe.com/api/subscription_schedules/release.md) ou interrompido e dissociado da assinatura, que permanece. | | `subscription_schedule.updated` | Enviado quando uma programação de assinatura é atualizada. | - [Criar um endpoint de webhook](https://docs.stripe.com/webhooks.md#webhook-endpoint-def) - [Ouvir eventos com a Stripe CLI](https://docs.stripe.com/webhooks.md#local-listener) - [Webhooks do Connect](https://docs.stripe.com/connect/webhooks.md) - [Webhooks de assinatura](https://docs.stripe.com/billing/subscriptions/webhooks.md) ## Teste a integração Após você criar sua assinatura, teste cuidadosamente sua integração antes de expô-la aos clientes ou usá-la para qualquer atividade real. Saiba mais sobre [testes do Stripe Billing](https://docs.stripe.com/billing/testing.md). ## Opções adicionais Depois de criar a sua assinatura, você poderá especificar um [application_fee_percent](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-application_fee_percent), configurar o *portal do cliente* (The customer portal is a secure, Stripe-hosted page that lets your customers manage their subscriptions and billing details) e monitorar as assinaturas com webhooks, entre outras opções. ### Cobrar tarifas sobre assinaturas Uma vez em cada período de faturamento, a Stripe coleta essa porcentagem do valor final da fatura, inclusive itens de fatura agrupados, descontos ou ajustes de saldo de conta, como tarifa para a plataforma. Nós fazemos essa dedução antes de cobrar qualquer tarifa da Stripe. Ao criar ou atualizar uma assinatura, é possível especificar uma [application_fee_percent](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-application_fee_percent). É preciso que seja um número decimal de 0 a 100, com no mínimo duas casas decimais. Este exemplo mostra o valor `application_fee_percent` de assinaturas que usam cobranças diretas em contas conectadas: #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "expand[0]=latest_invoice.confirmation_secret" \ -d application_fee_percent=10 ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "expand[0]=latest_invoice.confirmation_secret" \ -d application_fee_percent=10 ``` Este exemplo mostra o valor `application_fee_percent` de assinaturas que usam Destination Charges: #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "expand[0]=latest_invoice.confirmation_secret" \ -d application_fee_percent=10 \ -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "expand[0]=latest_invoice.confirmation_secret" \ -d application_fee_percent=10 \ -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}" ``` ### Calcular porcentagem de tarifa da plataforma Para ver como calculamos a `application_fee_percent`, considere o cenário: - Uma assinatura custa 30 USD por ciclo de faturamento - Há uma fatura de 10 USD que está na próxima fatura - Aplica-se um cupom de 50% - O valor de `application_fee_percent` é 10 Neste caso, a tarifa total do aplicativo é 2 USD: (30 USD + 10 USD) * 50% * 10%. ### Tarifas percentuais e tarifas fixas As tarifas da plataforma sobre assinaturas normalmente são porcentagens porque o valor cobrado nas assinaturas costuma ser variável. Você não pode definir a tarifa de plataforma recorrente da assinatura como um valor fixo. No entanto, você pode cobrar um `application_fee_amount` fixo em uma fatura, como explicado na [próxima seção](https://docs.stripe.com/connect/subscriptions.md#subscription-invoices). O parâmetro `application_fee_percent` não se aplica a faturas criadas fora de um período de faturamento de assinatura. Não se aplica, por exemplo, a itens de fatura proporcionais faturados imediatamente. Nesses casos, defina um `application_fee_amount` diretamente na fatura, com o valor a ser cobrado. ### Trabalhar com faturas criadas por assinaturas A cada ciclo, as assinaturas criam faturas e as faturas criam cobranças. Para entender melhor os ciclos de assinaturas, consulte o [ciclo de vida de assinaturas](https://docs.stripe.com/billing/subscriptions/overview.md#subscription-lifecycle). Para cobrar uma tarifa fixa ou dinâmica que não pode ser calculada automaticamente com `application_fee_percent`, adicione um `application_fee_amount` diretamente em cada fatura criada pela assinatura. Este exemplo mostra um `application_fee_amount` para uma fatura com uma Direct Charge na conta conectada: ```curl curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}} \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d application_fee_amount=100 ``` Este exemplo mostra um `application_fee_amount` para uma fatura com uma cobrança de destino: ```curl curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}} \ -u "<>:" \ -d application_fee_amount=100 \ -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}" ``` Para cobrar um `application_fee_amount` automaticamente, crie um *webhook* (A configurable endpoint that executes when it receives certain event notifications from an event destination) que escuta o evento `invoice.created`. Se quiser fazer isso manualmente, crie uma fatura com os itens de fatura pendentes e defina uma tarifa da plataforma nela. O `application_fee_amount` definido diretamente em uma fatura sobrepõe qualquer valor de tarifa de plataforma calculado com `application_fee_percent`, e seu teto é o valor da cobrança final da fatura. ### Usar cupons Após criar assinaturas, você pode adicionar cupons a elas. Os [cupons](https://docs.stripe.com/api/coupons.md) são objetos voltados ao comerciante que você pode usar para controlar descontos em [assinaturas](https://docs.stripe.com/billing/subscriptions/overview.md) ou [faturas](https://docs.stripe.com/api/invoices.md). Os [códigos promocionais](https://docs.stripe.com/api/promotion_codes.md) são códigos voltados para o cliente, criados a partir dos cupons e que podem ser compartilhados diretamente com os clientes. Saiba como [criar códigos voltados ao cliente](https://docs.stripe.com/billing/subscriptions/coupons.md#promotion-codes). ### Use períodos de avaliação Você pode iniciar a [assinatura](https://docs.stripe.com/billing/subscriptions/overview.md) de um cliente com um período de avaliação gratuita informando o argumento `trial_end` ao [criar a assinatura](https://docs.stripe.com/api.md#create_subscription): #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d trial_end=1610403705 ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d trial_end=1610403705 ``` O parâmetro `trial_end` aceita um carimbo de data e hora indicando o momento exato do término da avaliação. Quando cria uma assinatura, você também pode usar o argumento [trial_period_days](https://docs.stripe.com/api.md#create_subscription-trial_period_days), que é um número inteiro que representa a duração da avaliação em dias, a partir do momento atual. Quando criar uma assinatura com um período de avaliação, não precisamos de uma forma de pagamento para o cliente. Ainda criamos uma [fatura](https://docs.stripe.com/api/invoices.md) imediata, mas no valor de 0 USD. Um evento `customer.subscription.trial_will_end` é enviado ao [endpoint de webhook](https://docs.stripe.com/billing/subscriptions/webhooks.md) três dias antes do final do período de avaliação. Após ver essa notificação, tome as medidas necessárias, como informar ao cliente que o faturamento está prestes a começar. Quando a avaliação termina, é iniciado um novo ciclo de faturamento para o cliente. A Stripe gera uma fatura, envia uma notificação de evento `invoice.created` e tenta cobrar essa fatura aproximadamente 1 hora após o envio da notificação. Para encerrar antecipadamente uma avaliação, chame a API de [atualização de assinatura](https://docs.stripe.com/api.md#update_subscription) e defina o valor `trial_end` como um novo carimbo de data e hora ou **now** para encerrar imediatamente a fatura: ```curl curl https://api.stripe.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \ -u "<>:" \ -d trial_end=now ``` Saiba mais sobre como [adiar pagamentos em assinaturas ativas usando períodos de avaliação](https://docs.stripe.com/billing/subscriptions/trials/free-trials.md). ### Configurar o portal de clientes O portal do cliente permite que seus clientes gerenciem [assinaturas](https://docs.stripe.com/billing/subscriptions/overview.md) e [faturas](https://docs.stripe.com/api/invoices.md). Se você for um usuário do Billing, o portal permite que seus clientes gerenciem suas assinaturas (atualizar, cancelar, pausar e assim por diante). Os usuários somente do Invoicing podem usar o portal para pagar uma fatura, adicionar uma forma de pagamento e muito mais. Saiba mais como [integrar o portal do cliente](https://docs.stripe.com/customer-management.md). ### Monitorar assinaturas com webhooks Enviamos notificações ao seu aplicativo usando [webhooks](https://docs.stripe.com/webhooks.md). Os webhooks são especialmente importantes para [assinaturas](https://docs.stripe.com/billing/subscriptions/overview.md), onde a maioria das atividades ocorre de forma assíncrona. Para usar webhooks com suas assinaturas: 1. Crie um endpoint de webhook no aplicativo. 2. Adicione lógica para gerenciar os eventos da Stripe. Para assinaturas, esses eventos incluem falhas de pagamento e mudanças no estado de assinaturas (como mudar de avaliação para um estado ativo). 3. Teste o endpoint de webhook para confirmar se funciona da forma esperada. Saiba como usar webhooks para [receber notificações de atividade de assinatura](https://docs.stripe.com/billing/subscriptions/webhooks.md). ### Entenda o comportamento de desconexão Quando uma conta conectada é desconectada de uma plataforma, as assinaturas não são canceladas automaticamente. No entanto, alguns aspectos da cobrança de pagamentos podem continuar ou deixar de continuar, dependendo do tipo de cobrança usado. ### Cobranças diretas Após a desconexão, as assinaturas continuam sendo executadas na conta conectada. Se a assinatura foi criada com um `application_fee_percent`, a tarifa da plataforma continua sendo cobrada pela plataforma após a desconexão. Remova o `application_fee_percent` da assinatura antes que uma conta conectada se desconecte da sua plataforma. Após a desconexão, uma conta conectada pode limpar o parâmetro `application_fee_percent` das assinaturas existentes por meio da API. ### Destination Charges Após a desconexão, as assinaturas existentes criadas como destination charges continuam a gerar faturas, mas as faturas não podem ser finalizadas enquanto a conta de destino estiver desconectada. Antes de desconectar, ajude as contas conectadas a migrar ou cancele as assinaturas associadas. ### Cobranças e transferências separadas Após a desconexão, as assinaturas existentes criadas como cobranças e transferências separadas continuam a gerar faturas, mas não podem transferir fundos para uma conta conectada. Antes de desconectar, ajude as contas conectadas a migrar ou cancele as assinaturas associadas. ### Cobranças de destino com on_behalf_of Quando uma conta é desconectada de uma plataforma, assinaturas `on_behalf_of` não cobrarão o cliente em faturas de assinatura definidas como `charge_automatically`. Continuamos gerando faturas de assinatura para cada ciclo, mas elas permanecem como rascunhos com `auto_advance` definido como `false`. Para continuar cobrando pagamentos, reconecte-se à conta desconectada ou remova explicitamente esses campos da fatura da assinatura e tente repetir o pagamento dessas faturas. ### Integrar o cálculo e recolhimento de impostos Primeiro, você precisa determinar qual entidade está sujeita a impostos. Essa entidade pode ser sua conta conectada ou a plataforma, dependendo do seu modelo de negócio. Para saber mais, consulte [Stripe Tax com Connect](https://docs.stripe.com/tax/connect.md). ## See also - [Como criar faturas](https://docs.stripe.com/connect/invoices.md) - [Criar cobranças](https://docs.stripe.com/connect/charges.md) - [Compartilhar clientes entre várias contas](https://docs.stripe.com/connect/cloning-customers-across-accounts.md) - [Várias moedas](https://docs.stripe.com/connect/currencies.md)