Sobre as transferências

Essa funcionalidade permite realizar transferências de forma online, fazendo com que o envio junto ao banco destino seja realizado imediatamente e o cliente receba o status desta transferência no mesmo instante.

O que eu vou aprender nesse artigo?

  • Como realizar uma transferência

  • Como consultar o status de um transferência.

  • Como realizar a configuração de um webhook para receber as devoluções de uma transferência.

  • Como configurar o envio de arquivos de movimentação via SFTP.

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.

Criamos o protótipo abaixo para exemplificar a interface:

Como realizar uma transferência

Para realizar uma transferência com a Celcoin é muito simples, basta realizar uma requisição na API Efetuar uma transferência bancária.

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/v5/transactions/banktransfer' \
--header 'Accept: application/json' \
--header 'Content-Type: application/*+json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '
{
     "document": "35914746817",
     "externalTerminal": "123",
     "externalNSU": 123,
     "accountCode": "379424",
     "digitCode": "5",
     "branchCode": "30",
     "name": "Fulano de tal",
     "value": 5,
     "bankAccountType": "CC",
     "institutionIspb": "30306294"
}
'

Perceba que é necessário enviar o CPF, ou CNPJ na propriedade document.

O número da conta do cliente na propriedade accountCode.

O número da agência na propriedade branchCode e o dígito em digitCode.

O nome do cliente ou empresa deve ser preenchido no campo name.

A propriedade bankAccountType , deve ser populado com o tipo da conta podendo ser CC (conta corrente) ou CP (conta poupança).

A propriedade Intitutionspb, deve ser preenchida com o Ispb (identificador da instituição participante do Pix). Para encontrar a relação desses códigos recomendamos que entre no artigo

O campo value deve ser preenchido com valor que será realizado a transferência.

O campo externalNSU (sequencial da transação do lado do cliente) não é obrigatório na requisição, mas caso o cliente envie este campo, o mesmo não poderá ser repetido em uma próxima requisição;

📘

No payload dessa requisição, o campo institutionIspb, que trata-se do código de participante do banco destinatário no arranjo Pix, deve ser enviado com o código ISPB ou com as chaves vazias (exemplo: "institutionIspb": "").
Caso ele não seja preenchido com o código, ou seja, se informado vazio, é necessário informar o institutionCode.

Modelo de retorno:

{
  "authenticationAPI": {
    "bloco1": "CC.D7.0F.AF.BF.76.8B.D8",
    "bloco2": "E3.30.DC.BF.C5.FB.5F.54",
    "blocoCompleto": "CC.D7.0F.AF.BF.76.8B.D8.E3.30.DC.BF.C5.FB.5F.54"
  },
  "receipt": {
    "receiptData": "",
    "receiptformatted": "                 IS2B \r\n           PAGUESUACONTA.COM\r\n               IS2B TESTE\r\n          PROTOCOLO 0007110444\r\n1          24/06/2021        19:59\r\nTERM 228005 AGENTE 228005 AUTE 03973\r\n----------------------------------------\r\nAUTO 931554               TRANSFERENCIA\r\n \r\nCODIGO BANCO: 341\r\nAGENCIA: 371\r\nCONTA: 1232\r\nNOME: FULANO DE TAL\r\nCPF/CNPJ: 37141268804\r\nVALOR: 50,00\r\n \r\n----------------------------------------\r\n              AUTENTICACAO\r\n        66.90.12.35.14.7A.87.88\r\n        59.8F.C9.E5.BE.61.7B.06\r\n----------------------------------------\r\n"
  },
  "destinationAccountData": {
    "agency": 371,
    "institutionCode": 341,
    "account": 123,
    "accountVerifierDigit": "2",
    "document": "11122233344",
    "institutionName": "BANCO ITAU S.A.",
    "fullName": "Fulano de tal",
    "bankAccountType": 0,
    "documentType": "cpf",
    "value": 50
  },
  "createDate": "2021-06-24T11:31:10",
  "dateNextLiquidation": "2021-06-25T11:31:10",
  "nextSettle": true,
  "transactionId": 7110444,
  "endToEnd": "E1393589320211025185700524045867",
  "urlreceipt": "https://www.celcoin.com.br",
  "errorCode": "000",
  "message": "SUCESSO",
  "status": 0
}

🚧

Atenção!

Recomendamos que seja disponibilizado o comprovante da transferência para o usuário final da sua aplicação, consumindo da propriedade receipt.receiptformatted, ou montando conforme sua necessidade.

Fora isso deve ser armazenado o transactionId, pois ele será utilizado para validar se a transferência ocorreu de fato com sucesso, ou se ocorreu uma devolução do dinheiro por parte da instituição financeira recebedora.

Consultar o status de uma transferência.

Caso você queira saber o status de uma transferência, basta realizar um GET na API Consulta o status de uma transferência.

Modelo de request:

curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/v5/transactions/banktransfer/status-transfer/9198697' \
--header 'Authorization: Bearer {access_token}' \

Modelo de retorno

{
    "authentication": 0,
    "createDate": "2022-03-24T14:30:33",
    "refundReason": "",
    "externalNSU": "3123123123",
    "transactionId": 9198697,
    "stateCompensation": "Processado com sucesso",
    "externalTerminal": "123",
    "typeTransactions": null,
    "errorCode": "000",
    "message": "SUCESSO",
    "status": 0
}

Como realizar a configuração de um webhook para receber as devoluções de uma transferência

Para recebimento das transferências que não foram realizadas, disponibilizamos um webhook para retorno destas transações, ou envio do arquivo de “movimentação” e “recusas” em d+1, via SFTP.

Mas como configuro esse webhook?

Deve ser encaminhado os seguintes dados para nossa equipe de suporte realizar as configurações:

● Endpoint;
● Login;
● Senha.

O request será encaminhado com login e senha no formato Base64(basic Authentication).

Iremos retornar o status da compensação com o motivo da devolução da seguinte forma:

{
    "NsuExterno": 6088611,
    "TerminalExterno": "Celcoin",
    "ProtocoloId": 952766221,
    "TipoTransacao": "TRANSFERENCIA",
    "DadosTransacao": {
        "DataOperacao": "2022-03-19T14:22:21.127",
        "DataDevolucao": "2022-03-19T14:24:01.503",
        "Cpfcnpj": "12948038612",
        "Agencia": 318,
        "Conta": "0",
        "DigitoVerificador": "6",
        "NomeCompleto": "Tairony ferreira Fernandes ",
        "Valor": 5.0000
    },
    "StatusCompensacao": {
        "Status": "ERRO",
        "CodErro": "PBE326",
        "MensagemErro": "Creditor account number invalid or missing"
    }
}

Nosso envio de gatilhos opera 24x7, com envios de 15 em 15 minutos e caso o webhook configurado não nos retorne status http 200 (OK), nossa API tentará enviar novamente durante 24 horas, até que nos retorne o status OK;

🚧

Atenção!

As transferências podem ser realizadas 24/7. Após o retorno do processamento com sucesso, a transferência feita via TED terá o prazo de até 3 dias úteis para uma possível devolução do banco destinatário e em caso de PIX o tempo de devolução é de até 15 minutos.
Em ambos os casos será disparado um webhook com essa atualização e o status da transferência será alterado para devolvida.

O produto possui apenas uma etapa, por isso, sugerimos que a integração esteja preparada para tratar requisições duplicadas, tanto por uma eventual falha sistêmica, quanto para um comportamento adverso 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 todas as transferências solicitadas na API em d-1.

O arquivo de recusa contempla todas as transferências devolvidas na compensação em d-1.

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

Exemplo:
TRANSFERENCIA_MOV_ID0002_NSA001501_DATA20160901

Recusa:
TRANSFERENCIA_REC+ 9(4) – ID DO CLIENTE INTERNO + _NSA + (9(6) – NOTA DE DEBITO +
_DATA + AAAAMMDD – DATA CONTABIL DA NOTA DE DEBITO

Exemplo:
TRANSFERENCIA_REC_ID0002_NSA001501_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 = 33 (TRANSFERENCIA)

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)

ID-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 (AAAAM
MDD)

Sim

8

38

45

9(8)

IF-HORA-TRANS

Hora da transação (HHMMSS)

Sim

6

46

51

9(6)

IF-DESCRICAO

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-TERMIN ALEXTERNO

Número do terminal Externo

Não

50

112

161

X(50)

IF-NUM-SEQ-EX TERNO

Número do 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-CPFCNPJ

Número CPF ou CNPJ da conta
bancária

Não

14

184

197

9(14)

IF-NOMECOMPLETO

Nome completo da conta
bancária

Não

50

198

247

X(50)

IF-NUM-BANCO

Número do Banco da conta
bancária

Não

3

248

250

9(3)

IF-TIPO-CONTABANCARIA

Tipo da conta bancária, se é
CC-conta corrente ou CP-conta poupança

Não

2

251

252

X(2)

IF-AGENCIA-SEM-DV

Número da conta bancária
sem dígito verificador

Não

4

253

256

9(4)

IF-NUM-CONTA

Número da conta bancária
sem dígito verificador

Não

10

257

266

9(10)

IF-DV

Dígito verificador da conta
bancária

Não

2

267

268

X(2)

FILLER

Brancos

Sim

26

269

294

X(26)

IF-SEQ

Sequencial que indica o
número do registro dentro do
arquivo. O header deverá ser
montado com o sequencial

  1. (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?