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

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:

ScopeDescrição
payment.readConcede acesso para consultar um pagamento por conta.

Cabeçalhos (Headers)

NomeDescrição
api-versionObrigatório. Versão da API. Atualmente estamos na versão 1.0.
AuthorizationObrigatório. Token de autorização do tipo Bearer.
x-correlation-idObrigatório. Informe um GUID, sendo um novo cada requisição.

Parâmetros da rota (Path)

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

NomeTipoDescrição
bankBranchqueryObrigatório. Número da agência do banco do pagador.
bankAccountqueryObrigatório. Número da conta do pagador.
pageSizequeryNú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.
pageTokenqueryApó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:

NomeTipoDescrição
nextPagestringIdentificador da página retornada. Caso deseje consultar a próxima página, é preciso informá-lo no campo pageToken.
data[]array of objectsLista de objetos contendo informações sobre os pagamentos.
data[].authenticationCodestringId de confirmação da transação que poderá ser utilizado para consultar um pagamento específico.
data[].bankAccountstringNúmero da conta do pagador.
data[].bankBranchstringNúmero da agência do banco do pagador.
data[].paymentDatestringData do pagamento, no formato ISO 8601 - UTC.
data[].statusstringSituação do pagamento. Confira a lista dos possíveis status no final da página.
data[].companyKeystringChave identificadora da companhia.
data[].documentNumberstringNúmero do documento do pagador.
data[].confirmedAtstringData da confirmação do pagamento, no formato ISO 8601 - UTC.
data[].digitablestringLinha digitável.
data[].amountnumberValor pago.
data[].originalAmountnumberValor original, sem encargos.
data[].assignorstringNome do cedente.
data[].recipientDocumentstringNúmero do documento do recebedor.
data[].recipientNamestringNome do recebedor do pagamento.
data[].chargesobjectObjeto que contém informações sobre os encargos aplicados na transação.
data[].charges.interestAmountCalculatednumberValor dos juros.
data[].charges.fineAmountCalculatednumberValor da multa.
data[].charges.discountAmountnumberValor do desconto.
data[].settleDatestringData 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[].dueDatestringData 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[].descriptionstringDescriçã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

StatusDescrição
CreatedSignifica que o título já foi validado e o pagamento está sendo iniciado.
CompletedO pagamento do título foi confirmado.
CanceledO pagamento foi cancelado.

Erros

Este endpoint pode retornar erros específicos, conforme a tabela a seguir:

Status codeCodeMensagemDescrição
400PAGE_SIZE_ABOVE_MAX_ALLOWEDPage size cannot be above 100O número de transações por página informado é maior que 100.
400FORBIDDEN_SOURCE_ACCOUNTSource account forbidden for this transactionA conta informada não pertence a essa companyKey.
400NOT_FOUND_BILL_PAYMENTSNot found bill paymentsNão foram encontradas transações para a conta informada.
403AUTHORIZATION_ERRORInvalid credentialsFalha na autenticação do usuário.
403ASSIGNOR_NOT_AUTHORIZEDNon authorized assignor, payment was not completedFalha na autenticação do usuá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).

🚧

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.