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.

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

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:

🚧

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

Body

Se Código Transação = 45 (RECARGAINTERNACIONAL)

Trailer