Identity Verification Sheet

Stripe Identity prüft Identitätsdokumente unter iOS und Android in einem nativen Sheet und im Web über Stripe.js. Der Anwendungscode bleibt dabei in Capacitor.

Das Plugin unterstützt iOS, Android und Web. Native Plattformen zeigen das Stripe Identity Verification Sheet mit verificationId und ephemeralKeySecret an. Das Web ruft nach initialize verifyIdentity mit clientSecret auf.

Der Weg zur ersten Verifizierung

Gehen Sie für die erste erfolgreiche Übermittlung in dieser Reihenfolge vor:

Erstellen Sie eine VerificationSession auf Ihrem Backend und geben Sie die folgenden für den Client sicheren Felder zurück.
Registrieren Sie den Listener VerificationResult einmal beim Anwendungsstart, vor present().
Rufen Sie im Web initialize mit dem veröffentlichbaren Schlüssel auf.
Rufen Sie create und anschließend present() auf.

Erster Erfolg auf dem Gerät: Das Sheet öffnet sich und Sie erhalten Completed, nachdem der Nutzer das Testdokument hochgeladen hat. Completed bedeutet, dass die Übermittlung abgeschlossen ist, nicht die Prüfung. Bestätigen Sie das offizielle Ergebnis mit Identity-Webhooks auf Ihrem Server. Das Codepanel folgt demselben Ablauf.

Auf das Ergebnis hören

Registrieren Sie den Ergebnis-Listener einmal beim Anwendungsstart und vor dem Aufruf von present(). Android kann die Activity und die JavaScript-Laufzeit neu erstellen, während das native Sheet geöffnet ist. Frühe Registrierung verhindert deshalb, dass ein geliefertes Ergebnis verpasst wird.

Behalten Sie den Listener während der Lebensdauer seiner zuständigen Instanz auf Anwendungsebene bei, beispielsweise main.ts, einem Anwendungsinitialisierer oder einem beim Start initialisierten Singleton-Dienst. Entfernen Sie ihn nicht unmittelbar nach der Rückkehr von present(). Unter Android wird present() aufgelöst, sobald das Sheet angezeigt wird; das Ergebnis trifft später über VerificationResult ein.

Completed, Canceled und Failed sind Ergebniswerte in IdentityVerificationResult.result. Sie werden nicht als separate addListener-Überladungen unterstützt. Registrieren Sie IdentityVerificationSheetEventsEnum.VerificationResult und prüfen Sie result.

 enum IdentityVerificationSheetEventsEnum

Mitglied
Wert


Loaded
'identityVerificationSheetLoaded'

FailedToLoad
'identityVerificationSheetFailedToLoad'

Completed
'identityVerificationSheetCompleted'

Canceled
'identityVerificationSheetCanceled'

Failed
'identityVerificationSheetFailed'

VerificationResult
'identityVerificationResult'

Die native Ergebnisübergabe bleibt im Arbeitsspeicher. Sie garantiert keine Wiederherstellung nach dem Beenden des Prozesses durch das Betriebssystem.

Mitglied	Wert
`Loaded`	`'identityVerificationSheetLoaded'`
`FailedToLoad`	`'identityVerificationSheetFailedToLoad'`
`Completed`	`'identityVerificationSheetCompleted'`
`Canceled`	`'identityVerificationSheetCanceled'`
`Failed`	`'identityVerificationSheetFailed'`
`VerificationResult`	`'identityVerificationResult'`

Sitzungszugangsdaten beziehen

Erstellen Sie auf Ihrem Backend mit dem geheimen Stripe-Schlüssel eine VerificationSession. Erstellen Sie anschließend einen temporären Schlüssel für diese Sitzung und geben Sie ausschließlich für den Client sichere Felder zurück.

Der offizielle Demo-Server (POST /identify) erstellt eine VerificationSession vom Typ document, erstellt einen temporären Schlüssel mit { verification_session: session.id } und der Stripe-API-Version 2022-11-15 und antwortet mit:

Antwortfeld	Quelle	Plugin-Option von `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,
};

Bewahren Sie den geheimen Stripe-Schlüssel auf dem Server auf. Die Capacitor-Anwendung sollte ausschließlich den veröffentlichbaren Schlüssel für Web-initialize sowie verificationId, ephemeralKeySecret und clientSecret erhalten. Liefern Sie STRIPE_SECRET_KEY niemals im Client, in der nativen Binärdatei oder im Frontend-Bundle aus.

Completed auf dem Gerät bedeutet, dass der Nutzer seine Dokumente fertig hochgeladen hat. Die VerificationSession wechselt anschließend in die Verarbeitung. Bestätigen Sie das offizielle Ergebnis auf dem Server über Identity-Webhooks wie identity.verification_session.verified, identity.verification_session.requires_input, identity.verification_session.processing, identity.verification_session.canceled und identity.verification_session.redacted. Siehe Verifizierungsergebnisse verarbeiten.

Die Web-Plattform initialisieren

initialize ist nur im Web erforderlich. Es lädt Stripe.js mit dem veröffentlichbaren Schlüssel. Natives initialize wird aufgelöst, ohne diesen Schlüssel zu verwenden.

 method initialize(...)Initialisiert Stripe Identity. Im Web vor create() aufrufen.
initialize(options: InitializeIdentityVerificationSheetOption) => Promise<void>

Das Sheet erstellen und anzeigen

Übergeben Sie die Backend-Felder an create und rufen Sie anschließend present() auf.

iOS und Android benötigen verificationId und ephemeralKeySecret. Fehlt einer der Werte, wird create zurückgewiesen und FailedToLoad erzeugt.
Web verwendet ausschließlich clientSecret. Native Plattformen ignorieren clientSecret. Sie können es in nativen Builds weglassen; nehmen Sie es auf, wenn derselbe Code im Web läuft.
Importieren Sie CreateIdentityVerificationSheetOption und InitializeIdentityVerificationSheetOption nicht aus @capacitor-community/stripe-identity. Diese Optionstypen werden aus dem Paketindex nicht erneut exportiert.

 method create(...)Erstellt ein Identity VerificationSheet mit den vom

Server erzeugten Zugangsdaten. Vor present() dieses Promise oder das Ereignis Loaded abwarten.
create(options: CreateIdentityVerificationSheetOption) => Promise<void>

`interface` CreateIdentityVerificationSheetOption

Eigenschaft	Typ	Beschreibung	Seit
`verificationId`	`string`	Kennung der vom Server erstellten VerificationSession. Auf iOS und Android erforderlich.	5.0.3
`ephemeralKeySecret`	`string`	Auf die VerificationSession beschränktes Secret des temporären Schlüssels. Auf iOS und Android erforderlich; muss vom Server zurückgegeben werden.	5.0.3
`clientSecret`	`string`	Client Secret der VerificationSession. Im Web erforderlich; von den nativen Identity-SDKs ignoriert.	5.4.0

 method present()Zeigt das mit create() erstellte VerificationSheet an. Auf

VerificationResult reagieren, um abgeschlossene, abgebrochene und fehlgeschlagene Abläufe zu unterscheiden.
present() => Promise<void>
present() gibt Promise<void> zurück, nicht IdentityVerificationResult. Lesen Sie das Ergebnis aus dem Listener VerificationResult.

FailedToLoad verarbeiten

FailedToLoad wird ausgelöst, wenn create das Sheet nicht erstellen kann. Das Promise von create wird ebenfalls mit demselben Text zurückgewiesen.

Native Plattformen erzeugen es, wenn verificationId oder ephemeralKeySecret fehlt: Invalid Params. This method require verificationId or ephemeralKeySecret. unter Android; iOS verwendet denselben Satz mit kleingeschriebenem this. iOS erzeugt es außerdem, wenn die Schlüssel des primären Anwendungssymbols in Info.plist fehlen.

Der Listener-Typ ist StripeIdentityError. iOS liefert { message }. Android legt den Text derzeit als Zeichenfolge unter error ab. Verarbeiten Sie sowohl den Listener als auch das zurückgewiesene Promise von create.

Web-create erzeugt immer Loaded und validiert clientSecret nicht. Web-present löst Stripe is not initialized. oder clientSecret is not set. aus statt FailedToLoad.

`interface` StripeIdentityError

Eigenschaft	Typ	Beschreibung	Seit
`code`	`string`	Stripe-Fehlercode, sofern verfügbar.	5.1.0
`message`	`string`	Verständliche Fehlermeldung, die sich zur Protokollierung oder Anzeige eignet.	5.1.0

VerificationResult verarbeiten

IdentityVerificationResult.result ist IdentityVerificationSheetResultInterface: Completed, Canceled oder Failed.

`result`	Bedeutung
`Completed`	Der Nutzer hat Dokumente übermittelt. Die Verifizierung wird noch verarbeitet; warten Sie auf Webhooks.
`Canceled`	Der Nutzer hat das Sheet geschlossen. Ermöglichen Sie einen erneuten Versuch. Im Web entspricht dies `session_cancelled` von Stripe.js.
`Failed`	Der Ablauf ist fehlgeschlagen. Lesen Sie `error.message` und zeigen Sie es an. Native Plattformen senden den lokalisierten Fehlertext; das Web leitet den Stripe.js-Fehler weiter.

error ist bei Failed vorhanden. Registrieren Sie weder addListener(IdentityVerificationSheetEventsEnum.Completed) noch Canceled oder Failed. Diese Enum-Member sind Ergebniswerte, keine unterstützten Listener-Namen.

`interface` IdentityVerificationResult

Eigenschaft	Typ	Beschreibung	Seit
`result`	`IdentityVerificationSheetResultInterface`	Endzustand des angezeigten Verifizierungsablaufs.	4.2.0
`error`	`StripeIdentityError`	Fehlerdetails, wenn `result` `Failed` ist.	4.2.0

`type alias` IdentityVerificationSheetResultInterface

IdentityVerificationSheetEventsEnum.Completed | IdentityVerificationSheetEventsEnum.Canceled | IdentityVerificationSheetEventsEnum.Failed

Fehler und Abbruch

Behandeln Sie Abbruch als Nutzeraktion, nicht als Absturz. Behalten Sie den Listener registriert und ermöglichen Sie einen weiteren Zyklus aus create und present.

Das Verhalten von present() unterscheidet sich je nach Plattform:

Android löst auf, sobald das Sheet angezeigt ist. Ein späteres VerificationResult, das bis zur Verarbeitung im Speicher bleibt, meldet Completed, Canceled oder Failed. Ein beim Anzeigen ausgelöster Fehler weist das Promise zurück.
iOS wartet bis zum Schließen des Sheets, meldet VerificationResult und löst anschließend present() auf.
Web wartet auf verifyIdentity. Abbruch und Fehler melden VerificationResult und lösen auf. Fehlendes initialize oder clientSecret führt zur Zurückweisung.

Leiten Sie aus dem Auflösen von present() keinen Erfolg ab. Verzweigen Sie immer anhand von 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.

Capacitor-Plugins

Identity Verification Sheet

Der Weg zur ersten Verifizierung

Auf das Ergebnis hören

`enum` IdentityVerificationSheetEventsEnum

Sitzungszugangsdaten beziehen

Die Web-Plattform initialisieren

`method` initialize(...)

Das Sheet erstellen und anzeigen

`method` create(...)

`interface` CreateIdentityVerificationSheetOption

`method` present()

FailedToLoad verarbeiten

`interface` StripeIdentityError

VerificationResult verarbeiten

`interface` IdentityVerificationResult

`type alias` IdentityVerificationSheetResultInterface

Fehler und Abbruch

Identity Verification Sheet

Der Weg zur ersten Verifizierung

Auf das Ergebnis hören

enum IdentityVerificationSheetEventsEnum

Sitzungszugangsdaten beziehen

Die Web-Plattform initialisieren

method initialize(...)

Das Sheet erstellen und anzeigen

method create(...)

interface CreateIdentityVerificationSheetOption

method present()

FailedToLoad verarbeiten

interface StripeIdentityError

VerificationResult verarbeiten

interface IdentityVerificationResult

type alias IdentityVerificationSheetResultInterface

Fehler und Abbruch

`enum` IdentityVerificationSheetEventsEnum

`method` initialize(...)

`method` create(...)

`interface` CreateIdentityVerificationSheetOption

`method` present()

`interface` StripeIdentityError

`interface` IdentityVerificationResult

`type alias` IdentityVerificationSheetResultInterface