Este tópico, tem como objetivo de descrever alguns endpoints para execuçaõ do processo de conciliação de pagamento.

A verificação dos pagamentos recebidos através de uma cobrança, pode ser feito das seguintes formas:

Consulta dos pagamento da cobrança
~~Solicitação do envio de todos os pagamentos a partir de uma data ou nsu~~
Configuração via Webhook

Consulta de pagamento da cobrança

As cobranças do tipo QR Code, dependendo do seu tipo e/ou parametrização, é possível que o pagamento seja efetuado mais de uma vez, logo, para facilitar o processo de conciliação, é disponibilizado uma API para consulta de pagamentos de forma ou de uma cobrança específica.

IMPORTANTE: lembrar de sempre utilizar a chave de correlação correlationId, pois é esta chave de garante a integração entre o sistema cliente e o sistema de cobrança do Delbank.

A resposta da consulta de pagamento, sempre será em ordem decrescente conforme a data de pagamento e retornará por padrão as seguintes informações:

Nome	Descrição	Observações
Nsu	Número sequencial único	Poderá ser utilizado na consulta de pagamento, e utilizá-lo como referência de paginação a fim de facilitar o processo de conciliação
CorrelationId	Id de correlação	Id utilizada para conciliação com o `sistema cliente`
ReferenceId	Referência de pagamento	Este campo contém a identificação de pagamento conforme a sua origem. Para pagamentos via Pix, sempre será uma `EndToEndId`, para pagamentos via Boleto, será a `identificação da baixa` na PCR
Source	Origem de pagamento	Origem do pagamento. Para pagamentos via Pix, será informado SPI (Sistema de pagamentos instantâneos)
CreatedAt	Data de pagamento
Payer	Informações sobre o pagador
Proof	Comprovante de pagamento	Este campo, é um valor genérico que será retornando conforme a sua origem de pagamento. Segue abaixo o modelo de comprovante

Comprovantes (Proof)

A geração de cobrança pode ser do tipo Pix (QR Code Estático ou QR Code Dinâmico), Boleto ou Boleto Pix, logo, é possível ter mais de uma origem de pagamento. Por exemplo, ao efetuar um pagamento de Boleto, existe as informações do pagador, banco recebedor, agência recebedora, etc, já o pagamento via Pix, possui conta do pagador, chave pix, etc. Para permitir o mesmo fluxo de conciliação para ambos os tipos de cobrança, este campo proof, irá conter as informações referente a sua respectiva origem de pagamento e assim permitir que o sistema cliente utiliza as informações conforme sua necessidade.

Segue abaixo o modelo de comprovante de um pagamento via Pix

{
   "endToEndId":"E3822485720230705211537850921369",
   "key":"5b0ac9a4-fad6-43f9-be70-6d7c9a2fad26",
   "amount":12.12,
   "payer":{
      "number":"10065",
      "branch":"0001",
      "type":"CURRENT",
      "holder":{
         "name":"Marconi do Nascimento Oliveira",
         "document":"02542584508"
      },
      "participant":{
         "ispb":"38224857",
         "name":"DELCRED SCD S.A."
      }
   },
   // legacy object
   "payee":{
      "number":"29823",
      "branch":"0001",
      "type":"CURRENT",
      "holder":{
         "name":"HOMOLOGACAO INTEGRACAO API",
         "document":"30287697789"
      },
      "participant":{
         "ispb":"38224857",
         "name":"DELCRED SCD S.A."
      }
   },
   "beneficiary":{
      "number":"29823",
      "branch":"0001",
      "type":"CURRENT",
      "holder":{
         "name":"HOMOLOGACAO INTEGRACAO API",
         "document":"30287697789"
      },
      "participant":{
         "ispb":"38224857",
         "name":"DELCRED SCD S.A."
      }
   }
}

Exemplos de consulta

A consulta de pagamento, pode ser feita de uma forma geral, ou seja, consultar todos os pagamentos recebidos ou consultar os pagamentos de uma determinada cobrança.

Conforme a explicação sobre o uso da paginação na busca de informações na API, segue abaixo um exemplo:

// request cURL
curl --location 'http://.../api/v1/charges/217c34be-b374-4e33-9ae2-1b46f14b7116/payments?page=1&limit=10' \
--header 'x-delbank-api-key: PJPyJ2xGmyB9oDHyNIUwNOt1dgpgolBwcE16ybaKD5q5eXIoHXNudlu+EaCcwXyLnryGdeBNfqofzLQe9f7s/iMVnsMZrbAPO/cYn6pTQEHVErYL080/hmZYV8faI89D'

[
   {
      "nsu":513,
      "correlationId":"217c34be-b374-4e33-9ae2-1b46f14b7116",
      "referenceId":"E3822485720230705211537850921369",
      "source":"SPI",
      "amount":12.12,
      "createdAt":"2023-07-05T17:52:33Z",
      "payer":{
         "name":"MARCONI DO NASCIMENTO OLIVEIRA",
         "document":"***999999**"
      },
      "proof":{
         "endToEndId":"E3822485720230705211537850921369",
         "transactionId":"chargeCqkFlaENmal5NrPK58J",
         "key":"5b0ac9a4-fad6-43f9-be70-6d7c9a2fad26",
         "amount":12.12,
         "payer":{
            "number":"10065",
            "branch":"0001",
            "type":"CURRENT",
            "holder":{
               "name":"Marconi do Nascimento Oliveira",
               "document":"02599999908"
            },
            "participant":{
               "ispb":"38224857",
               "name":"DELCRED SCD S.A."
            }
         },
         // legacy object
         "payee":{
            "number":"29823",
            "branch":"0001",
            "type":"CURRENT",
            "holder":{
               "name":"HOMOLOGACAO INTEGRACAO API",
               "document":"30287697789"
            },
            "participant":{
               "ispb":"38224857",
               "name":"DELCRED SCD S.A."
            }
         },
         "beneficiary":{
            "number":"29823",
            "branch":"0001",
            "type":"CURRENT",
            "holder":{
               "name":"HOMOLOGACAO INTEGRACAO API",
               "document":"30287697789"
            },
            "participant":{
               "ispb":"38224857",
               "name":"DELCRED SCD S.A."
            }
         }
      }
   },
   {
      "nsu":512,
      "correlationId":"217c34be-b374-4e33-9ae2-1b46f14b7116",
      "referenceId":"E3822485720230705211537850921369",
      "source":"SPI",
      "amount":12.12,
      "createdAt":"2023-07-05T17:52:33Z",
      "payer":{
         "name":"MARCONI DO NASCIMENTO OLIVEIRA",
         "document":"***999999**"
      },
      "proof":{
         "endToEndId":"E3822485720230705211537850921369",
         "transactionId":"chargeCqkFlaENmal5NrPK58J",
         "key":"5b0ac9a4-fad6-43f9-be70-6d7c9a2fad26",
         "amount":12.12,
         "payer":{
            "number":"10065",
            "branch":"0001",
            "type":"CURRENT",
            "holder":{
               "name":"Marconi do Nascimento Oliveira",
               "document":"02599999908"
            },
            "participant":{
               "ispb":"38224857",
               "name":"DELCRED SCD S.A."
            }
         },
         // legacy object
         "payee":{
            "number":"29823",
            "branch":"0001",
            "type":"CURRENT",
            "holder":{
               "name":"HOMOLOGACAO INTEGRACAO API",
               "document":"30287697789"
            },
            "participant":{
               "ispb":"38224857",
               "name":"DELCRED SCD S.A."
            }
         },
         "beneficiary":{
            "number":"29823",
            "branch":"0001",
            "type":"CURRENT",
            "holder":{
               "name":"HOMOLOGACAO INTEGRACAO API",
               "document":"30287697789"
            },
            "participant":{
               "ispb":"38224857",
               "name":"DELCRED SCD S.A."
            }
         }
      }
   }
]

Para mais detalhes sobre este, cliente aqui.

Polling (algoritmo)

Para facilitar a busca de pagamentos, utilize o NSU como referência. Segue o exemplo abaixo:

Realize a busca de todos os pagamentos utilizando o seguinte endpoint GET charges/payments?page=1&limit=10
Processe todos os pagamentos, e salve o maior NSU retornado (sempre será o primeiro, pois o retorno é em ordem decrescente). Por exemplo o nsu 115
1. Note que será retornado a id de correlação correlationId e com este, poderá realizar os devidos processamentos no sistema cliente
Nas consultas subsequentes, utilize o NSU como referência charges/payments?page=1&limit=10&afterNsu=115
Volte ao passo 2

Para mais detalhes sobre este endpoint, clique aqui.

Webhook

Lista de eventos

Retorno do Webhook

{
   "nsu":513,
   "correlationId":"217c34be-b374-4e33-9ae2-1b46f14b7116",
   "referenceId":"E3822485720230705211537850921369",
   "source":"SPI",
   "amount":12.12,
   "createdAt":"2023-07-05T17:52:33Z",
   "payer":{
      "name":"MARCONI DO NASCIMENTO OLIVEIRA",
      "document":"***999999**"
   },
   "proof":{
      "endToEndId":"E3822485720230705211537850921369",
      "transactionId":"chargeCqkFlaENmal5NrPK58J",
      "key":"5b0ac9a4-fad6-43f9-be70-6d7c9a2fad26",
      "amount":12.12,
     	...
   }
}