Consulta de Solicitação de Autorização de Recorrência

Este endpoint permite realizar a consulta de uma ou mais autorizações de recorrência de Pix automático.

Requisição (Request)

Requisição HTTP

GET https://api-mtls.sandbox.bankly.com.br/pix/recurring-payments

--request GET \
--url 'https://api-mtls.sandbox.bankly.com.br/pix/recurring-payments?InitialDate=2025-01-01&FinalDate=2025-03-01&IdRecurrence=12345&ContractNumber=54321&Status=PENDING&Page=1&PageSize=100' \
--header 'accept: application/json' \
--header 'api-version: 1' \
--header 'x-bkly-pix-user-id: 2345b6uwaiyr98cn12988' \
--header 'x-correlation-id: 3298cn190-w222n7-240jirY0239'

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.read`	Concede acesso para consultar autorizações de pagamentos recorrentes 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.	`^([0-9]{11}\|[A-Z0-9]{12}[0-9]{2})$`
`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	Especificação
`initialDate`	`query`	Data de início do período para a busca das solicitações de autorização de recorrência.	Formato YYYY-MM-DD.
`finalDate`	`query`	Data de fim do período para a busca das solicitações de autorização de recorrência.	Formato YYYY-MM-DD.
`idRecurrence`	`query`	Identificador da recorrência.
Quando informado, os demais filtros de consulta (datas, status, paginação etc.)
são ignorados. Pode ser usado em conjunto com `contractNumber`.	—
`contractNumber`	`query`	Número do contrato associado à recorrência.
Quando informado, os demais filtros de consulta (datas, status, paginação etc.)
são ignorados. Pode ser usado em conjunto com `idRecurrence`.	—
`status`	`query`	Situação da recorrência.	Enum: `PENDING`, `APPROVED`, `CANCELED`, `EXPIRED`, `REJECTED`, `ERROR`, `COMPLETED`
`page`	`query`	Número da página que deseja consultar.	Valor mínimo 1.
`pageSize`	`query`	Quantidade de registros retornados por página.	Valor máximo 100.

Corpo da requisição (Body)

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

Resposta (Response)

O status code 200 indicará sucesso na consulta.

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

Nome	Obrigatoriedade	Tipo	Descrição
`idRecurrence`	`Obrigatório`	`string`	Identificador da recorrência.
`pagination`	`Obrigatório`	`object`	Objeto que contém os dados das páginas consultadas.
`pagination.page`	`Obrigatório`	`number`	Número da página atual.
`pagination.pageSize`	`Obrigatório`	`number`	Tamanho da página.
`pagination.totalPages`	`Obrigatório`	`number`	Total de páginas.
`pagination.totalItems`	`Obrigatório`	`number`	Total de itens disponíveis de acordo com os parâmetros informados.
`items`	`Obrigatório`	`object`	Objeto que contém a descrição dos itens da recorrência de pagamento.
`items.agents`	`Obrigatório`	`object`	Objeto que contém os dados de todos os agentes da consulta.
`items.agents.debtor`	`Obrigatório`	`object`	Objeto que contém os dados do cliente pagador da recorrência de pagamento.
`items.agents.debtor.accountIdentification`	`Obrigatório`	`string`	Conta do cliente pagador.
`items.agents.debtor.accountIssuer`	`Obrigatório`	`string`	Agência do cliente pagador.
`items.agents.debtor.agentMemberIdentification`	`Obrigatório`	`string`	ISPB do banco do cliente pagador.
`items.agents.debtor.cityCode`	`Opcional`	`string`	Código de município do usuário pagador no IBGE.
`items.agents.debtor.name`	`Obrigatório`	`string`	Nome do pagador.
`items.agents.debtor.privateIdentification`	`Obrigatório`	`string`	CPF ou CNPJ do cliente pagador.
`items.agents.originalDebtor`	`Opcional`	`object`	Objeto que contém os dados do usuário devedor da recorrência de pagamento.
`items.agents.originalDebtor.name`	`Opcional`	`string`	Nome do usuário devedor. Será retornado somente quando o campo `authorizationType` apresentar valor "AUT2", "AUT3" ou "AUT4".
`items.agents.originalDebtor.privateIdentification`	`Opcional`	`string`	CPF ou CNPJ do usuário devedor. Será retornado somente quando o campo `authorizationType` apresentar valor "AUT2", "AUT3" ou "AUT4".
`items.agents.creditor`	`Obrigatório`	`object`	Objeto que contém os dados do recebedor da recorrência de pagamento.
`items.agents.creditor.agentMemberIdentification`	`Obrigatório`	`string`	ISPB do banco do recebedor. Será retornado somente somente quando o campo `authorizationType` apresentar valor "AUT2", "AUT3" ou "AUT4".
`items.agents.creditor.name`	`Obrigatório`	`string`	Nome do recebedor. Será retornado somente quando o campo `authorizationType` apresentar valor "AUT2", "AUT3" ou "AUT4".
`items.agents.creditor.privateIdentification`	`Obrigatório`	`string`	CNPJ do cliente recebedor. Será retornado somente quando o campo `authorizationType` apresentar valor "AUT2", "AUT3" ou "AUT4".
`items.amount`	`Opcional`	`object`	Objeto que contém os dados referentes ao valor do pagamento recorrente.
`items.amount.fixedValue`	`Opcional`	`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.
`items.amount.minimumValue`	`Opcional`	`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 pagador pode ser limitado pelo valor máximo estabelecido a critério do usuário recebedor. 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.
`items.amount.maximumValue`	`Opcional`	`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.
`items.amount.currency`	`Obrigatório`	`string`	Tipo de moeda. Value: "BRL"
`items.calendar`	`Opcional`	`object`	Objeto que contém informações referentes às datas e periodicidade do pagamento.
`items.calendar.initialDate`	`Opcional`	`string`	Data do primeiro pagamento.
`items.calendar.finalDate`	`Opcional`	`string`	Data do último pagamento.
`items.calendar.frequency`	`Opcional`	`string`	Frequência da recorrência de pagamento, a qual pode ser pode ser WEEK (semanal), MNTH (mensal), QURT (trimestral), MIAN (semestral) e YEAR (anual).
`items.contractNumber`	`Opcional`	`string`	Número de contrato referente à recorrência.
`items.status`	`Obrigatório`	`string`	Status da autorização da recorrência de pagamento.
`items.description`	`Opcional`	`string`	Descrição do serviço/produto associado à recorrência.
`items.authorization`	`Obrigatório`	`object`	Objeto que contém dados da autorização da recorrência de pagamento.
`items.authorizationType`	`Obrigatório`	`string`	Tipo da jornada da autorização, que pode ser "AUT1", "AUT2", "AUT3" ou "AUT4".
`items.authorization.authorizationDateTime`	`Obrigatório`	`string`	Data de criação da autorização.
`items.rejectReason`	`Opcional`	`string`	Motivo de rejeição de uma autorização, que pode ser AP13 (não reconhecido pelo debitante) ou AP14 (rejeitado pelo debitante).
`items.retryPolicy`	`Opcional`	`string`	Política de retentativa de pagamento após vencimento da recorrência, a qual pode ser ALLOW_3R_7D ou DOES_NOT_ALLOW.
`items.endToEndId`	`Opcional`	`string`	Identificador de pagamento vinculado ao QR code composto. Retornará somente quando o campo `authorizationType` apresentar valor "AUT3" ou "AUT4".
`items.expirationDateTime`	`Obrigatório`	`string`	Data de expiração da recorrência de pagamento.
`items.recurrenceCreationDateTime`	`Obrigatório`	`string`	Data de criação da recorrência de pagamento.

{
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "totalItems": 100,
    "totalPages": 10
  },
  "items": [
    {
      "idRecurrence": "RR9V8I5MVE20250205ODA7UD3GYXA",
      "agents": {
        "debtor": {
          "name": "Nísia Floresta",
          "privateIdentification": "74271387088",
          "agentMemberIdentification": "59588111",
          "accountIdentification": "10319867",
          "accountIssuer": "2020",
          "cityCode": "4314902"
        },
        "originalDebtor": {
          "name": "Nome e Sobrenome",
          "privateIdentification": "74271387088"
        },
        "creditor": {
          "name": "Nome da Empresa",
          "privateIdentification": "44505365000143",
          "agentMemberIdentification": "59588111"
        }
      },
      "amount": {
        "fixedAmount": "123.22",
        "maximumAmount": "123.22",
        "currency": "BRL"
      },
      "calendar": {
        "initialDate": "2025-03-17",
        "finalDate": "2025-03-17",
        "frequency": "WEEK"
      },
      "contractInformation": "561238008",
      "description": "Descrição.",
      "status": "PENDING",
      "rejectReason": "AP13",
      "authorization": {},
      "retryPolicy": "ALLOW_3R_7D",
      "endToEndId": "E5958811120241016144644274P28HJO",
      "expirationDateTime": "2025-02-05T14:30:00Z",
      "recurrenceCreationDateTime": "2025-02-05T14:30:00Z"
    }
  ]
}

{
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "totalItems": 0,
    "totalPages": 0
  },
  "items": []
}

Status da autorização de recorrência de pagamento

Status	Descrição
PENDING	Solicitações de autorização ainda não respondidas pelo usuário pagador (aplicável apenas para jornada 1).
APROVED	Solicitações de autorização já aceitas pelo usuário pagador.
CANCELED	Autorização que foi cancelada seja a pedido do pagador ou do recebedor.
REJECTED	Solicitações de autorização não aceitas pelo usuário pagador (aplicável apenas para jornada 1).
EXPIRED	Solicitações de autorização cujo tempo para resposta foi ultrapassado.
COMPLETED	Indica que a data final da autorização foi atingida.
ERROR	Solicitações de autorizações com erro.

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

Erros

Este endpoint não retorna erros específicos. Porém, ele poderá retornar alguns erros comuns entre todos os endpoints.

Eventos

Este endpoint não possui eventos relacionados a ele.