本人確認シート

Stripe Identity は、Capacitor のアプリケーションコードを保ったまま、iOS と Android ではネイティブシート、Web では Stripe.js を使って本人確認書類を検証します。

ネイティブでは verificationId と ephemeralKeySecret で Stripe Identity Verification Sheet を表示します。Web では initialize 後、clientSecret を指定して verifyIdentity を呼びます。

結果を受け取る

結果リスナーはアプリケーション起動時に一度だけ、present() より前に登録します。Android ではネイティブシート表示中に Activity と JavaScript ランタイムが再生成されることがあるため、早期登録によって結果の取りこぼしを防ぎます。

リスナーは main.ts、アプリケーション初期化処理、シングルトンサービスなど、アプリケーションレベルの所有者が存続する間は保持してください。present() の直後に削除してはいけません。Android の present() はシート表示時に解決し、結果は後から VerificationResult で届きます。

Completed、Canceled、Failed は IdentityVerificationResult.result の値です。個別の addListener イベントではないため、VerificationResult を登録して result を確認します。

 enum IdentityVerificationSheetEventsEnum

Member
Value


Loaded
'identityVerificationSheetLoaded'

FailedToLoad
'identityVerificationSheetFailedToLoad'

Completed
'identityVerificationSheetCompleted'

Canceled
'identityVerificationSheetCanceled'

Failed
'identityVerificationSheetFailed'

VerificationResult
'identityVerificationResult'

ネイティブ結果の引き継ぎはメモリ上だけです。OS によるプロセス終了後の復旧は保証されません。

Member	Value
`Loaded`	`'identityVerificationSheetLoaded'`
`FailedToLoad`	`'identityVerificationSheetFailedToLoad'`
`Completed`	`'identityVerificationSheetCompleted'`
`Canceled`	`'identityVerificationSheetCanceled'`
`Failed`	`'identityVerificationSheetFailed'`
`VerificationResult`	`'identityVerificationResult'`

セッション認証情報を取得する

バックエンドで Stripe のシークレットキーを使って VerificationSession と、そのセッション用の一時キーを作成し、クライアントへ安全に渡せるフィールドだけを返します。

レスポンス	取得元	`create` オプション
`verificationId`	`VerificationSession.id`	`verificationId`
`ephemeralKeySecret`	`EphemeralKey.secret`	`ephemeralKeySecret`
`clientSecret`	`VerificationSession.client_secret`	`clientSecret`

const session = await stripe.identity.verificationSessions.create({ type: 'document' });
const ephemeralKey = await stripe.ephemeralKeys.create(
  { verification_session: session.id },
  { apiVersion: '2022-11-15' },
);
return {
  verificationId: session.id,
  ephemeralKeySecret: ephemeralKey.secret,
  clientSecret: session.client_secret,
};

シークレットキーはサーバーに保持します。Capacitor アプリへ渡すのは公開可能キーと上記3フィールドだけです。端末の Completed は書類アップロード完了を意味し、審査完了ではありません。最終結果は identity.verification_session.verified などの Identity Webhook で確認してください。

Webプラットフォームを初期化する

initialize は Web でのみ必須で、公開可能キーを使って Stripe.js を読み込みます。ネイティブではキーを使用せずに解決します。

 method initialize(...)Initializes Stripe Identity. Call this before create() on web.
initialize(options: InitializeIdentityVerificationSheetOption) => Promise<void>

シートを作成して表示する

バックエンドのフィールドを create へ渡し、present() を呼びます。

iOS と Android では verificationId と ephemeralKeySecret が必須です。
Web は clientSecret だけを使用し、ネイティブはこれを無視します。
オプション型はパッケージの index から再エクスポートされないため、直接 import しないでください。

 method create(...)Creates an Identity VerificationSheet from credentials generated by your

server. Wait for this Promise or the Loaded event before present().
create(options: CreateIdentityVerificationSheetOption) => Promise<void>

`interface` CreateIdentityVerificationSheetOption

Prop	Type	Description	Since
`verificationId`	`string`	ID of the VerificationSession created by your server. Required on iOS and Android.	5.0.3
`ephemeralKeySecret`	`string`	Ephemeral-key secret scoped to the VerificationSession. Required on iOS and Android and must be returned by your server.	5.0.3
`clientSecret`	`string`	Client secret of the VerificationSession. Required on web and ignored by the native Identity SDKs.	5.4.0

 method present()Presents the VerificationSheet created by create(). Listen for

VerificationResult to distinguish completed, canceled, and failed flows.
present() => Promise<void>
present() は Promise<void> を返します。結果は VerificationResult リスナーから読み取ります。

FailedToLoadを処理する

create がシートを構築できない場合に発生し、Promise も同じ文言で拒否されます。ネイティブでは必須パラメータ不足時、iOS ではプライマリアプリアイコンのキー不足時にも発生します。

iOS は { message }、Android は現在 error に文字列を設定します。リスナーと拒否された Promise の両方を処理してください。Web の create は常に Loaded を発生させ、present が未初期化または clientSecret 不足を例外として返します。

`interface` StripeIdentityError

Prop	Type	Description	Since
`code`	`string`	Stripe error code when one is available.	5.1.0
`message`	`string`	Human-readable error message suitable for logging or display.	5.1.0

VerificationResultを処理する

`result`	意味
`Completed`	書類送信完了。審査中なのでWebhookを待つ
`Canceled`	利用者がシートを閉じた。再試行を許可する
`Failed`	フロー失敗。`error.message` を表示する

Failed には error が含まれます。これらの結果値を addListener のイベント名として登録しないでください。

`interface` IdentityVerificationResult

Prop	Type	Description	Since
`result`	`IdentityVerificationSheetResultInterface`	Final state of the presented verification flow.	4.2.0
`error`	`StripeIdentityError`	Error details when `result` is `Failed`.	4.2.0

`type alias` IdentityVerificationSheetResultInterface

IdentityVerificationSheetEventsEnum.Completed | IdentityVerificationSheetEventsEnum.Canceled | IdentityVerificationSheetEventsEnum.Failed

エラーとキャンセル

キャンセルはクラッシュではなく利用者の操作として扱い、再度 create / present できるようにします。Android は表示時、iOS はシートを閉じた後、Web は verifyIdentity 完了後に present() が解決します。解決だけで成功と判断せず、必ず verification.result で分岐してください。

example.ts

import {
  IdentityVerificationSheetEventsEnum,
  StripeIdentity,
} from '@capacitor-community/stripe-identity';

const verificationResultListener = await StripeIdentity.addListener(
  IdentityVerificationSheetEventsEnum.VerificationResult,
  (verification) => {
    if (verification.result === IdentityVerificationSheetEventsEnum.Completed) {
      // Documents were submitted. Confirm the outcome with webhooks.
    } else if (verification.result === IdentityVerificationSheetEventsEnum.Canceled) {
      // The user dismissed the sheet. Allow them to try again.
    } else if (verification.result === IdentityVerificationSheetEventsEnum.Failed) {
      console.error(verification.error?.message);
    }
  },
);

const failedToLoadListener = await StripeIdentity.addListener(
  IdentityVerificationSheetEventsEnum.FailedToLoad,
  (error) => {
    // iOS follows StripeIdentityError; Android v8.2.1 currently emits `error`.
    const message = error.message ?? (error as unknown as { error?: string }).error;
    console.error(message);
  },
);

await StripeIdentity.initialize({
  publishableKey,
});

const response = await fetch('https://example.com/identify', { method: 'POST' });
const { verificationId, ephemeralKeySecret, clientSecret } = await response.json();

await StripeIdentity.create({
  verificationId,
  ephemeralKeySecret,
  clientSecret,
});

await StripeIdentity.present();

// Keep verificationResultListener and failedToLoadListener until their owner is destroyed.

本人確認シート

結果を受け取る

`enum` IdentityVerificationSheetEventsEnum

セッション認証情報を取得する

Webプラットフォームを初期化する

`method` initialize(...)

シートを作成して表示する

`method` create(...)

`interface` CreateIdentityVerificationSheetOption

`method` present()

FailedToLoadを処理する

`interface` StripeIdentityError

VerificationResultを処理する

`interface` IdentityVerificationResult

`type alias` IdentityVerificationSheetResultInterface

エラーとキャンセル

本人確認シート

結果を受け取る

enum IdentityVerificationSheetEventsEnum

セッション認証情報を取得する

Webプラットフォームを初期化する

method initialize(...)

シートを作成して表示する

method create(...)

interface CreateIdentityVerificationSheetOption

method present()

FailedToLoadを処理する

interface StripeIdentityError

VerificationResultを処理する

interface IdentityVerificationResult

type alias IdentityVerificationSheetResultInterface

エラーとキャンセル

`enum` IdentityVerificationSheetEventsEnum

`method` initialize(...)

`method` create(...)

`interface` CreateIdentityVerificationSheetOption

`method` present()

`interface` StripeIdentityError

`interface` IdentityVerificationResult

`type alias` IdentityVerificationSheetResultInterface