> ## 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.

# 取引モニタリング連携：KYT API

> Didit の取引モニタリング（KYT）連携のアーキテクチャとベストプラクティス。リアルタイムとバッチ、当事者、冪等性、過去データの取り込み、Webhookを解説。毎月1,000件まで含まれ、以降は1件あたり$0.001。

このガイドでは、トランザクションモニタリングの連携全体を扱います。[クイックスタート](https://docs.didit.me/ja/transaction-monitoring/quickstart.md)で利用を開始でき、このページで本番環境への移行を進められます。

## アーキテクチャ

```mermaid theme={null}
sequenceDiagram
    participant You as Your platform
    participant Didit as Didit API
    participant Rules as Rule engine
    participant AML as AML providers
    participant Webhook as Your webhook

    You->>Didit: POST /v3/transactions/ (txn_id, parties, amount)
    Didit->>Didit: IP enrichment (inline)
    Didit->>AML: Screen wallet or transaction hash + address
    AML-->>Didit: Hits / clean
    Didit->>Rules: Evaluate all active rules
    Rules-->>Didit: Score + matched rules + actions
    Didit-->>You: Transaction record with status
    Didit->>Webhook: transaction.created
    Didit->>Webhook: transaction.status.updated (if async rules)
```

## 認証

標準の`x-api-key`ヘッダーを使用します。セッションとエンティティで同じキーを使用します。[API認証](https://docs.didit.me/ja/getting-started/api-authentication.md)を参照してください。

## 取引の送信

エンドポイントは`POST /v3/transactions/`の1つだけです。完全なスキーマは[取引の送信](https://docs.didit.me/ja/transaction-monitoring/transactions.md)を参照してください。

**最小限のペイロード：**

```json theme={null}
{
  "transaction_id": "tx-0001",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "500.00",
    "currency": "EUR"
  },
  "subject": { "entity_type": "person", "vendor_data": "user-42", "full_name": "John Doe" },
  "counterparty": { "entity_type": "company", "full_name": "Acme Corp" }
}
```

**支払い方法、デバイスのコンテキスト、カスタムプロパティを含む詳細なペイロード：**

```json theme={null}
{
  "transaction_id": "tx-0002",
  "transaction_at": "2026-04-16T10:00:00Z",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "12500.00",
    "currency": "USD",
    "action_type": "withdrawal"
  },
  "subject": {
    "entity_type": "person",
    "vendor_data": "user-42",
    "full_name": "John Doe",
    "country_code": "US",
    "device_context": {
      "fingerprint": "fp-9f2c...",
      "user_agent": "Mozilla/5.0 ...",
      "browser_family": "Chrome",
      "platform": "web",
      "network_context": { "ip_address": "203.0.113.5" }
    },
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US12345678901234567890",
      "issuing_country": "US"
    }
  },
  "counterparty": {
    "entity_type": "company",
    "vendor_data": "biz-acme",
    "full_name": "Acme Corp",
    "country_code": "US",
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US09876543210987654321",
      "issuing_country": "US"
    }
  },
  "custom_properties": {
    "invoice_id": "INV-2026-00042",
    "category": "b2b_goods"
  }
}
```

すべてのトップレベルフィールドでcamelCaseのエイリアス（`txnId`、`txnDate`、`type`、`info`、`applicant`、`props`、`travelRule`、`includeCryptoScreening`）を受け付けます。SDKのワイヤーフォーマットとsnake\_case形式は、どちらも同じように扱われます。

## 当事者のモデリング

すべての取引には、必須の`subject`（顧客、つまりモニタリング対象の当事者）と任意の`counterparty`（取引相手）があります。それぞれが独自の`payment_method`と任意の`device`コンテキストを持ちます。

レスポンスでは、これらは`parties`配列に役割`APPLICANT`と`COUNTERPARTY`として返されます。`vendor_data`のない当事者は、エンティティと紐付かない外部スナップショット（`kind: EXTERNAL`）として保存されます。

当事者のフィールドについては[取引のペイロード](https://docs.didit.me/ja/transaction-monitoring/transactions.md)を参照してください。

## 冪等性

`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`は必ず送信前に自社側で生成してください**。冪等性の確保にDiditが生成するIDを頼りにしないでください。自社のデータベースID、UUID、または取引フィールドのハッシュを使用します。

## リアルタイム処理とバッチ処理

* **リアルタイム**：ほとんどのユースケースで推奨します。自社システムで取引が発生した時点で送信します。ルールは同期的に評価され、判定が返されます。
* **バッチ／バックフィル**：過去データの取り込みでは、過去の日付の`txn_date`を渡します。この場合もルールは実行され、Webhookがトリガーされることがあります。バックフィルでルールをトリガーしないようにするには、コンソールのCSVインポートで「dry ingest」フラグを使用します。

## 過去データの取り込み

別のトランザクションモニタリングシステムから移行する場合：

1. 過去の取引をCSVにエクスポートします。
2. コンソールの*Transactions → Import history*を使用し（またはAPI経由で繰り返し送信し）、過去の日付の`txn_date`を指定します。
3. ルールは取り込みの完了後に有効にするか、dry ingestを使ってルール評価をスキップします。

> [!WARNING]
>
> 過去データに対するルール評価は慎重に行ってください。6か月分の履歴を「30日間に20件の送金」ルールに通すと、一度に数千件のアラートが生成されます。

## Webhook

以下を購読してください：

* `transaction.created`：送信されたすべての取引。
* `transaction.status.updated`：ステータスの変更（例：アナリストがステータスを`IN_REVIEW`から`APPROVED`に変更した場合や、非同期のAMLチェックでスコアが更新された場合）。

詳細は[TMのWebhook](https://docs.didit.me/ja/transaction-monitoring/webhooks.md)を参照してください。

```typescript theme={null}
app.post('/webhooks/didit-tm', (req, res) => {
  if (!verifySignature(req)) return res.status(401).end();

  const { webhook_type, status, txn_id } = req.body;
  if (webhook_type === 'transaction.status.updated' && status === 'DECLINED') {
    suspendTransaction(txn_id);
  }
  res.status(200).end();
});
```

## ステータスへの対応

| ステータス | 対応 |
| - | - |
| `APPROVED` | 通常どおり取引を処理します。 |
| `IN_REVIEW` | アナリストのレビューまたは自動再チェックで結論が出るまで、取引を保留します。 |
| `DECLINED` | 取引を拒否します。ユーザーには汎用的なエラーを表示します。 |
| `AWAITING_USER` | 取引を確定するには、ユーザーが操作する必要があります。`action_required`ブロックを読み取り、その`url`をユーザーに送信してください（SDKでは[自動で処理できます](https://docs.didit.me/ja/transaction-monitoring/sdk-transaction-submission.md#ユーザーに必要なアクション)）。 |

[TMのステータス](https://docs.didit.me/ja/transaction-monitoring/statuses.md)を参照してください。

## 取引とエンティティの紐付け

すべての当事者に`vendor_data`を渡してください。メリットは次のとおりです。

* すべての取引がUserまたはBusinessのプロフィールに集約されます。
* 頻度（velocity）ルールや行動ルールが、評価に使う全履歴を参照できます。
* エンティティをブロックすると、以降の取引に自動的に反映されます。

`vendor_data`がなくてもエラーにはなりません（取引は外部スナップショットとして保存されます）が、エンティティ単位で集約できなくなります。

## リメディエーションセッション

ルールのアクションによって取引が`AWAITING_USER`に移行すると、Diditは自動的に**リメディエーションセッション**を作成します。これは同じ`vendor_data`に対する標準のホスト型検証セッションです。
カスタムルールでは、常にアクション自体でワークフローを指定します。組み込みのライブラリルールでは、[取引設定のリメディエーションワークフロー](https://docs.didit.me/ja/transaction-monitoring/settings.md#是正ワークフロー)、次にアプリケーションの生体認証ワークフロー（対象者に保存済みの参照顔がある場合）、次にアプリケーションのデフォルトワークフローの順にフォールバックします。
トラベルルールの取引はこの自動フォールバックの対象外です。これらの取引で保留中となるアクションは、ウォレット所有権の証明です。
取引（レスポンス、以降のすべての取得、すべてのWebhook）には、これが正規の`action_required`ブロックとして含まれます。

```json theme={null}
{
  "status": "AWAITING_USER",
  "action_required": {
    "type": "verification_session",
    "url": "https://verify.didit.me/session/...",
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "status": "Not Started"
  },
  "remediation": {
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "url": "https://verify.didit.me/session/...",
    "status": "Not Started"
  }
}
```

`remediation`は後方互換性のために残されています。正規のブロックは`action_required`です（[トラベルルール](https://docs.didit.me/ja/transaction-monitoring/travel-rule.md)の送金に対する`wallet_ownership`アクションも含みます）。
`wallet_ownership`アクションは、それ自体では取引のステータスを変更しません。取引はルールによって付与されたステータス（多くの場合`APPROVED`）のままとなるため、`AWAITING_USER`の場合だけでなく、すべてのレスポンスで`action_required`を確認してください。

ユーザーが認証を完了します。**生体認証**ワークフローの場合は、ライブネスチェック済みのセルフィーを、最初のKYCオンボーディング時に取得した顔と照合します。これは[高額取引](https://docs.didit.me/ja/transaction-monitoring/sdk-transaction-submission.md#例：高額出金時の生体認証によるステップアップ)に対する最も強力なステップアップ認証です。
セッションが判定に達すると、取引は自動的にその判定に従い、`APPROVED`（`decision_reason_code: user_action_approved`）、`DECLINED`（`user_action_declined`）、または`IN_REVIEW`（`user_action_in_review`）となり、`transaction.status.updated`のWebhookが送信されます。

> [!NOTE]
>
> KYB以外のすべてのワークフロータイプを選択できます。
> 生体認証ワークフロー（および本人確認の前に顔照合を実行するワークフロー）では、対象者が承認済みの認証による保存済みの参照顔をすでに持っている必要があります。参照顔を持たないユーザーは代わりにアプリケーションのデフォルトワークフローに送られ、その置き換えを記録したメモが取引に残されます。

## ベストプラクティス

| プラクティス | 理由 |
| - | - |
| 常に`vendor_data`を渡す | 集計が可能になります。 |
| 独自の`txn_id`を使用する | 冪等性のためです。 |
| `transaction.created`と`transaction.status.updated`の両方を購読する | 非同期の状態変化（例：アナリストによるレビュー結果）を検知できます。 |
| ルールのしきい値を慎重に設定する | しきい値が低いとアラートが増え、高いとリスクの見逃しが増えます。[リスクスコアリング](https://docs.didit.me/ja/transaction-monitoring/risk-scoring.md)を参照してください。 |
| コンソールでルールの実行回数を監視する | 一度も発火しないルール（設定ミス）や、すべてに発火するルール（条件が緩すぎる）を検出できます。 |
| 本番運用前にTESTモードでルールをテストする | [ルール](https://docs.didit.me/ja/transaction-monitoring/rules.md)を参照してください。 |

## レート制限

[レート制限](https://docs.didit.me/ja/integration/rate-limiting.md)を参照してください。取引作成エンドポイントは最もスループットの高いエンドポイントの1つで、一般的な制限は毎秒数百リクエストです。バーストリクエストは慎重に行ってください。

## 次のステップ

> [card] [取引](https://docs.didit.me/ja/transaction-monitoring/transactions.md)
>
> ペイロードの完全なリファレンスです。

> [card] [ルール](https://docs.didit.me/ja/transaction-monitoring/rules.md)
>
> ルールの評価方法です。

> [card] [Webhook](https://docs.didit.me/ja/transaction-monitoring/webhooks.md)
>
> イベントカタログです。

> [card] [トラブルシューティング](https://docs.didit.me/ja/transaction-monitoring/troubleshooting.md)
>
> 連携でよくある問題です。


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