POST /v3/transactions/와 GET /v3/transactions/{transaction_id}/가 반환하는 전체 페이로드를 설명합니다. 두 엔드포인트는 동일한 TransactionDetail 객체를 반환합니다. 필드별 스키마는 API 레퍼런스에 있으며, 이 페이지에서는 그 내용을 차례로 살펴봅니다.
최상위 구조
uuid는 Didit이 안정적으로 관리하는 식별자이며, GET /v3/transactions/{transaction_id}/의 경로에 전달해야 하는 값입니다. txn_id는 생성 시 제공한 transaction_id입니다. transaction_number는 콘솔에 표시되는 애플리케이션별 순차 번호입니다.
제출한 대상자와 거래 상대방은 최상위 키로 반환되지 않습니다. 이들은 parties 배열의 항목이며 role로 구분됩니다. 최상위 vendor_data는 신청자의 vendor_data를 편의를 위해 복사한 값입니다.
주요 필드
금융 필드
amount/currency: 제출된 거래 금액입니다.amount는 뒤쪽 0을 제거한 10진수 문자열이며("1500","0.5"), 소수점 이하 최대 18자리까지 허용합니다.currency_type:currency_kind로 제출된fiat또는crypto입니다. 생략된 경우null입니다.amount_in_default_currency/default_currency_code: 요청에 포함한 사전 환산 금액을 그대로 되돌려 준 값입니다. 전송하지 않았다면null입니다.preferred_currency_amount/preferred_currency_code:amount를 애플리케이션의 선호 통화로 환산한 금액입니다.currency에 대한 환율을 구할 수 없고amount_in_default_currency도 제공하지 않았다면null입니다.payment_details/payment_txn_id: 요청에 포함된 자유 형식 결제 참조 정보와 외부 결제 참조 값(예: 블록체인 트랜잭션 해시)입니다.
상태 필드
status:APPROVED,IN_REVIEW,DECLINED,AWAITING_USER중 하나입니다. 거래는APPROVED상태로 생성되며, 규칙에 따라 동기적으로 상태가 변경될 수 있습니다.score: 규칙이 누적한 정수형 위험 점수입니다. 값이 높을수록 위험도가 높습니다.severity:UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL중 하나이며, 규칙이나 제공업체가 값을 설정하기 전까지는null입니다.decision_reason_code/decision_reason_label: 현재 상태에 대한 구조화된 사유 코드와 사람이 읽을 수 있는 사유 설명입니다.environment: 거래를 소유한 애플리케이션에 따라live또는sandbox입니다.sandbox거래는 저장되지만 평가되지 않으므로, 비어 있는rule_runs는 “일치한 항목 없음”이 아니라 “평가되지 않음”을 뜻합니다. 샌드박스에서의 거래 모니터링을 참조하십시오.source: API 또는 SDK로 제출된 거래는LIVE, 콘솔의 CSV 가져오기로 불러온 거래는IMPORTED입니다.
당사자
거래의 모든 당사자는parties의 항목입니다. 생성 endpoint는 대상을 APPLICANT로, 선택 사항인 거래 상대방을 COUNTERPARTY로 기록합니다. role 열거형에는 REMITTER와 BENEFICIARY도 포함됩니다. 모든 항목은 같은 구조를 따릅니다.
role:APPLICANT,COUNTERPARTY,REMITTER,BENEFICIARY. 대상을 찾으려면 이 값으로 필터링하십시오.entity_type: 제출된 대로individual,company,external,unhostedWallet중 하나입니다.kind: 당사자가vendor_data를 통해 Didit 사용자 또는 기업과 연결된 경우USER또는BUSINESS이며, 그 밖의 경우에는EXTERNAL입니다.country_code/dob: 제출된address.country와date_of_birth에서 가져온 값입니다.address/institution_info: 제출된 객체 그대로입니다. 생략된 경우{}입니다.external_party_snapshot:EXTERNAL당사자의 데이터를 고정한 사본입니다. 당사자가 Didit 사용자 또는 기업과 연결되어 있는 동안에는null입니다.
device
device는 해당 당사자에 대해 제출된 device_context를 snake_case로 정규화한 값에 서버 측 IP 정보 보강 결과를 더한 것입니다. 요청에 기기 컨텍스트가 없으면 {}입니다. 따라서 모든 키를 선택 사항으로 취급하십시오.
별도의 보강 객체는 없습니다. 당사자가 공인
network_context.ip_address를 포함한 경우 Didit이 이를 인라인으로 해석하고, 보강된 필드를 같은 network_context 객체에 기록합니다. 이때 직접 제출하지 않은 키만 채웁니다. 해석기가 빈 값을 반환한 키는 생략되므로, 완전히 보강된 network_context에는 제출된 네 개의 키(ip_address, ip_country_code, latitude, longitude)와 함께 해석에 성공한 ip_country, ip_state, ip_city, isp, organization, is_vpn_or_tor, is_data_center, time_zone, time_zone_offset, asn_number, asn_organization, connection_type, carrier, proxy_type 중 일부가 포함됩니다. 해석에 성공하면 is_vpn_or_tor와 is_data_center는 항상 존재합니다.
보강을 건너뛰고 network_context를 제출된 그대로 반환하는 경우는 IP가 없거나 라우팅할 수 없는 경우, 애플리케이션이 샌드박스에 있는 경우, 또는 해석에 실패한 경우입니다. ip_country_code는 Didit이 해석한 경우 ISO 3166-1 alpha-2 코드이며, 그 밖에는 제출한 값입니다. 규칙 조건은 비교하기 전에 두 형식을 모두 정규화합니다.
결제 수단
role:SOURCE,DESTINATION,FUNDING,BENEFICIARY. 생성 endpoint는direction에 따라SOURCE/DESTINATION을 할당합니다. 발신 거래에서는 대상의 수단이SOURCE, 거래 상대방의 수단이DESTINATION입니다. 수신 거래는 이와 반대입니다.payment_method_type:bank_card,bank_account,e_wallet,crypto_wallet,unhosted_wallet,other중 하나입니다.fingerprint:type:account_id:issuing_country에 대한 SHA-256 값입니다. 거래마다 안정적으로 유지되므로 같은 수단이 재사용되는지 상관 분석할 수 있습니다.account_id가 제출되지 않은 경우null입니다.owner_kind/vendor_data/owner_name: 수단의 소유자를 나타내며, 당사자와 같은USER/BUSINESS/EXTERNAL규칙을 따릅니다.details: 제출된 원본payment_method객체입니다.
규칙 실행
rule: 실행된 규칙의 UUID입니다.rule_title,rule_description,rule_category는 이 규칙에서 복사됩니다.matched: 규칙의 조건이 일치한 경우에만 실행 기록이 남습니다. 따라서 라이브 평가에는 항상matched: true가 포함됩니다. 일치하지 않은 규칙은 항목을 남기지 않습니다. 데모 데이터에는matched: false행이 포함될 수 있습니다.is_test/mode: 규칙이 테스트 모드로 실행된 경우true와TEST입니다. 테스트 실행도 기록되지만status,score,severity에는 영향을 주지 않습니다.score_delta/status_target/severity: 이 실행이 기여한 값입니다.status_target은change_status작업이 실행되었거나, 추가된 점수가 임계값을 넘었을 때 설정됩니다.action_summary: 규칙이 실행한 작업을;로 이어 붙인 문자열 요약입니다(score +30,change_status:IN_REVIEW,add_tag:<name>,add_note,add_to_list,open_case). 규칙이 작업을 실행하지 않은 경우null입니다.metadata: 평가 상세 정보이며,scope_match와 함께conditions[],aggregations[]를 포함합니다. 두 목록은 서로 다른 값 키를 사용합니다.conditions[]: 조건마다 하나의 항목이 있으며,field,operator,expected_value, 거래에서 읽은current_value,matched,group_index,group_logic을 포함합니다. 거래 규칙 실행에서field_source는 항상null입니다. 이 값은 모니터링 이벤트에 대해서만 분류됩니다.aggregations[]: 속도, 횟수, 합계 집계마다 하나의 항목이 있으며,metric,field,operator,expected_value, 집계가 계산한computed_value,window,filters,matched,sample_references를 포함합니다. 비동기로만 계산할 수 있었던 집계는computed_value: null과deferred: true를 갖습니다.
알림
alerts는 현재 항상 빈 배열입니다.
열린 알림은 보류된 거래이므로, 대신 status(IN_REVIEW 또는 AWAITING_USER)를 확인하세요. 자세한 내용은 알림을 참조하세요.
활동
거래의 활동 로그로, 생성, 메모, 수동 검토, 상태 변경이 기록됩니다.TRANSACTION_NOTE_ADDED 항목으로 표시되며, 별도의 notes 배열은 없습니다.
문서
콘솔에서 거래에 첨부된 파일입니다. 첨부 파일이 없으면[]입니다.
file_url은 수명이 짧은 서명된 URL입니다. 저장하지 말고 필요할 때 가져오세요.
제공업체 결과
외부 제공업체의 출력 결과입니다(거래 해시 스크리닝, 지갑 스크리닝, 법정통화 모니터링, 제재 스크리닝).result_type: FIAT_MONITORING, WALLET_SCREENING, TRANSACTION_SCREENING, TRAVEL_RULE, NETWORK_GRAPH, CUSTOM.
payload.risk_factors는 score를 설명하는 순위 목록입니다. 판정을 이끈 요인을 보여 주며, 고위험 요인이 먼저 오고 그다음 이동한 금액 순으로 정렬됩니다. score가 높은데 is_high_risk 항목이 없다면, 제공업체가 제재나 귀속 개체 일치를 보고하지 않고 자체 노출 모델로 개체를 평가했다는 뜻입니다. 이 경우 summary에 그 내용이 명시됩니다. 필드별 참조는 위험 요인을 확인하세요. 이 필드가 도입되기 전에 스크리닝된 결과에는 이 키가 없습니다.
암호화폐 거래 해시 스크리닝의 경우, 온체인 보강 정보를 사용할 수 있으면 transaction_flows가 채워집니다. 체인 활동을 정규화하여 콘솔이 같은 응답 페이로드에서 거래 개요와 시각화 그래프를 모두 렌더링할 수 있도록 합니다.
지원되는 보강 소스는 다음과 같습니다.
- EVM 체인은 Blockscout을 사용해 주 거래, 내부 호출, 토큰 전송을 정규화합니다.
- Bitcoin은 mempool.space를 사용해 거래 입력과 출력을 정규화합니다.
- Solana는 Helius를 사용해 네이티브 SOL 전송, SPL 토큰 전송, 그리고 사용 가능한 NFT 이벤트 컨텍스트를 정규화합니다.
transaction_flows[] 항목에는 안정적인 정규화 필드(flow_type, from_address, to_address, amount, amount_usd, currency, token_name, token_address, transaction_hash, block_timestamp, index, success)와 제공업체별 metadata가 포함됩니다.
일반적인 metadata 예시는 다음과 같습니다.
metadata는 추가적으로 제공되며 제공업체마다 다릅니다. 모든 체인에서 모든 키가 존재해야 한다고 가정하는 중요한 연동은 구축하지 마세요.
Travel Rule
거래에 Travel Rule 전송이나 확인이 없으면null입니다. travel_rule_details를 제출하면 값이 채워집니다. 애플리케이션에서 Travel Rule이 활성화되어 있고 거래가 transaction_category: "travelRule"로 생성된 경우에도 값이 채워집니다. 이때 Didit이 travel_rule_details 유무와 관계없이 교환을 직접 시작하고, 그 status를 여기에 보고합니다. 보낸 요청이 아니라 이 필드를 읽으세요.
수신 전송의 경우, 지갑 소유권이 확인되기 전까지 거래 상대방의 originator_data와 beneficiary_data는 마스킹된 상태(data_masked: true)로 유지됩니다(마스킹된 거래 상대방 데이터 참조).
direction, rail, counterparty_vasp, delivery, discovery, reason, next_actions는 전송 엔드포인트와 같은 형태입니다.
reason과 next_actions는 COUNTERPARTY_VASP_NOT_FOUND 또는 COUNTERPARTY_VASP_NOT_REACHABLE 전송이 멈춘 이유와 다음으로 진행하기 위해 필요한 조치를 설명합니다. 다른 상태에서는 각각 ""와 []입니다. 자세한 내용은 전송이 멈추는 이유를 확인하세요.
GET /v3/transactions/의 각 행에도 같은 블록이 포함됩니다.
Travel rule을 참조하세요.
네트워크 스냅샷
참조가 아니라 저장된 그래프 자체입니다. 다음 두 가지 출처 중 하나에서 가져옵니다.- 거래와 함께 제출한
network_snapshot, 또는 - 암호화폐 거래에서 AML 지갑 스크리닝이 성공했을 때 Didit이 생성한 그래프입니다. 요청에
network_snapshot이 없었더라도 생성됩니다. 스크리닝으로 생성된 그래프는 제출된 그래프를 대체하며, 비동기 재스크리닝이 실행되면 그래프가 갱신됩니다.
null입니다.
태그, 메타데이터, props
tags[]: 첨부된 태그입니다(규칙 액션 또는 분석가가 추가). 형식은{ "uuid", "name", "color", "description", "source" }이며,source는 기본 제공 태그면didit, 사용자가 만든 태그면custom입니다.metadata: 생성 시 제출한subject와counterparty페이로드의 스냅샷이며, 이 두 키 아래에 제출한 그대로 저장됩니다.props: 생성 시 제공한custom_properties입니다. 각 키는 규칙 조건에서custom_values.<key>형태로 참조할 수 있습니다.
조치
규칙이AWAITING_USER를 발생시키면 Didit은 연결된 인증 세션을 만들고, 이를 두 필드에 담아 반환합니다.
remediation: 연결된 세션으로,{ "session_id", "session_token", "url", "status" }형식입니다. 거래 기간 내내 값이 유지되므로, 사용자 조치가 어떻게 끝났는지 언제든 확인할 수 있습니다.action_required: 사용자가 지금 해야 하는 조치이며, 대기 중인 조치가 없으면null입니다. 형식은{ "type": "verification_session", "url", "session_id", "session_token", "status" }입니다. 사용자를url로 리디렉션하거나session_token을 Didit SDK에 전달하세요. Travel Rule 지갑 소유권 조치는{ "type": "wallet_ownership", "url", "widget_session_id", "expires_at" }형식을 사용하며, 두 조치가 모두 해당될 수 있을 때는 이 조치가 우선합니다. 지갑 소유권 조치가 대기 중이고 전송의 거래 상대방을 찾지 못한 경우, 같은 블록에reason과next_actions도 포함됩니다(거래 상대방 탐색 참조).
transaction.created와 transaction.status.updated webhook 페이로드에도 포함됩니다(action_required). 자세한 내용은 webhook을 참조하세요.
비용 내역
거래에서 과금 대상 기능이 실행되기 전까지는null입니다. 실행된 뒤에는 { "total_price", "items": [ { "usage_type", "price", "details" } ] } 형식이며, 과금되는 기능(스크리닝, 보강 등)마다 항목이 하나씩 있습니다.
통화 환산
preferred_currency_amount는 amount를 애플리케이션의 선호 통화로 환산한 값이며, 환산에는 중간 시장 환율을 사용합니다. 단, amount_in_default_currency를 직접 제공한 경우에는 해당 사전 환산 값을 그대로 사용합니다. amount에 대한 규칙 조건은 원래 금액을 비교합니다. 여러 통화에 걸쳐 하나의 임계값을 적용해야 할 때는 조건에 preferred_currency_amount를 사용하십시오.
다음 단계
거래 제출
전체 요청 스키마입니다.
상태
각 상태의 의미입니다.
위험 점수 산정
점수가 계산되는 방식입니다.