# Token-Verwaltung Erfahren Sie, wie Sie mit Issuing Netzwerk-Token auf Ihren Karten verwalten können. Token sind virtuelle Darstellungen von ausgestellten Karten, die erstellt werden, wenn Karteninhaber/innen: - Karten zu einer Digital Wallet wie Apple Pay oder Google Pay hinzufügen - Zahlungsmethoden für ihr Konto bei einem Online-Geschäft oder Vermittler-Zahlungsmethoden speichern Kundinnen und Kunden nutzen Token, um Zahlungen zu tätigen. Der Vorteil von Token ist, dass nicht jedes Mal sensible Kartendaten preisgegeben werden. Die Token bilden eine Art Ersatz für Kartendaten wie z. B. Kartennummer, Ablaufdatum und Verifizierungscode und senken das Risiko, dass die Daten im Rahmen betrügerischer Transaktionen oder von böswilligen Akteuren gestohlen werden. Da dank der Token keine sensiblen Kartendaten preisgegeben werden, sind sie eine sicherere Zahlungsmethode als physische Karten oder Bezahlformulare, in denen manuelle Angaben gemacht werden müssen. Token sind besonders relevant, wenn Sie: - Ihren Karteninhaberinnen und Karteninhabern ermöglichen, mit Apple Pay, Google Pay oder Samsung Pay zu bezahlen - Ein erhebliches Ausgabevolumen für Card-Not-Present-Transaktionen (z. B. Online-Käufe) haben - Das Token-Verhalten in Ihre Geschäftslogik integrieren möchten ## Token-Verwaltung Mit Stripe Issuing können Sie über die [Tokens API](https://docs.stripe.com/api/issuing/tokens.md) Details zu allen über Ihr Programm ausgestellten Token anzeigen und verwalten. Wir stellen diese Details zur Verfügung, damit Sie die Eigenschaften Ihrer Token und wie diese verwendet werden, besser nachvollziehen können. Unten finden Sie beispielsweise Details zu den folgenden Hauptmerkmalen: - **Dem Urheber eines Tokens:** Gibt an, ob ein [Anbieter einer Digital Wallet oder ein Unternehmen](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-wallet_provider) das Token anfordert. - **Dem prognostizierten Risiko eines Tokens:** Die [Risikoeinschätzung](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data-visa-token_risk_score) des Kartennetzwerks und seine [Empfehlung](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data-wallet_provider-suggested_decision) für ein bestimmtes Token. - **Dem mit einem Token verknüpften Gerät:** Dies umfasst Smart Watches, Smartphones und andere [Geräte](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data-device-type), die das Token anfordern und die [Risikoeinschätzung](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data-wallet_provider-device_trust_score) dieses Geräts. - **Den Karteninhaberdetails des Tokenausstellers:** Gibt für eine zusätzliche Verifizierung an, ob die Karteninhaberdetails, wie der [Name](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data-wallet_provider-cardholder_name) und die [Adresse](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data-wallet_provider-cardholder_address) mit den Angaben der Karteninhaberin/des Karteninhabers bei Stripe übereinstimmen. Zusätzlich zur Transparenz der Token-Eigenschaften können Sie mit der Tokens API Token je nach Ihren gewünschten Arbeitsabläufen Token aktivieren, sperren oder deaktivieren. Dies können Sie zum Beispiel tun, um: - Zu überprüfen, welche vorhandenen Token auf eine neue Karte übertragen werden, wenn Ihr Programm eine Karte ersetzt. - Deaktivieren Sie Token, bei denen der Verdacht auf betrügerische Aktivitäten besteht, ohne dass dies Auswirkungen auf die zugrunde liegende Karte hat. Das `issuing.authorization`-Objekt verfügt auch über ein [Token-Feld](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-token), das ausgefüllt wird, wenn ein Token verwendet wird. ## Risikomanagement Wenn Stripe eine Tokenisierungsanfrage erhält, prüfen wir eine Vielzahl von Variablen, um zu bestimmen, ob wir die Anfrage genehmigen oder nicht. Als Ergebnis dieser Prüfung fahren wir mit einer der folgenden Optionen fort: - Wir genehmigen die Tokenisierungsanfrage, erstellen das Token und fügen dieses zu einer Digital Wallet hinzu. - Wir benötigen eine zusätzliche Authentifizierung und lösen einen einmaligen Zugangscode durch den Anbieter der Digital Wallet aus. Nachdem die Authentifizierung erfolgreich abgeschlossen wurde, erstellen wir das Token und fügen es zur entsprechenden Digital Wallet hinzu. In diesem Fall wird das [Statusfeld](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-status) mit `requested` ausgefüllt, bis die zusätzliche Authentifizierung abgeschlossen ist. - Wir lehnen die Tokenisierungsanfrage ab und verhindern, dass das Token erstellt wird. Sie können zusätzlich zu den Risikokontrollen von Stripe auch eigene Risikokontrollen einrichten. Die Token-API erlaubt keine vollständige Ablehnung einer Tokenisierungsanfrage zum Zeitpunkt der Erstellung, jedoch können Sie Token kurz nach ihrer Erstellung deaktivieren oder sperren. ## So funktionieren Token Lernen Sie nachfolgend, wie Token funktionieren und verstehen, wie Token erstellt werden und wie der Lebenszyklus von Token aussieht. ### Token erstellen Die Token-Erstellung bzw. Tokenisierung ist ein mehrstufiger Prozess, an dem Karteninhaberinnen und Karteninhaber, Stripe-Nutzerinnen und -Nutzer, ein Anbieter von Digital Wallets, Stripe sowie ein Kartennetzwerk beteiligt sind. Das nachstehende Beispielszenario zeigt die Schritte, die Karteninhaberinnen und Karteninhaber ausführen müssen, sowie die beteiligten Prozesse bei der Nutzung der Tokens API als Teil Ihres Programms. #### Beispielszenario Karteninhaber/innen Ihres Issuing-Programms möchten eine von Stripe ausgestellte Karte zu einer Digital Wallet wie Apple Pay hinzufügen. Dazu öffnen diese einfach die App ihrer Digital Wallet und geben wie aufgefordert ihre Karteninhaberdaten (z. B. Name und Rechnungsadresse) und Kartendaten (z. B. Kartennummer und Ablaufdatum) ein. Diese Informationen werden dann an den Anbieter der Wallet (in diesem Fall Apple Pay) übermittelt, der beim zugrundeliegenden Netzwerk der Karte (z, B. Visa oder Mastercard) innerhalb des Netzwerks als ‘token requestor’ registriert ist. Als Nächstes führt das Kartennetzwerk mit diesen Daten eine Reihe von Validierungen durch und kombiniert diese zusammen mit den ihm bekannten Daten zu einer Tokenisierungsanfrage. Anschließend leitet es die Daten zur Entscheidung an Stripe weiter. Stripe führt eine eigene zusätzliche Validierung durch, um zu bestimmen, wie mit der Anfrage verfahren wird. Wie bereits zuvor erwähnt, kann diese Validierung zu drei Ergebnissen führen: - Stripe genehmigt die Tokenisierung. Dadurch wird der Token in der Wallet aktiviert und kann verwendet werden. Stripe sendet das Ereignis `issuing_token.created` an alle überwachenden Webhook-Endpoints. - Stripe erfordert eine zusätzliche Verifizierung, folglich wird die Karteninhaberin/der Karteninhaber zur Authentifizierung aufgefordert. Stripe sendet das Ereignis `issuing_token.created` an alle überwachenden Webhook-Endpoints. Das Token wird aktiv, wenn die Karteninhaberin/der Karteninhaber diesen Schritt erfolgreich abschließt. Stripe sendet das Ereignis `issuing_token.updated` an alle überwachenden Webhook-Endpoints, sobald das Token aktiviert wird. - Stripe lehnt die Tokenisierungsanfrage ab, sodass das Token nicht zur Wallet hinzugefügt werden kann. Stripe sendet das Ereignis `issuing_token.created` nicht an überwachende Webhook-Endpoints. Der Wallet-Anbieter und das Kartennetzwerk können bei jedem Schritt des Tokenisierungsvorgangs die weitere Bearbeitung einer Tokenisierungsanfrage unterbrechen (Stripe wird in solchen Fällen nicht immer benachrichtigt). Das nachfolgende Sequenzdiagramm veranschaulicht den Tokenisierungsvorgang noch detaillierter. Übersicht über den Ablauf einer erfolgreichen Bereitstellungsanfrage (See full diagram at https://docs.stripe.com/issuing/controls/token-management) ### Lebenszyklus eines Tokens Nachdem ein Token erstellt wurde, kann dieses in der Digital Wallet vier Zustände annehmen: - **Inaktiv**: Die Token-Anfrage ist noch offen und das Token kann noch nicht für Autorisierungen verwendet werden. Ein inaktives Token in der Tokens API hat den Status `requested`. - **Gesperrt**: Das Token kann vorübergehend nicht in der Wallet verwendet werden. Karteninhaber/innen und Stripe-Nutzer/innen können über die Tokens API die Sperrung eines Tokens einleiten. Karteninhaber/innen können Sperrungen, die durch Stripe-Nutzer/innen (d. h. über eine Digital Wallet App) ausgelöst wurden, nicht aufheben. Nutzer/innen können gesperrte Karten nur direkt über die Tokens API reaktivieren. - **Aktiv**: Das Token kann in der Wallet, zu der es hinzugefügt wurde, verwendet werden. - **Gelöscht**: Das Token wurde aus der Wallet entfernt und kann nicht mehr verwendet werden. Sie können Token in diesem Status nicht ändern. Das folgende Statusdiagramm zeigt die verschiedenen Status, wie diese in der API angezeigt werden und wie Sie diese mit unseren APIs ändern können. Statusdiagramm des Lebenszyklus des Tokens (See full diagram at https://docs.stripe.com/issuing/controls/token-management) Stripe synchronisiert den Token-Status automatisch mit den Status der Karteninhaber/innen und der Karten, wenn diese sich ändern. Stripe migriert auch Token, während Ersatzkarten ausgestellt werden, wenn zuvor die ursprüngliche Karte nicht storniert wird. Mit der [List API](https://docs.stripe.com/api/issuing/tokens/list.md) können Sie anzeigen, welche Token mit welcher Karte verknüpft sind. ### Händler-Token Unternehmen können auch Token erstellen, wenn sie eine Zahlungsmethode zur späteren Verwendung bei einem Händler speichern (z. B. wenn eine Karteninhaberin oder ein Karteninhaber ihre bzw. seine Kartendaten für den Bezahlvorgang bei Amazon speichert). In diesen Szenarien initiiert das Unternehmen die Token-Erstellung und die Tokens API enthält kein Feld [wallet_provider](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-wallet_provider). Um das zugrunde liegende Unternehmen zu bewerten, das den Token erstellt hat, prüfen Sie die mit Autorisierungen verbundenen [Unternehmensinformationen](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-merchant_data), die unter Verwendung des Tokens durchgeführt wurden. Wenn Sie Karten von Mastercard ausgeben, können von ihnen stammende Tokens einen lesbaren Namen im Feld [network_data.mastercard.token_requestor_name](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data-mastercard-token_requestor_name) enthalten. Händler-Token sind an das jeweilige Unternehmen (Token-Anforderer im Kartennetzwerk) gebunden, von dem sie stammen, und können nicht bei anderen Unternehmen verwendet werden. ### Ermitteln, wann ein Token für eine Transaktion verwendet wurde Autorisierungen oder Transaktionen, die ein Token verwendet haben, haben einen erweiterbaren Verweis auf das Token-Objekt im `token`-Attribut. Dieses Feld ist „Null“ für Autorisierungen oder Transaktionen, die kein Token verwendet haben. Kombinieren Sie dies mit dem `wallet`-Attribut des Autorisierungs- oder Transaktions-Objekts oder dem [wallet_provider](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-wallet_provider)-Attribut des Token-Objekts, um zu bestimmen, ob das Token einer Digital Wallet verwendet wurde. Weitere Informationen finden Sie in der API-Dokumentation zu [Autorisierungen](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-token) und [Transaktionen](https://docs.stripe.com/api/issuing/transactions/object.md#issuing_transaction_object-token). ## Einschränkungen für Netzwerkdaten Das Issuing-Token-Objekt enthält ein optionales, [erweiterbares Feld](https://docs.stripe.com/api/expanding_objects.md) namens [network_data](https://docs.stripe.com/api/issuing/tokens/object.md#issuing_token_object-network_data). Es enthält zusätzliche, sensible Kartennetzwerkdetails zu Ihren Token, die in erster Linie mit dem Prozess der Token-Erstellung zusammenhängen. Da diese Daten äußerst sensibel sind, benötigen Sie einen [eingeschränkten Zugriffsschlüssel](https://docs.stripe.com/keys.md#create-restricted-api-key) mit den erforderlichen Berechtigungen, um auf die Daten zuzugreifen. Die Daten können nur innerhalb der ersten 24 Stunden nach der Token-Erstellung (basierend auf dem Wert **created**) für einen Token eingesehen werden. Diese Daten sind in der API nur über [Token abrufen](https://docs.stripe.com/api/issuing/tokens/retrieve.md) und über die API zum [Aktualisieren eines Token-Status](https://docs.stripe.com/api/issuing/tokens/update.md) verfügbar. Um auf diese Daten zuzugreifen, konfigurieren Sie Ihren eingeschränkten Zugriffsschlüssel mit den folgenden Berechtigungen: - Lesezugriff auf Token für die Methoden Retrieve API und List API - Schreibzugriff auf Token für die Methode Update Status API - Lesezugriff auf Token-Netzwerkdaten für den Zugriff auf **network\_data** innerhalb der 24-stündigen Zeitrahmens Wenn Sie über den anfänglichen 24-stündigen Verfügbarkeitszeitraum hinaus Zugriff auf `network_data` benötigen, müssen Sie [die IP-Adressen einschränken](https://docs.stripe.com/keys.md#limit-api-secret-keys-ip-address), die Ihre eingeschränkten Zugriffsschlüssel verwenden können. ## Testen Karteninhaber/innen von Kartenausstellern können Token kostenlos bei Geschäften oder in Digital Wallets erstellen. Wir empfehlen, ein Token in einer gewünschten Digital Wallet zu erstellen, um Webhook-Ereignisse, API-Felder und die Auswirkungen eines aktualisierten Token zu verstehen. Befolgen Sie dafür zunächst den [Leitfaden für Digital Wallets](https://docs.stripe.com/issuing/cards/digital-wallets.md) zur manuellen Bereitstellung. Wenn Sie die Tokens API lieber im Test-Modus testen möchten, können Sie eine Test-Modus-Autorisierung erstellen und dabei für das [Wallet-Feld](https://docs.stripe.com/api/issuing/authorizations/test_mode_create.md#test_mode_create_authorization-wallet) eine der verfügbaren Optionen auswählen. Das **Token**-Feld wird für die resultierende Autorisierung festgelegt. Anschließend können Sie die API-Methoden für dieses Token wie gewohnt verwenden. In diesen Szenarien sind nicht alle Felder festgelegt, einschließlich **network\_data** und das Token wird nicht für nachfolgenden Testautorisierungen verwendet. ## Die Tokens API Auf Token-Daten kann nur über die Tokens API zugegriffen werden. Nachfolgend finden Sie verschiedene Anwendungsbeispiele. ### Beispiel für eine erfolgreiche manuelle Bereitstellung überprüfen - In diesem Beispiel abonnieren Sie die Ereignisse `issuing_token.created` und `issuing_token.updated`. - Wenn Sie ein Ereignis des Typs `issuing_token.created` empfangen, erweitern Sie mithilfe der Retrieve API die **network\_data**, um die Bereitstellungsdetails anzuzeigen. Hier ist ein Beispiel: ```json { "id": "evt_1NxBn3FUQNp5XJkna0rkKU2r", "object": "event", "api_version": "2026-05-27.dahlia", "created": 1691100189, "data": { "object": { "id": "intok_1NuMIZFUQNp5XJknPmDzEz0t", "object": "issuing.token", "card": "{{CARD_ID}}", "created": 1691100179, "device_fingerprint": "intd_1JDmgz2OpvKigH2CxnEEs", "last4": "9203", "livemode": true, "network": "mastercard", "network_updated_at": 1691100170, "status": "requested", "wallet_provider": "apple_pay" } }, "livemode": true, "pending_webhooks": 0, "request": { "id": "req_ARTvFhTufhHna9", "idempotency_key": "49a40678-8f45-4c91-9d6f-98a5bd569f9d" }, "type": "issuing_token.created" } ``` - Überprüfen Sie, ob das Feld **wallet\_provider** ausgefüllt ist. Ist dies der Fall, so stammt das Token von einer Digital Wallet. Notieren Sie sich die **id** des Objekts und verwenden diese im Retrieve API -Aufruf: ```bash curl https://api.stripe.com/v1/issuing/tokens/intok_1NuMIZFUQNp5XJknPmDzEz0t \ -u <>: \ -d "expand[]"=network_data \ -G ``` Dies führt zu folgender Antwort: ```json { "id": "intok_1NuMIZFUQNp5XJknPmDzEz0t", "object": "issuing.token", "card": "{{CARD_ID}}", "created": 1691100159, "device_fingerprint": "intd_1JDmgz2OpvKigH2CxnEEs", "last4": "9203", "livemode": true, "network": "mastercard", "network_data": { "device": { "device_fingerprint": "intd_1JDmgz2OpvKigH2CxnEEs", "ip_address": null, "location": "+30.22/-89.10", "name": "AB's phone", "phone_number": null, "type": "phone" }, "mastercard": { "card_reference_id": "...", "token_reference_id": "...", "token_requestor_id": "...", "token_requestor_name": "APPLE PAY" }, "type": "mastercard", "wallet_provider": { "account_id": null, "account_trust_score": null, "card_number_source": "manual", "cardholder_address": null, "cardholder_name": null, "device_trust_score": null, "hashed_account_email_address": null, "reason_codes": [], "suggested_decision": null, "suggested_decision_version": null } }, "network_updated_at": 1691100170, "status": "requested", "wallet_provider": "apple_pay" } ``` - In dem Beispiel ist die **card\_number\_source** auf `manual` gesetzt, der **status** des Tokens ist `requested` und bei der Wallet handelt es sich um Apple Pay. Das heißt, dass der Karteninhaberin/dem Karteninhaber die Kartendaten bei Eingabe in die Apple Wallet vorlagen. Bevor die Karte in der Wallet verwenden werden kann, muss sie/er eine zusätzliche Verifizierung durchführen. - Ein paar Sekunden später wird Ihnen das Ereignis `issuing_token.updated` für dasselbe Token angezeigt. Das Token befindet sich jetzt im Status `active`. Dies bedeutet, dass die Karteninhaberin/der Karteninhaber die Verifizierung erfolgreich abgeschlossen hat und die Karte jetzt für Apple Pay verwenden kann. ### Beispiel für das Löschen eines verdächtigen Händler-Token - In diesem Beispiel abonnieren Sie das Ereignis `issuing_token.created`. - Der Webhook empfängt das Ereignis `issuing_token.created`. ```json { "object": { "id": "intok_1NuMIZuTQ2hhXJooNmDzEz0t", "object": "issuing.token", "card": "{{CARD_ID}}", "created": 1691100179, "device_fingerprint": null, "last4": "9203", "livemode": true, "network": "visa", "network_updated_at": 1691100170, "status": "active" } } ``` - Beim Token ist das Feld **wallet\_provider** nicht vorhanden, es handelt sich also um ein Händler-Token. Erweitern Sie mithilfe der Retrieve API die **network\_data**, um die Bereitstellungsdetails anzuzeigen. ```bash curl https://api.stripe.com/v1/issuing/tokens/intok_1NuMIZFUQNp5XJknPmDzEz0t \ -u <>: \ -d "expand[]"=network_data \ -G ``` Die folgende Antwort wird ausgegeben: ```json { "id": "intok_1NuMIZFUQNp5XJknPmDzEz0t", "object": "issuing.token", "card": "{{CARD_ID}}", "created": 1691100186, "device_fingerprint": null, "last4": "4674", "livemode": true, "network": "visa", "network_data": { "visa": { // ...other fields }, "type": "visa", "wallet_provider": { "card_number_source": "manual", "cardholder_address": null, "cardholder_name": "abc" // ...other fields } }, "network_updated_at": 1691100170, "status": "active" } ``` - Sie sehen, dass der Name der Karteninhaberin/des Karteninhabers ein ungültiger Wert ist, der nicht mit dem erwarteten Namen übereinstimmt. - Betrügerische Aktivitäten können Sie mit der Update Status API vermeiden. Mit Ihr können Sie das Token löschen, bevor es verwendet werden kann. Anschließend fragen Sie die Karteninhaberin/den Karteninhaber, ob sie/er das Token selbst angefordert hat. Ist dies nicht der Fall, so stornieren und ersetzen Sie die Karte, falls die Kartennummer gestohlen oder das Konto kompromittiert wurde. ```bash curl https://api.stripe.com/v1/issuing/tokens/intok_1NuMIZFUQNp5XJknPmDzEz0t \ -u <> \ -d status=deleted ``` ### Beispiel für die Überwachung der Geräte Abonnieren Sie wie in den vorherigen Beispielen die Token-Ereignisse und führen Sie eine Retrieve API-Anfrage für das Ausweisdokument durch, wenn Sie ein Ereignis empfangen. In diesem Fall sehen Sie, dass **device\_fingerprint** ausgefüllt ist und überprüfen das Feld **network\_data.device.location**. Die Standortkoordinaten geben Ihnen Auskunft darüber, dass die Übermittlung des Geräts aus einem anderen Land erfolgt. Ihnen wird außerdem angezeigt, dass die Karteninhaberin/der Karteninhaber Sie vorab über die Reise informiert hat und dass die Daten mit dem angegebenen Reiseziel übereinstimmen.