거래 제출 API: payload 및 데이터 모델

Create Transaction API를 통해 거래를 Didit에 제출하십시오. 각 거래에는 규칙 엔진이 실시간으로 평가하는 구조화된 당사자, 결제, 맥락 데이터가 포함됩니다.

거래가 최종 사용자의 기기에서 발생하는 경우(예: 암호화폐 출금, 앱 내 결제)에는 SDK 거래 제출을 고려하십시오. 이 방식에서는 API 키 대신 범위가 지정된 token을 사용하고, 기기 인텔리전스가 자동으로 수집되며, 지갑 소유 증명이나 단계별 추가 인증 같은 필수 사용자 작업이 즉시 실행됩니다.

거래 카테고리

모든 거래에는 규칙과 분석이 해당 거래를 처리하는 방식을 결정하는 transaction_category가 있습니다.

카테고리	설명
`finance`	표준 금융 거래(입금, 출금, 이체)
`kyc`	신분 인증 관련 이벤트
`travel_rule`	Travel Rule 준수가 필요한 가상 자산 이체
`user_event`	사용자 정의 플랫폼 이벤트(로그인, 프로필 변경 등)
`gambling_bet`	도박 베팅 또는 배팅 등록
`gambling_limit_change`	플레이어의 입금, 손실 또는 베팅 한도 변경
`gambling_bonus_change`	보너스 지급, 사용 또는 몰수
`audit_trail_event`	시스템 또는 컴플라이언스 감사 이벤트

거래 세부 정보

transaction_details 객체에는 금융 데이터가 포함됩니다.

필드	유형	설명
`direction`	string	`inbound` 또는 `outbound`
`amount`	string	소수 문자열로 표시된 거래 금액(예: `"1500.50"`)
`currency`	string	ISO 통화 코드(예: `USD`, `EUR`, `BTC`)
`currency_kind`	string	`fiat` 또는 `crypto`(별칭 `currencyType`). 암호화폐 스크리닝 실행 여부를 결정합니다.
`action_type`	string	공급자가 정의한 작업 레이블(예: `deposit`, `withdrawal`, `purchase`)
`payment_details`	string	결제에 대한 자유 텍스트 설명(예: `"Bank transfer from ABC Corp"`)
`payment_reference_id`	string	외부 결제 참조 식별자. 이체 후 암호화폐 스크리닝에는 블록체인 거래 해시를 사용하십시오.

주체 및 거래 상대방

각 거래에는 주체(필수)와 선택 사항인 거래 상대방이 있습니다. 두 항목 모두 동일한 당사자 모델을 사용합니다.

필드	유형	설명
`entity_type`	string	`person` 또는 `company`
`vendor_data`	string	이 당사자에 대해 귀사가 사용하는 식별자. 거래를 사용자 또는 기업 프로필에 연결합니다.
`full_name`	string	당사자의 성명
`first_name`	string	이름
`last_name`	string	성
`date_of_birth`	string	ISO 날짜(예: `1990-01-15`)
`country_code`	string	ISO 3166-1 alpha-2 국가 코드
`address`	object 또는 string	`street`, `city`, `state`, `country`, `postal_code`를 포함하는 구조화된 주소. 일반 문자열도 허용합니다(예: 암호화폐 거래 상대방의 주소와 같은 문자열). Didit는 값을 변경하지 않고 해당 당사자에 그대로 저장합니다.

address가 객체인 경우 Didit는 address.country에서 당사자의 country_code를 도출합니다. address가 문자열인 경우 해당 당사자의 country_code는 null로 반환됩니다. vendor_data가 기존 사용자 또는 기업과 일치하면 Didit는 거래를 해당 엔티티의 프로필에 자동으로 연결하여 세션 간 규칙 평가와 거래 빈도 검사를 가능하게 합니다. 응답에서는 두 당사자가 parties 배열에 APPLICANT 및 COUNTERPARTY 역할로 반환됩니다.

결제 수단

각 당사자에 payment_method를 연결하여 해당 측의 결제 수단을 설명하십시오.

필드	유형	설명
`method_type`	string	`bank_card`, `bank_account`, `e_wallet`, `crypto_wallet`, `unhosted_wallet`, `other`(별칭 `type`). `ewallet`, `card`, `crypto`도 별칭으로 허용되며, 인식되지 않는 값은 `other`로 저장됩니다.
`account_id`	string	계좌 번호, 주소 또는 카드 token
`issuing_country`	string	결제 수단을 발급한 국가

travelRule 거래에서 method_type: "unhosted_wallet"(별칭 type)을 사용하는 거래 상대방 결제 수단은 해당 거래 상대방 지갑이 자체 보관 지갑임을 선언합니다. Travel Rule이 활성화되어 있고 애플리케이션의 기본 통화 기준 금액이 threshold_amount 미만이 아닌 경우, 이체는 바로 UNCONFIRMED_OWNERSHIP 상태로 전환되며 소유권 증명 절차가 시작됩니다. 자세한 내용은 선언된 자체 보관 지갑을 참조하십시오. 암호화폐 거래의 경우 account_id에 지갑 주소를 포함하고 currency_kind를 crypto로 설정하여 블록체인 스크리닝이 자동으로 실행되도록 하십시오. 방향에 따라 스크리닝되는 지갑이 결정됩니다. 인바운드 이체 전 스크리닝은 counterparty.payment_method.account_id의 발신 지갑을 사용하고, 아웃바운드 스크리닝은 counterparty.payment_method.account_id의 수신 지갑을 사용합니다. transaction_details.payment_reference_id에 블록체인 해시를 전송하는 경우, 인바운드 거래 스크리닝에는 subject.payment_method.account_id에 서비스 입금 주소가 필요하고, 아웃바운드 거래 스크리닝에는 counterparty.payment_method.account_id에 수신 지갑이 필요합니다.

암호화폐 스크리닝 재정의

요청의 최상위 수준에서 include_crypto_screening을 사용하면 Console의 거래 > 설정에서 구성된 기본값을 재정의할 수 있습니다.

값	설명
`true`	이 거래에 대해 암호화폐 스크리닝을 강제로 실행합니다.
`false`	이 거래에 대해 암호화폐 스크리닝을 건너뜁니다.
생략 또는 `null`	애플리케이션 수준의 기본값을 사용합니다.

기기 컨텍스트

기기 인텔리전스 규칙을 작동시키려면 대상(선택적으로 거래 상대방) 당사자에 기기 정보를 포함합니다. 요청 필드는 각 당사자의 device_context입니다. SDK 와이어 형식에서 사용되는 카멜케이스 별칭 device도 허용됩니다. 응답에서는 parties 배열의 각 당사자에 device로 반환됩니다.

필드	유형	설명
`device_context.fingerprint`	string	고유 기기 지문
`device_context.persistent_device_id`	string	세션 간에 변하지 않는 기기 식별자(v2 지문 스키마)
`device_context.user_agent`	string	브라우저 또는 앱의 사용자 에이전트 문자열
`device_context.browser_family`	string	브라우저 제품군(예: `Chrome`, `Firefox`, `Safari`). 반드시 명시적으로 전송해야 합니다. `user_agent`에서 유추되지 않습니다. `subject_browser_family`와 같은 규칙을 작동시킵니다.
`device_context.browser_version`	string	브라우저 버전 문자열(예: `131.0`). 반드시 명시적으로 전송해야 합니다.
`device_context.platform`	string	플랫폼 식별자(`web`, `ios`, `android`, `macos`, `windows`, `linux`). 반드시 명시적으로 전송해야 합니다. `user_agent`에서 유추되지 않습니다. `subject_platform`과 같은 규칙을 작동시킵니다.
`device_context.os_family`	string	운영 체제 제품군(예: `iOS`, `Android`, `Windows`)
`device_context.os_version`	string	운영 체제 버전 문자열
`device_context.accept_language`	string	Accept-Language 헤더 값(예: `en-US,en;q=0.9`). SDK 경로에서는 자동으로 수집됩니다.
`device_context.session_id`	string	사용자의 현재 세션 식별자. 메타데이터에 저장됩니다. 카멜케이스 별칭: `sessionId`.
`device_context.session_age_ms`	number	거래 시점의 사용자 세션 경과 시간(밀리초). `subject_session_age_ms`와 같은 규칙을 작동시킵니다.
`device_context.network_context.ip_address`	string	클라이언트 IP 주소
`device_context.network_context.ip_country_code`	string	IP의 지리적 위치로 확인된 국가(ISO 3166-1 alpha-3)
`device_context.network_context.latitude`	number	IP의 위도
`device_context.network_context.longitude`	number	IP의 경도

browser_family와 platform은 user_agent에서 유추되지 않습니다. 기기 인텔리전스 규칙이 작동하려면 device_context 안에 명시적인 최상위 키로 전송해야 합니다. Didit SDK를 사용하는 경우 이 필드들은 자동으로 수집됩니다.

모든 필드에 카멜케이스 별칭을 사용할 수 있습니다: userAgent, browserFamily, browserVersion, osFamily, osVersion, acceptLang, sessionId, sessionAgeMs. network_context 하위 객체는 ip / countryCode3 / lat / lon 별칭을 허용하며, 최상위 ipInfo 블록도 network_context에 병합됩니다. 기기 컨텍스트로 다중 계정 탐지(같은 지문이 서로 다른 대상에서 나타나는 경우), 새 브라우저와 새 IP의 조합 탐지, 세션 경과 시간이 짧은 고액 이체 탐지, 위치 기반 위험 점수 산정 같은 규칙을 사용할 수 있습니다.

사용자 지정 속성

custom_properties 객체에 추가 키-값 쌍을 넣을 수 있습니다. 규칙은 조건에서 이 필드를 참조할 수 있습니다. 제품 카테고리, 가맹점 ID, 채널처럼 비즈니스에 특화된 컨텍스트를 전달할 때 유용합니다.

"custom_properties": {
  "product_category": "electronics",
  "merchant_id": "MER456",
  "channel": "mobile_app"
}

규칙 조건에서는 custom_values.<key>라는 필드 경로로 각 키를 참조합니다. 예를 들어 위 페이로드는 custom_values.product_category eq "electronics"와 일치합니다. Console 규칙 빌더에서는 최근에 수집된 거래에서 확인된 키가 조건 필드 선택기의 사용자 지정 속성 아래에 표시됩니다. 같은 그룹의 사용자 지정 속성 입력을 사용하면 원하는 키를 직접 입력할 수 있으며, 키는 대소문자를 구분합니다. 자세한 내용은 규칙 및 점수 산정을 참조하세요.

요청 예시

curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "TXN-20260410-001",
    "transaction_at": "2026-04-10T15:30:00Z",
    "transaction_category": "finance",
    "transaction_details": {
      "direction": "outbound",
      "amount": "1500.50",
      "currency": "EUR",
      "currency_kind": "fiat",
      "action_type": "withdrawal"
    },
    "subject": {
      "entity_type": "person",
      "vendor_data": "user-123",
      "full_name": "John Doe",
      "country_code": "US",
      "payment_method": {
        "method_type": "bank_account",
        "account_id": "DE89370400440532013000",
        "issuing_country": "DE"
      }
    },
    "counterparty": {
      "entity_type": "company",
      "full_name": "John Doe",
      "country_code": "GB"
    },
    "custom_properties": {
      "order_id": "ORD-7891"
    }
  }'

응답

API는 생성된 거래와 초기 평가 결과를 반환합니다:

필드	유형	설명
`uuid`	string	Didit의 고유 거래 식별자
`txn_id`	string	제공한 거래 ID
`status`	string	`APPROVED`, `IN_REVIEW`, `DECLINED`, `AWAITING_USER` 중 하나
`score`	number	일치한 모든 규칙의 누적 위험 점수
`severity`	string	일치한 규칙 중 가장 높은 심각도(`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`)
`decision_reason_code`	string	상태 결정에 대한 기계가 읽을 수 있는 사유
`decision_reason_label`	string	결정에 대한 사람이 읽을 수 있는 설명

전체 요청 및 응답 스키마는 API 레퍼런스를, 주석이 달린 페이로드 예시는 전용 응답 스키마 레퍼런스를 참조하세요.

검토자에게 거래 할당

write:transactions 권한이 있는 API 키로 보류 중인 거래를 애플리케이션 멤버에게 할당하거나 할당을 해제합니다. 각 변경 사항은 거래 타임라인에 TRANSACTION_ASSIGNED로 기록됩니다.

호출	용도
`POST /v3/transactions/{transaction_uuid}/assign/`	거래 하나를 할당합니다.
`POST /v3/transactions/assign/`	거래 최대 500건을 한 멤버에게 할당합니다.

두 호출 모두 assignee_email을 받습니다. 이는 Didit에 로그인한 적이 있는 애플리케이션 멤버의 이메일입니다. 할당을 해제하려면 null 또는 빈 문자열을 보냅니다. 일괄 호출은 1~500개의 거래 UUID 목록인 transaction_ids도 받습니다.

curl -X POST "https://verification.didit.me/v3/transactions/assign/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transaction_ids": ["<transaction-uuid>"], "assignee_email": "analyst@example.com"}'

단일 호출은 uuid, transaction_number, assignee, changed를 반환합니다(거래에 이미 이 담당자가 할당되어 있으면 false). 애플리케이션에 해당 거래가 없으면 404를 반환합니다. 일괄 호출은 transactions(위와 같은 항목이 하나씩 포함된 목록), updated_count, not_found_transaction_ids를 반환합니다. 거래 목록은 assignee 필터로 조회할 수 있습니다. 이 필터는 쉼표로 구분된 목록이며, 값 중 하나라도 일치하면 결과에 포함됩니다: me, unassigned, rules(검토자 없이 규칙만으로 결정된 거래), 또는 멤버 이메일.

멱등성

txn_id(전송하는 transaction_id)는 애플리케이션 안에서 고유해야 합니다. 이미 존재하는 transaction_id를 다시 전송하면 transaction_id 필드에 A transaction with this transaction_id already exists. 메시지와 함께 400이 반환됩니다. 거의 동시에 전송된 동일한 두 요청 중 두 번째 요청에는 409가 반환됩니다. 두 응답 모두 기존 거래를 반환하지 않습니다. 안전하게 재시도하려면 중복된 transaction_id에 대한 400 또는 409를 “이미 생성됨”으로 간주하고, 요청을 다시 보내는 대신 기존 거래를 조회하십시오. 첫 번째 응답의 uuid를 사용하여 GET /v3/transactions/{uuid}/로 조회하거나, transaction.created webhook에 txn_id와 함께 포함된 transaction_id(Didit uuid)를 사용하십시오. txn_id는 항상 자체적으로 생성하십시오(예: 자체 거래 DB ID, UUID 또는 결정적 해시).

과거 거래 백필

과거 거래를 수집하려면 과거 날짜의 txn_date를 전달하십시오. 기본적으로 규칙 평가는 계속 수행됩니다. 대량의 과거 데이터를 적재하는 동안 규칙 평가를 건너뛰려면 콘솔의 CSV 가져오기에서 dry-ingest 모드를 사용하십시오. 자세한 내용은 연동 가이드를 참조하십시오.

다음 단계

규칙 및 점수 산정

제출된 거래가 규칙에 따라 평가되는 방식입니다.

응답 스키마

주석이 포함된 전체 응답 payload입니다.

암호화폐 스크리닝

암호화폐 거래를 대상으로 하는 자동 지갑 및 거래 스크리닝입니다.

Travel Rule

가상 자산 이체에 Travel Rule 준수 데이터를 첨부합니다.

IP 보강

규칙에서 사용할 수 있는 IP 기반 컨텍스트입니다.

API 레퍼런스

Create Transaction endpoint의 전체 요청 스키마입니다.

시작하기

기능

레퍼런스

콘솔

거래 제출 API: payload 및 데이터 모델

거래 카테고리

거래 세부 정보

주체 및 거래 상대방

결제 수단

암호화폐 스크리닝 재정의

기기 컨텍스트

사용자 지정 속성

요청 예시

응답

검토자에게 거래 할당

멱등성

과거 거래 백필

다음 단계

규칙 및 점수 산정

응답 스키마

암호화폐 스크리닝

Travel Rule

IP 보강

API 레퍼런스

​거래 카테고리

​거래 세부 정보

​주체 및 거래 상대방

​결제 수단

​암호화폐 스크리닝 재정의

​기기 컨텍스트

​사용자 지정 속성

​요청 예시

​응답

​검토자에게 거래 할당

​멱등성

​과거 거래 백필

​다음 단계

규칙 및 점수 산정

응답 스키마

암호화폐 스크리닝

Travel Rule

IP 보강

API 레퍼런스

거래 카테고리

거래 세부 정보

주체 및 거래 상대방

결제 수단

암호화폐 스크리닝 재정의

기기 컨텍스트

사용자 지정 속성

요청 예시

응답

검토자에게 거래 할당

멱등성

과거 거래 백필

다음 단계