Para efetivamente cobrar seu cliente de forma recorrente, você deve criar uma assinatura atrelada a um plano, que então conterá os dados de cobrança.
A criação de uma subscription (assinatura) é parecida com a criação de uma transação. Em uma assinatura no cartão de crédito, é possível usar um card_id ou todos os dados do cartão. Da mesma forma, pode ser informado o customer_id ou então todos os dados do customer(cliente).
| Campo | Validação | Descrição | Exemplo |
|---|---|---|---|
| link (boolean) | Se cobranças dessa assinatura deverão gerar um link de pagamento ou não | true | |
| plan_id (integer) | ID do plano | 1 | |
| gateway_id (integer) | ID do gateway | 2 | |
| customer_id (integer) | ID do cliente (Não-obrigatório caso customer esteja preenchido) | 1 | |
| customer | Customer Post | Objeto cliente (Não-obrigatório caso customer_id esteja preenchido) | |
| payment_method (string) | boleto/credit_card (choice) | Nome do método de pagamento | boleto |
| card_id (integer) | ID do cartão (Não-obrigatório caso card_cvv, card_number, card_expiration_date e card_holder_name estejam preenchidos ou payment_method ≠ credit_card) | 1 | |
| card_cvv (string) | Verifica de acordo com número | CVV (Não-obrigatório caso card_id esteja preenchido ou payment_method ≠ credit_card) | 151 |
| card_number (string) | Valida se é válido, mas não se existe | Número do cartão (Não-obrigatório caso card_id esteja preenchido ou payment_method ≠ credit_card) | 5164 7214 9090 0869 |
| card_holder_name (string) | Nome do portador (Não-obrigatório caso card_id esteja preenchido ou payment_method ≠ credit_card) | Maria da Silva | |
| card_expiration_date (string) | "MMYY", verifica se já está vencido | Validade do cartão (Obrigatório caso card_id não esteja preenchido e payment_method = "credit_card") | 07/2027 |
| postback_url (string) | Endpoint informado pelo cliente para recebimento de notificações referentes ao status da assinatura | https://db8e-187-86-148-88.ngrok.io/api/teste | |
| soft_descriptor (string) | Informações extras que podem ser passados ao método de pagamento (Não-obrigatório) | Assinatura teste | |
| splits(array) | |||
| splits.[i].partner_id(int) | Parceiro deve possuir cadastro no gateway passado na assinatura (gateway_id) | Id do parceiro (Não-obrigatório caso document_number esteja preenchido) | 1 |
| splits.[i].document_number(int) | Parceiro deve possuir cadastro no gateway passado na assinatura (gateway_id) | Documento do parceiro (Não-obrigatório caso partner_id esteja preenchido) | 58373686045 |
| splits.[i].fixed_value(int) | Fixed_value e percentual_value não podem ser informados ao mesmo tempo | Valor em centavos que parceiro receberá | 50 |
| splits.[i].percentual_value(int) | Fixed_value e percentual_value não podem ser informados ao mesmo tempo | Valor em percentual que parceiro receberá sobre cada cobrança | 10 (%) |
| tags(array) | |||
| tags.[i].name(string) | Informação para identificação da assinatura | Tipo A | |
| emit_nfse(boolean) | Assinatura deve ou não emitir nota fiscal. Importante: o plano escolhido deverá oferecer essa funcionalidade e ter os dados referentes à nota. | True | |
| when_emit_nfse(boolean) | "emissao"/"pagamento" (escolha) | Escolha de quando a nota fiscal deverá ser emitida: na emissão da cobrança ou no pagamento da cobrança | Pagamento |
| note_id | Identificador do emissor das notas fiscais | Nibo |
| Campo | Validação | Descrição | Exemplo |
|---|---|---|---|
| plan_id(integer) | ID do plano | 1 | |
| payment_method(string) | "boleto"/"credit_card" (escolha) | Nome do método de pagamento | boleto |
| card_id | ID do cartão (Obrigatório caso card_cvv, card_number, card_expiration_date e card_holder_name não estejam preenchidos e payment_method = "credit_card") | 2 | |
| card_cvv (string) | Verifica de acordo com número | CVV (Obrigatório caso card_id não esteja preenchido e payment_method = "credit_card") | 585 |
| card_number (string) | Valida se é válido, mas não se existe | Número do cartão (Obrigatório caso card_id não esteja preenchido e payment_method = "credit_card") | 5201 6326 7203 1578 |
| card_expiration_date (string) | "MMYY", verifica se já está vencido | Validade do cartão (Obrigatório caso card_id não esteja preenchido e payment_method = "credit_card") | 07/2027 |
| card_holder_name (string) | Nome do portador (Obrigatório caso card_id não esteja preenchido e payment_method = "credit_card") | João Silva | |
| soft_descriptor (string) | Informações extras que podem ser passados ao método de pagamento | Assinatura teste | |
| postback_url (string) | Endpoint informado pelo cliente para recebimento de notificações referentes ao status da assinatura | https://db8e-187-86-148-88.ngrok.io/api/teste |
Rota para cancelamento. É necessário informar apenas o id da assinatura. Após o cancelamento, não haverá geração de novas cobranças, mesmo que haja o total de dias do plano não tenha sido completado.Importante: assinaturas que possuem status "pago" não podem ser canceladas. Para informações sobre a possibilidade de cancelamento no gateway setado na assinatura, consulte Gateways.
Através dessa rota haverá a retentativa de pagamento da cobrança do ciclo atual da assinatura, através de até 3 transações consecutivas. Esse processo independe do gateway escolhido.
Rota destinada a alteração de data de vencimento da cobrança do ciclo atual da assinatura. A cobrança (invoice) permanecerá a mesma e a transação será cancelada para geração de outra. Importante:somente é possível fazer alteração de data de vencimento em cobranças efetuadas no boleto.
Através dessa rota alteramos o gateway utilizado para o pagamento. A cobrança (invoice) permanecerá a mesma e a transação será cancelada para geração de outra. Processo independe do gateway original.
Mudança de método de pagamento entre cartão, boleto e pix. A cobrança (invoice) permanecerá a mesma, a transação será cancelada e gerada uma nova. Para informações sobre métodos aceitos em cada gateway, consulte Gateways
A primeira cobrança gerada dentro de uma assinatura poderá ocorrer em momentos diferentes, dependendo das configurações do plano. Caso seja utilizado um plano que não possua dias de teste, a primeira cobrança será gerada logo na criação da assinatura. Caso contrário, a primeira cobrança será gerada no dia posterior ao final do período de teste.
As demais cobranças serão geradas de acordo com o método de pagamento. Em assinaturas no cartão de crédito a nova cobrança e sua respectiva transação serão geradas no mesmo dia em que o ciclo se encerra.
Em assinaturas efetivadas no boleto bancário ou pix, 20 dias antes do início do novo ciclo haverá a geração da nova cobrançaAdicionais (addons) representam aumentos no valor das cobranças de uma assinatura, sem afetar o valor total do plano, que permanecerá inalterado. Importante: antes de vincular um adicional à uma assinatura, é necessário criar o cadastro do mesmo no sistema informando um nome e um valor (em centavos). Para informações sobre a criação do adicional, veja Adicionais