Consulta de Solicitação de Autorização de Recorrência
stable
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. | 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 | Especificação |
|---|---|---|---|
|
| Data de início do período para a busca das solicitações de autorização de recorrência. | Formato YYYY-MM-DD. |
|
| Data de fim do período para a busca das solicitações de autorização de recorrência. | Formato YYYY-MM-DD. |
|
| 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 | — |
|
| 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 | — |
|
| Situação da recorrência. | Enum: |
|
| Número da página que deseja consultar. | Valor mínimo 1. |
|
| 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 |
|---|---|---|---|
|
|
| Identificador da recorrência. |
|
|
| Objeto que contém os dados das páginas consultadas. |
|
|
| Número da página atual. |
|
|
| Tamanho da página. |
|
|
| Total de páginas. |
|
|
| Total de itens disponíveis de acordo com os parâmetros informados. |
|
|
| Objeto que contém a descrição dos itens da recorrência de pagamento. |
|
|
| Objeto que contém os dados de todos os agentes da consulta. |
|
|
| Objeto que contém os dados do cliente pagador da recorrência de pagamento. |
|
|
| Conta do cliente pagador. |
|
|
| Agência do cliente pagador. |
|
|
| ISPB do banco do cliente pagador. |
|
|
| Código de município do usuário pagador no IBGE. |
|
|
| Nome do pagador. |
|
|
| CPF ou CNPJ do cliente pagador. |
|
|
| Objeto que contém os dados do usuário devedor da recorrência de pagamento. |
|
|
| Nome do usuário devedor. Será retornado somente quando o campo |
|
|
| CPF ou CNPJ do usuário devedor. Será retornado somente quando o campo |
|
|
| Objeto que contém os dados do recebedor da recorrência de pagamento. |
|
|
| ISPB do banco do recebedor. Será retornado somente somente quando o campo |
|
|
| Nome do recebedor. Será retornado somente quando o campo |
|
|
| CNPJ do cliente recebedor. Será retornado somente quando o campo |
|
|
| Objeto que contém os dados referentes ao valor do pagamento recorrente. |
|
|
| Valor fixo configurado para a recorrência. Retornado somente quando a autorização utiliza um modelo de valor fixo ( |
|
|
| 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. |
|
|
| 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. |
|
|
| Tipo de moeda. Value: "BRL" |
|
|
| Objeto que contém informações referentes às datas e periodicidade do pagamento. |
|
|
| Data do primeiro pagamento. |
|
|
| Data do último pagamento. |
|
|
| Frequência da recorrência de pagamento, a qual pode ser pode ser WEEK (semanal), MNTH (mensal), QURT (trimestral), MIAN (semestral) e YEAR (anual). |
|
|
| Número de contrato referente à recorrência. |
|
|
| |
|
|
| Descrição do serviço/produto associado à recorrência. |
|
|
| Objeto que contém dados da autorização da recorrência de pagamento. |
|
|
| Tipo da jornada da autorização, que pode ser "AUT1", "AUT2", "AUT3" ou "AUT4". |
|
|
| Data de criação da autorização. |
|
|
| Motivo de rejeição de uma autorização, que pode ser AP13 (não reconhecido pelo debitante) ou AP14 (rejeitado pelo debitante). |
|
|
| Política de retentativa de pagamento após vencimento da recorrência, a qual pode ser ALLOW_3R_7D ou DOES_NOT_ALLOW. |
|
|
| Identificador de pagamento vinculado ao QR code composto. Retornará somente quando o campo |
|
|
| Data de expiração da recorrência de pagamento. |
|
|
| 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. |
DicaPara 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.
Updated about 2 months ago