Notificaciones

Esta página describe el servicio de notificaciones, el cual envía actualizaciones de las transacciones de la pantalla de fraudes.

Información general

Fraud Prevention API Notifications es una solución que te permite integrar tu sistema con la Fraud Prevention API más estrechamente que nunca. Cuando se produzcan cambios que puedan causar algún impacto en tu negocio, Fraud Prevention volcará los detalles del cambio directamente en tus sistemas mediante mensajes POST estándar. Con nuestras notificaciones, podrás estar al día, simplificar las operaciones y asegurarte de que tu negocio se mantenga protegido frente a situaciones de fraude.

Actualmente admitimos notificaciones para los eventos de las pantallas de cuentas y de órdenes de compra. De esta forma, si un analista ha revisado la transacción, se te notificará inmediatamente con la resolución y las acciones recomendadas.

Esquema y detalles de los mensajes

En esta sección profundizaremos en la composición arquitectónica de nuestros mensajes, que consta de dos partes principales: el sobre y la carga de la notificación. El sobre incorpora los metadatos de la notificación, mientras que la carga de la notificación contiene los detalles complejos de esta. Exploremos estos componentes en detalle.

Esquema del objeto "sobre"

| Campo | Tipo | Valores posibles | Anulable | Muestra | Descripción |-----------------|---------|------------------------|----------|--------------------------------------|----------------- | event_name | Cadena | MERCHANTSHIELD_FRAUD | false | MERCHANTSHIELD_FRAUD | Nombre del evento, siempre será MERCHANTSHIELD_FRAUD. | creation_time | Cadena | Hora (UTC) | false | 2024-01-18T10:29:20.484649887Z | Hora de creación del evento de notificación. | notification_id | Cadena | GUID | false | d72ac517-f0a7-4a65-8547-250cf81ce440 | Id. único de notificación | payload | Carga | Objeto Payload | false | | Carga real de la notificación. Consulta la descripción del esquema del objeto "carga" más abajo.

Esquema del objeto "carga"

Cada mensaje es una solicitud POST HTTPS con un cuerpo de mensaje JSON.

Ejemplo de actualización de fraude en 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"
    }
}

Ejemplo de actualización de apropiación de cuentas

{
    "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"
    }
}

Integración

Recepción de un mensaje

Para empezar a recibir notificaciones, tendrás que establecer un punto de conexión que pueda aceptar mensajes POST que se envíen a dicho punto de conexión. El punto de conexión debe cumplir los criterios siguientes:

• Ser de acceso público.
• Tener habilitado HTTPS y TLS 1.2 o una versión superior.
• Configurar un certificado TLS válido en el que confíen la mayoría de las aplicaciones modernas (es posible que no se confíe en un certificado con autofirma).

Trabaja con tu asesor de integración de Fraud Prevention para configurarlo y proporciónale la información siguiente:

• La dirección URL de tu punto de conexión para gestionar los mensajes.

Estamos trabajando para facilitarte herramientas de autogestión que te permitan probar la integración. Hasta entonces, el asesor de integración te puede ayudar a realizar reservas de prueba para confirmar que recibes las notificaciones de los eventos ocurridos fuera de línea a los que te has suscrito.

Notas importantes sobre la configuración

• Fraud Prevention utiliza servidores en la nube. Asegúrate de que los puntos de conexión del receptor estén configurados para recibir notificaciones procedentes de distintas direcciones IP.
• Si quieres cambiar la URL de tu punto de conexión, debes mantener activa la URL hasta que validemos la nueva para recibir notificaciones. Ponte en contacto con tu representante de Fraud Prevention antes de realizar este tipo de cambios.
• Solo se puede utilizar una dirección URL para las notificaciones.

Gestión de un mensaje

Resulta fundamental actuar con rapidez. Revisa cuidadosamente los detalles de la solicitud de devolución de llamada; asegúrate de que estás procesando todas las combinaciones de entidades, decisiones y medidas de corrección recomendadas.

Mensajes que no se pueden entregar

Si tenemos dificultades para entregar un mensaje a tu punto de conexión, hemos establecido un protocolo para intentar entregarlo de nuevo de forma automática. La reentrega se intentará cinco veces de manera exponencial y con un inicio que se producirá tras un retardo de cinco segundos.

Validación

Para validar el evento, deberás comparar el hash SHA512 de la firma del encabezado con uno que generes usando tu clave de la API, el secreto compartido y la marca de hora del encabezado de solicitud.

Asegúrate de verificar que el encabezado api-key es realmente una clave de API que recibiste durante el proceso de incorporación a Fraud Prevention.

Protección del secreto compartido

El secreto compartido que se te entregue es esencial para la seguridad de los datos de tus solicitudes; trátalo como si fuera una contraseña. No incluyas nunca el valor sin formato en ningún sitio accesible públicamente ni en el código de una aplicación. Te proporcionarán tu secreto compartido y tu clave para la API cuando recibas la aprobación para integrarte en Fraud Prevention.

Estructura del encabezado de la solicitud de devolución de llamada

Validación del hash comparándolo con los pasos de firma

1. Prepara la cadena signed_payload:

   • La cadena signed_payload se crea concatenando lo siguiente:
     • La marca de hora como una cadena del encabezado x-eg-notification-timestamp
     • El carácter .
     • La carga JSON real (es decir, el cuerpo de la solicitud)

2. Determina la firma esperada:

   • Calcula un HMAC con la función de hash SHA256. Utiliza el secreto de firma del punto de conexión como clave y la cadena signed_payload como mensaje.

3. Compara las firmas: Compara la firma (o firmas) del encabezado con la firma esperada. Para establecer si existe coincidencia, calcula la diferencia entre la marca de hora actual y la recibida, y luego decide si la diferencia se encuentra dentro de la tolerancia.

Ejemplo en 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);
    }
}