メインコンテンツへスキップ

コンテキストシグナル

はじめに​

コンテキストシグナルは完了済みのクレジット取引を評価し、自己不正またはソーシャルエンジニアリングのリスク評価を返して、お客様自身の不正対策の判断を補強します。

これはカード非提示認証を補完するものであり、既にご利用の取引エンドポイントの契約や動作を変更するものではありません。これまで通り取引の最終状態(approved、inconclusiveなど)を受け取った上で、コンテキストシグナルを照会します。

APIリクエストはアクセストークンを使用して認証されます。有効なアクセストークンを含まないリクエストはすべてエラーを返します。詳しくは認証をご覧ください。

権限で制御されたアクセス

このエンドポイントへのアクセスは、お客様の会社に割り当てられた権限(ロール)によって制御されています。権限がない場合、エンドポイントは403を返します。Unicoチームに有効化を依頼してください。

ベースURL
  • UAT:https://transactions.transactional.uat.unico.app/api/public/v1
  • 本番:https://transactions.transactional.unico.app/api/public/v1

コンテキストシグナルの取得​

GET /transactions/{transaction_id}/signals — 完了済み取引のリスク評価を返します。

結果は取引が最終状態に達した時点で非同期に事前計算されるため、このエンドポイントはすでに利用可能な結果を照会するだけです。

パスパラメーター
パラメーター型必須説明
transaction_idstringyes取引ID(UUID v4)。例:6ab1771e-dfab-4e47-8316-2452268e5481。
ヘッダー
ヘッダー値
AuthorizationBearer {token} — 有効なアクセストークン。
Acceptapplication/json
リクエスト例
GET /api/public/v1/transactions/6ab1771e-dfab-4e47-8316-2452268e5481/signals HTTP/1.1
Host: transactions.transactional.uat.unico.app
Authorization: Bearer {token}
Accept: application/json
200 OK
{
  "signals": {
    "auto_fraud_risk": "high",
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}
フィールド型有無説明
signals.auto_fraud_riskstring (enum)optional自己不正のリスクレベル。検出された場合のみ存在します。
signals.social_eng_riskstring (enum)optionalソーシャルエンジニアリングのリスクレベル。検出された場合のみ存在します。
signals.more_info.limited_databooleanalways十分な信頼性のある評価を行うためのデータが不足している場合にtrue。
signals.more_info.holder_identifiedbooleanalwaysカード名義人を特定できなかった場合にfalse。

考えられるリスク値:very_low、low、medium、high、very_high。

情報

auto_fraud_riskとsocial_eng_riskは互いに排他的であり、同じレスポンスに両方が含まれることはありません。limited_dataがtrueの場合、評価に十分なデータがないため、両方のリスクフィールドとも存在しないと想定されます。

レスポンス例

ソーシャルエンジニアリングのリスクが検出された場合:

{
  "signals": {
    "social_eng_risk": "very_high",
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

リスクが検出されない場合 — 通常の取引:

{
  "signals": {
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

データが不十分な場合:

{
  "signals": {
    "more_info": {
      "limited_data": true,
      "holder_identified": true
    }
  }
}

カード名義人を特定できなかった場合:

{
  "signals": {
    "more_info": {
      "limited_data": false,
      "holder_identified": false
    }
  }
}
その他のレスポンスコード

エラーはエラーで説明されている標準のエラー形式で返されます。

HTTPコードコード状況対応方法
202—結果がまだ計算されていません — 非同期処理が進行中です。200が返るまで呼び出しを繰り返してください(ポーリング)。
40040004transaction_idが無効(UUID v4でない)か、パラメーターの形式が不正です。IDの形式を修正してから再度リクエストしてください。
40340305会社にこのエンドポイントの権限(ロール)が有効化されていません。Unicoチームに有効化を依頼してください。
40440401取引が見つかりませんでした。取引IDを確認してください。
40440484評価対象の取引が見つかりませんでした。「結果は得られない」として扱い、照会を停止してください。
40940983取引がまだ最終状態に達していません。最終状態になるまで待ってから再度照会してください。
500—内部サービスエラー。バックオフしながら再試行してください。解消しない場合はUnicoサポートに連絡してください。

ルールとベストプラクティス​

  • 取引が最終状態に達した後にのみエンドポイントを照会してください。それより前に照会すると409が返ります。
  • 評価対象はクレジット取引のみです。サイレントモードで取得された取引は対象外です。
  • 202が返った場合は、200が返るまで呼び出しを繰り返してください。取引のレスポンスから1秒後に最初のリクエストを送信し、その後は2秒、4秒、8秒、16秒とバックオフしながら、最大5回まで試行してください。
  • サービスレベル目標は、取引のレスポンスから10秒以内です。
  • 404は「結果は得られない」として扱い、照会を停止してください。
  • auto_fraud_riskとsocial_eng_riskは互いに排他的です。
最終更新 に