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

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:
1 para PIN (Retorna o PIN no comprovante que será utilizado pelo usuário no provedor do serviço)
2 para ONLINE (Recarga convencional, realizada a partir das informações passadas na requisição)

maxValue

Double

Valor máximo permitido para
pagamento do título

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
pagamento do título

minValue

Double

Valor mínimo permitido para
pagamento do título

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
código do cliente estabelecido
pela Celcoin)

Sim

4

1

4

9(4)

IF-NUM-LOTE

Número Lote
(Número de sequência do
arquivo iniciando com 00001)

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

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
código do cliente estabelecido
pela Celcoin)

Sim

4

1

4

9(4)

IF-NUM-LOTE

Número Lote (Número de
sequencial do arquivo
iniciando com 00001)

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-REGISTRO

“MOV” – Movimentação
“LIQ” – Liquidação
“REC” – Recusa
“PRC” – Parcial

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
código estabelecido pela
Celcoin). (ver Tabela 1)

Sim

3

35

37

9(3)

IF-DATA-TRANS

Data da transação
(AAAAMMDD)

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
TodaConta

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-
TERMINALEXTERNO

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
Pagamento (ver Tabela 2)

Não

2

182

183

9(2)

IF-NUM-CARTÃO

Número do cartão que
efetuou a transação

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
Pagamento com cartão

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.
(Número do registro dentro do arquivo)

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
código do cliente estabelecido
pela Celcoin)

Sim

4

1

4

9(4)

IF-NUM-LOTE

Número Lote (Número de
sequencial do arquivo
iniciando com 00001)

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-
REGISTRO

“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
(a soma de todos os registros
incluindo o
Header e o Trailler)

Sim

5

42

46

9(05)

IF-VALORTOTAL

Valor total de todas as
transações em
REAL

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)


Did this page help you?