Pular para o conteúdo
Criar conta
 ou
Entrar
O logotipo da documentação da Stripe
/
Criar conta
Login

Criar assinaturas com o Stripe Billing

Com o Connect, você pode criar assinaturas para seus clientes ou contas conectadas.

Copiar página

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 e usar o Stripe Billing para apoiar seu modelo de receitas recorrentes.

Casos de uso

Você pode criar assinaturas 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.

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 usoDescrição
Crie assinaturas do cliente final para a conta conectadaCrie assinaturas para clientes finais para suas contas conectadas, o que apoia várias abordagens para coletar pagamentos. Neste exemplo, Prices residem na conta conectada.
Criar assinaturas para faturar plataforma e clientesMarketplaces podem oferecer assinaturas de associação diretamente sem envolver sua conta conectada. Neste exemplo, Prices residem na conta conectada.
Criar assinaturas para faturar contas conectadasPlataformas podem criar assinaturas para suas contas conectadas. Neste exemplo, Prices 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.
  • Assinaturas não são automaticamente canceladas quando você se desconecta da plataforma. É preciso cancelar a assinatura após a desconexão. Você pode usar webhooks para monitorar a atividade das contas conectadas.

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.

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.

Antes de começar

Antes de poder criar assinaturas para seus clientes ou contas conectadas, você deve:

  1. Criar uma conta conectada para cada pessoa que receber dinheiro na sua plataforma. 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 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 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.

Usar Direct Charges para criar uma assinatura

Para criar uma assinatura com Charges associadas à conta conectada, crie assinatura estando autenticado como a conta conectada. Certifique-se de definir o cliente com uma forma de pagamento padrão e o Preço 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.

Expanda latest_invoice.confirmation_secret para incluir o Payment Element, do qual você precisa para confirmar o pagamento. Saiba mais sobre os Payment Elements.

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.

Command Line
curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_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 associadas à plataforma e criar automaticamente transferências para uma conta conectada, fazer uma chamada criar assinatura enquanto fornece o ID da conta conectada como o valor de transfer_data[destination].

Expanda latest_invoice.confirmation_secret para incluir o Payment Element, do qual você precisa para confirmar o pagamento. Saiba mais sobre os Payment Elements.

Opcionalmente, você pode especificar uma application_fee_percent. Saiba mais sobre coletar tarifas.

Command Line
curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}}
 \
  -d "items[0][price]"=
{{PRICE_ID}}
 \
  -d "expand[0]"="latest_invoice.confirmation_secret" \
  -d "transfer_data[destination]"=
{{CONNECTED_ACCOUNT_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.

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.

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.

Antes de começar

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 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 para cada cliente que desejar faturar.

Você também pode criar uma conta conectada 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 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 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.

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.

Antes de começar

Antes de criar assinaturas para seus clientes ou contas conectadas, você deve:

  1. Crie uma conta conectada para cada usuário que receber dinheiro na sua plataforma. Neste exemplo, a conta conectada é a academia.
  2. Criar um modelo de preços. Para esse exemplo, criamos um modelo de preço 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 na plataforma com a forma de pagamento pretendida para cada conta conectada que você quiser faturar. No exemplo de software de gerenciamento de academias, você cria um cliente para cada academia:

Criar um objeto Customer para representar a conta conectada

Se as suas contas conectadas usarem a Stripe para processar pagamentos para seus clientes finais, elas podem já ter criado um objeto Customer para cada cliente final.

Para criar uma assinatura corretamente para que a conta conectada pague uma tarifa recorrente à plataforma, é preciso criar um objeto Customer separado para representar a conta conectada.

No exemplo da academia, as academias usam a Stripe para processar pagamentos avulsos de seus usuários. Eles já criaram um objeto Customer para cada usuário, mas você precisa criar um objeto Customer diferente para representar a própria academia. Crie somente um Customer para representar cada entidade comercial e não crie um Customer para representar cada proprietário, gerente ou operador do negócio.

Criar uma assinatura para a conta conectada

Para criar uma assinatura na qual sua plataforma recebe os fundos das suas contas conectadas, siga o Guia de assinatura para criar uma assinatura com o Stripe Billing. O objeto Customer envolvido na transação representa a conta conectada. No nosso exemplo da academia, o CUSTOMER_ID representa a academia, não o usuário da academia.

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

Eventdata.object typeDescription
account.application.deauthorizedapplicationOccurs when a connected account disconnects from your platform. You can use it to trigger cleanup on your server. Available for connected accounts with access to the Stripe Dashboard, which includes Standard accounts.
account.external_account.updatedAn external account, such as card or bank_accountOccurs when a bank account or debit card attached to a connected account is updated, which can impact payouts. Available for connected accounts that your platform controls, which includes Custom and Express accounts, and Standard accounts with platform controls enabled.
account.updatedaccountAllows you to monitor changes to connected account requirements and status changes. Available for all connected accounts.
balance.availablebalanceOccurs when your Stripe balance has been updated. For example, when funds you’ve added from your bank account are available for transfer to your connected account.
payment_intent.succeededpayment_intentOccurs when a payment intent results in a successful charge. Available for all payments, including destination and direct charges.
payout.failedpayoutOccurs when a payout fails. When a payout fails, the external account involved is disabled, and no automatic or manual payouts can be processed until the external account is updated.
person.updatedpersonOccurs when a Person associated with the Account is updated. If you use the Persons API to handle requirements, listen for this event to monitor changes to requirements and status changes for individuals. Available for connected accounts that your platform controls, which includes Custom and Express accounts, and Standard accounts with platform controls enabled.

Estas são as notificações de evento usadas pelas integrações de assinaturas.

customer.createdSent when a Customer is successfully created.
customer.subscription.createdSent when the subscription is created. The subscription status might be incomplete if customer authentication is required to complete the payment or if you set payment_behavior to default_incomplete. View subscription payment behavior to learn more.
customer.subscription.deletedEnviado quando a assinatura do cliente termina.
customer.subscription.pausedSent when a subscription’s status changes to paused. For example, this is sent when a subscription is configured to pause when a free trial ends without a payment method. Invoicing won’t occur until the subscription is resumed. We don’t send this event if payment collection is paused because invoices continue to be created during that time period.
customer.subscription.resumedSent when a subscription previously in a paused status is resumed. This doesn’t apply when payment collection is unpaused.
customer.subscription.trial_will_endSent three days before the trial period ends. If the trial is less than three days, this event is triggered.
customer.subscription.updatedSent when a subscription starts or changes. For example, renewing a subscription, adding a coupon, applying a discount, adding an invoice item, and changing plans all trigger this event.
entitlements.active_entitlement_summary.updatedEnviado 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.
invoice.createdSent when an invoice is created for a new or renewing subscription. If Stripe fails to receive a successful response to invoice.created, then finalizing all invoices with automatic collection is delayed for up to 72 hours. Read more about finalizing invoices.
invoice.finalizedEnviado quando uma fatura é finalizada e está pronta para pagamento.
  • You can send the invoice to the customer. View invoice finalization to learn more.
  • Depending on your settings, we automatically charge the default payment method or attempt collection. View emails after finalization to learn more.
invoice.finalization_failedThe invoice couldn’t be finalized. Learn how to handle invoice finalization failures by reading the guide. Learn more about invoice finalization in the invoices overview guide.
  • Inspect the Invoice’s last_finalization_error to determine the cause of the error.
  • If you’re using Stripe Tax, check the Invoice object’s automatic_tax field.
  • If automatic_tax[status]=requires_location_inputs, the invoice can’t be finalized and payments can’t be collected. Notify your customer and collect the required customer location.
  • Se automatic_tax[status]=failed, tente a solicitação outra vez mais tarde.
invoice.paidEnviado quando a fatura é paga. Você pode provisionar acesso ao produto quando recebe este evento e status é active.
invoice.payment_action_requiredSent when the invoice requires customer authentication. Learn how to handle the subscription when the invoice requires action.

invoice.payment_failed

Houve uma falha no pagamento de uma fatura. O status do PaymentIntent muda para requires_action. O status da assinatura continua incomplete somente na primeira fatura da assinatura. Você pode tomar várias providências quando um pagamento falha:

invoice.upcomingSent a few days prior to the renewal of the subscription. The number of days is based on the number set for Upcoming renewal events in the Dashboard. For existing subscriptions, changing the number of days takes effect on the next billing period. You can still add extra invoice items, if needed.
invoice.updatedEnviado 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.createdSent when a PaymentIntent is created.
payment_intent.succeededEnviado quando um PaymentIntent conclui um pagamento.
subscription_schedule.abortedEnviado quando um cronograma de assinatura é cancelado porque o pagamento inadimplente encerrou a assinatura relacionada.
subscription_schedule.canceledEnviado quando um cronograma de assinatura é cancelado, o que também cancela qualquer assinatura associada ativa.
subscription_schedule.completedSent when all phases of a subscription schedule complete.
subscription_schedule.createdEnviado quando um novo cronograma de assinatura é criado.
subscription_schedule.expiringEnviado 7 dias antes da data de vencimento de um cronograma de assinatura.
subscription_schedule.releasedSent when a subscription schedule is released, or stopped and disassociated from the subscription, which remains.
subscription_schedule.updatedEnviado quando uma programação de assinatura é atualizada.

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.

Opções adicionais

Depois de criar sua assinatura, você pode especificar um application_fee_percent, configurar o portal do cliente, 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

Usar cupons

Use períodos de avaliação

Configurar o portal de clientes

Monitorar assinaturas com webhooks

Tornar a conta conectada o comerciante da liquidação usando on_behalf_of

Entenda o comportamento de desconexão

Integrar o cálculo e recolhimento de impostos

Veja também

Esta página foi útil?
SimNão
Precisa de ajuda? Fale com o suporte.
Participe do nosso programa de acesso antecipado.
Confira nosso changelog.
Dúvidas? Fale com a equipe de vendas.
LLM? Read llms.txt.
Powered by Markdoc