Sobre Recargas internacionais

Essa funcionalidade é usada para disponibilizar aos seus usuários a possibilidade de realizar recargas de celulares internacionais.

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.

A Celcoin disponibiliza suas APIs para facilitar as conexões com os provedores. Assim, processa as transações e apresenta o retorno sobre seu andamento, desta forma um caso de uso seria:

Como Fintech, quero disponibilizar para os meus usuários a possibilidade de realizar recargas de celular internacionais, onde ele precisa selecionar o DDD, telefone, país e o valor que deseja contratar. Ao digitar os dados necessários e aprovar a compra, será retirado o saldo da sua conta e disponibilizado os créditos para o número de celular escolhido.

Em primeiro lugar o usuário deve acessar o aplicativo da Fintech e selecionar a opção compra de créditos para telefones internacionais, onde será apresentado uma tela. Nesse momento a Fintech precisa se autenticar na API da Celcoin. Caso tenha dúvida em como realizar esse processo indicamos a leitura do artigo Obtendo suas credenciais.

Consultar lista de países disponíveis

Com o access_token retornado da chamada autenticação é possível realizar uma consulta na API Lista países disponíveis, essa chamada irá retornar todos os países disponíveis para realizar recargas internacionais com a Celcoin.

🚧

Atenção!

Recomendamos que essa requisição não seja realizada em toda execução do fluxo de integração, o ideal seria realizá-la uma vez por dia e armazenar a propriedade code(código do DDD do país), em sua base de dados, desta forma, você sempre terá esses códigos atualizados para realizar as recargas de seus usuários.

Modelo de requisição:

curl --request GET \
     --url 'https://sandbox.openfinance.celcoin.dev/v5/transactions/internationaltopups/countrys?page=1&size=50' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer {access_token}'

Modelo de retorno:

{
  "countrys": [
    {
      "flagURL": "https://restcountries.eu/data/gmb.svg",
      "code": "+220",
      "name": "Gambia"
    },
    {
      "flagURL": "https://restcountries.eu/data/geo.svg",
      "code": "+995",
      "name": "Georgia"
    },
    {
      "flagURL": "https://restcountries.eu/data/deu.svg",
      "code": "+49",
      "name": "Germany"
    },
]
}

Consultar os valores disponíveis para realizar uma recarga

Uma vez que é apresentado para o usuários as possibilidades de recargas para diversos países, ele seleciona um país, insere o DDD e o número do telefone para realizar a recarga, nesse momento a Fintech deve realizar a chamada Consultar os valores disponíveis para um país por meio de seu código de discagem.

Modelo de requisição:

curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/v5/transactions/internationaltopups/values?countryCode=509&phoneNumber=48227030' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw ''

Modelo de retorno:

{
  "data": {
    "quotation": {
      "purchase": "5.2468",
      "quotationId": "206353",
      "quotationDateTime": "2021-08-13T13:04:27.62",
      "description": "PTAX (Banco Central)",
      "spread": "10",
      "sale": "5.2474"
    },
    "baseCurrency": "BRL",
    "destinyCurrency": "BRL",
    "localCurrency": "HTG",
    "number": "50948227030",
    "nameProvider": "Digicel Haiti BRL",
    "country": "Haiti",
    "products": [
      {
        "description": "113.25",
        "productId": "5",
        "rate": "0.0000",
        "value": "0.9000",
        "finalValue": "113.2500",
        "finalValueCalculated": "5.4300",
        "productValue": "113.2500",
        "retail": "0.9400",
        "finalRetail": "5.4300"
      },
      {
        "description": "226.50",
        "productId": "10",
        "rate": "0.0000",
        "value": "1.8900",
        "finalValue": "226.5000",
        "finalValueCalculated": "10.9700",
        "productValue": "226.5000",
        "retail": "1.9000",
        "finalRetail": "10.9700"
      }
    ]
  },
  "errorCode": "000",
  "message": "SUCESSO",
  "status": 0
}

Estrutura de dados do response:

CampoTipoDescrição
purchaseDoubleValor de compra de 1 USD (Dólar americano) considerando a MoedaBase na data da consulta
quotationIdIntDefine o identificador da cotação
quotationDateTimeDateTimeDefine a data e horário de consulta da cotação
descriptionString(200)Origem/Fonte onde a cotação foi consultada
spreadIntPercentual do spread aplicado sobre a cotação do dólar
saleDoubleValor de venda de 1 USD (Dólar americano) considerando a MoedaBase na data da consulta é o valor que será efetivamente considerado nos cálculos.
baseCurrencyString(10)Será BRL (Real) por padrão. Essa será a moeda usada para gerar o ValorFinalCalculado
destinyCurrencyString(10)Moeda corrente no país associado ao número de telefone que é beneficiário da recarga
localCurrencyString(10)Moeda base utilizada pelo fornecedor
numberString(50)Número de telefone a qual receberá a recarga (código de discagem + número de telefone)
nameProviderString(40)Nome da operadora responsável pelo número de telefone da recarga
countryString(30)Nome do país
descriptionString(100)Define a descrição do produto/valor retornado pela operadora
productIdIntIdentificador do produto/valor (Deverá ser enviado na efetivação)
rateDoubleDefine taxas que incidem no ValorFinalCalculado
valueDoubleDefine o custo por venda em USD (Dólar Americano)
finalValueDoubleDefine o valor em moeda local (MoedaDestino) , a qual o cliente irá de fato receber em seu telefone celular
finalValueCalculatedDoubleDefine o valor calculado, considerando a MoedaBase (BRL) + Taxas + Spread. Este é o valor que efetivamente será cobrando para efetuar a recarga
productValueDoubleDefine o valor Moeda local (MoedaDestino) que o cliente irá de fato receber em seu telefone, sem taxas e spread
retailDoubleDefine o valor da recarga no varejo, em dólar
finalRetailDoubleDefine o valor da recarga no varejo, usando a MoedaBase (BRL), sem taxas ou spread
errorCodeString(3)Mostra o código do erro
messageString(100)Reporta a descrição do erro
statusString(30)Mostra o status da operação

Perceba que será apresentado os valores disponíveis em real e dólar, o spread da compra, horário da cotação, qual a moeda corrente do país, fornecedor, operadora e os valores disponíveis para aquisição naquele país.

🚧

Atenção

Recomendamos que essa requisição sempre seja realizada no processo de integração, pois esses valores podem ser alterados. É importante que a Fintech apresente o máximo de informações para o usuário ter conhecimento do que está contratando.

Reservar saldo para realizar o pagamento de uma recarga

Uma vez que o usuário escolheu o valor e clicar em confirmar, deve ser realizada uma requisição que irá validar se existe saldo na conta bolsão da Fintech da Celcoin e retornar se é possível realizar uma recarga para o número de telefone. Para executá-la basta realizar a chamada na API Reservar saldo para realizar o pagamento de uma recarga.

Modelo de requisição:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/v5/transactions/internationaltopups' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
     "phone": {
          "number": 48227030,
          "countryCode": 509
     },
     "cpfCnpj": "35914746817",
     "externalNsu": 123231312,
     "externalTerminal": "6958",
     "value": "5.4300",
     "topupProductId": "5"
}'

Perceba que o valor utilizado no campo value é o finalValueCalculated, pois ele compõe o valor em real com todas as taxas aplicadas mais o spread com o valor convertido da moeda do país para o real.

Modelo de retorno:

{
  "NSUnameProvider": 0,
  "authentication": 4167,
  "authenticationAPI": null,
  "receipt": {
    "receiptData": "",
    "receiptformatted": "                 TESTE\r\n          PROTOCOLO 0816057734\r\n1          06/04/2022        14:29\r\nTERM 228001 AGENTE 228001 AUTE 04167\r\n----------------------------------------\r\nAUTO 907545       RECARGA INTERNACIONAL\r\nVALOR :R$ 5,43\r\nOPERADORA : DIGICEL HAITI BRL\r\nNUMERO : 50948227030\r\nMOEDA : BRL\r\nVALORLOCAL : \r\nNSU : \r\n----------------------------------------\r\n\r\n"
  },
  "settleDate": "0001-01-01T00:00:00",
  "createDate": "2022-04-06T14:29:27",
  "transactionId": 816057734,
  "Urlreceipt": null,
  "errorCode": "000",
  "message": null,
  "status": 0
}

Estrutura de dados do response:

Campo

Tipo

Descrição

nsuNameProvider

int

Identificador da operadora
do lado do cliente

authentication

int

Retorna o número autenticação do nosso sistema

authenticationAPI

Código de autenticação Celcoin

receiptData

DateTime

Informa a data em que a operação foi realizada.

receiptFormatted

String

Retorna o comprovante da transação formatado.

settlerDate

Datetime

Data Liquidação

createDate

Datetime

Data da operação

transationId

Int

Retorna o protocolo da operação

urlReceipt

String

URL do recibo

errorCode

String(3)

Mostra o código do erro

message

String(100)

Reporta a descrição do erro

status

String(30)

Mostra o status da operação

🚧

Atenção!

Recomendamos que seja armazenada a propriedade transactionId, pois ela será utilizada para executar o pagamento e caso exista uma intermitência, ou necessidade para consultar o status dessa transação.

O campo receiptformatted contém um comprovante que pode ser apresentado para o usuário validar se deseja de fato realizar a recarga.

Executar o pagamento de uma recarga

Após o usuário aprovar o pagamento da recarga no aplicativo da Fintech, deve ser realizado a requisição Confirmar uma transação de recarga, onde será aprovado o pagamento daquela recarga e de fato usado o saldo da conta bolsão Celcoin.

Modelo de requisição:

curl --location --request PUT 'https://sandbox.openfinance.celcoin.dev/v5/transactions/internationaltopups/816057734/capture' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
  "externalNSU": 123,
  "externalTerminal": "41233"
}'

Perceba que precisa ser usado o transactionId como querystring para executar essa chamada.

Modelo de retorno:

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

Caso a propriedade message seja SUCESSO e o errorCode 000, a Fintech pode retirar o saldo da conta do usuário e informar que a recarga foi realizada.

Criamos um protótipo para exemplificar como será a jornada do usuário e como a aplicação da Fintech pode se comportar, porém o design e UX não precisa ser exatamente assim o exemplo é apenas ilustrativo.

Medida de prevenção quando ocorrer uma intermitência na API da Celcoin.

Uma vez que a Fintech sofrer uma intermitência ao tentar se comunicar com as APIs da Celcoin, no processo de Confirmar uma transação de 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 uma transação de recarga, para que a liquidação ocorra com sucesso.

Modelo de requisição:

curl --location --request PUT 'https://sandbox.openfinance.celcoin.dev/v5/transactions/internationaltopups/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.

Como 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 internacionais solicitadas na API em d-1.

Movimentação:
RECINTERNACIONAL_MOV_ID + 9(4) – ID DO CLIENTE INTERNO + _NSA + (9(6) – NOTA DE DÉBITO) +
_DATA +AAAAMMDD – DATA CONTABIL DA NOTA DE DÉBITO

Exemplo:
RECINTERNACIONAL_MOV_ID0002_NSA001500_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 = 45 (RECARGAINTERNACIONAL)

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-COD-PAIS

Código do país

Não

10

184

193

9(10)

IF-TELEFONE

Número de telefone

Não

50

198

243

9(50)

IF-VALOR-TRANS-DOLAR

Valor da transação em dólar

Sim

15

218

258

9(15)

FILLER

Brancos

Sim

36

269

294

X(36)

IF-SEQ

Sequencial que indica o número do registro dentro do
arquivo. O header deverá ser montado com o sequencial
(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?