Token-Verwaltung

Allgemeine Infos zu Token

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 für Nutzer/innen am relevantesten, die:

• Ihren Karteninhaberinnen/Karteninhabern erlauben, Ausgaben mit Apple Pay, Google Pay oder Samsung Pay vorzunehmen
• Ein erhebliches Ausgabevolumen für Card-Not-Present-Transaktionen (z. B. Online-Käufe) haben
• Token-Verhalten in ihre Geschäftslogik integrieren möchten

Token-Verwaltung

Mit Stripe Issuing können Sie über die Tokens API 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 das Token anfordert.
• Dem prognostizierten Risiko eines Tokens: Die Risikoeinschätzung des Kartennetzwerks und seine Empfehlung für ein bestimmtes Token.
• Dem mit einem Token verknüpften Gerät: Dies umfasst Smart Watches, Smartphones und andere Geräte, die das Token anfordern und die Risikoeinschätzung dieses Geräts.
• Den Karteninhaberdetails des Tokenausstellers: Gibt für eine zusätzliche Verifizierung an, ob die Karteninhaberdetails, wie der Name und die Adresse 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, 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 mit requested ausgefüllt, bis die zusätzliche Authentifizierung abgeschlossen ist.
• Wir lehnen die Tokenisierungsanfrage ab und verhindern, dass das Token erstellt wird.

Nutzer/innen können außerdem ihre eigenen Verfahren für das Risikomanagement einsetzen –zusätzlich zu denen von Stripe. Die Tokens API lässt keine direkte Ablehnung einer Tokenisierungsanfrage zum Zeitpunkt der Erstellung zu. Nutzer/innen können Token jedoch kurz nach der 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 Vorgang, an dem Karteninhaber/innen, Nutzer/innen, die Anbieter von Digital Wallets, Stripe und das Kartennetzwerk beteiligt sind. Im folgenden Beispiel zeigen wir Ihnen die Schritte, die die Karteninhaber/innen vornehmen müssen, und welche Abläufe Sie beachten müssen, wenn Sie die Tokens API im Rahmen Ihres Programms verwenden.

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.

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.

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 können Sie anzeigen, welche Token mit welcher Karte verknüpft sind.

Händler-Token

Unternehmen können Token auch erstellen, wenn sie eine Zahlungsmethode für die spätere Verwendung bei einem Händler speichern (z. B. wenn Karteninhaber/innen ihre Kartendaten für den Bezahlvorgang bei Amazon hinterlegen). In diesen Fällen initiiert das Unternehmen die Token-Erstellung und die Tokens API verfügt nicht über das Feld wallet_provider field. Um ein Unternehmen und das von ihm stammende Token zu prüfen, sollten Sie die Angaben eines Unternehmens näher betrachten. Genauer gesagt achten Sie auf die verknüpften Autorisierungen, die das Token verwendet haben. Wenn Sie Karten über MasterCard ausstellen, ist es möglich, dass von MasterCard stammende Token einen sichtbaren Namen im Feld network_data.mastercard.token_requestor_name anzeigen.

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-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 und Transaktionen.

Einschränkungen für Netzwerkdaten

Das Issuing-Token-Objekt enthält ein optionales, erweiterbares Feld, und zwar die network_data. Es enthält zusätzliche, sensible Kartennetzwerkdetails zu Ihren Token, welche sich hauptsächlich auf den Erstellungsvorgang des Token beziehen. Da diese Daten äußerst vertraulich sind, benötigen Sie einen eingeschränkten Zugriffsschlüssel mit den erforderlichen Berechtigungen, um auf die Daten zugreifen zu können. Die Daten eines Tokens können Sie auch nur innerhalb der ersten 24 Stunden nach der Token-Erstellung (basierend auf dem Wert von created) anzeigen. Diese Daten sind nur in der API zum Abrufen eines Tokens und in der API zum Aktualisieren eines Token-Status 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-Stunden-Zeitraum hinaus Zugriff auf network_data benötigen, müssen Sie die IP-Adressen begrenzen, von denen aus Ihre eingeschränkten Zugriffsschlüssel verwendet werden.

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 zur manuellen Bereitstellung.

Wenn Sie die Tokens API lieber im Testmodus testen möchten, können Sie eine Testmodus-Autorisierung erstellen und dabei für das Wallet-Feld 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:

{
  "id": "evt_1NxBn3FUQNp5XJkna0rkKU2r",
  "object": "event",
  "api_version": "2024-11-20.acacia",
  "created": 1691100189,
  "data": {
    "object": {
      "id": "intok_1NuMIZFUQNp5XJknPmDzEz0t",
      "object": "issuing.token",
      "card": "ic_1JDmgz2eZvKYlo2CRXlTsXj6",
      "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:

curl https://api.stripe.com/v1/issuing/tokens/intok_1NuMIZFUQNp5XJknPmDzEz0t \
 -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
 -d "expand[]"=network_data \
 -G

Die folgende Antwort wird ausgegeben:

{
  "id": "intok_1NuMIZFUQNp5XJknPmDzEz0t",
  "object": "issuing.token",
  "card": "ic_1JDmgz2eZvKYlo2CRXlTsXj6",
  "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.

{
  "object": {
    "id": "intok_1NuMIZuTQ2hhXJooNmDzEz0t",
    "object": "issuing.token",
    "card": "ic_1JDmgz2eZvKYlo2CRXlTsXj6",
    "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.

curl https://api.stripe.com/v1/issuing/tokens/intok_1NuMIZFUQNp5XJknPmDzEz0t \
 -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
 -d "expand[]"=network_data \
 -G

Die folgende Antwort wird ausgegeben:

{
  "id": "intok_1NuMIZFUQNp5XJknPmDzEz0t",
  "object": "issuing.token",
  "card": "ic_1JDmgz2eZvKYlo2CRXlTsXj6",
  "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.

curl https://api.stripe.com/v1/issuing/tokens/intok_1NuMIZFUQNp5XJknPmDzEz0t \
 -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
 -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.