알림

이 페이지에서는 사기 화면 거래에 대한 업데이트를 전송하는 알림 서비스에 대해 간략하게 설명합니다.

개요

Fraud Prevention API 알림은 그 어느 때보다 긴밀하게 Fraud Prevention과 통합할 수 있도록 지원하는 솔루션입니다. 비즈니스에 영향을 줄 수 있는 변경이 발생하면 Fraud Prevention에서 표준 POST 메시지를 통해 시스템에 바로 자세한 변경 사항을 푸시합니다. 푸시 알림을 통해 계속해서 정보를 얻고 운영 작업을 간소화하며 사기로부터 비즈니스를 보호할 수 있습니다.

현재 주문 구매 및 계정 화면 이벤트에 대한 알림을 모두 지원합니다. 따라서 애널리스트가 거래를 검토하고 나면 해결 방법과 권장 조치를 즉시 알려드립니다.

메시지 스키마 및 세부 정보

이 섹션에서는 인벨롭과 알림 페이로드라는 두 가지 주요 항목으로 구성된 메시지의 구조에 대해 자세히 설명합니다. 인벨롭에는 알림 메타데이터가 통합되어 있고, 알림 페이로드에는 알림의 복잡한 세부 정보가 포함되어 있습니다. 이러한 구성 요소를 자세히 살펴보겠습니다.

Envelope 개체 스키마

| 필드 | 유형 | 가능한 값 | Null 가능 | 샘플 | 설명 |-----------------|---------|------------------------|----------|--------------------------------------|----------------- | event_name | String | MERCHANTSHIELD_FRAUD | false | MERCHANTSHIELD_FRAUD | 이벤트 이름은 항상 MERCHANTSHIELD_FRAUD입니다. | creation_time | String | 데이터 시간(UTC) | false | 2024-01-18T10:29:20.484649887Z | 시간 알림 이벤트가 생성됩니다. | notification_id | String | GUID | false | d72ac517-f0a7-4a65-8547-250cf81ce440 | 고유한 알림 ID | payload | Payload | Payload 개체 | false | | 실제 알림 페이로드 아래 Payload 개체 스키마 설명을 참조해 주세요.

Payload 개체 스키마

필드유형가능한 값Null 가능샘플설명
risk_idStringGUIDfalsefdeaf9dc-ac79-4c2f-a148-0e722374aef1위험 거래 고유 식별자
entity_typeStringBookingFraud, AccountfalseBookingFraud엔티티 유형
entity_idStringGUIDfalsebe8076bc-d17c-45fa-84e6-0fe6a609f3ac영향을 받는 화면 예약 또는 계정 탈취 거래의 참조 ID
decisionStringPASS, FAILtruePASS애널리스트가 거래를 검토한 후 내린 결정
decision_date_timeString데이터 시간(UTC)false2024-03-07T22:28:33.552Z애널리스트가 결정을 내린 날짜 및 시간(UTC 형식)
recommended_actionsArray of StringsBookingFraud 엔티티 유형의 경우: RELEASE, CANCEL_FULL_REFUND, CANCEL_NO_REFUND <hr> Account 엔티티 유형의 경우: TERMINATE_ACTIVE_SESSIONS, HARD_PASSWORD_RESET비어 있을 수 있음["CANCEL_FULL_REFUND"]권장되는 시정 조치 목록
partner_account_idStringGUIDfalseff1fddb1-29ac-41a1-8c0b-6db5932c913d파트너 계정 ID

각 메시지는 JSON 메시지 본문이 포함된 HTTPS POST 요청입니다.

BookingFraud 업데이트 예시

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

계정 탈취 업데이트 예시

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

통합

메시지 수신

알림을 받기 시작하려면 엔드포인트로 푸시되는 POST 메시지를 수락할 수 있는 엔드포인트의 효력을 유지해야 합니다. 엔드포인트는 다음 조건을 갖춰야 합니다.

  • 공개적으로 액세스 가능
  • HTTPS 및 TLS 1.2 이상 지원
  • 대부분의 최신 애플리케이션에서 신뢰하는 유효한 TLS 인증서 구성(자체 서명된 인증서는 신뢰하지 않을 수 있음)

Fraud Prevention 통합 컨설턴트와 협력하여 다음을 설정하고 제공합니다.

  • 메시지를 처리할 엔드포인트의 URL

통합을 테스트할 수 있는 셀프 서비스 도구를 제공하기 위해 노력하고 있습니다. 제공 준비가 마무리될 때까지 통합 컨설턴트가 테스트 예약을 만들어 구독 중인 오프라인 이벤트의 알림을 수신하는지 확인할 수 있도록 도와드립니다.

중요한 구성 참고 사항

  • Fraud Prevention은 클라우드 기반 서버를 사용하여 리스너 엔드포인트가 서로 다른 잠재적 IP 주소에서 푸시되는 알림을 받을 수 있도록 구성됩니다.
  • 엔드포인트 URL을 변경하려는 경우 알림 푸시 메시지를 수신할 새 URL의 유효성을 검사할 때까지 원래 URL을 계속 유지해야 합니다. 변경하기 전에 Fraud Prevention 담당자에게 문의해 주시기 바랍니다.
  • 알림에는 하나의 URL만 사용할 수 있습니다.

메시지 처리

신속한 조치의 중요성을 인식해야 합니다. 콜백 요청의 세부 사항을 주의 깊게 검토하여 엔티티, 의사 결정 및 권장 시정 조치의 모든 조합을 처리하고 있는지 확인해야 합니다.

전송할 수 없는 메시지

엔드포인트에 메시지를 전달하는 데 문제가 발생할 경우 자동으로 재전송을 시도하는 프로토콜을 설정했습니다. 5초의 지연 후 시작되는 지수 백오프가 5회 반복됩니다.

검증

이벤트를 검증하려면 헤더의 서명 SHA512 해시를 API 키, 공유 암호 및 요청 헤더의 타임스탬프를 사용하여 생성한 값과 비교해야 합니다.

api-key 헤더가 Fraud Prevention 등록 프로세스에서 실제로 제공받은 API 키인지 확인해 주세요.

공유 암호 보호

제공받은 공유 암호는 요청 데이터의 보안에 매우 중요합니다. 공유 암호를 비밀번호와 같이 취급해 주세요. 공개적으로 액세스 가능한 사이트 또는 앱 코드에 원시 값을 포함해서는 안 됩니다. Fraud Prevention을 통합하도록 승인되면 공유 암호와 API 키가 제공됩니다.

콜백 요청 헤더 구조

헤더 이름샘플 값
x-eg-notification-signatureSha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-eg-notification-timestamp13536472536
api-keyc05b7b59-0a29-4cb1-9b09-d36954c9a605

서명 단계에 대한 해시 유효성 검사

  1. signed_payload 문자열을 준비합니다.

    • signed_payload 문자열은 다음 값을 연결하여 생성됩니다.
      • x-eg-notification-timestamp 헤더의 문자열로 된 타임스탬프
      • . 문자
      • 실제 JSON 페이로드(예: 요청 본문)
  2. 예상되는 서명을 정합니다.

    • SHA256 해시 함수로 HMAC를 계산합니다. 엔드포인트의 서명 암호를 키로 사용하고 signed_payload 문자열을 메시지로 사용합니다.
  3. 서명을 비교합니다. 헤더의 서명(또는 서명)과 예상되는 서명을 비교합니다. 완전 일치의 경우 현재 타임스탬프와 수신된 타임스탬프의 차이를 계산한 다음 그 차이가 허용 오차 범위 내에 있는지 판단합니다.

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);
    }
}
이 페이지가 도움이 되었나요?
이 콘텐츠를 어떻게 개선하면 좋을까요?
더 나은 Developer Hub를 만드는 데 도움을 주셔서 감사합니다!