取引送信API：ペイロードとデータモデル

取引作成APIを使用して、Diditに取引を送信します。各取引には、ルールエンジンがリアルタイムで評価する構造化された当事者データ、支払いデータ、コンテキストデータが含まれます。

暗号資産の出金やアプリ内決済など、エンドユーザーのデバイス上で取引が発生する場合は、SDKによる取引送信をご検討ください。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	この当事者に対するお客様の識別子。取引をユーザーまたは企業プロファイルに紐付けます
`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に移行し、所有証明フローに入ります。詳しくは宣言されたセルフホスト型ウォレットを参照してください。暗号資産取引では、ブロックチェーンスクリーニングが自動的に実行されるように、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の地理的な経度

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、チャネルなど、ビジネス固有のコンテキストを渡すのに便利です。

"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を使うと、任意のキーを手動で入力できます(大文字と小文字は区別されます)。詳しくはルールとスコアリングを参照してください。

リクエスト例

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/`	1件の取引を割り当てます。
`POST /v3/transactions/assign/`	最大500件の取引を1人のメンバーに割り当てます。

どちらの呼び出しも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(上記と同じ形式のエントリーが1件ずつ)、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が返されます。また、同一のリクエストが2件同時に競合した場合は、2件目に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インポートをドライインジェストモードで使用してください。詳しくは連携ガイドを参照してください。

次のステップ

ルールとスコアリング

送信された取引がルールに照らしてどのように評価されるかを説明します。

レスポンススキーマ

注釈付きのレスポンスペイロード全体です。

暗号資産スクリーニング

暗号資産取引に対するウォレットと取引の自動スクリーニングです。

トラベルルール

暗号資産の移転にトラベルルールのコンプライアンスデータを添付します。

IPエンリッチメント

ルールで利用できる、IPから導出されたコンテキストです。

APIリファレンス

Create Transactionエンドポイントのリクエストスキーマ全体です。

​取引カテゴリー

​取引の詳細

​対象者と取引相手

​支払い方法

​暗号資産スクリーニングの上書き

​デバイスコンテキスト

​カスタムプロパティ

​リクエスト例

​レスポンス

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

​冪等性

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

​次のステップ

ルールとスコアリング

レスポンススキーマ

暗号資産スクリーニング

トラベルルール

IPエンリッチメント

APIリファレンス

取引カテゴリー

取引の詳細

対象者と取引相手

支払い方法

暗号資産スクリーニングの上書き

デバイスコンテキスト

カスタムプロパティ

リクエスト例

レスポンス

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

冪等性

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

次のステップ