is_ownership_verified: trueとしてマークされ、紐づくトラベルルール送金がUNCONFIRMED_OWNERSHIPから次の状態へ進めるようになります。
Diditが自動で発行する場合
セッションを自分で発行する必要はほとんどありません。 トラベルルールの設定でauto_wallet_verificationが有効な場合(デフォルト)、送金にエンドユーザーによるウォレットを管理していることの証明が必要になると、Diditは取引の作成時にウィジェットセッションを自動で発行します。
- 送金が
UNCONFIRMED_OWNERSHIPの状態にある場合。これは、送信時に取引相手のウォレットがセルフホスト型として申告されたことを意味します。 - 送金が送信方向で、かつ
COUNTERPARTY_VASP_NOT_FOUNDの状態にある場合。取引相手のVASPを特定できなかったため、完了に至る残りの手段は所有権の証明です。
action_requiredブロック(type: "wallet_ownership"、開くためのurl付き)で返され、クライアント側からの送信時にはSDKが自動的に起動します。
Diditが代わりに作成する受信方向の送金(サンライズ登録、受信方向のTRP照会、INTERNALレールの受信側レッグ)には、UNCONFIRMED_OWNERSHIPの状態になった場合でも、セッションが自動発行されることはありません。
送金が存在する前にウォレットを事前検証したい場合、auto_wallet_verificationを無効にしている場合、または上記の受信方向の送金のいずれかに対しては、POST /v3/travel-rule/widget-session/で手動で発行してください。
証明できること
ウィジェットでは最大4種類の証明方式を提供します。どの方式が表示されるかは、セッションのミント方法とトラベルルールの設定によって決まります。メッセージ署名の検証仕様
署名を送信すると、ウォレットの管理権限が証明された時点でstatus: "VERIFIED"とともに200が返されます。
証明できない場合は、以下のいずれかのcode値とともに400が返されます。証明はオープンのまま残るため、顧客は再度署名できます。
Satoshiテストの検証仕様
Satoshiテストの入金の検証は非同期で行われます。取引がオンチェーンで検出され、その後確定する必要があるためです。 入金のtxidを送信すると、入金がまだオンチェーンで確定していない間はstatus: "PENDING"とともに200が返されます。このときtxidは破棄されず保持されます。
入金が確定すると、status: "VERIFIED"とともに200が返されます。
入金が明らかに誤っている場合は、status: "REJECTED"とともに400が返されます。該当するのは、別のウォレットから送金された場合、入金アドレスへの送金額が想定と異なる場合、チャレンジより前の取引である場合、またはすでに別のウォレットの証明に使われた取引である場合です。この証明はクローズされますが、セッションに試行回数が残っていれば、顧客は新しい証明を開始できます。
まだインデックスされていない入金の場合もstatus: "PENDING"とともに200が返されます。また、Didit側で照会に失敗した場合は、コードDEPOSIT_LOOKUP_FAILEDとともに400が返されます。いずれの場合も証明はオープンのまま残り、Diditが確認を続けます。
有効な入金が検出される前にテスト期間が終了した場合は、410が返されます。
txidが送信されると、バックグラウンドジョブが保留中の入金を5分ごとに再確認し、取引の確定後に証明を完了します。そのため、顧客がtxidを再送信する必要はありません。
satoshi_deposit_addressを渡した場合、ウィジェットセッション自体のexpires_atは、Satoshiテストの24時間の期間以上になるよう延長されます。これにより、セッション自体が期限切れになる前に入金が確定する時間を確保できます。
フロー
1
ウィジェットセッションを発行する
検証が必要なウォレットを指定して
POST /v3/travel-rule/widget-session/を呼び出します。必要に応じて送金に紐付けると、所有権が証明された時点でその送金が自動的に進みます。2
返されたURLを開く
顧客をレスポンスの
urlに誘導します。顧客はそこで証明を完了します。DiditのアカウントやAPIキーは不要で、URL内のトークンが認証になります。3
完了を検知する
証明が検証されると、ウィジェットはアドレス帳エントリを検証済みにし、セッションが送金に紐付いている場合はその送金を進めます。
travel_rule.status.updated(紐付けた送金の場合)を監視するか、ウィジェットコンテキストをポーリングしてください。ウィジェットセッションを発行する
この例では、トラベルルールガイドの申告済みのセルフホスト型送金にセッションを紐付けるため、wallet_addressはその送金の送金先ウォレットです。
送金に紐付けたセッションは、その送金の取引相手のウォレットに対する証明のみを受け付けます。
urlは必ずそのまま開いてください。自分で組み立ててはいけません。
返されたURLを開く
完了を検知する
ウィジェットは、トークンをキーとする公開の読み取りエンドポイントを提供しています。これをポーリングして進捗を確認するか、セッションが送金に紐付いている場合はWebhookを利用してください。- 証明が検証されると、
completed_atがnull以外の値になります。 proofsの各エントリには、そのメソッドに必要なフィールドが含まれます。SATOSHI_TESTの証明にはdeposit_address、expected_amount、および独自のexpires_atが追加され、MESSAGE_SIGNINGの証明には顧客が署名する文字列であるchallengeが追加されます。SATOSHI_TESTの証明は、入金がオンチェーンで検出されたものの未承認の間、status: "PENDING"のままになることがあります。貴社や顧客の対応は不要です。上記のSatoshiテストの検証仕様を参照してください。transaction_idを指定してセッションを発行した場合、証明が検証されると紐付けた送金が進み、本番環境のアプリケーションではtravel_rule.status.updatedのWebhookが発火します。 ポーリングよりもWebhookを優先してください。 受信側のTRP照会は送信元に承認が返され、その承認が配信されるとCOMPLETEDに移行します。 その他のUNCONFIRMED_OWNERSHIPの送金(またはON_HOLDの受信送金)はCOMPLETEDに移行し、受取人の名前がウォレット保有者と一致しない場合はCOUNTERPARTY_MISMATCHED_DATAに移行します。また、決済済みのサンライズ入金が完了すると、さらにFINISHEDに進みます。COUNTERPARTY_VASP_NOT_FOUNDの送信側送金はCOMPLETEDに移行します。SCREENSHOTの証明は、所有権を確認した後も、このコンテキストではstatus: "PENDING"のままです。 承認にはPOST .../travel-rule/ownership/を使用しますが、これは所有権確認待ちの送金のみを受け付けます。 そのため、送金が紐付いていないセッションや、COUNTERPARTY_VASP_NOT_FOUNDの送信側送金に紐付いたセッションでは、スクリーンショットを承認する手段がありません。これらのセッションでスクリーンショットを提供してはならない場合は、allow_screenshot_proofをオフにしてください。- 証明が拒否された後も、試行回数が残っている間はセッションで新たな試行を受け付けます。
max_attempts、attempts_used、attempts_remainingが回数を示し、拒否された証明にはrejection_reasonが含まれます。attempts_remainingが0のときに別の証明を開始すると409が返されるため、新しいセッションを発行してください。 - コンテキストエンドポイントは、不明なトークンに対しては
404を、セッションが完了せずに期限切れになった後は410を返します。
ここには一度きりの処理に依存する箇所はありません。ウィジェットと貴社のバックエンドはどちらも同じ永続的な状態(検証済みのアドレス帳エントリと送金ステータス)に収束するため、Webhookが届かなかった場合やタブが閉じられた場合でも、送金またはウィジェットコンテキストを再取得すれば必ず復旧できます。
ローカライズとブランディング
ウィジェットは54言語で表示され、リンクの言語パス(またはブラウザーの既定言語)に従います。 アプリケーションでホワイトラベルが有効になっている場合、ウィジェットは認証フローのブランディングを自動的に引き継ぎます。対象はロゴ、ブランドカラー、ボタンとパネルのスタイル、カスタムフォント、ファビコン、そしてタイトルに表示されるアプリの公開名です。 個別の設定は不要です。KYCセッション用に設定したカスタマイズがそのまま適用されます。 すでに完了したリンクに戻ったユーザーには、完了画面が再度表示されます。callback_urlを渡している場合、ウィジェットはユーザーをそのURLに戻します。
期限切れのリンクでは、ブランディングが適用された期限切れ画面が表示され、新しいリンクをリクエストするよう案内されます。
そのユーザーのためにPOST /v3/travel-rule/widget-session/で新しいセッションを発行してください。action: "resend"で送金を再送しても、新しいセッションは発行されません。
次のステップ
トラベルルール
取引のライフサイクル全体、送金レール、設定、受取フロー。
ウォレットアドレス帳
管理しているウォレットを登録し、受信した送金をそのウォレットに照合できるようにします。
Webhook
travel_rule.status.updatedを購読し、証明によって送金が進んだときに対応します。
ネイティブSDK
ウィジェットのURLは、SDKのWebViewではなくシステムブラウザーで開いてください。