Autorização de Pix automático

Este endpoint permite ao usuário pagador autorizar ou rejeitar uma solicitação de recorrência de pagamento via Pix Automático. A operação atualiza o status da autorização associada ao identificador informado (idRecurrence), registrando a decisão tomada pelo usuário dentro do fluxo de consentimento do Pix Automático.

Requisição (Request)

Requisição HTTP

PATCH  https://api-mtls.sandbox.bankly.com.br/pix/recurring-payments/{idRecurrence}/confirm

curl --request PATCH \
--url https://api-mtls.sandbox.bankly.com.br/pix/recurring-payments/1234566/confirm \
--header 'Authorization: bearer' \
--header 'accept: application/json' \
--header 'api-version: 1' \
--header 'content-type: application/json' \
--header 'x-bkly-pix-user-id: 123456789' \
--header 'x-correlation-id: haseher-2414n-bnjk2-213jl' \
--data '
{
  "accepted": true,
  "authorizationType": "AUT3",
  "amount": {
    "fixedValue": "300",
    "minimumValue": "250",
    "maximumValue": "300"
  },
  "creditor": {
    "agentMemberIdentification": "12345678",
    "name": "Nísia Floresta",
    "privateIdentification": "2340414387"
  },
  "debtor": {
    "accountIdentification": "1111309",
    "accountIssuer": "0001",
    "agentMemberIdentification": "111111123",
    "cityCode": "5300108",
    "name": "Maria Firmina da Silva",
    "privateIdentification": "123456789"
  },
  "originalDebtor": {
    "name": "Maria Firmina da Silva",
    "privateIdentification": "1234245245"
  },
  "retryPolicy": "ALLOW_3R_7D",
  "recurrenceCreationDateTime": "2025-01-01",
  "endToEndId": "1235467558679",
  "scheduledPayment": true,
  "contractNumber": "123456789",
  "description": "Streamming",
  "frequencyType": "MNTH",
  "initialDateRecurrence": "2025-02-01",
  "finalDateRecurrence": "2026-02-01"
}
'

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.recurrence-payment-auth.write`	Concede acesso para solicitar a autorização de recorrência de um pagamento via Pix automático.

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.
`x-correlation-id`	Obrigatório. Identificador de correlação da requisição.	Formato GUID v4. A cada requisição, deve-se gerar um novo GUID.

Parâmetros da rota (Path)

No path desta requisição envie os seguintes campos:

Nome	Tipo	Descrição
`idRecurrence`	`path`	Obrigatório. Identificador único da recorrência.

Corpo da requisição (Body)

No body, envie o seguinte campo em formato JSON:

Nome	Tipo	Descrição
`accepted`	`boolean`	*Obrigatório*. Indicador de aceite (true) ou rejeição (false) da autorização.
`authorizationType`	`string`	*Obrigatório*. Tipo da jornada da autorização, a qual pode ser: "AUT1", "AUT2", "AUT3" ou "AUT4". Para mais detalhes sobre o tipo de jornada, consulte a documentação Pix automático.
`recurrenceCreationDateTime`	`string`	Data da criação da recorrência. Deve ser preenchido somente quando campo `authorizationType` for "AUT2", "AUT3" ou "AUT4"
`amount`	`object`	Objeto que deve conter os dados referentes ao valor do pagamento recorrente.
`amount.fixedValue`	`string`	Valor fixo configurado para a recorrência. Retornado somente quando a autorização utiliza um modelo de valor fixo (`authorizationType` seja igual a "AUT2", "AUT3" ou "AUT4"). Não é retornado em autorizações com valores variáveis. O Formato é uma string que representa um decimal com duas casas após a vírgula.
`amount.minimumValue`	`string`	Valor mínimo que pode ser debitado a cada pagamento efetuado sob a autorização correspondente. O valor mínimo definido pelo usuário recebedor pode ser limitado pelo valor máximo estabelecido a critério do usuário pagador. Não se aplica para recorrências com valor fixo. O Formato é uma string que representa um decimal com duas casas após a vírgula.
`amount.maximumValue`	`string`	Valor máximo permitido para cada débito da recorrência quando a autorização usa valores variáveis. Pode ser limitado pelo valor mínimo definido pelo usuário recebedor. Não se aplica a autorizações de valor fixo. O Formato é uma string que representa um decimal com duas casas após a vírgula.
`retryPolicy`	`string`	Política de retentativa de pagamento após vencimento da recorrência, a qual pode ser ALLOW_3R_7D ou DOES_NOT_ALLOW. Deve ser preenchido somente quando campo `authorizationType`for "AUT2", "AUT3" ou "AUT4"
`creditor`	`object`	Objeto que deve conter os dados do recebedor da recorrência de pagamento.
`creditor.agentMemberIdentification`	`string`	ISPB do banco do recebedor. Deve ser preenchido somente somente quando o campo `authorizationType` apresentar valor "AUT2", "AUT3" ou "AUT4".
`creditor.name`	`string`	Nome do recebedor. Deve ser preenchido somente quando o campo `authorizationType` apresentar valor "AUT2", "AUT3" ou "AUT4".
`creditor.privateIdentification`	`string`	CNPJ do cliente recebedor. Deve ser preenchido somente quando o campo `authorizationType` apresentar valor "AUT2", "AUT3" ou "AUT4".
`debtor`	`object`	Obrigatório. Objeto que deve conter os dados do pagador da recorrência de pagamento.
`debtor.accountIdentification`	`string`	Obrigatório. Número da conta do cliente pagador.
`debtor.accountIssuer`	`string`	Obrigatório. Agência do cliente pagador.
`debtor.agentMemberIdentification`	`string`	Obrigatório. ISPB do banco do cliente pagador.
`debtor.cityCode`	`string`	Código de município do usuário pagador no IBGE. Deve ser preenchido sempre que a autorização for aceita (`accepted`= true)
`debtor.name`	`string`	Obrigatório. Nome do pagador.
`debtor.privateIdentification`	`string`	Obrigatório. CPF ou CNPJ do cliente pagador.
`originalDebtor`	`object`	Objeto que deve conter os dados do usuário devedor da recorrência de pagamento.
`originalDebtor.name`	`string`	Nome do usuário devedor. Deve ser preenchido somente quando o campo `authorizationType` apresentar valor "AUT2", "AUT3" ou "AUT4".
`originalDebtor.privateIdentification`	`string`	CPF ou CNPJ do usuário devedor. Deve ser preenchido somente quando o campo `authorizationType` apresentar valor "AUT2", "AUT3" ou "AUT4".
`endToEndId`	`string`	Identificador do pagamento imediato ou do agendamento. Deverá ser enviado somente quando o campo `authorizationType` apresentar valor "AUT3" ou "AUT4".
`scheduledPayment`	`boolean`	Indica se é um pagamento agendado ou não. Deve ser preenchido somente na jornada 4.
`contractNumber`	`string`	Número de contrato referente à recorrência. Deve ser preenchido somente quando o campo `authorizationType` apresentar valor "AUT2", "AUT3" ou "AUT4".
`description`	`string`	Descrição do serviço/produto associado à recorrência. Deve ser preenchido somente quando o campo `authorizationType` apresentar valor "AUT2", "AUT3" ou "AUT4".
`frequencyType`	`string`	Periodicidade do pagamento recorrente via Pix automático, a qual pode ser WEEK (semanal), MNTH (mensal), QURT (trimestral), MIAN (semestral) e YEAR (anual). Deve ser preenchido somente quando o campo `authorizationType` apresentar valor "AUT2", "AUT3" ou "AUT4".
`initialDateRecurrence`	`string`	Data prevista do primeiro pagamento. Deve ser preenchido somente quando o campo `authorizationType` apresentar valor "AUT2", "AUT3" ou "AUT4".
`finalDateRecurrence`	`string`	Data prevista do último pagamento. Deve ser preenchido somente quando o campo `authorizationType` apresentar valor "AUT2", "AUT3" ou "AUT4".
`rejectReason`	`string`	Motivo de rejeição de uma autorização, que pode ser AP13 (não reconhecido pelo debitante) ou AP14 (rejeitado pelo debitante). Deve ser preenchido somente quando o campo `authorizationType` apresentar valor "AUT1".

{
  "accepted": true,
  "authorizationType": "AUT1",
  "amount": {
    "maximumValue": "100.25"
  },
  "debtor": {
    "name": "Nome do Pagador",
    "accountIdentification": "1111108",
    "accountIssuer": "0001",
    "agentMemberIdentification": "11111111",
    "privateIdentification": "23933333316",
    "cityCode": "5300108"
  }
}

{
  "accepted": false,
  "authorizationType": "AUT1",
  "debtor": {
    "name": "Nome do Pagador",
    "accountIdentification": "1111108",
    "accountIssuer": "0001",
    "agentMemberIdentification": "11111111",
    "privateIdentification": "23933333316"
  },
  "rejectReason": "AP13"
}

{
  "accepted": true,
  "authorizationType": "AUT2",
  "recurrenceCreationDateTime": "2024-04-30T12:57:00.480Z",
  "amount": {
    "fixedValue": "100.00",
    "maximumValue": "100.25"
  },
  "creditor": {
    "name": "Nome da Empresa",
    "privateIdentification": "12822222215001",
    "agentMemberIdentification": "22222222"
  },
  "debtor": {
    "name": "Nome do Pagador",
    "accountIdentification": "1111108",
    "accountIssuer": "0001",
    "agentMemberIdentification": "11111111",
    "privateIdentification": "23933333316",
    "cityCode": "5300108"
  },
  "originalDebtor": {
    "name": "Nome da Empresa",
    "privateIdentification": "02822222215"
  },
  "contractNumber": "1234567890",
  "description": "Descrição",
  "frequencyType": "MNTH",
  "initialDateRecurrence": "2024-05-03",
  "finalDateRecurrence": "2025-05-03",
  "endToEndId": "E5958811120200623194907049RDQQ5Z",
  "retryPolicy": "ALLOW_3R_7D"
}

{
  "accepted": true,
  "authorizationType": "AUT3",
  "amount": {
    "fixedValue": "100.00",
    "maximumValue": "100.25"
  },
  "creditor": {
    "name": "Nome da Empresa",
    "privateIdentification": "12822222215001",
    "agentMemberIdentification": "22222222"
  },
  "debtor": {
    "name": "Nome do Pagador",
    "accountIdentification": "1111108",
    "accountIssuer": "0001",
    "agentMemberIdentification": "11111111",
    "privateIdentification": "23933333316",
    "cityCode": "5300108"
  },
  "recurrenceCreationDateTime": "2024-04-30T12:57:00.480Z",
  "originalDebtor": {
    "name": "Nome da Empresa",
    "privateIdentification": "02822222215"
  },
  "contractNumber": "1234567890",
  "description": "Descrição",
  "frequencyType": "MNTH",
  "initialDateRecurrence": "2024-05-03",
  "finalDateRecurrence": "2025-05-03",
  "endToEndId": "E5958811120200623194907049RDQQ5Z",
  "retryPolicy": "ALLOW_3R_7D"
}

{
  "accepted": true,
  "authorizationType": "AUT4",
  "recurrenceCreationDateTime": "2024-04-30T12:57:00.480Z",
  "amount": {
    "fixedValue": "100.00",
    "maximumValue": "100.25"
  },
  "creditor": {
    "name": "Nome Empresa A",
    "privateIdentification": "28333333150443",
    "agentMemberIdentification": "22222222"
  },
  "debtor": {
    "name": "Nome do Pagador",
    "accountIdentification": "1111109",
    "accountIssuer": "0001",
    "agentMemberIdentification": "11111111",
    "privateIdentification": "23933333316",
    "cityCode": "5300108"
  },
  "originalDebtor": {
    "name": "Nome Empresa B",
    "privateIdentification": "02822222215"
  },
  "contractNumber": "1234567890",
  "description": "Descrição",
  "frequencyType": "MNTH",
  "initialDateRecurrence": "2024-05-03",
  "endToEndId": "E5958811120200623194907049RDQQ5Z",
  "scheduledPayment": true,
  "retryPolicy": "ALLOW_3R_7D"
}

Resposta (Response)

O status code 202 indicará que a requisição foi aceita e está sendo processada.

👍
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	AUTHORIZATION_REPROVED	Authorization request was not approved.	A solicitação de autorização do Pix Automático não pôde ser aprovada.
404			A notificação de recorrência não está vinculada ao CPF/CNPJ do usuário informado no x-bkly-pix-user-id e CompanyKey do token.
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`"
500	UNEXPECTED_ERROR	An unexpected result occurred during the operation	Ocorreu um erro inesperado.
500	PROCESSING_ERROR	Processing error.
503	SERVICE_UNAVAILABLE	Service unavailable.

`code`	`messages`
`BUSINESS_RULE_VIOLATED`	"O valor máximo definido para os pagamentos desta autorização não pode ser menor que o valor mínimo estabelecido pelo recebedor"
`BUSINESS_RULE_VIOLATED`	"Não é necessário realizar registro interno e envio para o bacen na rejeição de recorrência nas jornadas AUT2, AUT3 ou AUT4"
`BUSINESS_RULE_VIOLATED`	"Inconsistência com a solicitação de recorrência registrada em base, valor máximo não é permitido quando for indicado pelo recebedor um valor fixo"
`BUSINESS_RULE_VIOLATED`	"Campo `maximumValue`deverá ser maior que 0,00"
`BUSINESS_RULE_VIOLATED`	"Não é permitido enviar `maximumValue` em solicitações com accepted = false."
`BUSINESS_RULE_VIOLATED`	"Não é necessário envio do campo X na jornada AUT1", sendo X o nome do campo
`BUSINESS_RULE_VIOLATED`	"Esse ID de recorrência já foi aprovado em outra jornada"
`BUSINESS_RULE_VIOLATED`	"Não é permitida a utilização da conta-salário para a realização das cobranças recorrentes no pix automático"
`BUSINESS_RULE_VIOLATED`	"Pagamento imediato não efetivado com sucesso"
`BUSINESS_RULE_VIOLATED`	"Identificador do pagamento não encontrado"
`BUSINESS_RULE_VIOLATED`	"Identificador do agendamento não encontrado"
`BUSINESS_RULE_VIOLATED`	"Jornada indicada não deve estar atrelado a um pagamento imediato ou agendamento na etapa de autorização"
`BUSINESS_RULE_VIOLATED`	"Status da solicitação de recorrência deverá estar em pendente"
`BUSINESS_RULE_VIOLATED`	"Campo X - Campo X deverá ser preenchido com formatação correta", Sendo X o nome do campo
`BUSINESS_RULE_VIOLATED`	"Campo X - Preenchimento do campo X é obrigatório", sendo X o nome do campo obrigatório

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

Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. Os eventos são:

Nome do evento	Descrição
`PIX_RECURRENCE_PENDING_REQUEST_AUTH_CONFIRM`	A autorização para a recorrência de pagamento via Pix automático está pendente de confirmação.
`PIX_RECURRENCE_AUTH_WAS_CONFIRMED`	A autorização para a recorrência de pagamento via Pix automático foi confirmada/rejeitada.
`PIX_RECURRENCE_AUTH_REQUEST_WAS_CANCELED`	A autorização para a recorrência de pagamento via Pix automático foi cancelada.
`PIX_RECURRENCE_PENDING_REQUEST_AUTH_CONFIRM_DEADLINE_TODAY`	Último dia para autorizar uma recorrência de pagamento via Pix automático.