Assinaturas
O recurso de assinatura oferece uma maneira eficiente e automatizada de cobrar clientes (assinantes). Ao criar uma assinatura, você só precisa especificar o plano desejado, associar o cliente à assinatura e fornecer um identificador exclusivo para ela. Se preferir, é possível criar o cliente e seus detalhes de pagamento simultaneamente durante o processo de assinatura, simplificando ainda mais a gestão do ciclo de cobrança.
Assinatura e planos
Lembre-se de que uma assinatura só pode ser criada quando o plano associado estiver ativo.
Status das assinaturas
Toda assinatura possuí um estado que define a atual situação do seu processo de criação/utilização. A tabela a seguir apresenta todos os possíveis estados que podem ser associados a uma assinatura, juntamente com suas descrições:
| Estado | Descrição |
|---|---|
| ATIVO (ACTIVE) | A assinatura está ativa, com a fatura paga e pagamento aprovado dentro do ciclo vigente do plano. |
| ATRASADA (OVERDUE) | A fatura está em atraso, e o pagamento foi negado (aplica-se apenas a assinaturas com cartão). Para boletos, este estado não é aplicável. |
| AÇÃO PENDENTE (PENDING_ACTION) | O pagamento foi negado e no motivo consta NÃO TENTE NOVAMENTE. Esse status aplica-se apenas para assinaturas que utilizam cartão como meio de pagamento. Não serão executadas retentativas automática para assinaturas com esse status.Um novo cartão válido precisa ser informado e uma nova retentativa de cobrança pode ser feita manualmente. A opção manual estará disponível se houver ao menos uma retentativa automática agendada. Caso nenhuma ação seja realizada, a assinatura se manterá com o status por 7 dias. Em seguida a assinatura terá o status alterado para SUSPENDED ou CANCELED, conforme a preferência configurada. |
| CANCELADA (CANCELED) | O estabelecimento cancelou a assinatura por razões relacionadas ao cliente, falta de pagamento ou outros problemas. Alternativamente, o pagamento foi negado após todas as tentativas (configurável). Este é um estado final que não sofre alterações. |
| EXPIRADA (EXPIRED) | O ciclo da assinatura chegou ao fim, e todas as faturas e pagamentos precisam estar com status pago. Este é um estado final. |
| PENDENTE (PENDING) | Este é o estado inicial associado a criação de uma assinatura. O estado fica pendente até que o pagamento via cartão seja autorizado ou o boleto seja compensado pela instituição financeira. |
| SUSPENSA (SUSPENDED) | O estabelecimento pode suspender uma assinatura a qualquer momento utilizando a API ou o painel. Cada método de pagamento apresenta comportamentos distintos: - Cartão de Crédito: Se o estabelecimento configurou a suspensão da assinatura após todas as tentativas de cobrança falharem, a suspensão será automática. - Boleto: Caso não haja pagamento em até 7 dias, o sistema suspenderá automaticamente a assinatura. Em caso de dúvidas sobre a permanência da suspensão ou a possibilidade do estabelecimento configurá-la para cancelamento, entre em contato com o time de suporte do PagBank. |
| TRIAL | A assinatura foi criada a partir de um plano com período de teste (trial). |
Os estados CANCELED e EXPIRED são estados finais. Ou seja, você não pode reativar uma assinatura após ela assumir um desses estados. Portanto, se o seu cliente deseja reativar a utilização do seu produto ou serviço, será necessário a criação de uma nova assinatura.
Endpoints
A API de assinaturas do PagBank disponibiliza os seguintes endpoints para facilitar a gestão de suas assinaturas:
- Criar Assinatura: Inicie uma nova assinatura, informando o plano, o cliente e um identificador único.
- Consultar por ID: Obtenha detalhes específicos de uma assinatura usando seu identificador único.
- Listar Assinaturas: Visualize a lista completa de todas as assinaturas registradas em sua conta.
- Listar Faturas de Assinatura: Consulte as faturas associadas a uma assinatura específica.
- Alterar Assinatura: Faça modificações nos detalhes de uma assinatura existente.
- Cancelar Assinatura: Encerre uma assinatura de maneira definitiva.
- Suspender Assinatura: Coloque temporariamente em suspensão uma assinatura, permitindo a reativação no futuro.
- Ativar Assinatura: Torne ativa uma assinatura previamente suspensa.
- Retentativa de Cobrança Manual : Realize uma nova tentativa de cobrança manualmente de uma assinatura atrasada ou que tenha ações pendentes.
- Deletar Cupons de Assinatura: Remova cupons associados a uma assinatura específica.
Objeto Assinatura
A API de Assinaturas utiliza o objeto Assinatura. Para identificar todos os parâmetros, seus respectivos tipos e exemplos de cada parâmetro do objeto, acesse Objeto Assinatura.
Pro Rata
O Pro Rata é um cálculo realizado para ajustar o valor de uma fatura quando a data de pagamento do cliente é modificada. Esse cálculo assegura que o pagamento seja proporcional ao período efetivamente utilizado do plano durante um ciclo de cobrança.
O cálculo de Pro Rata será aplicado nas seguintes condições, em ordem de validação:
- O cliente ativou a configuração de Pro Rata na solicitação (
pro_rata = true). - O cliente alterou a data de pagamento na solicitação utilizando o parâmetro
best_invoice_date.
É necessário que os parâmetros pro_rata = true e best_invoice_date sejam enviados para que a configuração seja aplicada corretamente. Caso um desses parâmetros não seja informado, a alteração não será realizada.
O Pro Rata pode ser configurado no momento da criação ou edição de uma assinatura.
Updated 2 months ago