Sobre recargas nacionais
Essa funcionalidade é usada para disponibilizar aos seus usuários a possibilidade de realizar recargas de telefonia(Tim, Oi, Vivo, Claro), e conteúdos digitais (Xbox, Spotify, Ifood, Google Play, Level Up, Sky TV).
Pré requisitos para implementação:
-
Possuir uma chave API da Celcoin, para mais informações acessar esse link
-
Ter familiaridade com APIs Rest usando o protocolo OAuth 2.0.
-
Ter o produto/solução contratada, 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.
O que você irá aprender nesse artigo:
- Consultar Operadoras
- Consultar valores operacionais
- Realizar efetivação de uma recarga
- Confirmar a transação de uma recarga
- Medida de prevenção quando ocorrer uma intermitência na API da Celcoin
A Celcoin disponibiliza suas APIs para facilitar as conexões com os provedores. Assim, processa as transações e traz o retorno sobre seu andamento, desta forma um caso de uso seria:
Caso de uso:
Como fintech, quero disponibilizar para os meus usuários a possibilidade de realizar recargas de celular, jogos, transporte, ou tv, onde ele precisa selecionar a operadora e valor que deseja contratar, digitar os dados necessários e aprovar aquisição.
Consultar Operadoras
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.
Com o access_token retornado da chamada acima é possível realizar uma consulta na API Retorna a lista de operadoras, essa chamada irá retornar todos os provedores disponíveis para recargas na Celcoin.
Recomendamos que essa requisição não seja realizada em toda execução do fluxo de integração, basta você realizá- la uma vez ao dia e armazenar os providerId (Identificadores dos provedores) em sua base de dados, desta forma, você sempre terá eles atualizados para realizar as recargas de seus usuários e não precisará executar essa requisição diversas vezes.
Para essa requisição é necesário informar na querystring a propriedade type(tipo) que pode ser preenchido com:
0 para TODOS
1 para PIN
2 para ONLINEE a propriedade category(categoria) da recarga poderá ser informada como:
0 para TODOS
1 para TELEFONE
2 para JOGOS
3 para TV
4 para TRANSPORTE
5 para CONTEÚDO DIGITAL
Modelo de request:
curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/v5/transactions/topups/providers?stateCode=13&type=0&category=0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw ''
Modelo de retorno:
{
"providers": [
{
"category": 2,
"name": "Blizzard",
"providerId": 2139,
"RegionaisnameProvider": [],
"TipoRecarganameProvider": 1,
"maxValue": 0.0,
"minValue": 0.0
},
{
"category": 2,
"name": "Boa Compra",
"providerId": 2107,
"RegionaisnameProvider": [],
"TipoRecarganameProvider": 1,
"maxValue": 0.0,
"minValue": 0.0
}
]
}
Estrutura de dados response:
Campo | Tipo | Descrição |
---|---|---|
name | String(50) | Define o nome do produto/serviço |
providerID | int | Código do serviço |
tipoRecarganameProvider | String(1) | Retorna o tipo da operação: |
maxValue | Double | Valor máximo permitido para |
minValue | Double | Valor mínimo permitido para pagamento do título |
Consultar valores operacionais
Uma vez que é apresentado para o usuários as possibilidades de provedores, ele selecionando uma para realizar a recarga, nesse momento deve ser realizado a chamada Consulta valores operacionais para uma operadora ou provedor, onde será apresentado os valores disponíveis para aquela recarga na provedora, com esses valores pode ser apresentado para o usuário escolher qual tipo de recarga ele deseja realizar.
Recomendamos que essa requisição sempre seja realizada no processo, pois esses valores podem ser alterados pelas operadoras.
Modelo de request:
curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/v5/transactions/topups/provider-values?stateCode=11&providerId=2125' \
--header 'Content-Type: application/json' \
--header 'Authorization: {access_token}' \
--data-raw ''
Modelo de retorno:
{
"value": [
{
"properties": null,
"code": 0,
"cost": 0.0,
"detail": "",
"productName": "R$ 85,99 - Xbox Live 3 meses",
"checkSum": -18913591,
"dueProduct": 0,
"valueBonus": 0.0,
"maxValue": 85.99,
"minValue": 85.99
},
{
"properties": null,
"code": 0,
"cost": 0.0,
"detail": "",
"productName": "R$ 171,98 - Xbox Live 6 meses",
"checkSum": -2147483640,
"dueProduct": 0,
"valueBonus": 0.0,
"maxValue": 171.89,
"minValue": 171.98
},
{
"properties": null,
"code": 0,
"cost": 0.0,
"detail": "",
"productName": "R$ 199,00 - Xbox Live 12 meses",
"checkSum": -18913591,
"dueProduct": 0,
"valueBonus": 0.0,
"maxValue": 199.0,
"minValue": 199.0
}
],
"externalNsuQuery": null,
"errorCode": "000",
"message": "SUCESSO",
"status": 0
}
Estrutura de dados response:
Campo | Tipo | Descrição |
---|---|---|
productName | String(50) | Retorna as operações válidas (Sugerimos o espelhamento deste campo para o usuario) |
valueBonus | String(16) | Bônus para valor |
maxValue | Double | Valor máximo permitido para |
minValue | Double | Valor mínimo permitido para |
Reserva saldo para realizar recarga
Em seguida deve ser realizada a requisição Reserva saldo para realizar recarga, onde será validado se existe saldo em sua conta Celcoin e se é possível realizar a requisição.
Modelo de request:
curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/v5/transactions/topups' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
"externalTerminal": "1123123123",
"externalNsu": 1234,
"topupData": {
"value": 85.99
},
"cpfCnpj": "65419636069",
"signerCode": "1234567",
"providerId": 2125,
"phone": {
"stateCode": 15,
"countryCode": 55,
"number": 993134307
}
}'
A propriedade signerCode, deve ser populada com o cpf do assinante quando recargas de Tv, ou telefone quando de celular.
Modelo de retorno:
{
"NSUnameProvider": 0,
"authentication": 5878,
"authenticationAPI": null,
"receipt": {
"receiptData": "",
"receiptformatted": " AMBIENTE DE HOMOLOGACAO\r\n PROTOCOLO 0002751870\r\n1 11/03/2022 09:24\r\nTERM 228005 AGENTE 228005 AUTE 05878\r\n----------------------------------------\r\nAUTO 806689 \r\n<VIA1>\r\nESTE CUPOM NAO TEM VALOR FISCAL\r\n</VIA1>PRODUTO: R$ 85,99 - XBOX LIVE 3 MESES\r\n<VIA1>VALOR: R$ 85,99\r\nPIN: 6365-4427-6400-1327\r\nSERIE: 00000000\r\nTELEFONE: 15 993134307\r\n\r\n COMO RESGATAR O CODIGO XBOX:\r\n VISITE XBOX.COM/REDEEMCODE\r\nDIGITE O CODIGO DESTE RECIBO E COMECE A \r\n USAR!\r\n \r\n APOS O USO, INUTILIZE ESTE CUPOM\r\nIS2B - INTEGRATED SOLUTIONS TO BUSINESS\r\n \r\n \r\n \r\n \r\n</VIA1>----------------------------------------\r\n\r\n"
},
"settleDate": "2022-03-11T00:00:00",
"createDate": "2022-03-11T09:24:38",
"transactionId": 9172370,
"Urlreceipt": null,
"errorCode": "000",
"message": null,
"status": 0
}
Perceba que será apresentado o comprovante do pagamento para exibir ao usuário final.
Recomendamos que seja armazenada a propriedade transactionId (Id da transação), pois ela será utilizada para confirmar o pagamento e executar a recarga.
Confirmar a transação de uma recarga
Para finalizar de fato a recarga, deve ser realizada a chamada Confirmar a transação de uma recarga, informando o transactionId, onde a Celcoin irá se comunicar com o provedor e executar a recarga.
Modelo de request:
curl --location --request PUT 'https://sandbox.openfinance.celcoin.dev/v5/transactions/topups/9173139/capture' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
"externalNSU": 1234,
"externalTerminal": "1123123123"
}
'
Modelo de retorno:
{
"errorCode": "000",
"message": "SUCESSO",
"status": 0
}
Caso essa confirmação não seja executada em até 30 minutos, a Celcoin devolve o dinheiro que seria utilizado para a recarga para sua conta bolsão de forma automática.
Medida de prevenção quando ocorrer uma intermitência na api da Celcoin
Consultar informações de uma recarga
Basicamente uma vez que ocorrer uma intermitência ao tentar realizar a chamada API Confirmar a transação de uma recarga ou seja, nossa API retornou que ocorreu um erro inesperado, deve ser realizado um GET na API Consultar informações de uma recarga, passando um dos parâmetros 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 a transação de uma recarga, 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"
}
Configurar o envio de arquivos de movimentação via SFTP
Disponibilizamos também uma funcionalidade que envia arquivos para um SFTP com as movimentações que ocorreram no dia.
Caso o envio do arquivo das movimentações do dia seja feito via SFTP, compartilhamos abaixo o layout do arquivo de retorno de movimentação e recusa. O envio do arquivo será em d+1, no período da 1:00 ás 03:00 AM. A configuração deverá ser solicitada junto ao suporte.
O arquivo de movimentação contempla todas as recargas solicitadas na API em d-1.
Movimentação:
MOVIMENTACAO_ID + 9(4) – ID DO CLIENTE INTERNO + _NSA + (9(6) – NOTA DE DÉBITO) + _DATA +
AAAAMMDD – DATA CONTABIL DA NOTA DE DÉBITO
Exemplo:
MOVIMENTACAO_ID0002_NSA001494_DATA20160901
Header
Nome do campo | Descrição | Obrigatório | Tamanho | Pos. Inicial | Pos. Final | Tipo |
---|---|---|---|---|---|---|
IF-COD-CORP | Código da Corporação (Será o | Sim | 4 | 1 | 4 | 9(4) |
IF-NUM-LOTE | Número Lote | Sim | 5 | 5 | 9 | 9(5) |
IF-DATA-LOTE | Data (AAAAMMDD) | Sim | 8 | 10 | 17 | 9(8) |
IF-COD-ARQUIVO | Zeros | Sim | 2 | 18 | 19 | 9(2) |
IF-TIPO-REGISTRO | “HDR” – Movimentação | Sim | 3 | 20 | 22 | X(3) |
IF-NUM-CONTA | Zeros | Sim | 19 | 23 | 41 | 9(19) |
IF-TIPO-MOVTO | “MONETARIO” | Sim | 9 | 42 | 50 | X(09) |
FILLER | Brancos | Sim | 244 | 51 | 294 | x(244) |
IF-SEQ | Sequencial que indica o número | Sim | 6 | 295 | 300 | 9(6) |
Body
Se Código Transação = 10 (RECARGA)
Nome do campo | Descrição | Obrigatório | Tamanho | Pos. Inicial | Pos. Final | Tipo |
---|---|---|---|---|---|---|
IF-COD-CORP | Código da Corporação (Será o | Sim | 4 | 1 | 4 | 9(4) |
IF-NUM-LOTE | Número Lote (Número de | Sim | 5 | 5 | 9 | 9(5) |
IF-DATA-LOTE | Data (AAAAMMDD) (Data do | Sim | 8 | 10 | 17 | 9(8) |
IF-COD-ARQUIVO | Zeros | Sim | 2 | 18 | 19 | 9(2) |
IF-TIPO-REGISTRO | “MOV” – Movimentação | Sim | 3 | 20 | 22 | X(3) |
IF-VALOR-TRANS | Valor da Transação | Sim | 12 | 23 | 34 | 9(9)v99 |
IF-COD-TRANS | Código da transação (Será o | Sim | 3 | 35 | 37 | 9(3) |
IF-DATA-TRANS | Data da transação | Sim | 8 | 38 | 45 | 9(8) |
IF-HORA-TRANS | Hora da transação (HHMMSS) | Sim | 6 | 46 | 51 | 9(6) |
IF-DESCRIÇÃO | Descrição da transação | Sim | 40 | 52 | 91 | X(40) |
IF-COD-AUTORIZ. | O protocolo gerado pelo | Sim | 10 | 92 | 101 | 9(10) |
IF-NUM-SEQ-USUARIO | Número da Sequencial da transação do usuário | Sim | 10 | 102 | 111 | 9(10) |
IF-NUM- | Número do Terminal Externo | Não | 50 | 112 | 161 | X(50) |
IF-NUM-SEQ-EXTERNO | Número da Sequencial Externo | Não | 20 | 162 | 181 | 9(20) |
IF-COD-PAGTO | Número da Forma de | Não | 2 | 182 | 183 | 9(2) |
IF-NUM-CARTÃO | Número do cartão que | Não | 19 | 184 | 202 | 9(19) |
IF-QTDE-PARCELAS | Quantidade de parcelas | Não | 2 | 203 | 204 | 9(2) |
IF-NSU_AUTORIZADORA | NSU da Autorização online do | Não | 10 | 205 | 214 | 9(10) |
IF-LD | Linha Digitável | Não | 48 | 215 | 262 | 9(48) |
FILLER | Brancos | Sim | 32 | 263 | 294 | X(32) |
IF-SEQ | Sequencial que indica o número do registro dentro do arquivo. O header deverá ser montado com o sequencial 000001. | Sim | 6 | 295 | 300 | 9(6) |
Trailer
Nome do campo | Descrição | Obrigatório | Tamanho | Pos. Inicial | Pos. Final | Tipo |
---|---|---|---|---|---|---|
IF-COD-CORP | Código da Corporação (Será o | Sim | 4 | 1 | 4 | 9(4) |
IF-NUM-LOTE | Número Lote (Número de | Sim | 5 | 5 | 9 | 9(5) |
IF-DATA-LOTE | Data (AAAAMMDD) (Data do dia que está sendo enviado o arquivo) | Sim | 8 | 10 | 17 | 9(8) |
IF-COD-ARQUIVO | Zeros | Sim | 2 | 18 | 19 | 9(2) |
IF-TIPO- | “TLR” - Trailer | Sim | 3 | 20 | 22 | X(3) |
IF-NUMCONTA | Zeros | Sim | 19 | 23 | 41 | 9(19) |
IF-NUM-REGS | Total de registros no arquivo | Sim | 5 | 42 | 46 | 9(05) |
IF-VALORTOTAL | Valor total de todas as | Sim | 13 | 47 | 59 | 9(11)v99 |
FILLER | Brancos | Sim | 235 | 60 | 294 | x(235) |
IF-SEQ | Sequencial que indica o número do registro dentro do arquivo. O header deverá ser montado com o sequencial 000001 (Número do registro dentro do arquivo) | Sim | 6 | 295 | 300 | 9(6) |
Updated 11 days ago