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 dígito da conta na propriedade digitCode.

O número da agência na propriedade branchCode

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.

🚧

Bloqueio de segurança nas solicitações de transferências TED

Com o objetivo de oferecer maior segurança e prevenir possíveis fraudes ou erros operacionais que poderiam resultar em transações duplicadas, implementamos um bloqueio em nossas APIs.

Quando uma transferência for solicitada com os mesmos dados em menos de 60 segundos, o Banktransfer automaticamente rejeitará essa transação.

Dados que iremos validar na solicitação de transferência:

• document
• accountCode
• digitCode
• branchCode
• valuebankAccount
• institutionCode
• institutionIspb

O bloqueio será ativado somente se todos os dados acima forem idênticos dentro de um intervalo de 60 segundos.

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

Body

Se Código Transação = 33 (TRANSFERENCIA)

Trailer