Agendamento de recorrência

Este endpoint possibilita que o parceiro Bankly efetue o agendamento de uma cobrança recorrente para seu cliente.

O parceiro deverá informar os seguintes dados da contratação da recorrência:

Data da contratação;
Dia da postagem da cobrança na fatura;
Frequência da cobrança;
Quantidade de cobranças;
Valor e moeda;
Dados de desconto (se houver);
Como deseja que a cobrança aconteça, ou seja, se devemos persistir uma cobrança mesmo para um cartão bloqueado ou sem limite;
Dados do titular da cobrança e do produto contratado.

🚧
Importante
Atualmente, a cobrança recorrente é postada somente em faturas.

Pré-requisitos

Para que seja possível utilizar este endpoint, é necessário que:

O cliente do parceiro tenha contratado um produto/serviço que requeira pagamento periódico em intervalos regulares;
O parceiro tenha definido um programa para seus cartões;
O cartão do cliente do parceiro possua o status APPROVED;
O cliente do parceiro possua uma conta ativa.

Requisição (Request)

Requisição HTTP

POST 'https://api-mtls.sandbox.bankly.com.br/cards/invoices/recurrencies'

--request POST \
  --url 'https://api-mtls.sandbox.bankly.com.br/cards/invoices/recurrencies' 
  --header 'Content-Type: application/json' \ 
	--header 'api-version: 1.0' \
  --header 'Authorization: Bearer {Token}' \
  --header 'x-correlation-id: {Guid}'
  --data '{ 
       "hiringDate": "2024-01-01", 
       "billingType": "", 
       "recurrency": { 
         "postDate": 4, 
         "mustChargeOnHiringDate": false, 
         "frequency": "ANNUALY", 
         "quantity": 12, 
         "amount": { 
         "value": 101.5, 
         "currency": "BRL" 
       }, 
       "discount": { 
         "value": 2.00, 
         "currency": "BRL" 
       }, 
       "chargeOptions": { 
         "forceLimit": false, 
         "blockedAccount": false
         } 
       }, 
       "user": { 
         "documentNumber": { 
         "value": "47742663023", 
         "type": "CPF" 
       }, 
       "contract": { 
         "id": "12345678", 
         "type": "Credit" 
       } 
       }, 
       "product": { 
         "id": "1234", 
         "type": "Seguros", 
         "description": "Seguro Auto", 
         "transactionType": "SEGUROS_DEB" 
       } 
     }'

Autorização

Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.

Esta requisição requer o scope descrito a seguir:

Scope	Descrição
`recurrency.write`	Concede acesso para realizar o agendamento de uma recorrência de cobrança.

Cabeçalhos (Headers)

Nome	Descrição
`api-version`	Obrigatório. Versão da API. Atualmente estamos na versão 1.0.
`Authorization`	Obrigatório. Token de autorização do tipo Bearer.
`x-correlation-id`	Informe um GUID, sendo um novo cada requisição.

Parâmetros da rota (Path)

Não é necessário enviar parâmetros no path desta requisição.

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

Nome	Tipo	Descrição	Especificação
`hiringDate`	`string`	Obrigatório. Data da contratação do produto que deverá ser cobrado de forma recorrente.	Formato "yyyy-mm-dd"
`billingType`	`string`	Obrigatório. Tipo de cobrança.	Preencha este campo com "" ou com null.
`recurrency`	`object`	Obrigatório. Objeto que deverá conter informações sobre a recorrência.	—
`recurrency.postDate`	`int`	Dia em que deverá ser realizada a postagem de recorrência na fatura. Importante: caso este campo não seja preenchido, será considerada a data informada em `hiringDate`.	—
`recurrency.mustChargeOnHiringDate`	`boolean`	Obrigatório. Indica se a cobrança deverá ser realizada no mesmo dia da contratação (true) ou não (false). Importante: caso este campo seja preenchido com TRUE, o valor informado no campo `postDate` será desconsiderado.	—
`recurrency.frequency`	`string`	Obrigatório. Frequência em que a recorrência deverá ocorrer, que pode ser "ANNUALY" (Anualmente), "MONTHLY" (Mensalmente) ou "WEEKLY" (Semanalmente).	—
`recurrency.quantity`	`int`	Obrigatório. Quantidade de cobranças da recorrência. Este campo deverá indicar quantas vezes será realizada a cobrança dentro da frequência informada.	—
`recurrency.amount`	`object`	Obrigatório. Objeto que deverá conter informações sobre o valor da cobrança recorrente.	—
`recurrency.amount.currency`	`string`	Obrigatório. Código da moeda com base na ISO 3361.	—
`recurrency.amount.value`	`number`	Obrigatório. Valor da cobrança recorrente.	—
`recurrency.discount`	`object`	Objeto que deverá conter informações sobre o desconto aplicado na cobrança, caso exista. Importante: caso este objeto seja enviado, seus subcampos devem ser preenchidos obrigatoriamente.	—
`recurrency.discount.currency`	`string`	Código da moeda com base na ISO 3361.	—
`recurrency.discount.value`	`number`	Valor do desconto.	—
`recurrency.chargeOptions`	`object`	Obrigatório. Objeto que deverá conter informações sobre o formato de cobrança.	—
`recurrency.chargeOptions.forceLimit`	`boolean`	Obrigatório. Indica se a cobrança recorrente deverá ocorrer para cartão sem limite (true) ou não (false).	—
`recurrency.chargeOptions.blockedAccount`	`boolean`	Obrigatório. Indica se a cobrança recorrente deverá ocorrer para contas bloqueadas (true) ou não (false).	—
`user`	`object`	Obrigatório. Objeto que deverá conter informações sobre o titular do cartão.	—
`user.documentNumber`	`object`	Obrigatório. Objeto que deverá conter informações sobre o documento do titular.	—
`user.documentNumber.value`	`string`	Obrigatório. Número do documento.	Informe somente números.
`user.documentNumber.type`	`string`	Obrigatório. Tipo de documento, que pode ser "CPF" ou "CNPJ".	—
`user.contract`	`object`	Obrigatório. Objeto que deverá conter informações sobre o contrato de crédito do titular do cartão.	—
`user.contract.id`	`string`	Obrigatório. Identificador único do contrato, o qual pode ser um número de proposta, contrato etc. relativo ao produto que o cliente do parceiro contratou.	—
`user.contract.type`	`string`	Obrigatório. Tipo de contrato, que pode ser "Credit" ou "Debit".	—
`product`	`object`	Obrigatório. Objeto que deverá conter informações sobre o produto contratado que será cobrado de forma recorrente.	—
`product.id`	`string`	Obrigatório. Identificador único do contrato do produto.	—
`product.type`	`string`	Obrigatório. Tipo do produto que será cobrado.	—
`product.description`	`string`	Obrigatório. Descrição do produto. Essa mensagem será apresentada na postagem da cobrança.	—
`product.transactionType`	`string`	Obrigatório. Código da transação.	—

{ 
       "hiringDate": "2024-01-01", 
       "billingType": "", 
       "recurrency": { 
         "postDate": 4, 
         "mustChargeOnHiringDate": false, 
         "frequency": "ANNUALY", 
         "quantity": 12, 
         "amount": { 
         "value": 101.5, 
         "currency": "BRL" 
       }, 
       "discount": { 
         "value": 2.00, 
         "currency": "BRL" 
       }, 
       "chargeOptions": { 
         "forceLimit": false, 
         "blockedAccount": false
         } 
       }, 
       "user": { 
         "documentNumber": { 
         "value": "47742663023", 
         "type": "CPF" 
       }, 
       "contract": { 
         "id": "12345678", 
         "type": "Credit" 
       } 
       }, 
       "product": { 
         "id": "1234", 
         "type": "Seguros", 
         "description": "Seguro Auto", 
         "transactionType": "SEGUROS_DEB" 
       } 
     }

Possíveis códigos de transação

`transactionType`	Descrição
SEGUROS_DEB	Identificador de uma cobrança recorrente de seguros que gera débito na fatura.
SEGUROS_CRED	Identificador de um estorno de cobrança recorrente de seguros.

Resposta (Response)

O status code 201 indicará que a solicitação foi aceita e o agendamento de recorrência da cobrança foi criado.

Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:

Nome	Tipo	Descrição	Número máximo de caracteres
`value`	`object`	Objeto que contém informações sobre a recorrência agendada.	—
`value.code`	`string`	Código personalizado da mensagem de sucesso.	—
`value.message`	`string`	Descrição do código de sucesso.	—
`value.recurrencyId`	`string`	Identificador único da recorrência agendada. Importante: o parceiro deve armazenar essa informação, pois ela poderá ser utilizada para atualizações e cancelamentos de recorrências.	—
`value.productType`	`string`	Descrição do produto enviado na requisição.	—

{    
  "value": { 
    "code": "RECURRENCY_CREATED", 
    "message": "Recurrency created successfully.", 
    "recurrencyId": "COMPANY_KEY-edd874f6-6f00-4984-aa76-e50dabdba8a5", 
    "productType": "Seguros"
  } 
}

👍
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.

Erros

Este endpoint pode retornar erros específicos, conforme a tabela a seguir:

Status Code	Código	Mensagem	Descrição
400	REQUEST_VALIDATION_ERROR	'{parâmetro}' must not be empty	O campo não pode ser enviado vazio. O parâmetro entre chaves pode ser referente aos campos: `hiringDate` , `user.documentNumber.value`, `user.documentNumber.type`, `user.contract.id`, `user.contract.type`, `product.id`, `product.type`, `product.description` e `product.transactionType`.
400	REQUEST_VALIDATION_ERROR	'{parâmetro}' must be true or false	O valor do campo deve ser True ou False. O parâmetro entre chaves pode ser referente aos campos: `recurrency.mustChargeOnHiringDate` , `recurrency.chargeOptions.forceLimit` e `recurrency.chargeOptions.blockedAccount`.
400	REQUEST_VALIDATION_ERROR	'{parâmetro}' must be greater than 0	O valor desse campo não pode ser igual a 0. O parâmetro entre chaves pode ser referente aos campos: `recurrency.postDate`, `recurrency.quantity` e `recurrency.amount.value`.
400	REQUEST_VALIDATION_ERROR	'recurrency.amount.currency' must be 'BRL' or 'USD’	A moeda do valor da cobrança deve ser BRL ou USD.
400	REQUEST_VALIDATION_ERROR	'recurrency.frequency' must be 'ANNUALY', 'MONTHLY' or 'WEEKLY’	Informe uma frequência válida: ANNUALLY, MONTHLY ou WEEKLY.
406	CARD_NOT_ACTIVE	The requested card is not active.	O cartão informado não está ativo.

Válido lembrar que a API também poderá retornar erros comuns entre todos os endpoints.

Eventos

Este endpoint não possui eventos relacionados a ele.