Webリダイレクト型KYC：ホスト型検証ページ

リダイレクト方式では、ユーザーをDiditがホストするページに移動させて認証を行い、完了後にコールバックURL経由でアプリに戻します。

機能	説明
セットアップ時間	5分
バックエンドの要否	✅ 必要（セッション作成のため）
自社ドメインでの完結	❌ 不可（verify.didit.meまたはホワイトラベルのカスタムドメインにリダイレクト）
クロスデバイス対応	✅ 対応
ブラウザ互換性	✅ すべてのブラウザ

リダイレクトを使用する場合

クロスデバイス認証: デスクトップで開始し、モバイルで完了
最大限の互換性: 古いブラウザを含むすべてのブラウザで動作
シンプルな連携: iframeの設定が不要
カメラの問題: iframeでのカメラアクセスに問題がある場合

実装

ステップ1: セッションを作成する（バックエンド）

セッション作成のレスポンスにはurlという名前のフィールドが含まれます。この値をブラウザに渡してください。

// Node.js / Express
app.post('/api/create-verification', async (req, res) => {
  const { userId } = req.body;

  const response = await fetch('https://verification.didit.me/v3/session/', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.DIDIT_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      workflow_id: process.env.DIDIT_WORKFLOW_ID,
      vendor_data: userId,
      callback: 'https://yourapp.com/verification-complete',
      callback_method: 'both', // most reliable across desktop ↔ mobile handoffs
    }),
  });

  if (!response.ok) {
    return res.status(response.status).send(await response.text());
  }

  const session = await response.json();
  // 201 per OpenAPI: { session_id, session_number, session_token, url, vendor_data,
  //                    metadata, status, workflow_id, workflow_version, callback }
  res.json({ sessionId: session.session_id, verificationUrl: session.url });
});

ステップ2: ユーザーをリダイレクトする（フロントエンド）

HTML:

<button onclick="startVerification()">Verify Identity</button>

<script>
  async function startVerification() {
    const response = await fetch('/api/create-verification', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ userId: 'user-123' })
    });
    
    const { verificationUrl } = await response.json();
    window.location.href = verificationUrl;
  }
</script>

React:

function VerifyButton() {
  const [loading, setLoading] = useState(false);

  const startVerification = async () => {
    setLoading(true);
    
    const response = await fetch('/api/create-verification', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ userId: 'user-123' })
    });
    
    const { verificationUrl } = await response.json();
    window.location.assign(verificationUrl);
  };

  return (
    <button onClick={startVerification} disabled={loading}>
      {loading ? 'Loading...' : 'Verify Identity'}
    </button>
  );
}

Vue:

<template>
  <button @click="startVerification" :disabled="loading">
    {{ loading ? 'Loading...' : 'Verify Identity' }}
  </button>
</template>

<script setup>
import { ref } from 'vue';

const loading = ref(false);

async function startVerification() {
  loading.value = true;
  
  const response = await fetch('/api/create-verification', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ userId: 'user-123' })
  });
  
  const { verificationUrl } = await response.json();
  window.location.href = verificationUrl;
}
</script>

コールバックの処理

認証が完了すると、Diditはクエリパラメーター付きでコールバックURLにリダイレクトします。

https://yourapp.com/verification-complete?verificationSessionId=abc123&status=Approved

パラメーター	説明
`verificationSessionId`	セッションの一意な識別子
`status`	セッションの現在のステータス（例: `Approved`、`Declined`、`In Review`、`Expired`）。認証ステータスを参照してください

Next.jsの例

// pages/verification-complete.tsx
import { useRouter } from 'next/router';
import { useEffect, useState } from 'react';

export default function VerificationComplete() {
  const router = useRouter();
  const { verificationSessionId, status } = router.query;
  const [message, setMessage] = useState('Processing...');

  useEffect(() => {
    if (!router.isReady) return;

    async function handleResult() {
      // Optionally verify the result with your backend
      await fetch('/api/verify-session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ 
          sessionId: verificationSessionId, 
          status 
        })
      });

      // Redirect based on status
      switch (status) {
        case 'Approved':
          setMessage('Verification successful! Redirecting...');
          setTimeout(() => router.push('/dashboard'), 2000);
          break;
        case 'Declined':
          setMessage('Verification was not successful.');
          setTimeout(() => router.push('/verification-failed'), 2000);
          break;
        case 'In Review':
          setMessage('Your verification is under review.');
          setTimeout(() => router.push('/verification-pending'), 2000);
          break;
        default:
          setMessage('Unknown status. Please contact support.');
      }
    }

    handleResult();
  }, [router.isReady, verificationSessionId, status]);

  return (
    <div className="flex flex-col items-center justify-center min-h-screen">
      <div className="animate-spin w-8 h-8 border-4 border-blue-500 border-t-transparent rounded-full mb-4" />
      <p className="text-lg">{message}</p>
    </div>
  );
}

Express.jsの例

// routes/verification.js
app.get('/verification-complete', async (req, res) => {
  const { verificationSessionId, status } = req.query;
  
  // Optionally verify with Didit API
  // const session = await diditApi.getSession(verificationSessionId);
  
  // Update your database
  await db.users.update({
    where: { verificationSessionId },
    data: { verificationStatus: status }
  });
  
  // Redirect based on status
  switch (status) {
    case 'Approved':
      res.redirect('/dashboard?verified=true');
      break;
    case 'Declined':
      res.redirect('/verification-failed');
      break;
    case 'In Review':
      res.redirect('/verification-pending');
      break;
    default:
      res.redirect('/error');
  }
});

Vue Routerの例

// router/index.ts
{
  path: '/verification-complete',
  component: () => import('@/views/VerificationComplete.vue'),
  beforeEnter: async (to, from, next) => {
    const { verificationSessionId, status } = to.query;
    
    // Store result and redirect
    await store.dispatch('verification/handleResult', { 
      sessionId: verificationSessionId, 
      status 
    });
    
    if (status === 'Approved') {
      next('/dashboard');
    } else if (status === 'Declined') {
      next('/verification-failed');
    } else {
      next('/verification-pending');
    }
  }
}

新しいタブで開く

ユーザーが認証している間もアプリを開いたままにしておきたい場合は、次のようにします。

// Open in new tab
window.open(verificationUrl, '_blank');

// Poll for completion or use webhooks

新しいタブを使う場合は、Webhookと組み合わせて認証の完了を把握してください。

セキュリティのベストプラクティス

コールバックをサーバー側で検証する

クエリパラメーターのverificationSessionIdとstatusは、信頼できないUI用のヒントとして扱ってください。最終的な判定は必ずバックエンドで確認してください。Webhookを処理する方法（推奨）か、APIで判定を再取得する方法があります。

// Backend: re-fetch the canonical decision before granting access
app.get('/verification-complete', async (req, res) => {
  const { verificationSessionId } = req.query;

  const response = await fetch(
    `https://verification.didit.me/v3/session/${verificationSessionId}/decision/`,
    {
      headers: { 'x-api-key': process.env.DIDIT_API_KEY },
    }
  );

  if (!response.ok) {
    return res.status(response.status).send(await response.text());
  }

  const decision = await response.json();

  // decision.status uses the canonical enum:
  // Not Started | In Progress | Awaiting User | In Review | Approved |
  // Declined   | Resubmitted | Expired | Kyc Expired | Abandoned
  if (decision.status === 'Approved') {
    // Grant access. Per-feature reports are plural arrays:
    //   decision.id_verifications[], decision.face_matches[], decision.aml_screenings[], ...
  }

  res.redirect('/dashboard');
});

Webhookを使用する

最も信頼性の高い連携を実現するには、Webhookを使用して、ユーザーのブラウザの挙動に関係なく認証結果をバックエンドで直接受け取ってください。

クロスデバイスフロー

リダイレクト方式は、クロスデバイス認証に標準で対応しています。

ユーザーがデスクトップで「Verify」をクリックします
ユーザーが認証ページにリダイレクトされます
必要に応じて、ユーザーはQRコードをスキャンしてモバイルで続行できます
完了後、ユーザーはコールバックURLにリダイレクトされます。どのデバイスでリダイレクトされるかはcallback_method（initiator、completer、またはboth）で制御します

トラブルシューティング

コールバックを受信できない

セッション作成時にコールバックURLが正しく設定されているか確認してください
コールバックURLがインターネットからアクセス可能であることを確認してください
URLに誤字やエンコードの問題がないか確認してください

ステータスが常に「Declined」になる

Didit Consoleでワークフローの設定を確認してください
使用しているテスト用の書類が有効であるか確認してください
APIでセッションの詳細を確認し、具体的な却下理由を確認してください

リダイレクトループが発生する

コールバックハンドラーが認証ページにリダイレクトし直していないか確認してください
コールバックページのキャッシュに問題がないか確認してください
ブラウザのキャッシュをクリアして再試行してください

サンプルリポジトリ

GitHubリポジトリ

GitHubでソースコードとサンプルを確認できます

ガイド

認証

Model Context Protocol (MCP)

Web SDK

ネイティブSDK

サーバーSDK

連携

Webリダイレクト型KYC：ホスト型検証ページ

リダイレクトを使用する場合

実装

ステップ1: セッションを作成する（バックエンド）

ステップ2: ユーザーをリダイレクトする（フロントエンド）

コールバックの処理

Next.jsの例

Express.jsの例

Vue Routerの例

新しいタブで開く

セキュリティのベストプラクティス

コールバックをサーバー側で検証する

Webhookを使用する

クロスデバイスフロー

トラブルシューティング

コールバックを受信できない

ステータスが常に「Declined」になる

リダイレクトループが発生する

サンプルリポジトリ

GitHubリポジトリ

​リダイレクトを使用する場合

​実装

​ステップ1: セッションを作成する（バックエンド）

​ステップ2: ユーザーをリダイレクトする（フロントエンド）

​コールバックの処理

​Next.jsの例

​Express.jsの例

​Vue Routerの例

​新しいタブで開く

​セキュリティのベストプラクティス

​コールバックをサーバー側で検証する

​Webhookを使用する

​クロスデバイスフロー

​トラブルシューティング

​コールバックを受信できない

​ステータスが常に「Declined」になる

​リダイレクトループが発生する

​サンプルリポジトリ

GitHubリポジトリ

リダイレクトを使用する場合

実装

ステップ1: セッションを作成する（バックエンド）

ステップ2: ユーザーをリダイレクトする（フロントエンド）

コールバックの処理

Next.jsの例

Express.jsの例

Vue Routerの例

新しいタブで開く

セキュリティのベストプラクティス

コールバックをサーバー側で検証する

Webhookを使用する

クロスデバイスフロー

トラブルシューティング

コールバックを受信できない

ステータスが常に「Declined」になる

リダイレクトループが発生する

サンプルリポジトリ