# 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) 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 não 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) 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. Criar uma [conta conectada](https://docs.stripe.com/connect/accounts.md) para cada pessoa que receber dinheiro na sua plataforma. No nosso exemplo de publicação online, uma conta conectada representa um autor. 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. 1. 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. ### Decidir entre Direct Charges e Destination Charges Você pode usar cobranças diretas ou cobranças de destino para dividir o pagamento de um cliente entre a conta conectada e sua plataforma. Com cobranças diretas, os clientes não saberão da existência da sua plataforma porque o nome do autor, e não o nome da sua plataforma, é exibido na descrição do extrato. No nosso exemplo de publicação online, os leitores interagem com os autores diretamente. As cobranças diretas são recomendadas para contas conectadas com acesso ao Stripe Dashboard completo, o que inclui contas Standard. Se quiser que sua plataforma seja responsável pelas tarifas da Stripe, reembolsos e estornos, use cobranças de destino. No nosso exemplo de publicação, os clientes assinam sua plataforma de publicação, não diretamente com autores específicos. 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). ```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" ``` ### 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]`. 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 [application_fee_percent](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-application_fee_percent). Saiba mais sobre [coletar tarifas](https://docs.stripe.com/connect/subscriptions.md#collect-fees). ```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}}" ``` ### Etapas adicionais antes de você criar uma assinatura Para criar uma cobrança de destino, defina o cliente e o preço na conta da plataforma. Você deve ter criado uma conta conectada na plataforma. O cliente deve existir dentro da conta da plataforma. Quando você usa cobranças de destino, a plataforma é o *comerciante responsável* (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). ## 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) 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. 1. Criar um registro de [cliente](https://docs.stripe.com/billing/customer.md#manage-customers) para cada cliente que desejar faturar. Você também pode criar uma [conta conectada](https://docs.stripe.com/connect/accounts.md) para cada usuário que receber 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 é exigida para os clientes assinarem 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) 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. 1. 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: ### Criar um objeto Customer para representar a conta conectada 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 o objeto Customer que representa a conta conectada no parâmetro `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 webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests). 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. | 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/payouts-connected-accounts.md#webhooks). Quando um repasse falha, a conta externa envolvida é desativada e nenhum repasse automático ou manual é processado até que ela 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/connect/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 (suspenso)`. Por exemplo, enviamos isso quando você [configura](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-trial_settings-end_behavior-missing_payment_method) uma assinatura para pausar 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 (/api/subscriptions/resume). Não enviamos esse evento se você [suspender a cobrança de pagamentos](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 três dias antes do [final do período de avaliação](https://docs.stripe.com/billing/subscriptions/trials.md). O evento é acionado quando o período de avaliação é inferior a três dias. | | `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. O status do PaymentIntent muda para `requires_action`. O status da assinatura permanece como `incomplete` *only* para a primeira fatura da assinatura. Se um pagamento falhar, você pode tomar várias ações 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 sua assinatura, você pode 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), cobrar seu cliente usando o parâmetro `on_behalf_of` e monitorar assinaturas com webhooks, além de 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: ```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: ```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 ```bash curl https://api.stripe.com/v1/invoices/{INVOICE_ID} \ -u <>: \ -d application_fee_amount=100 \ -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}" ``` Este exemplo mostra um `application_fee_amount` para uma fatura com uma cobrança de destino: #### curl ```bash curl https://api.stripe.com/v1/invoices/{INVOICE_ID} \ -u <>: \ -d application_fee_amount=100 \ -d "transfer_data[destination]"="{{CONNECTED_STRIPE_ACCOUNT_ID}}" ``` Para cobrar um `application_fee_amount` automaticamente, crie um *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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): ```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.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. 1. 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). 1. 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). ### Tornar a conta conectada o comerciante da liquidação usando on_behalf_of Você pode criar ou atualizar uma assinatura com o parâmetro `on_behalf_of` para algumas finalidades: - Para tornar a conta conectada o comerciante da liquidação de fundos - Para usar a marca de uma conta conectada em recursos hospedados (recibos de e-mail, faturas e o portal do cliente) Leia a documentação a seguir para ver os requisitos de uso de `on_behalf_of` e mais informações sobre como isso afeta os pagamentos em assinaturas: - Para transferências automáticas para a conta conectada, consulte os detalhes do parâmetro `on_behalf_of` em [Cobrança em nome de uma conta conectada](https://docs.stripe.com/connect/charges.md#on_behalf_of). - Para obter informações sobre como transferir pagamentos manualmente, consulte a seção Disponibilidade de transferências em [Criar cobranças e transferências separadas](https://docs.stripe.com/connect/separate-charges-and-transfers.md#settlement-merchant). - Veja uma lista de funções de conta necessárias para processar formas de pagamento em [Funções de forma de pagamento](https://docs.stripe.com/connect/account-capabilities.md#payment-methods). - Para ver uma lista de opções de marca a serem ativadas na conta conectada, consulte os detalhes do parâmetro `settings.branding` na [documentação de referência da API](https://docs.stripe.com/api/accounts/object.md#account_object-settings-branding) Este exemplo mostra `on_behalf_of` para uma nova assinatura usando cobranças e transferências separadas: ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "customer={{CUSTOMER_ID}}" \ -d "on_behalf_of={{CONNECTEDACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" ``` Este exemplo mostra como usar `on_behalf_of` com uma cobrança de destino e tarifa da plataforma: ```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}}" ``` ### 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. ### Cobranças de destino ou cobranças e transferências separadas Após a desconexão, as assinaturas existentes criadas como cobranças de destino ou cobranças e transferências separadas continuam a gerar faturas, mas não podem transferir fundos para uma conta conectada. Antes de desconectar, você deve auxiliar as contas conectadas com migrações de assinatura ou cancelar 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 - [Criar faturas](https://docs.stripe.com/invoicing/connect.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)