Criar agendamento único

Este endpoint permite que o usuário pagador possa criar um agendamento de um pagamento.

Requisição (Request)

Requisição HTTP

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

curl --request POST \
     --url https://api-mtls.sandbox.bankly.com.br/pix/scheduling-payments \
     --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 um agendamento de pagamento. testeste

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.	`^([0-9]{11}\|[A-Z0-9]{12}[0-9]{2})$`

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
`initiationForm`	`string`	Obrigatório: Forma de iniciação do agendamento	`DICT` - pagamento por chave Pix `MANU` - pagamento por inserção manual dos dados da conta transacional do usuário recebedor `QRDN` - pagamento por QR code dinâmico na modalidade de cobrança com vencimento `QRES` - pagamento por QR code estático
`transactionIdentification`	`string`	Identificador único da transação, utilizado no processo de conciliação de pagamentos. Nele, deve ser informado o valor do `conciliationId` retornado na leitura do QR Code. Obrigatório quando `initiationForm` for `QRDN` e opcional quando `initiationForm` = `QRES`	`initiationForm` = `QRES`: Deve conter até 25 caracteres alfanuméricos ([A-Za-z0-9]). `initiationForm` = `QRDN`: preenchimento obrigatório com o valor do payload JSON do QR Code dinâmico, contendo entre 26 e 35 caracteres alfanuméricos ([A-Za-z0-9]).
`interbankSettlementAmount`	`number`	Obrigatório: Valor do agendamento.	`\d{1,16}.\d{2}`
`requestDateTime`	`datetime`	Obrigatório: Data e hora que o usuário solicitou o agendamento.	Exemplo: `2026-02-10T16:41:47.191Z`
`dateSchedule`	`date`	Obrigatório: Data do agendamento. Este campo deve ser preenchido com no mínimo D+1.	`yyyy-MM-dd`
`endToEndId`	`string`	Identificador fim-a-fim do agendamento. Obrigatório quando `initiationForm` for igual a `DICT` , `QRDN` ou `QRES`. `initiationForm` = `MANU` o campo deverá ser nulo.	`[a-zA-Z0-9]{32}` `ExxxxxxxxyyyyMMddHHmmkkkkkkkkkkk`
`creditor`	`objeto`	Dados da conta recebedora. Obrigatório somente quando `initiationForm` for igual a `MANU`. Quando `initiationForm` for igual a `DICT` , `QRDN` ou `QRES` o campo deverá ser nulo.
`creditor.accountIdentification`	`string`	Conta do cliente recebedor. Obrigatório somente quando `initiationForm` for igual a `MANU`.	`^[0-9]{1,20}$`
`creditor.accountIssuer`	`string`	Agência do usuário recebedor sem dígito verificador. Obrigatório somente quando `initiationForm` for igual a `MANU`.	`^[0-9]{1,4}$`
`creditor.accountType`	`string`	Tipo de conta transacional do usuário recebedor. Obrigatório somente quando `initiationForm` for igual a `MANU`.	`CACC` - Conta Corrente `TRAN` - Conta de Pagamento `SVGS` - Conta Poupança
`creditor.agentMemberIdentification`	`string`	ISPB do banco do cliente recebedor. Obrigatório somente quando `initiationForm` for igual a `MANU`.	`^[0-9]{8}$`
`creditor.name`	`string`	Nome do recebedor. Obrigatório somente quando `initiationForm` for igual a `MANU`.	`<= 140 caracteres`
`creditor.privateIdentification`	`string`	CPF ou CNPJ do cliente recebedor. Obrigatório somente quando `initiationForm` for igual a `MANU`.	`^([0-9]{11}\|[A-Z0-9]{12}[0-9]{2})$`
`debtor`	`objeto`	Obrigatório: Dados da conta pagadora.
`debtor.accountIdentification`	`string`	Obrigatório: Conta do cliente pagador.	`^[0-9]{1,20}$`
`debtor.accountIssuer`	`string`	Obrigatório: Agência do cliente pagador.	`^[0-9]{1,4}$`
`debtor.accountType`	`string`	Obrigatório: Tipo de conta pagadora.	`CACC` - Conta Corrente `TRAN` - Conta de Pagamento `SVGS` - Conta Poupança
`debtor.name`	`string`	Obrigatório: Nome do pagador.	`<= 140 caracteres`
`debtor.privateIdentification`	`string`	Obrigatório: CPF ou CNPJ do cliente pagador.	`^([0-9]{11}\|[A-Z0-9]{12}[0-9]{2})$`
`remittanceInformation`	`string`	Obrigatório: Informações do usuário pagador para o usuário recebedor.	`<= 140 caracteres`

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
`requestIdentifier`	`string`	Identificador do agendamento.
`message`	`string`	Mensagem de sucesso.

{
  "requestIdentifier": "E9999901012341234123412345678900",
  "message": "Agendamento cadastrado com sucesso"
}

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

Erros

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 consulta de chave associada a este EndToEndId foi encontrada.
422	INCORRECT_END_TO_END_ID_OR_INITIATION_FORM	EndToEndId with this InitiationForm not found.	EndToEndId com o InitiationForm informado não foi encontrado.
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.

Updated 2 months ago

Did this page help you?