Sobre o pagamento de contas

Essa funcionalidade permite realizar pagamentos das mais diversas modalidades, incluindo contas de água, luz, gás, telefone, internet, multas, tributos e boletos.

A Celcoin disponibiliza a API e realiza uma conexão com concessionárias e bancos liquidantes. Assim, processa as transações e traz o retorno sobre seu andamento.
Somos um grande agregador de instituições e concessionárias, concentrando a possibilidade de mais de 2.300 convênios, proporcionando comodidade para quem realiza os pagamentos, gerando economia de tempo.

Nesse artigo você irá aprender como:

• Realizar um pagamento e sua confirmação.
• Cancelar uma tentativa de pagamento.
• Reverter 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 sua devolução.

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.

• Obter uma massa de dados para testes, incluindo:

  • Ficha de compensação: Utilizar a lista de boletos da massa de dados oficial da Celcoin, que pode ser acessado aqui, ou;
  • Concessionárias: Entrar em contato com nosso time de CX (Customer Experience/Suporte) por meio deste link para solicitar uma massa de dados de boletos de concessionaria.

📘

Glossário

Ficha de compensação: São boletos bancários, seus dígitos iniciam sempre com o código do banco, por exemplo, no caso do Bradesco o começo da linha digitável será preenchido com o número 237.

Concessionárias: São contas de consumo, ou de órgãos governamentais, alguns exemplos de consumo, água, luz, telefone, internet, seu dígito sempre começa com o número 8 e para os órgãos governamentais como tributos, um exemplo seria o IPVA, iniciam geralmente com os dígitos 85 e 81.

🚧

Atenção

Com o objetivo de aperfeiçoar a sua experiência no processo de homologação do produto Pagamento de Contas, a Celcoin disponibiliza uma massa permanente de testes para os principais casos de pagamento de fichas de compensação (tipo 2) no seu ambiente de Sandbox.

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

Diagrama de Sequência - Pagamento de Contas

Com objetivo de exibir como pode ser a jornada de pagamento de contas para um usuário, criamos essa apresentação que simula o processo como todo:

Consultar os dados de uma conta (Authorize)

Em primeiro lugar é preciso se autenticar na API da Celcoin, caso tenha dúvida em como realizar esse processo indicamos a leitura do artigo Obtendo suas credenciais.

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

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

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 o pagamento de uma conta

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 cenario de uma devolução em sandbox é necessario solicitar via suporte, enviando o "transactionId" da efetivação , de um pagamento realizado com sucesso.

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

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
}