Consulta por conta
stable
O endpoint de consulta de pagamentos por conta retorna todos os pagamentos realizados pela conta informada na requisição, tenham sido eles completados ou não.
Pré-requisito
Para que seja possível utilizar este endpoint, é necessário que:
- O pagamento tenha sido confirmado com sucesso.
Requisição (Request)
Requisição HTTP
GET https://api-mtls.sandbox.bankly.com.br/bill-payment
--request GET 'https://api-mtls.sandbox.bankly.com.br/bill-payment?bankBranch={{0000}}&bankAccount={{123456}}&pageSize={{100}}&pageToken={{xxxxxx}}' \
--header 'accept: application/json' \
--header 'api-version: 1.0' \
--header 'authorization: Bearer {{Token}}' \
--header 'x-correlation-id: GUID' \
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 |
|---|---|
payment.read | Concede acesso para consultar um pagamento por conta. |
Cabeçalhos (Headers)
| Nome | Descrição |
|---|---|
api-version | Obrigatório. Versão da API. Atualmente estamos na versão 1.0. |
Authorization | Obrigatório. Token de autorização do tipo Bearer. |
x-correlation-id | Obrigatório. Informe um GUID, sendo um novo cada requisição. |
Parâmetros da rota (Path)
No path desta requisição envie os seguintes campos:
| Nome | Tipo | Descrição |
|---|---|---|
bankBranch | query | Obrigatório. Número da agência do banco do pagador. |
bankAccount | query | Obrigatório. Número da conta do pagador. |
pageSize | query | Número de itens por página que a consulta deve retornar. Caso este campo não seja preenchido, o valor padrão é de dez itens por página. |
pageToken | query | Após a primeira consulta, será retornado um token no campo nextPage, que identifica as páginas retornadas. Caso deseje consultar a próxima página, é preciso informá-lo neste campo (pageToken). |
Corpo da requisição (Body)
Não é necessário enviar parâmetros no body desta requisição.
Resposta (Response)
O status code 200 indicará que a solicitação foi aceita com sucesso e trará uma lista contendo os pagamentos realizados e suas informações.
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:
| Nome | Tipo | Descrição |
|---|---|---|
nextPage | string | Identificador da página retornada. Caso deseje consultar a próxima página, é preciso informá-lo no campo pageToken. |
data[] | array of objects | Lista de objetos contendo informações sobre os pagamentos. |
data[].authenticationCode | string | Id de confirmação da transação que poderá ser utilizado para consultar um pagamento específico. |
data[].bankAccount | string | Número da conta do pagador. |
data[].bankBranch | string | Número da agência do banco do pagador. |
data[].paymentDate | string | Data do pagamento, no formato ISO 8601 - UTC. |
data[].status | string | Situação do pagamento. Confira a lista dos possíveis status no final da página. |
data[].companyKey | string | Chave identificadora da companhia. |
data[].documentNumber | string | Número do documento do pagador. |
data[].confirmedAt | string | Data da confirmação do pagamento, no formato ISO 8601 - UTC. |
data[].digitable | string | Linha digitável. |
data[].amount | number | Valor pago. |
data[].originalAmount | number | Valor original, sem encargos. |
data[].assignor | string | Nome do cedente. |
data[].recipientDocument | string | Número do documento do recebedor. |
data[].recipientName | string | Nome do recebedor do pagamento. |
data[].charges | object | Objeto que contém informações sobre os encargos aplicados na transação. |
data[].charges.interestAmountCalculated | number | Valor dos juros. |
data[].charges.fineAmountCalculated | number | Valor da multa. |
data[].charges.discountAmount | number | Valor do desconto. |
data[].settleDate | string | Data em que o pagamento será liquidado, no formato ISO 8601 - UTC. Caso a data de vencimento coincida com feriados ou finais de semana, esse campo informará a data do próximo dia úti |
data[].dueDate | string | Data de vencimento, no formato ISO 8601 - UTC. Importante: No caso de contas concessionárias (contas de consumo, como água, luz, telefone) e de tributos (como IPVA, IPTU), é esperado que este campo retorne nulo. |
data[].description | string | Descrição do pagamento. |
{
"nextPage": null,
"data": [
{
"authenticationCode": "4b3eaf21-0e70-47f1-ab39-8f742dd5eaaaa",
"bankAccount": "540108",
"bankBranch": "0001",
"paymentDate": "2022-03-23T19:39:50.974+00:00",
"status": "Completed",
"companyKey": "XXX",
"documentNumber": "47742663023",
"confirmedAt": "2022-03-23T19:39:54.972+00:00",
"digitable": "856400000001954102132212231121522164795335403333",
"amount": 95.41,
"originalAmount": 95.41,
"assignor": "Conta - 1",
"recipientDocument": 09992220074,
"recipientName": "Maria Quitéria de Jesus",
"charges": {
"interestAmountCalculated": 0,
"fineAmountCalculated": 0,
"discountAmount": 0
},
"settleDate": "2022-03-24T00:00:00+00:00",
"dueDate": "2022-03-24T00:00:00+00:00",
"description": "TESTE_"
},
{
"authenticationCode": "5786b5c8-9be4-4e19-9333-f1461d500000",
"bankAccount": "15164",
"bankBranch": "0000",
"paymentDate": "2022-03-23T18:35:56.813+00:00",
"status": "Completed",
"companyKey": "XXX",
"documentNumber": "09992220074",
"confirmedAt": "2022-03-23T18:36:00.997+00:00",
"digitable": "858000000003770803282201900708220662414568811980",
"amount": 77.08,
"originalAmount": 77.08,
"assignor": "Conta 2",
"recipientDocument": 09992220074,
"recipientName": "Maria Quitéria de Jesus",
"charges": {
"interestAmountCalculated": 0,
"fineAmountCalculated": 0,
"discountAmount": 0
},
"settleDate": "2022-03-23T00:00:00+00:00",
"dueDate": "2022-03-23T00:00:00+00:00",
"description": "TESTE_"
},
{
"authenticationCode": "ff3923f5-fe83-48c6-b2fe-dad9115b39fa",
"bankAccount": "540108",
"bankBranch": "0001",
"paymentDate": "2022-03-17T15:29:01.827+00:00",
"status": "Created",
"companyKey": "XXX",
"documentNumber": "09992220074",
"confirmedAt": null,
"digitable": "858900000077200003282204800720220670699417872779",
"amount": 720,
"originalAmount": 720,
"assignor": "Conta - 3",
"recipientDocument": 09992220074,
"recipientName": "Maria Quitéria de Jesus",
"charges": {
"interestAmountCalculated": 0,
"fineAmountCalculated": 0,
"discountAmount": 0
},
"settleDate": "2022-03-17T00:00:00+00:00",
"dueDate": "2022-03-17T00:00:00+00:00",
"description": "TESTE_"
}
]
}
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.
Status
| Status | Descrição |
|---|---|
| Created | Significa que o título já foi validado e o pagamento está sendo iniciado. |
| Completed | O pagamento do título foi confirmado. |
| Canceled | O pagamento foi cancelado. |
Erros
Este endpoint pode retornar erros específicos, conforme a tabela a seguir:
| Status code | Code | Mensagem | Descrição |
|---|---|---|---|
| 400 | PAGE_SIZE_ABOVE_MAX_ALLOWED | Page size cannot be above 100 | O número de transações por página informado é maior que 100. |
| 400 | FORBIDDEN_SOURCE_ACCOUNT | Source account forbidden for this transaction | A conta informada não pertence a essa companyKey. |
| 400 | MISSING_COMPANY_KEY | A company key was not provided for this request. | companyKey não informada. |
| 403 | AUTHORIZATION_ERROR | Invalid credentials | Falha na autenticação do usuário. |
| 403 | ASSIGNOR_NOT_AUTHORIZED | Non authorized assignor, payment was not completed | Falha na autenticação do usuário. |
| 404 | NOT_FOUND_BILL_PAYMENTS | Not found bill payments | Não foram encontradas transações para a conta informada. |
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).
Importante
Os erros estão em processo de mapeamento. Em breve, as listas serão atualizadas.
Eventos
Este endpoint não possui eventos relacionados a ele.
Updated 22 days ago