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 [email protected]. 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

Realizar autenticação na API - [API Reference]
Consultar Código de Barras - [API Reference]
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:

Campo	Tipo	Descrição
assignor	String (100)	Cedente do pagamento consultado
documentRecipient	String (18)	CPF ou CNPJ do beneficiário
documentPayer	String (18)	CPF ou CNPJ do pagador
payDueDate	Datetime	Data de baixa do boleto
nextBusinessDay	Datetime	Próximo dia útil
dueDateRegister	Datetime	Data de vencimento do registro
allowChangeValue	Bool	Indica que o Boleto permite alterar valor entre o range “maxValue” e “minValue”, sugerimos que caso seja retornado “True” libere que o usuário insira na efetivação (Billpayments) o valor desejado.
recipient	String (100)	Nome do beneficiário
payer	String (100)	Nome do pagador
discountValue	Double	Valor do desconto calculado
interestValueCalculated	Double	Valor juros já calculado
maxValue	Double	Valor máximo permitido para pagamento do título. Utilizado nos cenários onde o “AllowChangeValue” for “True”.
minValue	Double	Valor mínimo permitido para pagamento do título. Utilizado nos cenários onde o “AllowChangeValue” for “True”.
fineValueCalculated	Double	Valor multa já calculado
originalValue	Double	Valor nominal do título
totalUpdated	Double	Valor atualizado a ser pago do título. Caso o campo “AllowChangeValue” retorne “False” apenas o valor retornado neste campo será aceito.
totalWithDiscount	Double	Valor total de descontos e abatimentos
totalWithAdditional	Double	Valor total de juros e multa
settleDate	Datetime	Informa a data em que o pagamento será enviado para liquidação
dueDate	Datetime	Retorna a data de vencimento extraída do código
endHour	String (5)	Informa a Hora corte do convênio (HH:MM)
initeHour	String (5)	Informa a Hora recebimento Inicial do convênio (HH:MM)
nextSettle	String (1)	Informa se o título será liquidado no próximo dia útil. Pode ser N ou S.
digitable	String (48)	Define a linha digitável consultada
transactionId	BigInt	Protocolo de identificação da operação
type	Int	Tipo de conta que está realizando a consulta
value	Double	Valor extraído do código
errorCode	String (3)	Define o código status da operação
message	String (100)	Informa descrição do erro
status	String (30)	Define o status da operação

Note que no retorno é possível validar diversas informações sendo elas:

A categoria do pagamento é definida na propriedade type sendo, "1" para Concessionarias/Tributos e "2" para fichas de compensação. Nas consultas para fichas de compensação realizaremos a consulta CIP, retornando no agrupamento registerData todas as informações atualizadas. Para Concessionárias/Tributos extraímos as informações da linha digitável, sendo assim o mencionado agrupamento registerData não é retornado.

Para consultas de fichas de compensação, retornamos o valor atualizado para o pagamento no campo "totalUpdated". Apenas nas consultas onde o "AllowChangeValue" for true, será possível efetivar o pagamento com um valor diferente do retornado no totalUpdated, lembrando que é necessário respeitar o intervalo máximo(maxValue) e mínimo(minValue).

Disponibilizamos o intervalo que esse pagamento pode ser processado através nas propriedades initeHour e EndHour, desta forma é possível validar qual é a hora inicial e final do processamento do pagamento. Caso seja realizado a tentativa de pagamento fora desse horário de corte o pagamento será postergado para o próximo dia útil.

É possível validar a data em que será realizada a liquidação do boleto através da propriedade settleDate. Também pode ser validado se o título será, ou não liquidado no o dia, através da propriedade nextSettle, onde S mostra que será liquidado no próximo dia útil e N que a liquidação será no mesmo dia. As vezes em ambiente de sandbox, pode ser que a propriedade settleDate seja populada como null, então recomendamos que seja realizado um tratamento para esse cenário do lado da sua aplicação, ou seja ela entenda que uma vez que populado com N a data de liquidação será no dia da confirmação do pagamento.

O transactionId é o id da transação que foi criada para esse pagamento.

O documentPayer é o documento do pagador e o value é o valor do pagamento com descontos ou juros.

Para alguns convênios de concessionária, não será possível realizar a extração da data de vencimento por meio da linha digitável, nesses casos, retornaremos o campo "dueDate" com o valor "null", e no momento da efetivação (billpayments) deve ser enviado a data em que está sendo realizado tal pagamento. Em ambiente de homologação a data de vencimento é mockada para qualquer convênio de concessionária, por isso retornará sempre "null". Porém, em produção, podemos retornar a data de vencimento corretamente em casos que o convênio a informa na linha digitável.

Ou seja, em ambiente de produção, nós retornaremos no atributo "dueDate" o valor "null" quando o convênio não disponibiliza a data de vencimento, e retornaremos o valor correto da data de vencimento em formato de Datetime nos casos em que temos a informação por parte do convênio. Por isso na integração os dois cenários devem ser considerados em produção.

OBS:

Para contas do tipo 1 (concessionárias/tributos), é necessário considerar sempre o atributo "dueDate", o qual refere-se a data de vencimento extraída na linha digitável do registro;
Para contas do tipo 2 (ficha de compensação), é necessário considerar sempre o atributo "registerData.dueDateRegister", o qual refere-se a data de vencimento recuperada na consulta junto a CIP (Câmara Interbancária de Pagamentos).

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

Campo	Descrição	Tipo Campo
clientRequestId	Identificador do cliente.	string
amount	Valor a ser pago.	number($double)
account	Numero da conta a ser realizado o débito do boleto	string
transactionIdAuthorize	ProtocoloId retornado no endpoint Authorize.	number
key	Chave pix da conta BaaS.	string
tags		Array
barCodeInfo		Objeto
barCodeInfo.digitable	Linha digitável - Quando enviada não precisa ser enviado o campo BarCode	sting
barCodeInfo.barCode	Código de barras - Quando enviada não precisa ser enviado o campo Linha Digitavel	string

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

Code	Message
PCE001	É obirgatório informar o campo clientRequestId.
PCE002	O campo account ultrapassou os 20 caracteres permitidos.
PCE003	É obrigatório informar o campo account.
PCE004	É necessário informar o campo barcodeInfo.digitable ou barcodeInfo.barcode.
PCE005	Apenas um dos campos devem estar preenchido, barcodeInfo.digitable ou barcodeInfo.barcode.
PCE006	Conta informada esta encerrada.
PCE007	Conta informada esta bloqueada.
PCE008	Conta informada esta com pendências no KYC.
PCE009	O campo transactionIdAuthorize é obrigatório.
PCE010	Conta não encontrada.
PCE011	O campo clientRequestId não pode conter mais de 20 caracteres.
PCE012	O campo amount esta inválido.
PCE013	É obirgatório informar o campo amount.
PCE014	O campo amount de ser a partir de 0.01.
PCE015	Cliente não esta ativo para utilizar a Api.
PCE016	É obirgatório informar o clientRequestId ou id.
PCE018	Não foi encontrada nenhuma transação com os parâmetros informados.
PCE019	Operação não realizada. Cliente não esta autorizado para esse produto.
PCE024	Request fora do padrão. Favor verificar a documentação.
PCE025	Já existe um pagamento com o mesmo clientRequestId.
PCE026	Já existe um pagamento com o mesmo transactionIdAuthorize

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"
         }
      ]
   }
}

Realizar um pagamento de boletos

Passos para Integrar

Consultar Informações do Boleto

Realizar pagamento do Boleto

Descrição dos campos

Exemplo de retorno

👍
Sucesso 200

❗
Error 400

Webhooks de Pagamento de Contas

Exemplo de Webhook de billpayment

Exemplo de Webhook de billpayment-occurrence

Passos para Integrar

Consultar Informações do Boleto

Realizar pagamento do Boleto

Descrição dos campos

Exemplo de retorno

👍Sucesso 200

❗Error 400

Webhooks de Pagamento de Contas

Exemplo de Webhook de billpayment

Exemplo de Webhook de billpayment-occurrence

👍
Sucesso 200

❗
Error 400