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.

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.
  • 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.
  • 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
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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.

Eventotipo data.objectDescrição
account.application.deauthorizedapplicationOcorre 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.
account.external_account.updatedUma conta externa, como card ou bank_accountOcorre quando uma conta bancária ou cartão de débito vinculado a uma conta conectada é atualizado, 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 habilitados.
account.updatedaccountPermite monitorar alterações nos requisitos e mudanças de status das contas conectadas. Disponível para todas as contas conectadas.
balance.availablebalanceOcorre quando seu saldo da Stripe é atualizado. Por exemplo, quando os fundos adicionados à sua conta bancária estiverem disponíveis para transferência à sua conta conectada.
payment_intent.succeededpayment_intentOcorre quando uma intenção de pagamento resulta em uma cobrança bem-sucedida. Disponível para todos os pagamentos, incluindo cobranças de destino e diretas.
payout.failedpayoutOcorre quando um repasse falha. Quando um repasse falha, a conta externa envolvida é desativada e nenhum repasse automático ou manual é processado até que ela seja atualizada.
person.updatedpersonOcorre quando uma Person associada à Account é atualizada. Se você usa a API Persons para gerenciar requisitos, 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 habilitados.

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

customer.createdEnviado quando um Customer é criado.
customer.subscription.createdEnviado 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.
customer.subscription.deletedEnviado quando a assinatura do cliente termina.
customer.subscription.pausedEnviado quando o status de uma assinatura muda para paused. Por exemplo, isso é enviado quando uma assinatura é configurada para ser suspensa ao final de uma avaliação gratuita sem forma de pagamento. O faturamento só ocorre quando a assinatura é retomada. Não enviamos esse evento se o recebimento de pagamentos for suspenso porque as faturas continuam sendo criadas durante esse período.
customer.subscription.resumedEnviado quando uma assinatura com status paused é retomada. Não se aplica quando a cobrança do pagamento é reiniciada.
customer.subscription.trial_will_endEnviado três dias antes do final do período de avaliação. O evento é acionado quando o período de avaliação é inferior a três dias.
customer.subscription.updatedEnviado quando uma assinatura inicia ou é alterada. Por exemplo, o evento é acionado ao renovar uma assinatura, adicionar cupons, aplicar descontos, incluir itens de fatura ou alterar planos.
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.createdEnviado 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 será adiada por até 72 horas. Leia mais sobre a finalização de faturas.
invoice.finalizedEnviado quando uma fatura é finalizada e está pronta para pagamento.
  • Você pode enviar a fatura ao cliente. Para saber mais, consulte finalização de faturas.
  • 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.
invoice.finalization_failedNão foi possível finalizar a fatura. Leia o guia para saber como gerenciar falhas de finalização de faturas. Saiba mais sobre a finalização de faturas no guia de visão geral de faturas.
  • Inspecione last_finalization_error da fatura para determinar a causa do erro.
  • Se você usa o Stripe Tax, confira o campo automatic_tax do objeto Invoice.
  • Se automatic_tax[status]=requires_location_inputs, não é possível finalizar a fatura e cobrar os pagamentos. Notifique o cliente e colete a localização do cliente obrigatória.
  • 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_requiredEnviado quando a fatura exige autenticação do cliente. Saiba como gerenciar a assinatura quando a fatura exigir ação.

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.upcomingEnviado 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. 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.
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.createdEnviado quando um PaymentIntent é criado.
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.completedEnviado quando todas as fases de um cronograma de assinatura são concluídas.
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.releasedEnviado quando um cronograma de assinatura é lançado ou interrompido e dissociado da assinatura, que permanece.
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

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

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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" \
  -d application_fee_percent=10

Este exemplo mostra o valor application_fee_percent de assinaturas que usam Destination Charges:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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 application_fee_percent=10 \
  -d "transfer_data[destination]"=
{{CONNECTED_ACCOUNT_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.

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

Command Line
curl
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/invoices/{INVOICE_ID} \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -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:

Command Line
curl
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/invoices/{INVOICE_ID} \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d application_fee_amount=100 \
  -d "transfer_data[destination]"="{{CONNECTED_STRIPE_ACCOUNT_ID}}"

Para cobrar um application_fee_amount automaticamente, crie um webhook 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 são objetos voltados ao comerciante que você pode usar para controlar descontos em assinaturas ou faturas. Os códigos promocionais 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.

Use períodos de avaliação

Você pode iniciar a assinatura de um cliente com um período de avaliação gratuita informando o argumento trial_end ao criar a assinatura:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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 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, 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 imediata, mas no valor de 0 USD.

Um evento customer.subscription.trial_will_end é enviado ao endpoint de webhook 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 e defina o valor trial_end como um novo carimbo de data e hora ou now para encerrar imediatamente a fatura:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscriptions/
{{SUBSCRIPTION_ID}}
 \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d trial_end=now

Saiba mais sobre como adiar pagamentos em assinaturas ativas usando períodos de avaliação.

Configurar o portal de clientes

O portal do cliente permite que seus clientes gerenciem assinaturas e faturas. 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.

Monitorar assinaturas com webhooks

Enviamos notificações ao seu aplicativo usando webhooks. Os webhooks são especialmente importantes para assinaturas, 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.

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:

Este exemplo mostra on_behalf_of para uma nova assinatura usando cobranças e transferências separadas:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d customer=
{{CUSTOMER_ID}}
 \
  -d on_behalf_of=
{{CONNECTED_ACCOUNT_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:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}}
 \
  -d on_behalf_of=
{{CONNECTED_ACCOUNT_ID}}
 \
  -d application_fee_percent=10 \
  -d "transfer_data[destination]"=
{{CONNECTED_ACCOUNT_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.

Veja também

Esta página foi útil?
SimNão