Realizar um pagamento de boletos

Essa funcionalidade permite que os clientes BaaS da Celcoin consigam realizar pagamentos de boletos a partir das contas de seus cliente.

Pré requisitos para implementação:

• Possuir uma chave api da Celcoin, para mais informações acessar esse link

• Ter familiaridade com o padrão REST usando o protocolo OAuth 2.0.

• Ter o produto/solução contratado e habilitado em produção.

  • Caso queira usar a funcionalidade em ambiente produtivo, por favor entre em contato com a nossa equipe comercial através do e-mail corp@celcoin.com.br. Para dúvidas técnicas, basta entrar em contato com o suporte através do link.

• Possuir uma conta no BaaS da Celcoin (Conta essa responsável por receber o valor da cobrança)

Passos para Integrar

1. Realizar autenticação na API - [API Reference]
2. Consultar Código de Barras - [API Reference]
3. Efetuar Pagamento do Boleto - [API Reference]

Caso seja necessário você pode consultar o pagamento de boleto manualmente.

• Consultar Cobrança - [API Reference]

Consultar Informações do Boleto

Para realizar a consulta de um pagamento, o usuário precisa informar o código de barras, ou linha digitável do pagamento que deseja realizar.

Ao receber essa informação deve ser realizada uma consulta através do método POST na api Consultar os dados de uma conta, onde a Celcoin irá validar se essa conta está registrada e irá retornar os dados desse pagamento. Para realizar essa requisição é necessário informar o barCode (código de barras), ou o digitable (código da linha digitável). Uma vez que é de conhecimento da aplicação o tipo de pagamento que o usuário está querendo pagar (ficha de compensação representada pelo número 2, ou concessionária 1), essa informação pode ser passada na propriedade type, caso não tenha essa informação, basta informar o valor 0.

Existem outras duas propriedades externalTerminal onde pode ser preenchida com uma informação externa do cliente como CPF, telefone etc e o externalNSU que pode ser preenchido com um id identificador da transação.

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/v5/transactions/billpayments/authorize' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
    "externalTerminal": "Terminal de identificação externa do sistema do cliente, Ex: CPF",
    "externalNSU": 0, //Identificador da transação do sistema cliente
    "barCode": {
        "type": 2,
        "digitable": "03399853012970000135607559001016189020000020271",
        "barCode": ""
    }
}'

Modelo de response:

{
    "assignor": "BANCO SANTANDER S.A",
    "registerData": {
        "documentRecipient": "21.568.259/0001-00",
        "documentPayer": "96.906.497/0001-00",
        "payDueDate": "2022-03-22T00:00:00",
        "nextBusinessDay": null,
        "dueDateRegister": "2022-02-20T00:00:00",
        "allowChangeValue": false,
        "recipient": "BENEFICIARIO AMBIENTE HOMOLOGACAO",
        "payer": "PAGADOR AMBIENTE HOMOLOGACAO",
        "discountValue": 0.0,
        "interestValueCalculated": 0.0,
        "maxValue": 202.71,
        "minValue": 202.71,
        "fineValueCalculated": 0.0,
        "originalValue": 202.71,
        "totalUpdated": 202.71,
        "totalWithDiscount": 0.0,
        "totalWithAdditional": 0.0
    },
    "settleDate": "15/02/2022",
    "dueDate": "2022-02-20T00:00:00Z",
    "endHour": "20:00",
    "initeHour": "07:00",
    "nextSettle": "N",
    "digitable": "03399853012970000135607559001016189020000020271",
    "transactionId": 9087400,
    "type": 2,
    "value": 202.71,
    "maxValue": null,
    "minValue": null,
    "errorCode": "000",
    "message": null,
    "status": 0
}

Estrutura de dados response:

No retorno da consulta, diversas informações importantes são disponibilizadas para o correto processamento do pagamento. A seguir, descrevemos cada uma delas e seus respectivos comportamentos:

1. Categoria do Pagamento (type)

   • Descrição:
     Define a categoria do pagamento:
     • "1": Concessionárias/Tributos.
     • "2": Fichas de Compensação.
   • Observações:
     • Fichas de Compensação:
       É realizada a consulta CIP, e todas as informações atualizadas são agrupadas no objeto registerData.
     • Concessionárias/Tributos:
       As informações são extraídas diretamente da linha digitável; portanto, o agrupamento registerData não é retornado.

2. Valor Atualizado do Pagamento (totalUpdated)

   • Descrição:
     Para consultas de fichas de compensação, o campo totalUpdated retorna o valor atualizado a ser pago.
   • Observação:
     Se a propriedade AllowChangeValue estiver definida como true, o pagamento poderá ser efetuado com um valor diferente do totalUpdated, desde que o valor informado esteja dentro dos limites especificados por maxValue e minValue.

3. Intervalo de Processamento (initeHour e EndHour)

   • Descrição:
     Estes campos indicam o horário permitido para o processamento do pagamento:
     • initeHour: Hora inicial.
     • EndHour: Hora final.
   • Observação:
     Se a tentativa de pagamento ocorrer fora deste intervalo (horário de corte), o processamento será adiado para o próximo dia útil.

4. Liquidação do Boleto (settleDate e nextSettle)

   • settleDate:
     Indica a data em que o boleto será liquidado.

   • nextSettle:
     Informa se a liquidação ocorrerá no mesmo dia útil da confirmação ou se será adiada para o próximo dia útil.

   • Valores Possíveis:

     • N: Liquidação no mesmo dia útil da confirmação.
     • S: Liquidação adiada para o próximo dia útil.

   • Regras de Funcionamento e Use Cases:

     • Caso 1: Operação em dia útil dentro da janela operacional
       • Exemplo: Uma consulta realizada às 10h de uma terça-feira, estando dentro do horário de processamento.
       • Resultado:
         • settleDate: Data da terça-feira (mesmo dia).
         • nextSettle: N.
     • Caso 2: Operação em dia útil fora da janela operacional
       • Exemplo: Uma consulta realizada às 23h de uma terça-feira, quando o horário de corte (por exemplo, às 16h) já foi ultrapassado.
       • Resultado:
         • settleDate: Data da quarta-feira (próximo dia útil).
         • nextSettle: S.
     • Caso 3: Operação em dia não útil (sábado, domingo ou feriado)
       • Exemplo: Uma consulta realizada em um domingo.
       • Resultado:
         • settleDate: Data da segunda-feira (primeiro dia útil após o fim de semana).
         • nextSettle: N
           (Neste cenário, a liquidação na segunda-feira é natural devido à ausência de expediente no domingo e não é considerada um adiamento decorrente de horário fora da janela operacional).

   • Observações Adicionais:

     • Em ambiente de sandbox, o campo settleDate pode ser retornado como null. Nesse cenário, recomenda-se que a aplicação trate essa situação, considerando que, se nextSettle for N, a liquidação ocorrerá no dia da confirmação do pagamento.
     • O campo nextSettle é utilizado apenas para indicar que, em dias úteis, a operação foi realizada fora do horário permitido (horário de corte) e, portanto, a liquidação será adiada para o próximo dia útil. Operações efetuadas em dias não úteis, que naturalmente têm a liquidação postergada para o próximo dia útil, devem manter nextSettle = N.

5. Identificador da Transação (transactionId)

   • Descrição:
     Representa o ID da transação criada para o pagamento.

6. Dados do Pagador e Valor do Pagamento

   • documentPayer:
     Documento do pagador (CPF/CNPJ).
   • value:
     Valor do pagamento, já considerando eventuais descontos ou juros.

7. Data de Vencimento (dueDate)

   • Descrição e Cenários:
     • Concessionárias/Tributos (Tipo 1):
       • Em alguns convênios, a data de vencimento não pode ser extraída da linha digitável; nesses casos, o campo dueDate será retornado como null.
       • Em ambiente de homologação, a data de vencimento é mockada para qualquer convênio, retornando sempre null.
       • Em produção, se o convênio fornecer a data de vencimento na linha digitável, o valor correto (no formato DateTime) será retornado.
     • Fichas de Compensação (Tipo 2):
       A data de vencimento deve ser considerada no atributo registerData.dueDateRegister, obtida na consulta junto à CIP (Câmara Interbancária de Pagamentos).
   • Observação:
     Durante a integração, é fundamental que sejam tratados os dois cenários:
     • Para contas do Tipo 1 (Concessionárias/Tributos): Utilize sempre o campo dueDate.
     • Para contas do Tipo 2 (Fichas de Compensação): Utilize o campo registerData.dueDateRegister.

Realizar pagamento do Boleto

cURL da chamada

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/baas/v2/billpayment' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {token}' \
--data-raw '{
    "clientRequestId": "5555",
    "amount": 59.9,
    "account": "333333",
    "transactionIdAuthorize": 321,
    "tags": [
        {
            "key": "PaymentType",
            "value": "Contas Internas"
        }
    ],
    "barCodeInfo": {
        "digitable": "23793381286008301352856000063307789840000150000",
        "barCode": "23797898400001500003381260083013525600006330"
    }
}'

JSON de exemplo

{
    "clientRequestId": "5555",
    "amount": 59.9,
    "account": "333333",
    "transactionIdAuthorize": 321,
    "tags": [
        {
            "key": "PaymentType",
            "value": "Contas Internas"
        }
    ],
    "barCodeInfo": {
        "digitable": "23793381286008301352856000063307789840000150000",
        "barCode": "23797898400001500003381260083013525600006330"
    }
}

Descrição dos campos

Exemplo de retorno

👍

Sucesso 200

{
    "body": {
        "id": "ce9b8d9b-0617-42e1-b500-80bf9d8154cf",
        "clientRequestId": "5555",
        "amount": 59.9,
        "transactionIdAuthorize": 1234,
        "tags": [
            {
                "key": "PaymentType",
                "value": "Contas Internas"
            }
        ],
        "barCodeInfo": {
            "digitable": "23793381286008301352856000063307789840000150000"
        }
    },
    "status": "PROCESSING",
    "version": "1.0.0"
}

❗

Error 400

{
  "version": "1.0.0",
  "status": "ERROR",
  "error": {
    "errorCode": "CBE001",
    "message": "Ocorreu um erro interno durante a chamada da api."
  }
}

Tabela de errorCode

Webhooks de Pagamento de Contas

Possuimos 2 eventos de webhook para pagamento de contas, são eles:

billpayment.
billpayment-occurrence

billpayment
Após realizar um pagamento de uma conta vocês receberá a confirmação desse pagamento, por esse evento.

billpayment-occurrence
Após realizar um pagamento de uma conta você pode receber em até 7 dias uma ocorrência desse pagamento, ocorrência significa que houve um problema no pagamento e esse valor é estornado para conta que realizou o pagamento.

Exemplo de Webhook de billpayment

Status: CONFIRMED

{
   "entity":"billpayment",
   "createTimestamp":"2023-10-04T04:49:23.0761616",
   "status":"CONFIRMED",
   "body":{
      "amount":5,
      "transactionId":123456,
      "status":"CONFIRMED",
      "id":"5aa85398-51f6-451c-b550-999999999",
      "clientRequestId":1234,
      "createDate":"2023-10-04T01:49:21",
      "account":30000005000,
      "barCodeInfo":{
         "digitable":"3000000000000000000000000000"
      },
      "tags":[
         {
            "key":"PaymentType",
            "value":"Contas Internas"
         }
      ],
      "transactionIdAuthorize":123453,
      "authentication":222,
      "authenticationAPI":{
         "bloco1":"9A.94.F52.D5.4C.05.DE",
         "bloco2":"9P.D7.CK.EA.B8.AB.DJ.A0",
         "blocoCompleto":"9E.84.F5.5C.RD.4D.05.DE.9D.D7.CB.EA.B8.AB.DF.A0"
      },
      "convenant":"BANCO S/A",
      "isExpired":false,
      "receipt":{
         "receiptformatted":"         CELCOIN - TESTES BAAS\\r\\n          PROTOCOLO 1231321321\\r\\n1          04/10/2023        01:49\\r\\nTERM 22258579 AGENTE 33333 AUTE 0854541\\r\\n----------------------------------------\\r\\nAUTO 1454524          RECEBIMENTO CONTA\\r\\n                    \\r\\n            BANCO CELCOIN S.A.\\r\\n        34191.09545  00044.840912      \\r\\n       01588.946001  6 90040000000500\\r\\n\\r\\nBENEF:   CELCOIN INSTITUICAO DE PAGAMEN\\r\\nCPF/CNPJ:            13.935.893/0001-09\\r\\nPAGADOR:               MINHA EMPRESA ME\\r\\nCPF/CNPJ:                657.155.460-79\\r\\n----------------------------------------\\r\\nDATA DE VENCIMENTO           05/10/2023\\r\\nDATA DO PAGAMENTO            04/10/2023\\r\\nDATA DE LIQUIDACAO           04/10/2023\\r\\nVALOR TITULO                       5,00\\r\\nVALOR COBRADO                      5,00\\r\\n\\r\\n<VIA1>CONVENIO: BANCO SA\\r\\n \\r\\n</VIA1>    VALIDO COMO RECIBO DE PAGAMENTO\\r\\n----------------------------------------\\r\\n              AUTENTICACAO\\r\\n        9E.94.F8.2C.TD.dC.05.DE\\r\\n        9E.94.F8.2C.TD.dC.05.DE\\r\\n----------------------------------------\\r\\n\\r\\n"
      },
      "settleDate":"2023-10-04T00:00:00"
   }
}

Status: ERROR

{
   "entity":"billpayment",
   "createTimestamp":"2023-07-27T09:46:35.0203706",
   "status":"ERROR",
   "body":{
      "amount":202.71,
      "id":"34fee7bc-4d40-4605-9af8-398ed7d0d6b5",
      "clientRequestId":3,
      "account":30551551515,
      "barCodeInfo":{
         "digitable":"03399853012970000135607559001016189020000020271"
      },
      "transactionIdAuthorize":321
   },
   "error":"Falha na liquidação"
}

Exemplo de Webhook de billpayment-occurrence

Status: REVERSED

{
   "entity":"billpayment-occurrence",
   "createTimestamp":"2023-10-11T17:23:37.3619902",
   "status":"REVERSED",
   "body":{
      "amount":5,
      "id":"5aa85398-51f6-451c-b550-9e45073bd5554",
      "clientRequestId":1234,
      "account":300559898989899,
      "occurrence":{
         "reason":"Boleto não válido",
         "devolutionDate":"2023-10-11T14:23:37.2009803",
         "occurrenceId":1515151
      },
      "tags":[
         {
            "Value":"Contas Internas",
            "Key":"PaymentType"
         }
      ]
   }
}