거래 모니터링 문제 해결: 원인과 수정 방법

거래 모니터링에서 자주 발생하는 문제를 증상, 원인, 해결 방법과 함께 정리한 참조 자료입니다.

​

txn_id 중복 오류

증상. 거래를 제출했을 때 transaction_id 필드에 A transaction with this transaction_id already exists. 메시지와 함께 400이 반환되거나, 동일한 요청 두 개가 경합할 때 409가 반환됩니다. 원인. txn_id(전송하는 transaction_id)는 애플리케이션마다 고유해야 합니다. Didit는 같은 transaction_id를 가진 두 번째 거래를 거부하며, 기존 레코드를 반환하지 않습니다. 해결 방법.

• 자체 시스템에서 txn_id를 결정론적으로 생성하십시오(예: 자체 거래 DB ID 사용).
• 재시도 중 중복 transaction_id에 대해 400 또는 409가 반환되면 요청을 다시 제출하지 말고 기존 거래를 조회하십시오. 첫 번째 응답의 uuid를 사용해 GET /v3/transactions/{uuid}/로 읽거나, transaction.created webhook이 txn_id와 함께 전달하는 transaction_id(Didit uuid)를 사용하십시오.
• 재시도가 아닌 요청이라면 새 거래에 고유한 transaction_id를 부여하십시오.

​

규칙이 적용되지 않음

증상. 일치해야 하는 규칙을 만들었지만 rule_runs[]에서 matched: true로 표시되는 거래가 없습니다. 원인과 해결 방법.

• 애플리케이션이 샌드박스 모드임 - 샌드박스 애플리케이션은 규칙 평가, AML 스크리닝, 결제, transaction.created 및 transaction.status.updated webhook을 건너뜁니다. Travel Rule 교환은 활성화된 경우 여전히 실행되며, Didit Test VASP를 대상으로 하고 environment: sandbox로 표시된 travel_rule.status.updated webhook을 전송합니다. 규칙 모드와 관계없이 rule_runs는 비어 있고 점수는 0으로 유지되며, 만료되는 Travel Rule 전송으로 인해 timeout_outcome이 적용되는 경우가 아니라면 거래는 APPROVED 상태로 남습니다. 거래 응답의 environment를 확인하십시오. "sandbox"이면 평가된 적이 없다는 뜻입니다. 실제 운영 전에 규칙을 검증하는 방법은 샌드박스의 거래 모니터링을 참조하십시오.
• 규칙 모드가 DISABLED 또는 TEST임 - Rules → [rule] → Mode에서 확인하십시오. 점수 산정에는 ACTIVE 규칙만 반영됩니다. TEST 규칙은 평가되지만 거래 상태에는 영향을 주지 않습니다.
• 범위 필터가 거래를 제외함 - 예를 들어 범위를 transaction_type = finance로 설정하면 travelRule 거래와 일치하지 않습니다.
• 집계 기간이 필요한 기간보다 짧음 - “30일 동안 20건의 거래” 규칙은 거래가 15건뿐일 때는 일치하지 않습니다.
• 조건 필드가 null임 - 예를 들어 규칙이 counterparty.country_code를 확인하지만 거래 상대방을 전송하지 않은 경우입니다.
• 통화 환산 - 규칙은 amount_in_default_currency를 기준으로 임계값을 확인합니다. 애플리케이션의 기본 통화가 거래 통화와 다르면 환산된 금액이 임계값보다 낮을 수 있습니다.

Rules → [rule] → Backtest 기능을 사용하면 과거 거래를 다시 실행해 규칙이 실행되었거나 실행되지 않은 이유를 확인할 수 있습니다.

​

규칙이 거의 모든 거래에서 실행됨

증상. 규칙이 거래의 90% 이상에서 실행되어 검토 대기열이 넘쳐납니다. 원인. 조건이 지나치게 넓거나 임계값이 지나치게 낮습니다. 해결 방법.

• scope 필터를 추가해 적용 범위를 좁히십시오(예: 발신 거래만, 특정 거래 유형만).
• 임계값(금액, 거래 빈도)을 높이십시오.
• 규칙을 1주일 동안 TEST 모드로 두고 rule_runs를 분석해 일치율을 확인하십시오. 다시 활성화하기 전에 조건을 더 엄격하게 조정하십시오.

​

암호화폐 스크리닝 시간 초과

증상. 거래가 status: APPROVED로 완료되었지만 provider_results[] 배열에서 지갑, 트랜잭션 해시 또는 암호화폐 스크리닝 제공업체에 대해 status: FAILED가 표시됩니다. 원인.

• 제공업체 API를 일시적으로 사용할 수 없었습니다.
• 쿼리 시간이 초과되었습니다(보통 약 10초).

해결 방법.

• 제공업체 문제로 거래가 실패하는 경우는 없습니다. 데이터 보강은 최선의 노력으로 처리됩니다.
• 특정 제공업체가 반복적으로 실패하면 상태 페이지를 확인하거나 지원 티켓을 여십시오.
• Settings → Transaction Monitoring → Providers에서 제공업체 기본 설정을 구성해 다른 제공업체로 라우팅하는 것을 고려하십시오.

​

IP 데이터 보강 누락

증상. 거래의 applicant.ip_enrichment가 없거나 일부만 있습니다. 원인.

• 제출 데이터에 applicant.device.ip가 없습니다.
• IP가 사설 또는 예약 주소이므로 라우팅할 수 없습니다.
• 모든 보강 제공업체를 일시적으로 사용할 수 없었습니다.

해결 방법.

• 클라이언트 또는 서버에서 제출자의 IP를 수집하고 모든 거래에 전달하십시오.
• 라우팅 가능한 IP만 사용하십시오. Didit는 사설 범위를 알림 없이 건너뜁니다.
• 콘솔의 Settings → Status에서 제공업체 상태를 확인하십시오.

​

Webhook 서명 불일치

증상. 엔드포인트가 서명이 일치하지 않는다는 이유로 이벤트를 거부합니다. 원인.

• 원시 요청 본문이 변경되었습니다(JSON이 다른 공백으로 다시 직렬화됨).
• 잘못된 비밀 값을 사용했습니다.
• 동일한 URL을 가진 webhook 대상이 여러 개입니다. 서명은 대상마다 다릅니다.

해결 방법.

• 파싱된 JSON이 아니라 원시 요청 본문에 대해 서명을 계산하십시오. 많은 프레임워크가 원시 본문 미들웨어를 제공합니다.
• 비밀 값이 노출되었다면 교체하십시오: Webhook destinations → [destination] → Rotate secret.
• 비밀 값 혼동을 피하려면 URL마다 webhook 대상을 하나만 두십시오.

​

Webhook이 도착하지 않음

증상. 거래는 생성되고 있지만 webhook이 전혀 도착하지 않습니다. 원인.

• 대상의 enabled 값이 false입니다.
• URL을 공개적으로 연결할 수 없습니다.
• 반복된 실패 후 대상이 자동으로 비활성화되었습니다.
• 이벤트가 subscribed_events에 없습니다.

해결 방법.

• 테스트 이벤트를 전송하십시오: Webhook destinations → [destination] → Send test.
• 최근 전송 내역을 확인하십시오: Webhooks → [destination] → Deliveries. 본문과 헤더가 포함된 4xx/5xx 응답을 확인할 수 있습니다.
• 비활성화된 대상은 다시 활성화하십시오.

​

통화 환산 결과가 잘못된 것 같음

증상. amount_in_default_currency가 예상한 환율과 일치하지 않습니다. 원인.

• FX 환율은 txn_date 기준의 중간 시장 환율입니다.
• 소급 적용된 거래는 해당 날짜의 과거 환율을 사용합니다.
• 일부 통화(이색 통화)는 업데이트 간격이 더 깁니다.

해결 방법.

• 표시에는 amount와 currency(원래 통화)를 사용하십시오.
• amount_in_default_currency는 내부 규칙 임계값 판단에만 사용하십시오.
• 감사를 위해 거래 레코드에는 평가 시점에 사용된 환산 환율이 고정되어 기록됩니다.

​

거래 상대방이 내 차단 목록과 일치하지 않음

증상. vendor_data로 기업을 차단 목록에 추가했지만, 해당 거래 상대방이 포함된 거래가 여전히 통과되었습니다. 원인.

• 거래 페이로드의 거래 상대방에 vendor_data가 없습니다. 외부 스냅샷으로 저장되어 있습니다.
• vendor_data의 대소문자가 다릅니다.

해결 방법.

• 거래 상대방이 플랫폼의 엔터티인 경우 항상 counterparty.vendor_data를 전달하세요.
• 모든 곳에서 같은 대소문자를 사용하세요. vendor_data는 대소문자를 구분합니다.

​

AWAITING_USER 거래가 멈춤

증상. 사용자가 조치 세션을 완료하지 않아 거래가 AWAITING_USER 상태에서 멈춰 있습니다. 원인.

• 사용자가 조치 세션 URL을 열지 않았습니다.
• 조치 세션이 만료되었습니다.
• 거래가 travel-rule-pending-action과 같은 라이브러리 규칙에 의해 AWAITING_USER로 전환된 Travel Rule 전송입니다. Didit는 Travel Rule 거래에 대해 기본 조치 세션을 생성하지 않으므로, 규칙에 별도의 조치 워크플로를 지정하지 않았다면 전달할 링크가 없습니다.

해결 방법.

• 거래 응답의 remediation_session_url이 전달할 링크입니다. 사용자에게 다시 전달하세요.
• Travel Rule 거래라면 Travel Rule 탭에서 해당 전송을 해결한 다음 거래 상태를 직접 변경하세요. 전송을 해결하는 것만으로는 거래가 AWAITING_USER 상태에서 자동으로 벗어나지 않습니다.
• 조치 세션은 KYC 빠른 시작 가이드와 같은 방식을 따릅니다. 완료 webhook을 구독하세요.
• 조치가 완료되지 않을 경우 시스템에서 시간 초과 설정을 두어 오래된 거래를 만료시키세요.

​

생성 시 속도 제한

증상. 대용량 요청이 급증하는 동안 429 Too Many Requests가 발생합니다. 해결 방법.

• Retry-After 헤더를 준수하세요.
• 버스트 트래픽에 대해 클라이언트 측에서 요청 속도를 조절하세요.
• 검증된 프로덕션 거래량에 대해 더 높은 한도가 필요하면 지원팀에 문의하세요.

자세한 내용은 속도 제한을 참조하세요.

​

다음 단계