Procedimento Técnico de Handshake

​

Introdução

O handshake é um procedimento técnico essencial de autenticação de segurança realizado entre a BMP e seus parceiros.

Ele garante a integridade dos dados e estabelece uma comunicação criptografada e segura, assegurando que todas as partes envolvidas concordem com os parâmetros necessários antes do início da troca de informações. Isso previne acessos não autorizados e reforça a confiabilidade das operações financeiras.

Esse processo funciona como uma etapa inicial de “negociação” entre duas partes, na qual são definidos os parâmetros técnicos da comunicação. Durante o handshake, as partes se identificam mutuamente, validam suas identidades e estabelecem um canal seguro para o tráfego de dados.

Nas transações financeiras, o handshake permite que a BMP e seus parceiros confirmem suas identidades antes de seguir com a operação. Com isso, o procedimento ajuda a mitigar riscos de acessos indevidos, ataques cibernéticos e fraudes.

Para realizar o procedimento técnico de handshake é necessário se atentar aos seguintes parâmetros:

• Protocolo de comunicação utilizado é HTTPS;
• Os dados devem ser enviados e são recebidos no formato JSON;
• Medidas de segurança aplicada, como criptografia e autenticação;
• A versão da API que será utilizada.

Saiba mais sobre a obrigatoriedade do handshake em endpoints específicos abaixo.

Para a API Externa, os seguintes endpoints são protegidos pelo handshake:

• /api/Boleto/Pagar: para pagamento de boletos;
• /api/TransferenciaOutroBanco: para transferências entre contas de instituições financeiras diferentes (TED);
• /api/TransferenciaEntreContas: para transferências entre contas internas da BMP;
• /api/CNAB/240/Importar: para pagamentos de boletos ou transferência em lote.

Para a API do PIX, os seguintes endpoints são protegidos pelo handshake:

• /api/Recurso/Tranferir: para transferências via PIX;
• /api/Recurso/Devolver: para devoluções de valores enviados via PIX.

​

Pré-requisitos

Para que a BMP possa configurar adequadamente a validação de segurança por meio do handshake, o parceiro deve se atentar as seguites informações:

• Deve configurar um endpoint HTTPS que aceite requisições POST. O endpoint deve responder dentro de um timeout padrão de 5 segundos para garantir eficiência no processo de handshake. As informações necessárias incluem URL do endpoint disponibilizado na API do parceiro;
• Método HTTPS;
• Headers desejados.
• Chave HMAC.

​

Chave HMAC

A chave HMAC também é um pré-requisito para o processo de handshake. O parceiro deve gerar uma chave HMAC forte e segura, com 128 caracteres.

Essa chave será utilizada para assinar as mensagens e verificar a assinatura das mensagens recebidas da BMP.

​

Headers

É necessário informar os headers Content-Type e IdempotencyKey. O header Content-Type deve ser definido como application/json, enquanto o header IdempotencyKey deve conter um valor único para cada requisição, garantindo que a BMP possa identificar e evitar duplicações de transações.

Exemplo de headers:

--header 'Authorization: Basic Ym1wX3dpc2VfaGFuZHNoMAtlOlJaU2dLclBTbGVKaTV3cWl2cTBjZXF2bVBVOFV6VkR2bUutVGtIeVBxTXFFRFFvVGYwbXYwV3M1a1pZRzZvWmN4OXFrRAV0Zm5NVHhrd09qVnJ2OVRGRlNMSGttVmxhWHJQanJhU1hYTkk4TDM5' \
--header 'Content-Type: application/json' \
--header 'IdempotencyKey: <idempotencykey>' \

​

Body

As requisições do processo de handshake devem ser enviadas sempre com o body linearizado (minificado ou compactado), sem espaços. Dessa forma:

{"TipoTransacao":"EnvioTED","DataTransacao":"2025-02-14","Valor":1345.83}

Além disso, o parceiro precisa se preocupar com valores numéricos, que devem ser sempre no formato decimal.

Exemplo:

{"Valor": 1345.83}

​

Etapas do processo de handshake

O processo de handshake da BMP inicia-se a partir da requisição para um endpoint da API da BMP, que exige este tipo de validação.

O endpoint, após receber a requisição, executa uma série de ações, das quais uma delas é a confirmação da transação através da chamada de um endpoint da API do parceiro configurado para a finalidade do handshake.

​

1. Início da Transação via API BMP com Validação por Handshake

Nessa primeira etapa, o parceiro envia uma requisição de transação para a API da BMP que exige validação por meio do handshake.

Nesta etapa, o parceiro, já conhecendo que a requisição a ser enviada, exige validação mediante hanshake, deverá executar as seguintes ações:

• Gerar o JSON do corpo da requisição com os dados da transação a ser executada;
• Gerar um hash HMAC SHA-512 do JSON da requisição com a chave para validação do handshake que foi configurada na BMP;
• Adicionar o hash gerado à chave HMAC no cabeçalho da requisição;
• Enviar a requisição para o endpoint da API da BMP;
• Receber o response HTTPS da requisição enviada para a API da BMP;
• Realizar as tratativas após receber o response da requisição enviada para a API da BMP.

​

2. Processo de Validação e Confirmação de Transações no BMP

BMP recebe a requisição do parceiro, valida o hash recebido, solicita a confirmação da transação para o parceiro e aguarda o retorno da confirmação

Quando a BMP receber uma requisição que exige autenticação através de handshake, o middleware de validação entrará em ação, executando as seguintes ações:

1. Validação Inicial da Requisição:

   • A BMP analisa os headers da requisição recebida.
     • Se os headers estiverem corretos:
       • Responde com 200 - OK.
       • Prossegue para a próxima etapa.
     • Se os headers estiverem incorretos:
       • Retorna:

         406 - Não foi possível fornecer o recurso solicitado em um formato aceitável para o cliente

       • Encerra o processo.

2. Validação do Handshake

   • A BMP gera um hash HMAC SHA-512 usando:
     • O body da requisição.
     • A chave de validação do handshake.
   • O hash gerado é retornado ao parceiro.
   • A BMP compara o hash gerado com o hash recebido:
     • Se forem iguais: o processo segue.
     • Se forem diferentes:
       • Retorna:

         406 - Não foi possível fornecer o recurso solicitado em um formato aceitável para o cliente

       • Encerra a execução do endpoint.

3. Confirmação da Transação com o Parceiro

   • A BMP prepara a requisição de confirmação da transação:
     • Inclui os dados da transação original.
     • Adiciona headers específicos, se exigidos pelo parceiro.
   • O parceiro recebe a requisição de confirmação:
     • Verifica os headers obrigatórios:
       • Se estiverem ausentes ou incorretos, encerra a execução.
   • O parceiro valida os dados da confirmação com os dados da solicitação original:
     • Se divergirem, a execução é encerrada.
   • O parceiro gera um novo hash HMAC SHA-512 a partir do JSON recebido, utilizando a mesma chave do handshake.
   • O hash é adicionado no header da resposta na chave "hmac".
   • O parceiro retorna:
     • HTTP 200 indicando sucesso.
     • Encerra a execução do endpoint de confirmação.

4. Validação Final pelo BMP

   • A BMP analisa o status HTTP da resposta do parceiro:
     • Se for diferente de 200, retorna:

       406 * Não foi possível fornecer o recurso solicitado em um formato aceitável para o cliente

       e encerra a execução.
   • A BMP gera novamente o hash HMAC SHA-512 com o JSON da confirmação.
   • Compara o novo hash com o valor da chave "hmac" no header recebido:
     • Se forem diferentes, retorna erro 406 e encerra a execução.
   • Se forem iguais:
     • Dá sequência à execução do endpoint da transação.
     • Retorna o response code e o JSON da mensagem da transação.
     • Se houver erro, retorna 406 com a mensagem de recurso inaceitável.

​

Referências para o body das requisições de handshake

​

Pagamento de boletos

​

Transferências entre contas de instituições financeiras diferentes (TED)

​

Transferências entre contas internas da BMP

​

Envio de valores através do PIX

​

Devolução de valores recebidos através do PIX