Criar recorrência de agendamento

Este endpoint permite que o usuário pagador possa criar uma recorrência de agendamentos.

Requisição (Request)

Requisição HTTP

POST https://api-mtls.sandbox.bankly.com.br/pix/scheduling-payments/recurrences

curl --request POST \
     --url https://api-mtls.sandbox.bankly.com.br/pix/scheduling-payments/recurrences \
     --header 'accept: application/json' \
     --header 'api-version: 1' \
     --header 'content-type: application/json'

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
`pix.schedule-payment.write`	Concede acesso para criar uma recorrência de agendamento.

Cabeçalhos (Headers)

Nome	Descrição	Especificação
`api-version`	Obrigatório. Versão da API. Atualmente estamos na versão 1.	—
`Authorization`	Obrigatório. Token de autorização do tipo Bearer.	—
`x-bkly-pix-user-id`	Obrigatório. Número do documento do usuário que está fazendo a requisição.	Informe somente números.

Parâmetros da rota (Path)

Não é necessário enviar campos no path desta requisição.

Corpo da requisição (Body)

No body, envie o seguinte campo em formato JSON:

Nome	Tipo	Descrição	Especificação
`requestDateTime`	`datetime`	Obrigatório: Data e hora que o usuário solicitou o agendamento.	Exemplo: `2026-02-11T16:50:08.243Z`
`payment`	`objeto`	Objeto que contem os dados do pagamento.
`payment.endToEndId`	`string`	Identificador fim-a-fim do agendamento. Obrigatório quando `initiationForm` for igual a `DICT`. Quando `initiationForm` for igual a `MANU` o campo devera ser nulo.	`[a-zA-Z0-9]{32}` `ExxxxxxxxyyyyMMddHHmmkkkkkkkkkkk`
`payment.initiationForm`	`string`	Obrigatório: Forma de iniciação do agendamento de recorrência.	`DICT` - pagamento por chave Pix `MANU` - pagamento por inserção manual dos dados da conta transacional do usuário recebedor
`payment.interbankSettlementAmount`	`number`	Obrigatório: Valor do agendamento da recorrência.	`\d{1,16}\.\d{2}`
`payment.remittanceInformation`	`string`	Informações do usuário pagador para o usuário recebedor.	`<= 140 caracteres`
`payment.creditor`	`objeto`	Objeto que contem os dados da conta recebedora. Obrigatório somente quando `initiationForm` for igual a `MANU`. Quando `initiationForm` for igual a `DICT` devera ser nulo.
`payment.creditor.accountIdentification`	`string`	Conta do cliente recebedor. Obrigatório somente quando `initiationForm` for igual a `MANU`.	`^[0-9]{1,20}$`
`payment.creditor.accountIssuer`	`string`	Agência do cliente recebedor sem dígito verificador. Obrigatório somente quando `initiationForm` for igual a `MANU`.	`^[0-9]{1,4}$`
`payment.creditor.accountType`	`string`	Tipo de conta. Obrigatório somente quando `initiationForm` for igual a `MANU`.	`CACC` - Conta Corrente `TRAN` - Conta de Pagamento `SVGS` - Conta Poupança
`payment.creditor.agentMemberIdentification`	`string`	ISPB do banco do cliente recebedor. Obrigatório somente quando `initiationForm` for igual a `MANU`.	`^[0-9]{8}$`
`payment.creditor.name`	`string`	Nome do recebedor. Obrigatório somente quando `initiationForm` for igual a `MANU`.	`<= 140 caracteres`
`payment.creditor.privateIdentification`	`string`	CPF ou CNPJ do cliente recebedor. Obrigatório somente quando `initiationForm` for igual a `MANU`.	`([0-9]{11}\|[0-9]{14})`
`payment.debtor`	`objeto`	Obrigatório: Objeto que contem os dados da conta pagadora.
`payment.debtor.accountIdentification`	`string`	Obrigatório: Conta do cliente pagador.	`^[0-9]{1,20}$`
`payment.debtor.accountIssuer`	`string`	Obrigatório: Agência do cliente pagador.	`^[0-9]{1,4}$`
`payment.debtor.accountType`	`string`	Obrigatório: Tipo de conta pagadora.	`CACC` - Conta Corrente `TRAN` - Conta de Pagamento `SVGS` - Conta Poupança
`payment.debtor.name`	`string`	Obrigatório: Nome do pagador.	`<= 140 caracteres`
`payment.debtor.privateIdentification`	`string`	Obrigatório: CPF ou CNPJ do cliente pagador.	`([0-9]{11}\|[0-9]{14})`
`recurrence`	`objeto`	Obrigatório: Objeto que contem os dados da recorrência.
`recurrence.frequency`	`string`	Obrigatório: Frequência da recorrência.	`WEEKLY` - Semanal `MONTHLY` - Mensal `YEARLY` - Anual
`recurrence.initialDateSchedule`	`date`	Obrigatório: Data de início da recorrência, ou seja, data do primeiro pagamento agendado.	`yyyy-MM-dd`
`recurrence.finalDateSchedule`	`date`	Data de fim da recorrência, ou seja, data do último agendamento. Não deve ser preenchido simultaneamente ao campo `recurrence.repetition`	`yyyy-MM-dd`
`recurrence.repetition`	`number`	Quantidade de repetições da recorrência Não deve ser preenchido simultaneamente ao campo `recurrence.finalDateSchedule`	`>=2`
`recurrence.description`	`string`	Descrição da recorrência.	`<= 140 caracteres`
`recurrence.invalidDatePayment`	`string`	Indica se o agendamento deve ser antecipado ou postergado em caso de data inexistente (ex. dias 29 e 31).	ENUM: `ANTICIPATE` `POSTPONE`

Resposta (Response)

O status code 201 indicará sucesso na criação do agendamento.

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

Nome	Tipo	Descrição
`recurrence`	`objeto`	Objeto que contem os dados da recorrência.
`recurrence.requestIdentifier`	`string`	Identificador da recorrência.
`message`	`string`	Mensagem de sucesso.

{
  "recurrence": {
    "requestIdentifier": "R1314008820250926102859521EET8W2KAYM"
  },
  "message": "Solicitação de recorrência recebida com sucesso"
}

👍
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	INVALID_PARAMETER		Algum parâmetro não foi informado corretamente.
403	INVALID_LICENSE	Invalid license.	A licença informada está fora do padrão ou não existe.
422	RECURRENCE_REPROVED	The recurrence request could not be processed.	A solicitação de recorrência não pôde ser processada.
422	BUSINESS_RULE_VIOLATED	A mensagem a ser retornada está na tabela abaixo.	Este erro pode retornar por vários motivos. Os motivos estarão descritos no campo "`messages`"
422	END_TO_END_ID_NOT_FOUND	No decode or entry request associated with this EndToEndId was found.	Nenhuma solicitação de decodificação ou entrada associada a este EndToEndId foi encontrada.
500	UNEXPECTED_ERROR	An unexpected result occurred during the operation	Ocorreu um erro inesperado.
503	SERVICE_UNAVAILABLE	Service unavailable.

`code`	`messages`
`BUSINESS_RULE_VIOLATED`	"Infelizmente, não foi possível aprovar a solicitação (Motivo: o campo recurrence.requestIdentifier já existe"
`BUSINESS_RULE_VIOLATED`	"Infelizmente não foi possível aprovar a solicitação (Motivo: transação não concluída. Erro de processamento"

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400 (se houver).

Eventos

Este endpoint não possui eventos relacionados a ele.