Sobre Saques e depósitos

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

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.

O que é TecBan?

Empresa dona dos caixas 24 horas disponibilizados em postos de gasolina, mercados e etc. Seu principal negócio é o Banco24Horas, que está presente na vida de 152 milhões de brasileiros.

🚧

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?

Nessa transação o usuário acessa o aplicativo e procura pela opção de Saque com Qrcode, onde será apresentado uma tela solicitando o valor que ele deseja sacar. Após digitar o valor, será necessário escanear o Qrcode.

Nesse momento o usuário deve ir a um caixa 24 horas, acessá-lo e escolher a opção de realizar saque com Qrcode, onde será apresentado o Qrcode que deve ser escaneado no aplicativo, ou sistema da Fintech.

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.

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.

Como executar um saque com token?

Para essa transação de saque o usuário deve conseguir acessar o aplicativo, onde será apresentado a opção de Saque via token, onde é necessário preencher o valor que deseja realizar o saque e clicar em gerar token.

Nesse momento será apresentado para ele uma tela de inserção do token, onde ele acessa seu aplicativo para gerar esse token. Nesse momento a aplicação da Fintech, deve realizar a chamada Gerar um token para um saque no caixa 24h.

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 deve ser preenchido os seguintes campos:
externalTerminal : Identificador do terminal do sistema cliente
externalNSU: Identificador da transação do sistema cliente
receivingDocument: Documento do recebedor:
receivingName: Nome do recebedor
value: valor da transação

Modelo retorno:

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

Note que é retornada uma propriedade token, ela deve ser exibida para o usuário do seu aplicativo usar no caixa 24 horas.

Uma vez que o usuário digitar o token, será disponibilizado pelo caixa 24 horas o valor, em seguida a TecBan irá notificar a Celcoin, que por sua vez irá retirar o valor da sua conta bolsão.

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

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

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

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

80

112

191

X80)

IF-NUM-SEQ-EXTERNO

Número da Sequencial Externo

Não

20

192

211

9(20)

IF-COD-PAGTO

Número da Forma de
Pagamento (ver Tabela 2)

Não

2

212

213

9(2)

IF-CPFCNPJF

Número CPF ou CNPJ da conta
bancária

Não

14

214

227

9(14)

IF-NUMEROPEDIDO

Identificador do
correspondente

Não

20

228

247

9(20)

FILLER

Brancos

Sim

26

248

273

X(26)

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

274

279

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?