> ## 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：ペイロードとデータモデル

> Diditの取引送信APIで、当事者、決済手段、デバイス、カスタムプロパティを含む取引をリアルタイムでモニタリングできます。毎月1,000件まで含まれ、以降は1件あたり$0.001です。

[取引作成](https://docs.didit.me/ja/management-api/transactions/create.md)APIを使用して、Diditに取引を送信します。各取引には、ルールエンジンがリアルタイムで評価する構造化された当事者データ、支払いデータ、コンテキストデータが含まれます。

> [!TIP]
>
> 暗号資産の出金やアプリ内決済など、エンドユーザーのデバイス上で取引が発生する場合は、[SDKによる取引送信](https://docs.didit.me/ja/transaction-monitoring/sdk-transaction-submission.md)をご検討ください。APIキーの代わりにスコープ付きトークンを使用し、デバイスインテリジェンスが自動的に収集され、必要なユーザーアクション（ウォレット所有証明、ステップアップ認証）がその場で起動します。

## 取引カテゴリー

すべての取引には`transaction_category`があり、ルールと分析での取引の扱いを決定します。

| カテゴリー | 説明 |
| - | - |
| `finance` | 標準的な金融取引（入金、出金、送金） |
| `kyc` | 本人確認に関連するイベント |
| `travel_rule` | トラベルルールへの準拠が必要な暗号資産の送金 |
| `user_event` | プラットフォーム独自のイベント（ログイン、プロフィール変更など） |
| `gambling_bet` | ギャンブルの賭けまたはベットの実行 |
| `gambling_limit_change` | プレイヤーの入金、損失、または賭け金の上限の変更 |
| `gambling_bonus_change` | ボーナスの付与、利用、または没収 |
| `audit_trail_event` | システムまたはコンプライアンスの監査イベント |

## 取引の詳細

`transaction_details`オブジェクトには金融データが含まれます。

| フィールド | 型 | 説明 |
| - | - | - |
| `direction` | string | `inbound`または`outbound` |
| `amount` | string | 10進数の文字列で表した取引金額（例：`"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 | 外部の支払い参照ID。送金後の暗号資産スクリーニングでは、ブロックチェーンの取引ハッシュを使用してください。 |

## 対象者と取引相手

各取引には**対象者**（必須）と、任意の**取引相手**があります。どちらも同じ当事者モデルを使用します。

| フィールド | 型 | 説明 |
| - | - | - |
| `entity_type` | string | `person`または`company` |
| `vendor_data` | string | この当事者に対するお客様の識別子。取引を[ユーザー](https://docs.didit.me/ja/management-api/users/list.md)または[企業プロファイル](https://docs.didit.me/ja/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 or 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 | 口座番号、アドレス、またはカードトークン |
| `issuing_country` | string | 支払い手段を発行した国 |

`travelRule`取引では、`method_type: "unhosted_wallet"`（エイリアス`type`）を取引相手の支払い方法に指定すると、取引相手のウォレットがセルフホスト型であることを宣言します。
トラベルルールが有効で、アプリケーションのデフォルト通貨での金額が`threshold_amount`を下回らない場合、送金は直接`UNCONFIRMED_OWNERSHIP`に移行し、所有証明フローに入ります。詳しくは[宣言されたセルフホスト型ウォレット](https://docs.didit.me/ja/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`です。camelCaseのエイリアス`device`も使用でき、SDKの送信形式ではこちらが使われます。レスポンスでは、`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 | ユーザーの現在のセッションの識別子。メタデータに保存されます。camelCaseのエイリアス:`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を利用している場合、これらのフィールドは自動的に収集されます。

すべてのフィールドでcamelCaseのエイリアスを使用できます:`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のルールビルダーでは、最近取り込まれた取引で確認されたキーが、条件のフィールド選択の**Custom Properties**の下に表示されます。同じグループ内の**Enter custom property**を使うと、任意のキーを手動で入力できます(大文字と小文字は区別されます)。詳しくは[ルールとスコアリング](https://docs.didit.me/ja/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/ja/management-api/transactions/create.md)を、注釈付きのペイロード解説は専用の[レスポンススキーマリファレンス](https://docs.didit.me/ja/transaction-monitoring/response-schema.md)を参照してください。

## 取引をレビュアーに割り当てる

`write:transactions`権限を持つAPIキーを使って、保留中の取引をアプリケーションのメンバーに割り当てたり、割り当てを解除したりできます。
変更はそれぞれ`TRANSACTION_ASSIGNED`として取引のタイムラインに記録されます。

| 呼び出し | 用途 |
| - | - |
| `POST /v3/transactions/{transaction_uuid}/assign/` | 1件の取引を割り当てます。 |
| `POST /v3/transactions/assign/` | 最大500件の取引を1人のメンバーに割り当てます。 |

どちらの呼び出しも`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`(上記と同じ形式のエントリーが1件ずつ)、`updated_count`、`not_found_transaction_ids`を返します。

[取引一覧](https://docs.didit.me/ja/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`が返されます。また、同一のリクエストが2件同時に競合した場合は、2件目に`409`が返されます。
どちらのレスポンスにも既存の取引は含まれません。
安全に再試行するには、重複した`transaction_id`に対する`400`または`409`を「作成済み」として扱い、再送信せずに既存の取引を照会してください。最初のレスポンスの`uuid`を使って[`GET /v3/transactions/{uuid}/`](https://docs.didit.me/ja/management-api/transactions/get)で取得するか、`transaction.created` Webhookが`txn_id`とともに渡す`transaction_id`（Diditのuuid）を使用します。
`txn_id`は必ず自社側で生成してください（例: 自社の取引DBのID、UUID、決定論的ハッシュ）。

## 過去データのバックフィル

`txn_date`に過去の日付を指定すると、過去の取引を取り込めます。デフォルトではルールは引き続き評価されます。大量の過去データを一括で読み込む際にルール評価をスキップしたい場合は、コンソールのCSVインポートをドライインジェストモードで使用してください。詳しくは[連携ガイド](https://docs.didit.me/ja/transaction-monitoring/integration-guide.md#過去データの取り込み)を参照してください。

## 次のステップ

> [card] [ルールとスコアリング](https://docs.didit.me/ja/transaction-monitoring/rules.md)
>
> 送信された取引がルールに照らしてどのように評価されるかを説明します。

> [card] [レスポンススキーマ](https://docs.didit.me/ja/transaction-monitoring/response-schema.md)
>
> 注釈付きのレスポンスペイロード全体です。

> [card] [暗号資産スクリーニング](https://docs.didit.me/ja/transaction-monitoring/aml-screening.md)
>
> 暗号資産取引に対するウォレットと取引の自動スクリーニングです。

> [card] [トラベルルール](https://docs.didit.me/ja/transaction-monitoring/travel-rule.md)
>
> 暗号資産の移転にトラベルルールのコンプライアンスデータを添付します。

> [card] [IPエンリッチメント](https://docs.didit.me/ja/transaction-monitoring/ip-enrichment.md)
>
> ルールで利用できる、IPから導出されたコンテキストです。

> [card] [APIリファレンス](https://docs.didit.me/ja/management-api/transactions/create.md)
>
> Create Transactionエンドポイントのリクエストスキーマ全体です。


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