賃貸・物件管理
賃貸申込書と同じメールでホスト型リンクを送ってください。ファイルを確認する前に、Webhookによってお客様のシステム上で申請者が確認済みに切り替わります。
Webhookと連携
本人確認のWebhook、ホスト型ページ、ウィジェット。
申請者をホスト型の確認ページへ案内するか、ウィジェットをご自身のフローに組み込んでください。結果が出た瞬間に署名付きWebhookを受け取り、リンクを持つ誰もが公開の資格確認ページで結果を確認できます。KYC APIの連携を、半日で本番稼働できるように設計しています。
- HMAC-SHA256で署名されたコールバック
- デスクトップからスマートフォンへのQRによる引き継ぎ
- Sandboxセッションには課金されません
ホスト型認証ページ
1つのリンクでフロー全体を完結。
API でセッションを作成すると、認証用URLが返されます。メールやテキストメッセージ、またはご自身のアプリで送信してください。あとはページがすべて処理します。
デスクトップ
申請者がパソコンでリンクを開きます。
QR コードによる引き継ぎ
ページにQRコードと短い案内カードが表示されます。
スマートフォンでの撮影
QRコードを読み取ると、同じセッションが書類と自撮りの撮影に切り替わります。
確認済み
セッションはスマートフォン上でVERIFIEDになります。
お客様のアプリへ戻る
結果にかかわらず、戻り先URLへのリダイレクトと署名付きWebhookが送られます。
決済のリダイレクトのように動作
申請者はセッション固有のURLのページにアクセスします。アカウントも、インストールするアプリも不要です。
QR コードによる引き継ぎ(デスクトップからスマートフォンへ)
デスクトップで開くと、カメラへのアクセスを求める代わりに、QR コードと簡単な案内カードが表示されます。スキャンするとスマートフォンで同じリンクが開き、そのまま書類と自撮りの撮影に切り替わります。
結果とともにお客様のもとへ戻ります
セッションが VERIFIED になると、ページはセッションIDとステータスを付加した返却URLにリダイレクトします。そのため、他に何も待つことなく、アプリ側で結果を把握できます。
ブランド対応(対象プランのみ)
貴社名、ロゴ、アクセントカラー、利用規約とプライバシーポリシーへのリンクを、ホスト型ページと認証情報チェックページに反映します。
Webhook
結果が出た瞬間に届く署名付きコールバック。
セッション作成時に webhook URL を指定すると、セッションが完了次第、その URL に結果を送信します。ポーリングは不要です。
送るだけでなく、署名付き
すべての配信に X-Bio-Signature ヘッダーが付与されます。これはリクエストボディの HMAC-SHA256 で、信頼する前に、当社から送信されたものであることを検証できます。
送りっぱなしではなく、再試行あり
失敗した配信は3回再試行され、試行のたびに待機時間が長くなります。
すべての試行を記録
成功・失敗にかかわらず、試行の記録を当社側で保管しています。
近日公開 すべての試行をご自身で確認できるポータル内の配信ログは近日公開予定です。
最新の VERIFIED を正としてください
再試行により、まれに配信の順序が前後して届くことがあります。webhook を受信したかどうかをロジックの基準にせず、セッションIDを基準にして、後から届いた VERIFIED が先のものを上書きするようにしてください。独自に状態を保持する場合は、webhook の受信単位ではなくセッションIDで重複を排除してください。
署名を検証する
ペイロードを信頼できることを確認してから処理しましょう。
何かを解析する前に、リクエスト本文そのままに対してHMAC-SHA256を再計算し、X-Bio-Signatureと比較してください。
javascript
const crypto = require("crypto");
function verifySignature(rawBody, signatureHeader, secret) {
const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected, "hex");
const b = Buffer.from(signatureHeader || "", "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// Read the raw body — don't let a JSON body-parser touch it first.
app.post("/hooks/shieldid", express.raw({ type: "application/json" }), (req, res) => {
const signature = req.header("X-Bio-Signature") || "";
if (!verifySignature(req.body, signature, process.env.SHIELDID_WEBHOOK_SECRET)) {
return res.status(401).send("invalid signature");
}
const event = JSON.parse(req.body);
// Treat the latest VERIFIED status as authoritative; de-duplicate by session_id.
res.status(200).send("ok");
});JS ウィジェット
ホスト型フローを、お客様のページにそのまま組み込めます。
ウィジェットはセッションを作成し、同じホスト型フローを iframe 内にインライン表示するため、申請者はお客様のサイトから離れません。
- カメラとマイクへのアクセスを許可した iframe で表示され、サイズはコンテナに合わせて調整されます。
- ホスト型ページと同じ方法でセッションのステータスを読み取ります。セッションの終了後に、リターンURLとWebhookを通じて取得します。
近日公開 ページ内の完了コールバック(onComplete、onCancel、onStep、自動リサイズ)は近日公開予定です。それまでは、return_urlとWebhookを使ってセッションの終了を把握してください。これらは現在でもご利用いただけます。
本番環境に公開する前に
ウィジェットは現在、ブラウザ上で直接APIキーを受け付けます。これはsandbox向けの便宜であり、本番環境で使うパターンではありません。キーをサーバー側に保管したまま、ご自身のバックエンドからセッションを作成し、ウィジェットには作成されたセッションだけを渡してください。訪問者のブラウザから読み取れる本番キーは決して渡さないでください。
html
<script src="https://cdn.shieldid.ca/sdk/v1/widget.js"></script>
<div id="shieldid-verify"></div>
<script>
TLVerify.init({
apiKey: "vk_sand_your_key", // sandbox only — see the note above for production
containerId: "shieldid-verify",
returnUrl: "https://yourapp.example/verified",
webhookUrl: "https://yourapp.example/hooks/shieldid",
locale: "en",
});
</script>資格確認ページ
確認済みセッション向けの公開ページ。
セッションがVERIFIEDになると、そのセッション専用の資格確認リンクに、申請者の名前、書類の種類、ステータスが分かりやすい言葉で表示されます。共同署名者、受付担当者、取引先など、リンクを持っている人なら誰でも、ダッシュボードにサインインすることなく結果を確認できます。
Jordan Reyes
サンプルデータカリフォルニア州の運転免許証
確認済み
- 閲覧にサインインは不要です。
- ID画像の原本や信頼度スコアが表示されることは一切なく、表示されるのはステータスと本人情報のみです。
- 対象プランでは、ホスト型ページと同じブランドで表示できます。
連携パターン
6種類の事業者がどのように連携しているかをご紹介します。
基本の構成要素はどこでも同じで、セッション、リンクまたはウィジェット、そしてWebhookです。どのパターンが合うかは、答えがいつ、どのように必要かによって変わります。
法務・法律事務所
クライアントの受付時にリンクを送り、Webhookの受領記録をファイルとともに保管します。これにより、委任契約の開始前にクライアントの本人確認が記録として残ります。
コンドミニアム・HOA管理組合
理事会がすでに使用している所有者または入居者の登録フォームからリンクします。結果は、その部屋が名簿に追加される前に届きます。
フィンテック・融資
Webhookがお客様独自の審査ステップを自動的に起動するため、結果が届いたことに誰かが気づくのを申請者が待つことはありません。
マーケットプレイス・ギグプラットフォーム
ウィジェットを販売者やドライバーのオンボーディングに埋め込めば、アプリから一度も離れないフローを実現できます。上記の推奨どおり、セッションはバックエンドから作成してください。
E-signature
署名手続きが始まる前にホスト型フローを実行し、書類の公開は申請者本人の申告ではなく、webhook に基づいて制御してください。
ご質問
連携についての率直なお答え。
はじめる
webhook を設定して、動作を確認しましょう。
webhook URL を指定して sandbox セッションを作成し、ご自身のスマートフォンで認証を実行して、送信される署名付きコールバックをご確認ください。