A API de Recargas Nacionais disponibiliza aos seus usuários a possibilidade de realizar recargas de telefonia e conteúdos digitais listados abaixo:

Recargas de Telefonia disponíveis

Algar (Móvel e Fixo)
Claro (Móvel)
Correios
Embratel
Sercomtel Fixo
Tim
Vivo (Móvel e Fixo)

Recargas de Conteúdo Digital disponíveis

Claro TV
Google Play
League of Legends
Oi TV
PSN Store
SKY TV
Spotify
STEAM
Uber
Xbox Live

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
• Homologação

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.

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

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 é necessário informar na querystring a propriedade type(tipo) que pode ser preenchido com:

0 para TODOS
1 para PIN
2 para ONLINE

E 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:

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:

🚧

A operadora Steam efetua o desconto da tarifa para recargas. O valor desse desconto é variável e depende do montante recarregado, conforme detalhado abaixo:

Valor cobrado	Valor em Créditos
R$10,80	R$10,00
R$21,00	R$20,00
R$32,00	R$30,00
R$53,00	R$50,00
R$105,00	R$100,00
R$160,00	R$150,00
R$210,00	R$200,00

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": 11,
        "countryCode": 55,
        "number": 994114386
    }
}'

A propriedade signerCode, deve ser populada com o cpf do assinante quando recargas de Tv, ou telefone quando de celular.

Para recargas de conteúdo digital, que não possuem um vínculo a um número de telefone, o objeto phone deve ser preenchido utilizando o seguinte número default: 55 11 999999999 .

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:  11 994114386\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.

No campo "receiptformatted" a api retorna todas as orientações necessárias para que o usuário realize o resgate da recarga na plataforma solicitada. O PIN é a chave individual de cada recarga, utilizada para concluir o resgate na plataforma. Veja mais orientações em Termos de Uso.

Recomendamos que seja armazenada a propriedade transactionId (Id da transação), pois ela será utilizada para confirmar o pagamento e executar a recarga.

❗

Importante

Não disponibilize o PIN antes de Confirmar o Pagamento. Caso ocorra algum problema a Celcoin não irá se responsabilizar por possíveis prejuízos.

Nesta etapa o PIN é retornado na requisição, conforme response abaixo, porém ele só pode ser disponibilizado ao usuário final na etapa de Confirmação da Recarga.

Importante lembrar, para Recargas de Conteúdo Digital ao solicitar esse tipo de Recarga, já é disponibilizado o PIN, com isso não existe a possibilidade de Cancelamento.

JSON

"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:  11 994114386\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"
    }

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, exceto para a Recargas de Conteúdo Digital.

❗️

Para Recargas de Conteúdo Digital não é preciso confirmar, pois a partir do momento que você solicita a Reserva de Saldo na etapa anterior, ela já é CONFIRMADA AUTOMATICAMENTE e o PIN disponibilizado, sem possibilidade de Cancelamento.

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

Body

Se Código Transação = 10 (RECARGA)

Trailer

Homologação

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