> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Didit에 거래를 제출해 실시간 모니터링을 받으세요. 거래 당사자, 결제 수단, 기기, 커스텀 속성을 포함합니다. 월 1,000건 포함, 이후 건당 $0.001.

[Create Transaction](https://docs.didit.me/ko/management-api/transactions/create.md) API를 통해 거래를 Didit에 제출하십시오. 각 거래에는 규칙 엔진이 실시간으로 평가하는 구조화된 당사자, 결제, 맥락 데이터가 포함됩니다.

> [!TIP]
>
> 거래가 최종 사용자의 기기에서 발생하는 경우(예: 암호화폐 출금, 앱 내 결제)에는 [SDK 거래 제출](https://docs.didit.me/ko/transaction-monitoring/sdk-transaction-submission.md)을 고려하십시오. 이 방식에서는 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 | 이 당사자에 대해 귀사가 사용하는 식별자. 거래를 [사용자](https://docs.didit.me/ko/management-api/users/list.md) 또는 [기업 프로필](https://docs.didit.me/ko/business-verification/business-profiles.md)에 연결합니다. |
| `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` 상태로 전환되며 소유권 증명 절차가 시작됩니다. 자세한 내용은 [선언된 자체 보관 지갑](https://docs.didit.me/ko/transaction-monitoring/travel-rule.md#선언된-자체-보관-지갑)을 참조하십시오.

암호화폐 거래의 경우 `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의 경도 |

> [!NOTE]
>
> `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, 채널처럼 비즈니스에 특화된 컨텍스트를 전달할 때 유용합니다.

```json theme={null}
"custom_properties": {
  "product_category": "electronics",
  "merchant_id": "MER456",
  "channel": "mobile_app"
}
```

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

## 요청 예시

```bash theme={null}
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 레퍼런스](https://docs.didit.me/ko/management-api/transactions/create.md)를, 주석이 달린 페이로드 예시는 전용 [응답 스키마 레퍼런스](https://docs.didit.me/ko/transaction-monitoring/response-schema.md)를 참조하세요.

## 검토자에게 거래 할당

`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`도 받습니다.

```bash theme={null}
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`를 반환합니다.

[거래 목록](https://docs.didit.me/ko/management-api/transactions/list.md)은 `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}/`](https://docs.didit.me/ko/management-api/transactions/get)로 조회하거나, `transaction.created` webhook에 `txn_id`와 함께 포함된 `transaction_id`(Didit uuid)를 사용하십시오.
`txn_id`는 항상 자체적으로 생성하십시오(예: 자체 거래 DB ID, UUID 또는 결정적 해시).

## 과거 거래 백필

과거 거래를 수집하려면 과거 날짜의 `txn_date`를 전달하십시오. 기본적으로 규칙 평가는 계속 수행됩니다. 대량의 과거 데이터를 적재하는 동안 규칙 평가를 건너뛰려면 콘솔의 CSV 가져오기에서 dry-ingest 모드를 사용하십시오. 자세한 내용은 [연동 가이드](https://docs.didit.me/ko/transaction-monitoring/integration-guide.md#과거-데이터-수집)를 참조하십시오.

## 다음 단계

> [card] [규칙 및 점수 산정](https://docs.didit.me/ko/transaction-monitoring/rules.md)
>
> 제출된 거래가 규칙에 따라 평가되는 방식입니다.

> [card] [응답 스키마](https://docs.didit.me/ko/transaction-monitoring/response-schema.md)
>
> 주석이 포함된 전체 응답 payload입니다.

> [card] [암호화폐 스크리닝](https://docs.didit.me/ko/transaction-monitoring/aml-screening.md)
>
> 암호화폐 거래를 대상으로 하는 자동 지갑 및 거래 스크리닝입니다.

> [card] [Travel Rule](https://docs.didit.me/ko/transaction-monitoring/travel-rule.md)
>
> 가상 자산 이체에 Travel Rule 준수 데이터를 첨부합니다.

> [card] [IP 보강](https://docs.didit.me/ko/transaction-monitoring/ip-enrichment.md)
>
> 규칙에서 사용할 수 있는 IP 기반 컨텍스트입니다.

> [card] [API 레퍼런스](https://docs.didit.me/ko/management-api/transactions/create.md)
>
> Create Transaction endpoint의 전체 요청 스키마입니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.