O que é o Produto de Pagamento de Contas?

Esta funcionalidade permite a realização de pagamentos de contas de diferentes origens, dentre elas as Fichas de Compensação (Boletos Bancários) e Guias de Convênios (Concessionárias e Tributos). Mas afinal, qual a diferença entre elas? Confira abaixo:

Ficha de Compensação (Boletos Bancários): são boletos e contas geralmente relacionadas a empréstimos, compras online e depósitos. Esses documentos são gerados por instituições financeiras e de pagamentos integradas à Núclea, a instituição centralizadora de cobranças regulada pelo BACEN (Banco Central do Brasil). Os dígitos iniciam sempre com o código da instituição, por exemplo:

• Emitido pela Celcoin: a linha digitável será iniciada com o número 509;
• Emitido pelo Bradesco: a linha digitável será iniciada com o número 237;
• Emitido pelo Itaú: a linha digitável será iniciada com o número 341.

Guias de Convênios (Concessionárias e Tributos): No caso das Concessionárias, referem-se às contas de consumo, como, por exemplo: água, energia elétrica, gás, internet e telefonia. Já no caso dos Tributos, referem-se à tributação realizada pelos governos Federal, Estadual e Municipal, como, por exemplo: IPTU, IPVA, multas, DAS (Simples Nacional), entre outros. O dígito dessas contas sempre começará com o número 8, e o segundo dígito indicará o segmento da cobrança. Exemplos:

• 81: Convênios de Prefeituras;
• 82: Convênios de empresas de Saneamento;
• 83: Convênios de empresas de Energia Elétrica e Gás;
• 84:Convênios de empresas de Telecomunicações;
• 85: Convênios de Órgãos Governamentais;
• 86: Convênios de Carnês/Assemelhados ou demais empresas/órgãos com CNPJ específico;
• 87: Convênios de Multas de Trânsito.

A Celcoin oferece uma API que se conecta diretamente com diferentes parceiros liquidantes, facilitando o processamento das transações e fornecendo atualizações sobre o andamento de cada pagamento. Com mais de 5.900 convênios integrados, somos um grande agregador de instituições e concessionárias, oferecendo comodidade e economia de tempo para quem realiza os pagamentos.

Nesse artigo você aprenderá como:

• Consultar uma Ficha de Compensação ou Guia de Convênio (Concessionárias e Tributos).;
• Reservar saldo para realização de um pagamento;
• Confirmar o pagamento;
• Cancelar uma reserva antes da confirmação do pagamento;
• Reverter um pagamento realizado;
• Consultar as informações de um pagamento realizado;
• Como seguir com o fluxo de integração quando ocorrer uma intermitência ao tentar realizar o pagamento de uma conta;
• Consultar uma ocorrência e como é feita a sua devolução;
• Realizar a Homologação.

🚧

Pré-requisitos para implementação:

• Possuir uma chave API da Celcoin. Para mais informações, acesse esse link;

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

• Ter o Produto contratado e habilitado em produção;

  • Caso queira utilizar a funcionalidade em ambiente produtivo, entre em contato com nossa time Comercial através do e-mail [email protected]. Para questões técnicas, basta entrar em contato com o nosso time de Suporte através deste link.

• Utilizar nossa Massa de Dados para os testes:

  • Fichas de Compensação (Boletos Bancários): Utilizar a lista de boletos presentes na Massa de Dados oficial da Celcoin, que pode ser encontrado aqui. Importante reforçar que o ambiente de Sandbox irá rejeitar qualquer consulta a códigos de barras diferentes da lista oficial da documentação com o erro "999 - BOLETO NAO REGISTRADO PARA TESTES. CONSULTE NOSSA DOCUMENTACAO".
  • Guias de Convênios (Concessionárias e Tributos): Entrar em contato com nosso time de Suporte através deste link , solicitando uma Massa de Dados específica de Concessionárias e Tributos.

Diagrama de Sequência - Pagamento de Contas

Consultar os dados de uma conta (Authorize)

Para consultar os dados de uma conta, siga as etapas abaixo:

1. Autenticação na API: Antes de realizar qualquer consulta, é necessário autenticar-se na API da Celcoin. Caso tenha dúvidas sobre como realizar esse processo, recomendamos a leitura do artigo Obtendo suas credenciais.
2. Obter o código de barras ou linha digitável: Para realizar a consulta de uma conta, o usuário final precisará informar o Código de Barras ou a Linha Digitável da conta que deseja pagar;
3. Realizar a consulta: Após obter essas informações, você deve fazer uma requisição POST na API Consultar os dados de uma conta. A Celcoin irá validar se a conta está registrada e retornará os dados desta conta a ser paga;
4. Parâmetros obrigatórios a serem informados:
   1. barCode (código de barras) ou digitable (linha digitável): Um dos dois parâmetros deve ser informado para que a consulta seja realizada.
5. Parâmetro opcional a ser informado:
   1. Se a aplicação obter a informação do tipo de pagamento que o usuário está realizando, poderá ser informado na propriedade type. O valor pode ser:
      1. 2 para Ficha de Compensação (Boleto Bancário);
      2. 1 para Guia de Convênio (Concessionárias e Tributos);
      3. 0 caso não tenha a informação sobre o tipo de pagamento.
6. Parâmetros adicionais a serem informados:
   1. externalTerminal: Esta propriedade é opcional e pode ser preenchida com uma informação externa do cliente, como CPF, telefone, entre outros;
   2. externalNSU: Outra propriedade opcional que pode ser preenchida com um identificador único da transação (ID) do sistema do cliente.

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": "ITAU UNIBANCO S.A.",
    "registerData": {
        "documentRecipient": "00.031.572/3670-91",
        "documentPayer": "698.447.801-44",
        "payDueDate": "2024-09-23T00:00:00",
        "nextBusinessDay": null,
        "dueDateRegister": "2024-09-23T00:00:00",
        "allowChangeValue": true,
        "recipient": "MOCK BENEFICIARIO",
        "payer": "MOCK PAGADOR",
        "discountValue": 0.0,
        "interestValueCalculated": 0.0,
        "maxValue": 999999999999.99,
        "minValue": 0.0,
        "fineValueCalculated": 0.0,
        "originalValue": 1627.87,
        "totalUpdated": 1000.0,
        "totalWithDiscount": 0.0,
        "totalWithAdditional": 0.0,
        "totalPaymentPaid": 1,
        "totalValuePaid": 627.87,
        "maxPartialsAccepts": 99,
        "paymentSpecies": 31,
        "documentRecipientFinal": "19.101.991/0002-83",
        "recipientFinal": "MOCK BENEFICIARIO FINAL"
    },
    "settleDate": "23/09/2024",
    "dueDate": null,
    "endHour": "23:00",
    "initeHour": "07:00",
    "nextSettle": "N",
    "digitable": "34191755464601559252350040380003100000000000000",
    "transactionId": 2147504239,
    "type": 2,
    "value": null,
    "maxValue": null,
    "minValue": null,
    "errorCode": "000",
    "message": null,
    "status": 0
}

Estrutura de dados response:

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". Em casos que sejam permitidos pagamentos parciais ("AllowChangeValue" = true), o valor calculado levará em consideração pagamentos efetuados anteriormente, retornando o valor ainda devido. Caso a somatória desses pagamentos anteriores ultrapasse o valor original corrigido, o campo "totalUpdated" poderá exibir valor negativo.

Outro ponto importante é que apenas nas consultas onde o "AllowChangeValue" for true, será possível efetivar o pagamento com um valor diferente do retornado no totalUpdated, respeitando o intervalo entre valor máximo(maxValue) e mínimo(minValue).

Importante: Nos casos em que a ficha de compensação não aceite pagamentos parciais, os campos "totalPaymentPaid", "totalValuePaid" e "maxPartialsAccepts", voltarão com os valores zerados. Portanto, não trata-se de um erro, mas sim de uma condição da regra de negócio.

Quanto ao intervalo em que esse pagamento pode ser efetuado, disponibilizamos a informação através das 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.

Obs.: Para pagamentos de Fichas de Compensação acima de R$ 249.999 ou de Convênios (Concessionárias e Tributos) acima de R$ 999.999, o horário limite de pagamento (endHour) será sempre 16h30.

É 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.

Em alguns casos, o campo documentFinalRecipient pode não retornar um dado no momento da consulta. Isso ocorre porque, dependendo do tipo de boleto, o Beneficiário Final pode ser opcional no momento da emissão da cobrança ou estar informado em outro campo, como o Sacador Avalista (quando houver). Em algumas consultas essa informação é apresentada no campo documentFinalRecipient, enquanto em outros ela pode estar ausente, seguindo os dados que foram informados pelo emissor do boleto.

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).

Payment species: Ele traz o tipo de boleto que está sendo consultado, que é declarado pelo banco emissor no momento da emissão. Seguem abaixo os possíveis retornos:

Reservar saldo para efetuar o pagamento de uma conta (billpayments)

Em seguida, a aplicação deverá executar a efetivação junto à API da Celcoin através do POST na API Reservar saldo para efetuar o pagamento de uma conta, para criar a transação de pagamento e retirada do saldo da conta de recursos próprios.

Modelo de request:

Modelo de request:
curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/v5/transactions/billpayments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
  "externalNSU": 1234, //Identificador Transação Externo
  "externalTerminal": "t2", //Identificador Cliente Externo
  "cpfcnpj": "51680002000100", //cpf/CNPJ do pagador
  "billData": {
    "value": 202.71,
    "originalValue": 202.71,
    "valueWithDiscount": 0,
    "valueWithAdditional": 0
  },
  "barCode": {
    "type": 2, //1-Concessionária, 2-Ficha de compensação
    "digitable": "03399853012970000135607559001016189020000020271",
    "barCode": ""
  },
  "dueDate": "2022-02-20T00:00:00.0000000-00:00",
  "transactionIdAuthorize": 9087400 //Id consulta gerado no authorize
}'

Modelo de response:

{
	"convenant": "509 | CELCOIN INST. PAGAMENTO SA / AGENCIA 0001",
	"isExpired": true,
	"authentication": 1913,
	"authenticationAPI": {
		"Bloco1": "59.A8.B9.FB.E4.FB.C5.1D",
		"Bloco2": "95.A6.3E.D3.04.31.22.3F",
		"BlocoCompleto": "59.A8.B9.FB.E4.FB.C5.1D.95.A6.3E.D3.04.31.22.3F"
	},
	"receipt": {
		"receiptData": "",
		"receiptformatted": 
NOME DO CLIENTE - PAGAMENTO SA
          PROTOCOLO 11111111111
1          10/10/2023        19:11
TERM 1111111 AGENTE 111111 AUTE 111111
----------------------------------------
AUTO 111111           RECEBIMENTO CONTA
                    
            BANCO ITAU S.A.
        11111.11111  11111.111111      
       11111.111111  1 11111111111111

BENEF:    			NOME DO BENEFICIARIO
CPF/CNPJ:            11.111.111/1111-11
PAGADOR:            NOME DO PAGADOR
CPF/CNPJ:                111.111.111-11
----------------------------------------
DATA DE VENCIMENTO           10/10/2023
DATA DO PAGAMENTO            10/10/2023
DATA DE LIQUIDACAO           10/10/2023
VALOR TITULO                     111,11
VALOR COBRADO                    111,11

<VIA1>CONVENIO: 509 | CELCOIN INST. 
PAGAMENTO SA / AGENCIA 0001
 
</VIA1>    VALIDO COMO RECIBO DE PAGAMENTO
----------------------------------------
              AUTENTICACAO
        E1.E4.F0.5E.EA.9A.5A.0F
        1B.26.21.98.99.10.E5.D6
----------------------------------------


		},
	"settleDate": "2023-10-05T00:00:00",
	"createDate": "2023-10-04T19:25:13",
	"transactionId": 10111325,
	"Urlreceipt": null,
	"errorCode": "000",
	"message": null,
	"status": 0
}

Estrutura de dados response:

Onde deve ser consumido as informações retornadas da api da Celcoin e apresentar para o usuário confirmar a veracidade do pagamento.

📘

Informação importante

Abaixo, mais detalhes sobre o campo Convenant

No campo convenant retornamos em qual instituição o pagamento será liquidado, seguindo o formato abaixo:

Código da instituição | Nome da instituição / Agência utilizada na instituição para realizar a liquidação

Na prática, retornamos assim: 509 | CELCOIN INST. PAGAMENTO SA / AGENCIA 0001

Seguem todos os retornos possíveis para esse campo:

001 | BANCO DO BRASIL / AGENCIA 3221
237 | BANCO BRADESCO / AGENCIA 3392
341 | BANCO ITAU / AGENCIA 0910
509 | CELCOIN INST. PAGAMENTO SA / AGENCIA 0001
655 | BANCO VOTORANTIN / AGENCIA 0001
756 | BANCO SICOOB / AGENCIA 4327

Confirmar o pagamento de uma conta

Após criar a transação, deve ser realizada a confirmação do pagamento através do PUT na api Confirmar o pagamento de uma conta, onde será realizado de fato a liquidação do pagamento.

É importante ressaltar que, caso essa chamada não seja executada em até 30 minutos após a chamada de efetivação, o valor retirado da conta de recursos próprios é estornado para a conta do cliente Celcoin.

Modelo de request:

curl --location --request PUT 'https://sandbox.openfinance.celcoin.dev/v5/transactions/billpayments/9087426/capture' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
  "externalNSU": 1234,
  "externalTerminal": "testevaldir2"
}'

Modelo de response:

{
    "errorCode": "000",
    "message": "SUCESSO",
    "status": 0
}

Estrutura de dados response:

Após receber esse retorno deve ser apresentado para o usuário que o pagamento foi realizado com sucesso.

Criamos um protótipo no figma para exemplificar esse processo.

Período de liquidação dos pagamentos:

A Celcoin aceita pagamentos 24(horas) por 7(dias), então todos os pagamentos enviados serão processados, porém cada tipo de conta tem seu horário de compensação, para ficha de compensação será enviado pela Celcoin os pagamentos dentre as 7h da manhã até 23h da noite, porém para concessionária esse horário pode variar de acordo com cada uma.

Reverter uma transação de pagamento de contas efetuada

A Celcoin segue um horário definido pelos convênios para realizar o pagamento das contas, porém uma vez que o pagamento não foi liberado para liquidação, ou seja, foi realizado uma solicitação de pagamento em um período diferente da hora de recebimento e corte definido pelo convênio, é possível cancelar essa operação.
Caso exista esse cenário para o seu modelo de negócio, basta realizar a requisição que vamos detalhar a seguir. Desta forma, o dinheiro que foi retirado para pagar a conta retornará ao saldo da sua conta de recursos próprios Celcoin.

Atualmente todas as linhas digitáveis aceitam esse tipo de cancelamento após a aprovação de uma normativa do BACEN.

🚧

Atenção!

Essa requisição só pode ser utilizado após uma transação ter sido confirmada com sucesso!
Além disso, para fichas de compensação funcionará apenas fora da janela de liquidação (exemplo: 23h até as 7h)

Para seguir com a reversão, basta realizar um POST na api Reverter uma transação de pagamento de contas efetuada, informando o transactionId na url da requisição para Celcoin identificar qual transação deve ser cancelada.

Modelo de request:

curl --location --request DELETE 'https://sandbox.openfinance.celcoin.dev/v5/transactions/billpayments/9117792/reverse' \
--header 'Authorization: Bearer {access_token}

Modelo de retorno:

{
  "errorCode": "000",
  "message": "Pedido de estorno registrado com sucesso.",
  "status": "0"
}

É importante ressaltar que esse processo só irá funcionar se a confirmação da transação ocorrer depois do horário permitido para liquidação e se essa requisição ocorrer dentro do período no qual o pagamento não foi liquidado.

Fluxo de integração quando ocorre uma intermitência ao tentar realizar a confirmação para uma efetivação

Exemplo 01:

Exemplo 2:

Consultar informações de um pagamento

Basicamente uma vez que ocorrer uma intermitência ao tentar realizar a chamada api Confirma a transação de pagamento de contas efetuada, ou seja, nossa api retorna que ocorreu um erro inesperado, deve ser realizado um GET na api Consultar informações de uma transação, passando um dos paramêtros abaixo;

• transactionId (Id único gerado pela Celcoin para a transação)
• externalNSU (Identificador da transação do sistema se integrando a Celcoin)
• externalTerminal (Terminal de identificação externa do sistema integrando a Celcoin)
• operationDate (Data da operação)

Onde será retornado o status da transação, podendo ser pendente, ou sucesso.
No caso de sucesso, deve ser retornado ao usuário final que o pagamento ocorreu como esperado, agora se o status estiver pendente, deve ser realizado novamente a chamada de Confirmar o pagamento de uma conta para que a liquidação ocorra com sucesso.

Modelo de request:

curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/v5/transactions/status-consult?transactionId=9087426' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw ''

Modelo de retorno:

{
  "transaction": {
    "authentication": 6088,
    "errorCode": "000",
    "createDate": "2021-06-24T17:48:08",
    "message": "SUCESSO",
    "externalNSU": 1234,
    "transactionId": "7097995",
    "status": 0,
    "externalTerminal": "11122233344"
  },
  "erroCode": "000",
  "message": "SUCESSO",
  "status": "0"
}

A propriedade status retorna o status da consulta podendo ser preenchida com os seguintes valores:

0 - para "SUCESSO" – sinaliza que a confirmação foi enviada e o pagamento será liquidado.

4 - para "ESPERANDO_CONFIRMAÇÃO_CLIENTE" – sinaliza que não houve a confirmação (capture). Nesses casos aguardamos o recebimento da confirmação por até 30 minutos, após isso a mesma será cancelada automaticamente pelo circuit breaker.

6 - PENDENTE_DESFAZIMENTO_AUTORIZADOR - Sinaliza que a transação entrou no nosso processo interno de desfazimento e vai passar para o próximo status

1 - para "DESFEITO_AUTORIZADOR" – sinaliza que a transação foi cancelada. Possíveis motivos como: falta de confirmação onde finaliza após 30 minutos ou o envio de uma confirmação negativa (void).

Consultar Ocorrências

Às vezes, ao realizar o pagamento de uma conta, o beneficiário, entidade final que está recebendo o dinheiro, rejeita um ou alguns pagamentos. Nesses casos, a Celcoin, ao identificar essa situação, devolve o dinheiro na conta de recursos próprios para o seu cliente e disponibiliza os pagamentos que foram rejeitados em uma API GET chamada Consultar ocorrências de um pagamento. Desta forma, é possível criar uma rotina de busca nessa API filtrando por data inicial e final, para saber quais pagamentos foram rejeitados em um determinado intervalo de tempo.

👍

Importante

Para simular o cenário de uma ocorrência em sandbox, é necessário utilizar os dados disponíveis em uma das tabelas de nossa massa de testes, disponível nesse link..

Modelo de request:

curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/v5/transactions/occurrency?DataInicio=2021-06-24T23:00:00&DataFim=2021-06-26T23:00:00' \
--header 'Authorization: Bearer {access_token}'

Modelo de retorno:

{
  "occurrences": {
    "date": "2021-06-24T19:03:43",
    "createDate": "2021-06-24T15:54:14",
    "descriptionMotivo": "Recusado pelo beneficiário",
    "externalNSU": 1234,
    "transactionId": 7061967,
    "externalTerminal": "11122233344",
    "linhaDigitavel": "34191090080012213037050059980008586260000065000 ",
    "value": "20"
  }
}

Consultar lista de convênios disponíveis

Para que os nossos clientes saibam quais são os convênios disponíveis para realizar o pagamento de contas, criamos a API de consulta Obtenha a lista de convênios. Importante ressaltar que a API retorna automaticamente novos convênios que são cadastrados ou descadastrados ao longo do tempo. Portanto, orienta-se que a API seja utilizada periodicamente de forma proativa.

Modelo de request:

curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/v5/transactions/institutions' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}'

Modelo de retorno:

{
    "convenants": [
        {
            "timeLimit": "19:00",
            "mask": "83______________0221____________________________",
            "Nomeconvenant": "CONSIGAZ - SP"
        },
        {
            "timeLimit": "16:00",
            "mask": "87______________3466____________________________",
            "Nomeconvenant": "Minas Gerais Multa"
        },
        {
            "timeLimit": "19:00",
            "mask": "82______________1699____________________________",
            "Nomeconvenant": "AGUAS DO RIO 4  RJ"
        }
    ],
    "errorCode": "000",
    "message": "SUCESSO",
    "status": 0
}

Homologação

As instruções para realizar a homologação deste produto estão centralizadas neste link