Webhooksイベントタイプ

Verification.Result

確認試行の結果とともに発行されます。

配信とリカバリー

webhookイベントは失敗時に最大2回リトライされます。サーバーがイベントを受信できなかった場合、保存した確認IDを使用してGET /age-verification/get-statusをポーリングしてください。詳細は配信、リトライ、リカバリーを参照してください。

フィールド

フィールドタイプ必須説明
eventTypestringはい常に"Verification.Result"
dataobjectはい確認結果データ
data.idstring (UUID)はい一意の確認ID
data.statusstringはいPASSまたはFAILのいずれか
data.ageCategorystringいいえ推定年齢カテゴリ。adult、digital-youth、またはdigital-minorのいずれか。PASSステータスの場合、プロダクトの設定で選択されていれば存在します。FAILステータスの場合、failureReasonがage-criteria-not-metでageが存在する場合にのみ存在します。受け取る年齢フィールドを選ぶを参照してください
data.ageBandobjectいいえ年齢が当てはまる年齢区分。ageCategoryが存在し、確認の管轄に対する区分に年齢が収まる場合にのみ存在します。年齢区分を参照してください
data.ageBand.keystringはい区分の安定した識別子。nameではなくこの値で照合してください
data.ageBand.namestringはい区分名。例: 11-13、18+
data.ageBand.lowerAgenumberはい区分に含まれる最小の年齢
data.ageBand.upperAgenumberいいえ区分に含まれる最大の年齢。18+のような上限のない区分では存在しません
data.methodstringいいえ使用された確認方法。PASSステータスの場合は常に存在します。FAILステータスの場合、failureReasonがage-criteria-not-metの場合にのみ存在します
data.providerstringいいえメソッドを実行したベンダー。methodが存在する場合は常に存在します
data.failureReasonstringいいえ確認が失敗した理由。statusがFAILの場合は常に存在します。age-criteria-not-met、max-attempts-exceeded、またはfraudulent-activity-detectedのいずれかです
data.ageobjectいいえ年齢の詳細。age.lowとage.highの両方が利用可能で、プロダクトの設定で選択されている場合に存在します。FAILステータスの場合、failureReasonがage-criteria-not-metの場合にのみ存在します
data.age.lownumberいいえ推定年齢の下限。ID文書チェックなどのハード年齢確認方法の場合、これは正確な年齢です
data.age.highnumberいいえ推定年齢の上限。ID文書チェックなどのハード年齢確認方法の場合、これは正確な年齢です
data.dobstring (YYYY-MM-DD)いいえ確認された生年月日。確認方法が提供し、プロダクトのWebhook設定が含める場合にのみ含まれます

例

{
  "eventType": "Verification.Result",
  "data": {
    "id": "4e57301e-a4d1-498f-ac3f-f3d4de19abf6",
    "status": "PASS",
    "method": "id-document",
    "provider": "veratad",
    "age": {
      "low": 43,
      "high": 43
    },
    "dob": "1981-06-20"
  }
}

受け取る年齢フィールドを選ぶ

確認結果を受け取る方法ごとに、k-IDが返す年齢フィールドを選べます。Compliance Studioでプロダクトを開き、Product accessに進んで、Age resultカードを見つけてください。

カードには3つのチャネルがあります。

チャネル対象
Get statusGET /age-verification/get-statusのレスポンス
WebhooksVerification.Resultなど、確認結果を運ぶWebhookイベント
JavaScript result確認画面があなたのページに送信する結果メッセージ

各チャネルには3つのトグルがあります。

  • Date of birthはdobを制御します。
  • Ageはageを制御します。
  • Age categoryはageCategoryとageBandを制御します。

k-IDは、チャネルの設定で選択されているフィールドだけをそのチャネルで返します。各チャネルの設定は互いに独立しています。

トグルを変更して保存するまで、プロダクト独自の設定はありません。その間、k-IDは組織の設定に従います。カードには現在のデフォルトが表示されます。

設定の変更は、プロダクトを公開した後に反映されます。

includeDobクエリパラメータ

GET /age-verification/get-statusのincludeDobクエリパラメータは、レスポンスにdobを含めるかどうかを決めます。優先順位は、プロダクトに保存済みのAge result設定があるかどうかで変わります。

プロダクトincludeDobの値結果
保存済みの設定ありtrueまたはfalseパラメータがGet statusのDate of birthトグルより優先されます
保存済みの設定あり送信しないGet statusのDate of birthトグルが決めます
保存済みの設定なしtruedobが含まれます。ただし、組織が合否のみを返す設定の場合は含まれません
保存済みの設定なしfalseまたは送信しないdobは含まれません

includeDobパラメータはget-statusにのみ適用されます。WebhookイベントとJavaScript結果は、それぞれのトグルに従います。

検証イベントコントラクト

概要

このセクションは、2つのメカニズムを通じて提供される検証ステータスのAPIコントラクトを定義します:

  1. Webhookイベント: 検証が完了したときに送信されるVerification.Result Webhookイベント
  2. APIエンドポイント: 検証ステータスをポーリングするためのGET /age-verification/get-statusエンドポイント

このコントラクトは、すべての可能な結果タイプのフィールド存在ルール、データ型、および解釈ガイダンスを指定します。両方のメカニズムは類似のデータを提供しますが、ステータス値、フィールドの存在、および構造に重要な違いがあることに注意する必要があります。

DOMメッセージは信頼できる情報源ではありません

検証結果は、UI制御の目的でDOMメッセージを介してフロントエンドアプリケーションにも伝達されます。ただし、統合ロジックでは、webhookイベントとGET /age-verification/get-statusエンドポイントの応答のみを信頼できる権威あるデータソースとして考慮する必要があります。DOMメッセージは、フロントエンドアプリケーションの状態管理のみを目的として提供され、重要なビジネス決定やデータ永続化の基礎として使用すべきではありません。

データ構造

Webhookイベント構造

Webhookイベントはイベントエンベロープでラップされます:

{
  "eventType": "Verification.Result",
  "data": {
    "id": "uuid",
    "status": "PASS" | "FAIL",
    "ageCategory": "adult" | "digital-youth" | "digital-minor",
    "method": "id-document" | "credit-card" | "self-confirmation" | "social-security-number" | "email-confirmation" | "age-estimation-scan",
    "provider": string,
    "age": {
      "low": number,
      "high": number
    },
    "dob": "YYYY-MM-DD",
    "failureReason": string
  }
}

APIエンドポイント応答構造

GET /age-verification/get-statusエンドポイントは直接応答を返します:

{
  "id": "uuid",
  "status": "PASS" | "FAIL" | "PENDING" | "IN_PROGRESS",
  "ageCategory": "adult" | "digital-youth" | "digital-minor",
  "method": "id-document" | "credit-card" | "self-confirmation" | "social-security-number" | "email-confirmation" | "age-estimation-scan",
  "provider": string,
  "age": {
    "low": number,
    "high": number
  },
  "dob": "YYYY-MM-DD",
  "failureReason": string
}

クエリパラメータ:

  • id (必須): 検証ID
  • includeDob (オプション): trueまたはfalseの場合、プロダクトに保存済みのAge result設定があるとき、Get statusのDate of birthトグルを上書きします。保存済みの設定がない場合、trueは利用可能なときにdobフィールドを含め、それ以外の値では含めません。includeDobクエリパラメータを参照してください

完全なエンドポイントドキュメントについては、GET /age-verification/get-statusを参照してください。

WebhookとAPIエンドポイントの主な違い

側面WebhookイベントAPIエンドポイント
ステータス値PASSまたはFAILのみPASS、FAIL、PENDING、IN_PROGRESS
構造{ eventType, data }でラップ直接応答オブジェクト
DOBフィールド利用可能で、WebhookのDate of birthトグルが許可する場合に含まれるincludeDobクエリパラメータとGet statusのDate of birthトグルに従う(優先順位を参照)
AgeCategoryPASSステータスの場合(プロダクトの設定で選択されている場合)、およびFAILステータスでfailureReasonがage-criteria-not-metの場合に存在PASSとFAILの両方のステータスで年齢データが利用可能な場合に存在(プロダクトの設定で選択されている場合)
MethodステータスがPASSの場合にのみ存在PASSとFAILの両方のステータスで存在
利用可能なタイミング検証が完了したときのみ検証中を含め、いつでもポーリング可能

ステータスタイプ

PASS

検証が成功し、ユーザーが年齢基準を満たしていることが確認されました。

利用可能性:

  • Webhook: ✅ 検証が正常に完了したときに送信されます
  • APIエンドポイント: ✅ 検証が完了して成功したときに返されます

FAIL

検証により、ユーザーが年齢基準を満たしていないことが確認されたか、決定的な年齢判定ができなかったため、または不正行為が検出されたため、検証プロセスが失敗しました。これらのシナリオは、適切なfailureReason値を持つFAILステータスになります。

利用可能性:

  • Webhook: ✅ 検証が失敗して完了したときに送信されます
  • APIエンドポイント: ✅ 検証が完了して失敗したときに返されます

ステータス: PENDING

検証リクエストが作成されましたが、まだ処理が開始されていません。

利用可能性:

  • Webhook: ❌ 送信されません(webhookは完了時のみ発火します)
  • APIエンドポイント: ✅ 検証が初期状態のときに返されます

PENDINGのAPIエンドポイント応答:

  • id (UUID) - 常に含まれます
  • status ("PENDING") - 常に含まれます
  • 他のすべてのフィールドは存在しません

ステータス: IN_PROGRESS

検証は現在処理中です。

利用可能性:

  • Webhook: ❌ 送信されません(webhookは完了時のみ発火します)
  • APIエンドポイント: ✅ 検証が積極的に処理されているときに返されます

IN_PROGRESSのAPIエンドポイント応答:

  • id (UUID) - 常に含まれます
  • status ("IN_PROGRESS") - 常に含まれます
  • 他のすべてのフィールドは存在しません

ステータス別のフィールド存在ルール

Webhookイベント

Webhookイベントは、検証が完了したとき(ステータスがPASSまたはFAIL)にのみ送信されます。PENDINGやIN_PROGRESSなどの中間ステータスは含まれません。

ステータス: PASS

Webhookイベント

常に含まれる:

  • id (UUID)
  • status ("PASS")
  • method (string) - 使用された検証方法
  • provider (string) - メソッドを実行したベンダー

プロダクトの設定で選択されている場合に含まれる:

  • age (object) - lowとhighの両方の境界を含む
  • ageCategory (string) - adult、digital-youth、またはdigital-minorのいずれか

場合によって含まれる:

  • ageBand (object) - 年齢が当てはまる年齢区分。ageCategoryが存在する場合にのみ存在します(年齢区分を参照)
  • dob (string, YYYY-MM-DD形式) - 確認された生年月日。検証方法が提供し、プロダクトのWebhook設定が含める場合にのみ含まれます(特定の方法については生年月日フィールドセクションを参照)

含まれない:

  • failureReason

APIエンドポイント

常に含まれる:

  • id (UUID)
  • status ("PASS")
  • method (string) - 使用された検証方法(利用可能な場合)
  • provider (string) - メソッドを実行したベンダー(利用可能な場合)

プロダクトの設定で選択されている場合に含まれる:

  • age (object) - lowとhighの両方の境界を含む
  • ageCategory (string) - adult、digital-youth、またはdigital-minorのいずれか

場合によって含まれる:

  • ageBand (object) - 年齢が当てはまる年齢区分。ageCategoryが存在する場合にのみ存在します(年齢区分を参照)
  • dob (string, YYYY-MM-DD形式) - includeDobクエリパラメータまたはGet statusのDate of birthトグルが許可し、かつ検証方法が提供する場合にのみ含まれます(includeDobクエリパラメータと、特定の方法については生年月日フィールドセクションを参照)

含まれない:

  • failureReason

知っておくべきこと

  • PASSステータスを成功した検証として扱います
  • PASSとなるすべての検証方法が年齢情報を提供しますが、各チャネルにage、ageCategory、dobを含めるかどうかはプロダクトの設定で決まります。ageやageCategoryが存在すると想定しないでください
  • ユーザーの権限とアクセスレベルを決定するためにageCategoryフィールドを使用します
  • アクセス制御にage.lowやage.highのみに依存せず、代わりにageCategoryを使用します
  • dobが提供されている場合は使用できますが、常に利用可能であると想定しないでください
  • APIエンドポイントの場合: DOBデータが必要な場合は、クエリパラメータでincludeDob=trueを設定します。プロダクトに保存済みのAge result設定がある場合、パラメータがトグルより優先されます(GET /age-verification/get-statusと優先順位を参照)

ステータス: FAIL

Webhookイベント

常に含まれる:

  • id (UUID)
  • status ("FAIL")
  • failureReason (string) - 失敗の理由

場合によって含まれる:

  • method (string) - 失敗がmax-attempts-exceededまたはfraudulent-activity-detectedによるものでない場合にのみ存在
  • provider (string) - methodが存在する場合にのみ存在
  • age (object) - failureReasonがage-criteria-not-metの場合にのみ存在
  • ageCategory (string) - failureReasonがage-criteria-not-metでageが存在する場合にのみ存在
  • ageBand (object) - ageCategoryが存在する場合にのみ存在します(年齢区分を参照)
  • dob (string) - 検証方法が提供し、プロダクトのWebhook設定が含める場合にのみ存在します(特定の方法については生年月日フィールドセクションを参照)。

APIエンドポイント

常に含まれる:

  • id (UUID)
  • status ("FAIL")
  • failureReason (string) - 失敗の理由

場合によって含まれる:

  • method (string) - 失敗がage-criteria-not-metによる場合にのみ存在
  • provider (string) - methodが存在する場合にのみ存在
  • age (object) - failureReasonがage-criteria-not-metの場合にのみ存在
  • ageCategory (string) - ageが存在する場合にのみ存在
  • ageBand (object) - ageCategoryが存在する場合にのみ存在します(年齢区分を参照)
  • dob (string) - includeDobクエリパラメータまたはGet statusのDate of birthトグルが許可し、かつ検証方法が提供する場合にのみ含まれます(特定の方法については生年月日フィールドセクションを参照)

含まれない:

  • ageが存在しない場合のageCategory

知っておくべきこと

  • FAILステータスを失敗した検証として扱い、アクセスや権限を付与しないでください
  • 検証が失敗した理由を理解するために、常にfailureReasonを確認してください
  • FAILステータスでageフィールドが存在するとは想定しないでください。利用できない場合があります
  • FAIL結果でageが存在する場合、ログ記録や分析に使用できますが、アクセス制御の決定には使用しないでください
  • methodとageが存在しない場合を処理してください。これはシステムレベルの失敗を示し、年齢判定の失敗ではありません
  • Webhookイベントの場合: FAILステータスでfailureReasonがage-criteria-not-metの場合、ageCategoryが存在する可能性がありますが、アクセス制御の決定には使用しないでください
  • APIエンドポイントの場合: FAILステータスでageCategoryが存在する場合でも、アクセス制御の決定には使用しないでください

一般的な失敗理由:

  • age-criteria-not-met - ユーザーの確認された年齢が必要なしきい値を満たしていません
  • max-attempts-exceeded - ユーザーが利用可能なすべての検証試行を尽くしました(これは、失敗または不確定な年齢判定の後にユーザーが再試行を尽くした場合の最終的な失敗理由です)
  • fraudulent-activity-detected - システムが不審または不正な行動を検出しました

年齢フィールドの設定ルール

ageオブジェクトが存在する場合

ageオブジェクトには2つのフィールドが含まれます:

  • low (number): 年齢推定の下限、またはハード検証方法(例:ID文書)の正確な年齢。検証方法が正確な年齢を提供しない場合、これは検証に必要な最小年齢のしきい値です。
  • high (number): 年齢推定の上限、またはハード検証方法の正確な年齢。検証方法が正確な年齢を提供しない場合、これは100です。

ageが存在する条件:

  • PASSステータスの場合: プロダクトの設定でチャネルのageが選択されている場合に存在します。PASSとなるすべての検証方法が年齢情報を提供します
  • FAILステータスの場合: failureReasonがage-criteria-not-met

知っておくべきこと

  • PASSステータスでは、プロダクトの設定でチャネルのageが選択されていない場合、ageは存在しません。アクセスの判断にはageCategoryを使用してください
  • ageオブジェクトが存在すること、およびage.lowとage.highの両方が存在することを確認してから読み取ってください
  • age.low === age.highが正確な年齢を意味すると想定しないでください。そうなる場合もありますが、検証方法によって異なります
  • statusがPASSでない場合、アクセス制御にageフィールドを使用しないでください
  • PASSステータスの場合、アクセス決定を行う際は、生のage値よりもageCategoryを使用することを推奨します

ageCategoryが存在する場合

ageCategoryフィールドは、年齢と管轄情報から導出されます。

値:

  • adult - ユーザーは成人として分類されます
  • digital-youth - ユーザーはデジタルユースとして分類されます(年齢制限があるが未成年ではない)
  • digital-minor - ユーザーはデジタル未成年として分類されます

ageCategoryが存在する条件:

  • PASSステータスの場合: プロダクトの設定でチャネルのageCategoryが選択されている場合に存在します。k-IDは検証が成功したときに常に年齢カテゴリを計算します
  • FAILステータスの場合: failureReasonがage-criteria-not-metで年齢データが利用可能な場合(age.lowとage.highの両方が存在する場合)に存在します

知っておくべきこと

  • PASSステータスの場合、プロダクトの設定でチャネルのageCategoryが選択されていればageCategoryは存在します。存在する場合は、アクセス制御の決定に使用できます
  • 生のage値ではなく、アクセス制御の決定にageCategoryを使用してください
  • FAILステータスの場合、存在する場合でも、アクセス制御の決定にageCategoryを使用しないでください

ageとageCategoryが存在しない場合

条件:

  • 検証はPASSで、プロダクトの設定でそのチャネルのフィールドが選択されていなかった。その場合、PASS結果がage、ageCategory、またはその両方なしで届くことがあります
  • 検証がmax-attempts-exceededのfailureReasonで失敗した - 年齢判定は行われませんでした
  • 検証がfraudulent-activity-detectedのfailureReasonで失敗した - セキュリティ上の理由で年齢データが除外されました
  • 検証方法が年齢情報を提供しなかった

知っておくべきこと

  • 年齢情報が常に利用可能であると想定せず、欠落している年齢フィールドを適切に処理してください
  • ageが存在しない場合、他のフィールドから年齢を推測しようとしないでください
  • 年齢フィールドがないFAILステータスの場合、何が間違っていたかを理解するためにfailureReasonに依存してください

年齢区分

ageBandフィールドは、確認された年齢が当てはまる年齢区分を示します。区分は、確認の管轄に対するプロダクトの年齢区分から取得されます。区分はCompliance StudioのProduct accessタブにあるAge bandsカードで設定します。

ageBandオブジェクトには次のフィールドがあります。

  • key (string): 安定した識別子。nameは変更される可能性があるため、この値で照合してください。
  • name (string): 区分名。例: 11-13。
  • lowerAge (number): 区分に含まれる最小の年齢。
  • upperAge (number): 区分に含まれる最大の年齢(この値を含む)。18+のような上限のない区分では存在しません。

ageBandが存在する条件:

  • チャネルでageCategoryが含まれている。ageCategoryが含まれない場合、ageBandも含まれません。
  • 年齢が、確認の管轄に対する区分に収まる。k-IDはage.lowで年齢を区分に当てはめます。
  • その管轄に区分が存在する。完全一致する管轄のプロダクト独自の区分が最初に適用され、次にその国のプロダクト独自の区分、最後にその国に対するk-IDのデフォルト区分が適用されます。k-IDのデフォルト区分があるのはインドネシア(ID)のみです。他の市場では、区分を自分で設定する必要があります。

ageBandが存在しない場合:

  • 年齢が最初の区分より下である。
  • その管轄に適用される区分がない。
  • チャネルでageCategoryが含まれていない。

k-IDが区分を決定するタイミング:

  • Webhookは、確認が完了した時点の区分を含みます。
  • get-statusは、呼び出すたびに現在の区分から区分を決定します。
  • 確認の完了後に区分を変更した場合、get-statusは、その確認についてWebhookが送信した区分とは異なる区分を返すことがあります。

区分は市場ごとに異なります。 各市場はそれぞれ独自の区分を使用するため、同じ年齢でも市場によって異なる区分に入ることがあります。どこでも同じグループ分けにしたい場合は、すべての市場に同じ区分を設定してください。

ManualAgeAppeal.PendingReviewイベントはWebhooksチャネルのAgeとAge categoryのトグルに従いますが、ageBandは含まれません。

例: upperAgeのない18+区分

{
  "eventType": "Verification.Result",
  "data": {
    "id": "0b83055f-642a-44f5-8abb-e37cb907dfcd",
    "status": "PASS",
    "ageCategory": "adult",
    "ageBand": {
      "key": "18-plus",
      "name": "18+",
      "lowerAge": 18
    },
    "method": "id-document",
    "provider": "veratad",
    "age": {
      "low": 30,
      "high": 30
    }
  }
}

知っておくべきこと

  • ageBandは省略可能なものとして扱い、アクセス制御には使用しないでください。ageCategoryを使用してください。
  • ageBand.nameではなくageBand.keyで照合してください。
  • ageBandがなくても、確認が失敗したことを意味しません。
  • ageBandは、社内向けに使う独自のグループ分けです。ageCategoryは、k-IDのコンプライアンスエンジンが管轄のルールから決定する法的なカテゴリーです。
  • この2つは一致しないことがあります。たとえばインドネシアでは、19歳はデフォルトの18+区分に入りますが、インドネシアの成年年齢は21歳であるためdigital-youthになります。

生年月日フィールド

形式: YYYY-MM-DD (ISO 8601日付形式)

存在する場合: dobフィールドは、検証方法が確認された生年月日を提供する場合にのみ含まれます。年齢推定または年齢範囲のみを提供する方法では含まれません。検証方法と管轄の様々な組み合わせを考慮すると、dobがいつ存在しなければならないかについて検証や期待を行うべきではありません。このフィールドは検証方法から利用可能な場合に提供されますが、すべてのシナリオでその存在を保証することはできません。

dobを提供できる方法:

  • id-document - ID文書に読み取り可能な生年月日情報が含まれている場合
  • privy - 常に提供されます(インドネシアの本人確認)
  • korean-real-name - 常に提供されます(Inicis経由の韓国の実名確認)
  • age-attestation - 証明に生年月日情報が含まれている場合
  • singpass - 常に提供されます(シンガポールの国民本人確認)

dobを提供しない方法:

  • age-estimation-scan - 年齢範囲のみを提供し、確認されたDOBは提供しません
  • connect-id - 年齢しきい値を満たしているかのみを確認し、生年月日は提供しません
  • credit-card - 成人のカード保有者であることを確認するもので、生年月日は提供しません
  • email-estimation - 年齢推定のみを提供し、確認されたDOBは提供しません
  • social-security-number - 成人の本人情報を確認するもので、生年月日は提供しません

ステータス条件:

  • 方法が提供する場合、PASSステータスで存在
  • ユーザーが年齢基準を満たしていないと判定される前に方法が提供した場合、FAILステータスで存在

知っておくべきこと

  • PASSステータスでも、dobが常に存在するとは想定しないでください
  • dobが存在する場合、YYYY-MM-DD形式であることを確認してください
  • dobを追加の検証やログ記録に使用できますが、年齢を決定する主要な方法として依存しないでください

方法フィールド

存在する場合:

  • PASSステータスの場合は常に存在
  • FAILステータスの場合、failureReasonがage-criteria-not-metの場合に存在

可能な値:

  • id-document - 政府発行のID文書検証(DOBを含む場合があります)
  • credit-card - クレジットカード検証
  • age-estimation-scan - 顔年齢推定スキャン(DOBなし、年齢範囲を返す)
  • social-security-number - SSNベースの検証
  • email-estimation - メールベースの年齢推定(DOBなし、年齢推定のみ)
  • privy - インドネシアの本人確認(常にDOBを含む)
  • korean-real-name - Inicis経由の韓国の実名確認(常にDOBを含む)
  • age-attestation - k-ID経由の年齢証明(DOBを含む場合があります)
  • singpass - シンガポールの国民本人確認(常にDOBを含む)
  • age-key - 発行済みのAgeKey
  • brazil-cpf - ブラジルのCPF検証
  • email-confirmation - 確認済みの保護者のメールアドレス
  • pre-verified - 事前に確認済みとして申告された保護者
  • self-confirmation - 保護者による自己申告
  • connect-id - オーストラリアのConnectID検証

知っておくべきこと

  • 分析やログ記録の目的でmethodを使用できます
  • アクセス制御の決定にmethodを使用しないでください

プロバイダーフィールド

存在する場合:

  • methodが存在する場合は常に存在

取り得る値: connect-id, inicis, k-id, kws, openage, persona, pre-verified, privateid, privately, privy, serpro, singpass, spruce-id, stripe, veratad, verify-my, xsolla

メソッドからプロバイダーは一意に決まりません。age-estimation-scanは複数のベンダーが提供しており、credit-cardは決済が確認の代わりになった場合にレコードマーチャントを示します。

知っておくべきこと

  • 分析やログ記録の目的でproviderを使用できます
  • アクセス制御の決定にproviderを使用しないでください
  • 未知のprovider値も適切に処理してください。k-IDは順次ベンダーを追加します

失敗理由の値

一般的なfailureReason値:

  • age-criteria-not-met - ユーザーの確認された年齢が必要なしきい値を満たしていません
  • max-attempts-exceeded - ユーザーが利用可能なすべての検証試行を尽くしました
  • fraudulent-activity-detected - システムが不審または不正な行動を検出しました

知っておくべきこと

  • 未知のfailureReason値を適切に処理し、予期しない値が表示されても壊れないようにしてください
  • failureReasonのみに基づいてアクセス決定を行わず、常にstatusフィールドを考慮してください
  • デバッグや分析の目的でfailureReasonをログに記録することをお勧めします

完全なフィールドマトリックス

Webhookイベント

フィールドPASSFAIL
idalwaysalways
statusalwaysalways
methodalwayssometimes¹
provideralwayssometimes¹
agesometimes⁴sometimes²
ageCategorysometimes⁴sometimes²
ageBandsometimes⁵sometimes⁵
dobsometimes³sometimes³
failureReasonneveralways

¹ failureReasonがmax-attempts-exceededまたはfraudulent-activity-detectedでない限り存在
² age.lowとage.highの両方が利用可能で、かつfailureReasonがage-criteria-not-metの場合にのみ存在
³ 検証方法が提供し、WebhookのDate of birthトグルが許可する場合に含まれます
⁴ プロダクトの設定でチャネルのフィールドが選択されている場合に存在します
⁵ ageCategoryが存在し、年齢が管轄の区分に収まる場合にのみ存在します

APIエンドポイント

フィールドPENDINGIN_PROGRESSPASSFAIL
idalwaysalwaysalwaysalways
statusalwaysalwaysalwaysalways
methodneverneversometimes²sometimes¹
providerneverneversometimes²sometimes¹
ageneverneversometimes⁶sometimes³
ageCategoryneverneversometimes⁶sometimes⁴
ageBandneverneversometimes⁷sometimes⁷
dobneverneversometimes⁵sometimes⁵
failureReasonneverneverneveralways

¹ failureReasonがmax-attempts-exceededまたはfraudulent-activity-detectedでない限り存在
² 検証方法から利用可能な場合に存在
³ age.lowとage.highの両方が利用可能で、かつfailureReasonがage-criteria-not-metの場合にのみ存在
⁴ 年齢と管轄から年齢カテゴリが正常に計算された場合にのみ存在(FAILステータス)
⁵ includeDobクエリパラメータまたはGet statusのDate of birthトグルが許可し、かつ検証方法が提供する場合に含まれます(優先順位を参照)
⁶ プロダクトの設定でチャネルのフィールドが選択されている場合に存在します
⁷ ageCategoryが存在し、年齢が管轄の区分に収まる場合にのみ存在します

ペイロードの例

Webhookイベントの例

年齢情報を含むPASSステータス

{
  "eventType": "Verification.Result",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "PASS",
    "method": "id-document",
    "provider": "veratad",
    "ageCategory": "adult",
    "age": {
      "low": 25,
      "high": 25
    },
    "dob": "1998-05-15"
  }
}

年齢情報を含むFAILステータス

{
  "eventType": "Verification.Result",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174001",
    "status": "FAIL",
    "method": "age-estimation-scan",
    "provider": "privately",
    "failureReason": "age-criteria-not-met",
    "age": {
      "low": 16,
      "high": 17
    },
    "ageCategory": "digital-minor"
  }
}

年齢情報を含まないFAILステータス

{
  "eventType": "Verification.Result",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174002",
    "status": "FAIL",
    "failureReason": "max-attempts-exceeded"
  }
}

APIエンドポイント応答の例

PENDINGステータス

{
  "id": "123e4567-e89b-12d3-a456-426614174003",
  "status": "PENDING"
}

IN_PROGRESSステータス

{
  "id": "123e4567-e89b-12d3-a456-426614174004",
  "status": "IN_PROGRESS"
}

年齢情報を含むPASSステータス(DOBなし)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "PASS",
  "method": "id-document",
  "provider": "veratad",
  "ageCategory": "adult",
  "age": {
    "low": 25,
    "high": 25
  }
}

DOBを含むPASSステータス(includeDob = true)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "PASS",
  "method": "id-document",
  "provider": "veratad",
  "ageCategory": "adult",
  "age": {
    "low": 25,
    "high": 25
  },
  "dob": "1998-05-15"
}

年齢情報を含むFAILステータス

{
  "id": "123e4567-e89b-12d3-a456-426614174001",
  "status": "FAIL",
  "method": "age-estimation-scan",
  "provider": "privately",
  "failureReason": "age-criteria-not-met",
  "age": {
    "low": 16,
    "high": 17
  },
  "ageCategory": "digital-minor"
}

年齢情報を含まないFAILステータス

{
  "id": "123e4567-e89b-12d3-a456-426614174002",
  "status": "FAIL",
  "failureReason": "max-attempts-exceeded"
}

実装チェックリスト

Webhookイベント

  • 両方のステータスタイプを処理: PASSとFAIL(webhookはPENDINGやIN_PROGRESSを送信しません)
  • age.lowやage.highにアクセスする前にageオブジェクトの存在を確認
  • ステータスがPASSでageCategoryが存在する場合、アクセス制御にageCategoryを使用
  • ステータスがFAILの場合、存在する場合でも、アクセス制御にageCategoryを使用しない
  • methodが存在しない場合を処理(システムレベルの失敗)
  • ageとageCategoryが存在しない場合を処理(特定の失敗シナリオ、またはプロダクトの設定で選択されていないフィールド)
  • ageBandは省略可能なものとして扱う
  • dob形式(YYYY-MM-DD)を検証(存在する場合)
  • デバッグのためにfailureReasonをログに記録
  • FAILステータスでアクセスを付与しない
  • 未知のfailureReason値を適切に処理

APIエンドポイント

  • すべてのステータスタイプを処理: PENDING、IN_PROGRESS、PASS、FAIL
  • PENDINGとIN_PROGRESSステータスの場合、idとstatusフィールドのみを期待
  • DOBデータが必要な場合は、includeDobクエリパラメータを設定します。プロダクトに保存済みの設定がある場合、トグルより優先されます(GET /age-verification/get-statusを参照)
  • age.lowやage.highにアクセスする前にageオブジェクトの存在を確認
  • ステータスがPASSでageCategoryが存在する場合、アクセス制御にageCategoryを使用
  • ステータスがFAILの場合、存在する場合でも、アクセス制御にageCategoryを使用しない
  • methodが存在しない場合を処理(システムレベルの失敗)
  • ageとageCategoryが存在しない場合を処理(特定の失敗シナリオ、またはプロダクトの設定で選択されていないフィールド)
  • ageBandは省略可能なものとして扱う
  • dob形式(YYYY-MM-DD)を検証(存在する場合)
  • デバッグのためにfailureReasonをログに記録
  • FAILステータスでアクセスを付与しない
  • 未知のfailureReason値を適切に処理
  • PENDINGとIN_PROGRESSステータスに適切なポーリング戦略を実装

実装ノート

AgeCategoryの動作

ageCategoryフィールドは、WebhookイベントではPASSステータスの場合、プロダクトの設定で選択されていれば含まれます。FAILステータスの場合、failureReasonがage-criteria-not-metで年齢データが利用可能な場合、ageCategoryが含まれる場合があります。ただし、ステータスがFAILの場合、存在する場合でも、アクセス制御の決定にageCategoryを使用すべきではありません。APIエンドポイントも同じパターンに従います - ageCategoryは年齢データが利用可能な場合にFAILステータスで存在する可能性がありますが、アクセス制御の決定に使用すべきではありません。

バージョン履歴

  • 2026-11-12: 各チャネル(get-status、Webhook、JavaScript result)は、age、ageCategory、dobについてプロダクトのAge result設定に従うようになりました。そのため、PASS結果がageやageCategoryなしで届く場合があります。任意のageBandフィールドを追加し、includeDobの優先順位を記載しました。
  • 2026-09-01: メソッドを実行したベンダーを示すproviderフィールドをWebhookイベントとAPIエンドポイントに追加しました。
  • 2026-01-07: failureReasonがage-criteria-not-metで年齢データが利用可能な場合、FAILステータスのWebhookイベントにageCategoryフィールドが含まれるようになりました。
  • 2025-12-04: 初期APIコントラクトドキュメント

On this page