Notificações

Esta página descreve o serviço de notificações, que envia atualizações sobre transações de triagem de fraude.

Visão geral

Notificações da API do Fraud Prevention é uma solução que permite que você se integre ainda mais com o Fraud Prevention. Quando ocorrerem alterações que possam afetar a sua empresa, o Fraud Prevention vai enviar os detalhes da alteração direto aos seus sistemas via mensagens POST padrão. Com as nossas notificações de push, você pode se manter a par de tudo, simplificar operações e garantir que os seus negócios estejam protegidos contra fraudes.

No momento, aceitamos notificações para eventos de triagem de contas e compras de pedidos. Assim, se um analista tiver analisado a transação, você vai receber uma notificação imediata com a resolução e as ações recomendadas.

Esquema e detalhes da mensagem

Nesta seção, vamos nos aprofundar na composição arquitetônica das nossas mensagens, que consiste em duas partes principais: o envelope e o conteúdo da notificação. O envelope incorpora os metadados da notificação, enquanto o conteúdo da notificação inclui os detalhes complexos dela. Vamos detalhar esses componentes.

Esquema do objeto "envelope"

| Campo | Tipo | Valores possíveis | anulável | Exemplo | Descrição |-----------------|---------|------------------------|----------|--------------------------------------|----------------- | event_name | Sequência | MERCHANTSHIELD_FRAUD | false | MERCHANTSHIELD_FRAUD | Nome do evento, que sempre vai ser MERCHANTSHIELD_FRAUD. | creation_time | Sequência | Data e hora (UTC) | false | 2024-01-18T10:29:20.484649887Z | Hora em que o evento de notificação foi criado. | notification_id | Sequência | GUID | false | d72ac517-f0a7-4a65-8547-250cf81ce440 | ID de notificação único | payload | Conteúdo | Objeto Payload | false | | Conteúdo real da notificação Consulte a descrição do esquema do objeto "conteúdo" abaixo.

Esquema do objeto "conteúdo"

Cada mensagem é uma solicitação HTTPS POST com um corpo de mensagem JSON.

Exemplo de atualização de fraude em reserva

{
    "event_name": "MERCHANTSHIELD_FRAUD",
    "creation_time": "2024-01-18T10:29:20.484649887Z",
    "notification_id": "0597ae4c-b6d2-4d47-ba58-36534e04f1cf",
    "payload": {
        "risk_id": "9beabb6d-77b9-474e-852a-3cb9fedabb3a",
        "entity_type": "BookingFraud",
        "entity_id": "1e5092ad-4440-40cf-9a14-0bf76ced339c",
        "decision_date_time": "2024-03-07T22:28:33.552Z",
        "decision": "PASS",
        "recommended_actions": [
            "RELEASE"
        ],
        "partner_account_id": "972edd1c-b50f-4d7e-b5bb-05212aa20d03"
    }
}

Exemplo de atualização de invasão de contas

{
    "event_name": "MERCHANTSHIELD_FRAUD",
    "creation_time": "2024-01-18T10:29:20.484649887Z",
    "notification_id": "c9235ccb-8716-4ac3-a3ad-ef96042aa32a",
    "payload": {
        "risk_id": "d2f0d5ab-cda1-484e-9507-e0fcf81960dc",
        "entity_type": "Account",
        "entity_id": "13538ba1-df41-446c-8266-4f325e4ef264",
        "decision_date_time": "2024-03-07T22:28:33.552Z",
        "decision": "PASS",
        "recommended_actions": [],
        "partner_account_id": "34f8df88-26f3-48f2-a81b-12fae9306192"
    }
}

Integração

Recebimento de uma mensagem

Para começar a receber notificações, você vai precisar de um ponto de extremidade que aceite a mensagem POST que será enviada ao seu ponto de extremidade. O ponto de extremidade deve:

• ser acessível ao público.
• ter HTTPS e TLS 1.2 ou superior habilitados.
• configurar um certificado TLS válido, confiável para a maioria dos aplicativos modernos (um certificado autoassinado pode não ser confiável).

Entre em contato com o seu consultor de integração do Fraud Prevention para configurar e enviar:

• o URL do seu ponto de extremidade para receber mensagens.

Estamos trabalhando para oferecer ferramentas de autoatendimento para você testar a sua integração. Até lá, o seu consultor de integração pode ajudar você com as reservas de teste para confirmar que você está recebendo notificações dos eventos off-line para os quais se inscreveu.

Observações importantes sobre a configuração

• O Fraud Prevention usa servidores baseados em nuvem que garantem que os seus pontos de extremidade receptores estejam configurados para receber notificações de push de endereços IP em potencial.
• Se você desejar alterar o URL do seu ponto de extremidade, deve manter o URL original ativo até que validemos o seu novo URL para receber notificação de push. Fale com o seu representante do Fraud Prevention antes de fazer essas alterações.
• Apenas um URL pode ser usado nas notificações.

Tratamento de mensagens

É fundamental agir com rapidez. Revise com cuidado os detalhes da solicitação de callback e confirme que você está processando todas as combinações de entidades, decisões e ações de correção recomendadas.

Mensagens que não podem ser entregues

Estabelecemos um protocolo para tentar entregá-la de modo automático em caso de dificuldades para entregar uma mensagem ao seu ponto de extremidade. A tentativa vai ocorrer cinco vezes de maneira exponencial, sendo iniciada com um atraso de 5 segundos.

Validação

Para validar o evento, você precisa comparar o hash de assinatura SHA512 no cabeçalho com um que você gerou usando a sua chave de API, o seu segredo compartilhado e o carimbo de data e hora no cabeçalho da solicitação.

Não se esqueça de verificar se o cabeçalho api-key é uma chave de API que você recebeu durante o processo de ativação do Fraud Prevention.

Como proteger o seu segredo compartilhado

O segredo compartilhado fornecido a você é crucial para a segurança dos seus dados de solicitação e deve ser tratado como uma senha. Nunca inclua o valor bruto em nenhum site ou código de aplicativo que possa ser acessado de maneira pública. Você vai receber o seu segredo compartilhado e a sua chave de API quando tiver aprovação para integrar o Fraud Prevention.

Estrutura do cabeçalho da solicitação de callback

Validação do hash em comparação com os passos de assinatura

1. Prepare a sequência signed_payload:

   • A sequência signed_payload é criada por meio da concatenação do:
     • carimbo de data/hora como uma sequência do cabeçalho x-eg-notification-timestamp
     • caractere .
     • conteúdo JSON real (ou seja, o corpo da solicitação)

2. Determine a assinatura esperada:

   • Calcule um HMAC com a função hash SHA256. Use o segredo de assinatura do ponto de extremidade como a chave, e a sequência signed_payload como a mensagem.

3. Compare as assinaturas: compare a assinatura, ou as assinaturas, no cabeçalho com a assinatura esperada. Para determinar se há correspondência, calcule a diferença entre o carimbo de data e hora atual e o carimbo de data e hora recebido. Depois, decida se a diferença está dentro do limite de tolerância.

Exemplo em Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;

public class TestApplication {

    public static final String HMAC_SHA_256 = "HmacSHA256";

    public static void main(String[] args){

        // extracted data from the notification request payload
        // x-eg-notification-timestamp: 1634021234
        String eg_timestamp_header_value = "timestamp_header_value";
        // x-eg-notification-signature: SHA256=signature_header_value
        String eg_signature_header_value = "signature_header_value";
        // api-key: api_key_to_validate
        String api_key_header_value = "api_key_to_validate";
        // json payload
        String json_payload = "json_payload";

        // your api key
        String api_key = "your_api_key";
        // signing secret from the secret store
        String your_endpoints_signing_secret = "your_endpoints_signing_secret";


        if (!api_key.equals(api_key_header_value)) {
            throw new RuntimeException("Failure! Api key does not match expected value!");
        }

        try {
            // Prepare the `signed_payload` string
            String signed_payload = eg_timestamp_header_value + "." + json_payload;

            // Determine the expected signature
            String expected_signature = generate_hmac(signed_payload,
                    your_endpoints_signing_secret);

            if (!eg_signature_header_value.equals(expected_signature)) {
                throw new RuntimeException("Failure! Signature does not match expected value!");
            }

            System.out.println("Success! The generated signature matches the expected value.");
        } catch (NoSuchAlgorithmException | InvalidKeyException e) {
            System.err.println("Error generating HMAC: " + e.getMessage());
        }
    }

    /**
     * Generates a hashed message authentication code using the HMAC-SHA256 algorithm.
     * This method may throw an Exception when the HMAC-SHA256 algorithm is not supported
     * or the secret key is invalid.
     *
     * @param message The message to be encoded
     * @param secret The secret key
     * @return The Base64 encoded HMAC
     */
    public static String generate_hmac(String message, String secret)
            throws NoSuchAlgorithmException, InvalidKeyException {
        Mac sha256_hmac = Mac.getInstance(HMAC_SHA_256);
        SecretKeySpec secret_key_spec = new SecretKeySpec(secret.getBytes(), HMAC_SHA_256);
        sha256_hmac.init(secret_key_spec);
        byte[] hmac = sha256_hmac.doFinal(message.getBytes());
        return Base64.getEncoder().encodeToString(hmac);
    }
}