Essa funcionalidade permite que sejam realizados depósitos, ou saques através de um Qrcode, ou token nos caixas 24 horas disponibilizados em mercados e postos de gasolina pela TecBan.

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 Celcoin 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.

• Ter o produto Tecban contratado.

• Após finalizar a integração, realizar a homologação.

O que é o Banco24Horas?

O Banco24Horas é uma marca da TecBan que está presente em mais de 23 mil terminais distribuídos em todo território nacional.

Por meio desses terminais é possível realizar diversas transações, com ou sem cartão, entre elas saques e depósitos que são objetos desse documento.

🚧

Atenção!

Para todos modelos de integração abaixo, deve ser realizado a autenticação em nossa api, para mais informações de como realizar esse processo por favor acesse o link

Como funciona um saque no caixa eletrônico com Qrcode?

Antes de acessar o terminal do Banco24Horas o cliente deverá iniciar uma jornada em seu aplicativo. Dentro do aplicativo o usuário irá procurar pela opção de Saque com Qrcode ou nomenclatura escolhida.

No aplicativo deverá ser solicitado em tela o valor que o cliente deseja sacar, em múltiplos de 20, 50 e 100, as notas mais comuns nos terminais.

Após escolha, ainda em seu aplicativo, deve ser aberta a câmera para realizar a leitura do QR Code.

Nesse momento o usuário deve ir a um terminal do Banco24Horas, acessá-lo e escolher a opção Saque Digital, Saque QR Code, onde será gerado e apresentado o Qrcode que deve ser escaneado no aplicativo, ou sistema da Fintech.

📘

Vale lembrar!

• Esse QR Code tem validade de cerca de 45 segundos, o que é mais que suficiente para leitura, validação e saque.
• É importante informar no seu aplicativo que o cliente deverá ter o saldo suficiente no momento que for realizado o saque incluindo eventuais tarifas cobradas em seu ambiente.
• Não são permitidos valores de saque que não sejam múltiplos de 20, 50 e 100. Adicionalmente, após leitura do QR code deve ser validado se o valor é múltiplo das notas disponíveis naquele terminal onde o QR Code foi gerado. Caso não seja, o cliente deve escolher outro valor ou dirigir-se para outro terminal não devendo seguir com o saque nessas condições neste terminal, pois poderá gerar ocorrências tarifadas
• Dentro desse Qrcode será apresentado uma string que deve ser utilizada para popular a propriedade transactionIdentifier (id da transação, que será disponibilizado pela TecBan), para realizar a chamada de Efetuar um Saque eletrônico com Qrcode.

🚧

Atenção!

Recomendamos que em ambiente sandbox seja utilizado o transactionIdentifier populado com valor "05e07b49-f57a-453c-b5e7-46ebe7bc5037", pois nosso ambiente sandbox está preparado para retornar sucesso para esse UUID.

Com os dados lidos e o terminal identificado, deve ser feita a chamada na API de saque utilizando informações recuperadas do QR Code lido. Nesse momento pode ser enviado um texto e um código numérico para ser digitado como fator adicional de autenticação no terminal.

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/v5/transactions/electronictransactions/electronic-receipt' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
  "externalNSU": 1234,
  "externalTerminal": "11122233344",
  "receivingContact": "944445555",
  "receivingDocument": "11122233344",
  "transactionIdentifier": "05e07b49-f57a-453c-b5e7-46ebe7bc5037",
  "receivingName": "Fulano de tal",
  "namePartner": "TECBAN_BANCO24H",
  "value": 150,
  "secondAuthentication": {
    "dataForSecondAuthentication": 12345,
    "textForSecondIdentification": "ID do usuário",
    "useSecondAuthentication": false
  }
}'

Perceba que nessa requisição deve ser enviado os campos:

externalTerminal : Identificador do terminal do sistema cliente
externalNSU: Identificador da transação do sistema cliente
receivingContact: Contato telefônico do usuário, não deve ser preenchido com caracteres especiais.
receivingDocument: Documento CPF ou CNPJ do usuário.
transactionIdentifier: Id da transação de saque gerado no Qrcode.
namePartner: deve ser preenchido como TECBAN_BANCO24H
value: Valor da transação
secondAuthentication.dataForSecondAuthentication: dados para segunda autenticação.
textForSecondIdentification: texto para segunda autenticação.
useSecondAuthentication : Por padrão usar false.

📘

O campo value deve ser preenchido com valor maior que R$20.00, devido a obrigatoriedade de valor mínimo para o saque do caixa 24 horas.

Modelo retorno:

{
    "BarCodeBase64": null,
    "convenant": "0720",
    "externalWithdrawIdentifier": "27cd1b67-976d-4ab1-a2f4-017492c2ed21-0124",
    "transactionIdentifier": "05e07b49-f57a-453c-b5e7-46ebe7bc5037",
    "orderNumber": null,
    "product": null,
    "transactionId": 816055786,
    "QRCodeBase64": null,
    "token": null,
    "value": 150.0,
    "errorCode": "000",
    "message": "SUCESSO",
    "status": 0
}

🚧

Atenção!

Recomendamos que seja realizado o armazenamento da propriedade transactionId, pois ela será utilizada para validar se a transação ocorreu com sucesso.

Após escanear o QrCode, consumir o transactionIdentifier e realizar a requisição citada acima, nossa aplicação irá se comunicar com a TecBan que irá disponibilizar o dinheiro para o usuário, em seguida a Celcoin irá retirar o valor usado para a transação de saque da sua conta bolsão.

Para validar se essa transação ocorreu com sucesso, seu aplicativo deve consultar a Celcoin através da API Consultar informações de uma transação, utilizando o transactionId retornado na chamada anterior.

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

{
  "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"
}

É possível validar se a transação ocorreu com sucesso através campo errorCode, uma vez que preenchido com 000, mostra que o retorno é sucesso, desta forma, a Fintech pode retirar o saldo usado para a transação dá conta de seu usuário.

Dentro do objeto transaction também é possivel realizar validaçōes utilizando a propriedade status que pode ser retornada com o seguintes valores:

0 - SUCESSO
1 - Transação não encontrada
6 - PENDENTE_DESFAZIMENTO_AUTORIZADOR
4 - ESPERANDO_CONFIRMACAO_CLIENTE

🚧

Temos um valor limite de R$1.200,00 por saque ou 20 notas.

Não temos limite de depósitos por CPF/CNPJ

🚧

Atenção!

• Caso haja um problema de conexão, queda de energia ou outro problema com o terminal, poderá ser retornado um erro e o valor não deve ser estornado até que seja recebido o webhook de confirmação de que a liberação do valor não ocorreu. Esse webhook pode ser enviado minutos após a transação ou até 2 dias úteis seguintes caso seja necessário confirmação com o arquivo de conciliação.
• Em casos de mal funcionamento do terminal, queda de conexão ou outros não cabíveis ao cliente, não será cobrada tarifa pelo saque.
• Em caso de saque sem saldo, será cobrada tarifa.
• Caso haja algum problema com o saque, o cliente deve ser orientado a buscar inicialmente atendimento com o Banco24Horas, pois este é o canal mais rápido e certo em caso de problemas e solução online. Um ticket deve ser aberto junto à Celcoin apenas após o período de conciliação e não resolução direto com o Banco24Horas.

Como funciona um saque no caixa eletrônico com Token?

Para realizar o saque via token, o primeiro passo acontece no APP da fintech, onde o cliente após acessa-lo escolhe a opção de saque digital com Token ou nomenclatura escolhida. Em seguida o usuário define um valor baseado em múltiplos de 20, 50 e 100, as notas mais comuns nos terminais.

Caso o saque seja realizado pelo dono da conta, não é necessário coletar mais informações. No caso ser um pagamento para terceiros é necessário identificar quem realizará o saque através do Nome Completo e CPF, pois essas informações são necessárias para o request.

Após isso, o cliente clica em gerar token.

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/v5/transactions/electronictransactions/withdraw-thirdparty' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
  "externalNSU": 1,
  "externalTerminal": "123123",
  "receivingDocument": "11122233344",
  "receivingName": "fulano de tal",
  "value": 20
}'

Perceba que devem ser preenchidos os seguintes campos:

externalTerminal : Identificador do terminal do sistema cliente
externalNSU: Identificador da transação do sistema cliente
receivingDocument: Documento CPF do recebedor
receivingName: Nome do recebedor
value: valor da transação

📘

Vale Lembrar !

• Ainda em seu aplicativo, o cliente deverá escolher se o valor a ser sacado será retirado pelo próprio titular ou por outra pessoa. É necessário enviar o nome completo e o CPF de quem irá fazer o saque, pois o CPF servirá como chave para o saque.
• Nesta modalidade não é permitido gerar um saque para pessoa jurídica (CNPJ), apenas pessoa física (CPF).
• Caso seja necessário, você pode realizar possíveis confirmações adicionais no APP como digitação de senha ou biometria, após as etapas de segurança adicionais você deve debitar a conta do seu usuário e em caso de sucesso usar a API Celcoin para registrar um token.

Modelo retorno:

{
    "convenant": "0720",
    "transactionIdentifier": null,
    "transactionId": 816055814,
    "token": "0720199812",
    "value": 20.0,
    "errorCode": "000",
    "message": "SUCESSO",
    "status": 0
}

Após confirmação de token gerado, ele deve ser exibido para o cliente.

📘

Vale Lembrar!

• Deve ser observada a instrução no caso de um terceiro realizar o saque.
• Caso o saque não seja realizado no mesmo momento, você pode optar por armazená-lo e exibi-lo novamente para evitar a geração de um novo código. A forma de compartilhá-lo com terceiros irá depender da experiência e segurança praticados.
• Note que é retornada uma propriedade token, ela deve ser exibida para o usuário do seu aplicativo usar no terminal Banco24Horas.
• Um token tem duração padrão de 4 horas. Uma vez gerado, não é possível fazer a exclusão do token.
• É importante destacar que, caso o usuário decida gerar um novo código pois perdeu ou se esqueceu do anterior, ambos ficarão válidos e poderão ser realizados. Assim, é importante avaliar as formas de reexibição de um token.

Em seguida, a pessoa responsável pelo saque deve se dirigir a um terminal do Banco24Horas dentro do período de validade do token e acessar o Saque Digital e em seguida Saque com Token.

Será solicitado em tela o CPF e o token. Nesse momento a Celcoin será acionada e fará a verificação quanto à disponibilidade de saldo com a Fintech. Havendo o saldo, o valor será liberado.

Cancelamento do Token

Caso no seu modelo de negócio tenha a necessidade de realizar o cancelamento do token, basta realizar a requisição de cancelamento, passando o transactionId que é retornado na solicitação de gerar token. Com isso revogaremos o token da transação solicitada.

Segue abaixo o exemplo de como realizar essa requisição:

Modelo request:

curl --location --request DELETE 'https://sandbox.openfinance.celcoin.dev/v5/transactions/821401076/void' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{}'

Modelo retorno:

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

📘

Após a finalização do saque, o token passa a ficar indisponível para uso, ou seja, pode ser utilizado uma única vez.

🚧

Temos um valor limite de R$1.200,00 por saque ou 20 notas.

Não temos limite de depósitos por CPF/CNPJ

🚧

Atenção !

• Caso haja um problema de conexão, queda de energia ou outro problema com o terminal, poderá ser retornado um erro e o valor não deve ser estornado até que seja recebido o webhook de confirmação de que a liberação do valor não ocorreu. Esse webhook pode ser enviado minutos após a transação ou até 2 dias úteis seguintes caso seja necessário confirmação com o arquivo de conciliação.
• Em casos de mal funcionamento do terminal, queda de conexão ou outros não cabíveis ao cliente, não será cobrada tarifa pelo saque.
• Em caso de saque sem saldo, será cobrada tarifa.
• Caso haja algum problema com o saque, o cliente deve ser orientado a buscar inicialmente atendimento com o Banco24Horas, pois este é o canal mais rápido e certo em caso de problemas e solução online. Um ticket deve ser aberto junto à Celcoin apenas após o período de conciliação e não resolução direto com o Banco24Horas.

Para a Fintech validar se essa transação de saque ocorreu com sucesso, deve realizar um GET na API Consultar informações de uma transação, utilizando o transactionId retornado na chamada anterior.

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"
}

É possível validar se a transação ocorreu com sucesso através do campo errorCode, uma vez que preenchido com 000, mostra que o retorno foi um sucesso, desta forma pode ser retirado o saldo da conta de seu cliente em seu aplicativo.

Como funciona um depósito eletrônico com a Celcoin?

Para realizar um depósito eletrônico o usuário precisa abrir seu aplicativo da Fintech e selecionar a opção Depósito com Qrcode, onde será apresentado uma tela pedindo para inserir o valor da transação e após confirmar o valor, será necessário escanear o Qrcode.

Nesse momento ele precisa ir até um caixa 24 horas, acessar a opção depósito bancário, onde o caixa irá disponibilizar um Qrcode para escanear.

Ao escanear o Qrcode, a Fintech deve iniciar o processo de comunicação com a API Realizar um depósito em um caixa 24h.

🚧

Atenção!

Ao decodificar o Qrcode será apresentado uma string que será utilizada nessa requisição como valor da propriedade transactionIdentifier.

Recomendamos que essa propriedade seja preenchida com o valor "Banco24Horas/DepositoDigital/v1/a0a0d296-3754-454d-bc0c-b1c4d114467f/ea9dd655/1240004", para testes em ambiente sandbox, pois nosso ambiente está preparado para receber esse valor e processar a transação com sucesso.

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/v5/transactions/electronictransactions/electronic-payment' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
  "externalNSU": 1234,
  "externalTerminal": "11122233344",
  "payerContact": "944445555",
  "payerDocument": "11122233344",
  "transactionIdentifier": "Banco24Horas/DepositoDigital/v1/a0a0d296-3754-454d-bc0c-b1c4d114467f/ea9dd655/1240004",
  "payerName": "Fulano de tal",
  "namePartner": "TECBAN_BANCO24H",
  "value": 150
}'

Perceba que deve ser preenchido os seguintes campos:
externalTerminal : Identificador do terminal do sistema cliente
externalNSU: Identificador da transação do sistema cliente
payerContact: Nome do contato
payerDocument: Documento do contato.
transactionIdentifier: Id da transação que será disponibilizado dentro do Qrcode ao escaniar o caixa 24 horas.
payerName: Nome do pagador
namePartner: Descritivo do parceiro por padrão deve ser preenchido com TECBAN_BANCO24H
value: Valor do deposito.

Modelo de retorno

{
    "BarCodeBase64": null,
    "convenant": "0720",
    "orderNumber": "a0a0d296-3754-454d-bc0c-b1c4d114467f",
    "product": null,
    "transactionId": 816055940,
    "QRCodeBase64": null,
    "token": null,
    "value": 150.0,
    "errorCode": "000",
    "message": "SUCESSO",
    "status": 0
}

Ao receber o retorno de Sucesso, pode ser apresentado para o usuário que tudo ocorreu como esperado e ele pode inserir as cédulas de dinheiro na máquina para realizar o depósito. Ao receber o valor, o caixa 24 horas irá notificar a Celcoin que por hora irá imputar o valor do saldo na conta bolsão da Fintech.

Em seguida para a Fintech validar se esse deposito ocorreu com sucesso, deve ser realizado um GET na API Consultar informações de uma transação, utilizando o transactionId retornado na chamada anterior.

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"
}

É possível validar se a transação ocorreu com sucesso através campo errorCode, uma vez que preenchido com 000, mostra que o retorno é sucesso, desta forma pode ser depositado o valor na conta do usuário.

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 todos os saques e depósitos solicitados na API em d-1.

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

Exemplo:
RECEBIMENTOELETRONICO_ID0002_NSA001498_DATA20160901

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

Exemplo:
PAGAMENTOELETRONICO_ID0002_NSA001499_DATA20160901

🚧

Atenção!

Temos um valor limite de R$2.000,00 por depósito.
Não temos limite de depósitos por CPF/CNPJ

Header

Body (SAQUEBANCO)

Se Código Transação = 22 (SAQUEBANCO) ou Código Transação = 23 (DEPOSITOBANCO)

Trailer

Homologação

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