ユーザーの本人確認書類を確認する
このガイドでは、Stripe Identity を使用して、身分証明書を安全に収集し、確認する方法について説明します。
はじめに
- 本番環境利用の申請を行う。
- Stripe Identity 申請書にご記入ください。
- (オプション) ブランディング設定ページでブランド設定をカスタマイズする。
注
Identity iOS SDK を利用するには、Identity 設定ページにアクセスして、有効にするをクリックします。
iOS でユーザーの本人確認を行うには、自社のアプリケーションに確認画面を表示します。このガイドでは、以下の手順を説明します。
- Stripe を設定します。
- サーバーエンドポイントを追加します。
- 確認画面を表示します。
- 確認イベントを処理します。
このガイドの手順は、サンプルアプリおよびサンプルバックエンドサーバーにすべて実装されています。
設定サーバー側クライアント側
注
この SDK を Stripe Identity サービスで使用する場合、この SDK を改変してはいけません。Stripe の書面による承認を得ずに、改変された SDK を Stripe Identity サービスで使用することは Stripe との契約に違反することになり、Stripe アカウントが閉鎖される場合があります。
SDK をインストールする クライアント側
Stripe iOS SDK はオープンソースです。詳細なドキュメントが提供されており、iOS 13.0 以降をサポートするアプリと互換性があります。
注
For details on the latest SDK release and past versions, see the Releases page on GitHub. To receive notifications when a new release is published, watch releases for the repository.
カメラの使用許可を設定する クライアント側
Stripe Identity iOS SDK では、デバイスのカメラにアクセスして本人確認書類をキャプチャーする必要があります。アプリがカメラの使用許可をリクエストできるようにするには、以下の手順に従います。
- Xcode で、プロジェクトの Info.plist を開きます。
NSCameraUsageDescription
キーを追加します。- アプリがカメラの使用許可を必要とする理由をユーザーに説明するために、以下のような文字列の値を追加します。
このアプリはカメラを使用して、本人確認書類の写真を撮影します。
カメラ使用許可のリクエストの詳細については、Apple のドキュメントをご覧ください。
サーバーに Stripe をインストールする サーバー側
まず、Stripe アカウントを登録します。
次に、アプリケーションから Stripe API へアクセスするためにライブラリをインストールします。
サーバーエンドポイントを追加するサーバー側
VerificationSession を作成する
VerificationSession は、本人確認をプログラムで示したものです。確認のタイプに関する詳細 (実行するチェックの内容など) が含まれています。確認済みの出力フィールドを展開して、確認済みのデータの詳細を表示できます。
VerificationSession を作成するには、サーバー側のエンドポイントが必要です。サーバー側で VerificationSession
を作成することにより、悪意のあるユーザーによる確認オプションの上書き、およびお客様のアカウントでの決済処理の偽装を防止できます。セッションのメタデータにユーザー参照を含めるか、データベースにセッション ID を保存することで、このエンドポイントに認証を追加します。
For security, don’t create a VerificationSession
object that’s directly accessible from the mobile client. Instead, your server provides the SDK with an ephemeral key — a short-lived API key with restricted access to the VerificationSession. You can think of an ephemeral key as a session, authorizing the SDK to retrieve and update a specific VerificationSession
object for the duration of the session.
VerificationSession
と一時キーを作成したら、その VerificationSession
の ID と一時キーシークレットをクライアントに送信し、書類のアップロード画面を表示します。
注
このエンドポイントの実行可能な実装が Glitch で提供されており、簡単なテストに利用できます。
// Set your secret key. Remember to switch to your live secret key in production. // See your keys here: https://dashboard.stripe.com/apikeys const stripe = require('stripe')(
); // In the route handler for /create-verification-session: // Authenticate your user. // Create the session. const verificationSession = await stripe.identity.verificationSessions.create({ type: 'document', metadata: { user_id: '{{USER_ID}}', }, }); // Create an ephemeral key for the VerificationSession const ephemeralKey = await stripe.ephemeralKeys.create( {verification_session: verificationSession.id}, {apiVersion: '2024-04-10'} ); // Return only the ID and ephemeral key secret to the frontend. const verficationSessionId = verificationSession.id; const ephemeralKeySecret = ephemeralKey.secret;'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
注意
一時キーシークレットは VerificationSession
にバインドされており、これによりアプリは機密データである本人確認情報 (書類や自撮り写真のファイルなど) を収集できるようになります。使用できるのは 1 回限りで、1 時間後に有効期限が切れます。一時キーシークレットは、記録したり、URL に埋め込んだり、対象のユーザー以外に公開したりしないでください。一時キーシークレットを返すエンドポイントで必ず TLS を有効化します。本人確認の設定や結果の漏洩を防止するため、一時キーシークレットのみをアプリに送信してください。
Web サーバー (localhost:4242
など) を起動し、curl で VerificationSession を作成する POST リクエストを送信して、エンドポイントをテストします。
curl -X POST -is "http://localhost:4242/create-verification-session" -d ""
端末に次のようなレスポンスが表示されます。
HTTP/1.1 200 OK Content-Type: application/json { id: "vs_QdfQQ6xfGNJR7ogV6...", ephemeral_key_secret: "ek_YWNjdF8xRm..." }
確認画面を表示するクライアント側
確認画面を表示するボタンをセットアップします。このボタンをタップすると、ユーザーはパスポート、運転免許証、または国民 ID をキャプチャーしてアップロードできます。
開始する前に、確認ページで以下を行う必要があります。
- 本人確認が必要な理由をユーザーに説明します。
- Stripe の UI を表示する本人確認ボタンを含めます。
ボタンを追加する
まず、タップアクションと読み込みインジケータを持つ、ボタン付きのビューコントローラーを作成します。
import UIKit class VerifyViewController: UIViewController { @IBOutlet weak var verifyButton: UIButton! @IBOutlet weak var activityIndicator: UIActivityIndicatorView! }
StripeIdentity SDK をインポートする
StripeIdentity
をビューコントローラーに追加します。
import UIKit import StripeIdentity class VerifyViewController: UIViewController { @IBOutlet weak var verifyButton: UIButton! @IBOutlet weak var activityIndicator: UIActivityIndicatorView! }
確認ボタンにアクションを追加する
VerificationSession
を作成するためのボタンとエンドポイントが準備できたため、次にボタンを変更して、ボタンがタップされたら、書類のアップロード画面が表示されるようにします。
次のためのコールを追加します。
- エンドポイントから、
VerificationSession
ID と一時キーシークレットを取得します。 - ブランドロゴで
IdentityVerificationSheet
をインスタンス化し、ユーザーに提示します。 VerificationFlowResult
を処理し、ユーザーが確認フローを完了したかを知ることができるようにします。
import UIKit import StripeIdentity class VerifyViewController: UIViewController { @IBOutlet weak var verifyButton: UIButton! @IBOutlet weak var activityIndicator: UIActivityIndicatorView! override func viewDidLoad() { super.viewDidLoad() verifyButton.addTarget(self, action: #selector(didTapVerifyButton), for: .touchUpInside) } @objc func didTapVerifyButton() { // Disable the button while the request is made verifyButton.isEnabled = false activityIndicator.startAnimating() // Make request to your verification endpoint var urlRequest = URLRequest(url: URL(string: "https://{{YOUR_SERVER_BASE_URL}}/create-verification-session")!) urlRequest.httpMethod = "POST" let task = URLSession.shared.dataTask(with: urlRequest) { [weak self] data, response, error in DispatchQueue.main.async { [weak self] in // Re-enable button self?.verifyButton.isEnabled = true self?.activityIndicator.stopAnimating() guard error == nil, let data = data, let responseJson = try? JSONDecoder().decode([String: String].self, from: data), let verificationSessionId = responseJson["id"], let ephemeralKeySecret = responseJson["ephemeral_key_secret"] else { // Handle error print(error as Any) return } self?.presentVerificationSheet(verificationSessionId: verificationSessionId, ephemeralKeySecret: ephemeralKeySecret) } } task.resume() } func presentVerificationSheet(verificationSessionId: String, ephemeralKeySecret: String) { // Configure a square brand logo. Recommended image size is 32 x 32 points. let configuration = IdentityVerificationSheet.Configuration( brandLogo: UIImage(named: "{{YOUR_BRAND_LOGO}}")! ) // Instantiate and present the sheet let verificationSheet = IdentityVerificationSheet( verificationSessionId: verificationSessionId, ephemeralKeySecret: ephemeralKeySecret, configuration: configuration ) verificationSheet.present(from: self, completion: { result in switch result { case .flowCompleted: // The user has completed uploading their documents. // Let them know that the verification is processing. print("Verification Flow Completed!") case .flowCanceled: // The user did not complete uploading their documents. // You should allow them to try again. print("Verification Flow Canceled!") case .flowFailed(let error): // If the flow fails, you should display the localized error // message to your user using error.localizedDescription print("Verification Flow Failed!") print(error.localizedDescription) } }) } }
確認画面をテストする
確認ボタンで書類のアップロード画面が表示されるかどうかテストします。
- 本人確認ボタンをタップします。
- エラーメッセージが表示されないことを確認します。
構築したシステムが機能しない場合:
VerificationSession
ID と一時キーシークレットを取得する場所にブレークポイントを配置します。- ネットワークエラーがないこと、およびエンドポイントが
VerificationSession
ID と一時キーシークレットを返すことを確認します。
確認イベントを処理する
本人確認書類のチェックは非同期であるため、確認結果がすぐに提供されるわけではありません。通常、完了までに 1 ~ 3 分かかります。処理が完了すると、VerificationSession のステータスが変わり、processing
から verified
になります。
セッションのステータスに変化があると、Stripe は以下のイベントを送信します。
イベント名 | 説明 | 次のステップ |
---|---|---|
identity.verification_session.verified | すべての検証チェックの処理が完了し、すべての確認が成功しました。 | アプリケーションで関連するアクションをトリガーします。 |
identity.verification_session.requires_input | すべての検証チェックの処理が完了し、少なくとも 1 つの確認が失敗しました。 | アプリケーションで関連するアクションをトリガーするとともに、ユーザーに本人確認の再試行を許可できます。 |
Webhook ハンドラーを使用してこれらのイベントを受信し、確定メールの送信、お客様のデータベース内の確認結果の更新、アカウント登録ステップの完了などのアクションを自動化します。ダッシュボードに確認イベントを表示することもできます。
イベントを受信して、ビジネスアクションを実行する
コード使用
Webhook ハンドラを構築してイベントをリッスンし、非同期型のカスタムの確認フローを作成します。Stripe CLI を使用して、ローカルで Webhook の組み込みのテストとデバッグを行います。
コードなし
ダッシュボードを使用してすべての本人確認を表示し、収集されたデータを調査して、確認の失敗について把握します。