Bankkonten mit tokenisierten Kontonummern verwalten

Bevor Sie loslegen

1. Basiswissen zu Financial Connections
2. Informieren Sie sich über Webhook-Ereignisse für ein Financial Connections-Konto, um zu erfahren, wie Sie Aktualisierungen zu Änderungen an Financial Connections-Konten erhalten können.

Tokenisierte Kontonummern (TANs) sind temporäre Bankkonto-Anmeldedaten, die von Finanzinstituten anstelle von echten Kontonummern ausgestellt werden. Chase, PNC Bank und die US Bank stellen TANs aus.

TANs verhalten sich ähnlich wie echte Konto- und Routingnummern. Nur wenn ihr Status aktive ist, können Sie sie zum Akzeptieren von ACH-Zahlungen und zum Senden von Auszahlungen verwenden. Im Gegensatz zu echten Kontonummern kann eine TAN deaktiviert werden, was dazu führen kann, dass nachfolgende ACH-Transaktionen auf dem Financial Connections-Konto fehlschlagen.

Dies sind die Unterschiede zwischen echten Kontonummern und TANs:

TANs werden in zwei Szenarien deaktiviert:

• Widerruf: Wenn eine Kundin oder ein Kunde den Zugriff auf seine Kontodaten über das Online-Banking-Portal seines Finanzinstituts (z. B. über das Chase Security Center) aktiv widerruft. Diese Option steht der Kundin oder dem Kunden jederzeit zur Verfügung.
• Ablauf: Die TAN verliert nach einer von der Institution festgelegten Zeitspanne ihre Gültigkeit.

Wenn eine TAN deaktiviert wurde, müssen Ihre Kundinnen und Kunden ihr Bankkonto erneut verknüpfen oder ein anderes Bankkonto verknüpfen, damit sie weiterhin Zahlungen tätigen oder Auszahlungen empfangen können.

So verwalten Sie TANs

Kundinnen und Kunden echte Kontodetails in Ihrer Nutzeroberfläche anzeigen

Wenn Sie Kontokennungen anzeigen, damit Kundinnen und Kunden ein Bankkonto in Ihrer Anwendung erkennen und auswählen können, zeigen Sie das Feld last4 aus dem Objekt Financial Connections-Konto an. Dieses Feld zeigt unabhängig davon, ob das Institut TANs oder echte Kontonummern verwendet, die letzten vier Ziffern der echten Konto Nummer.

Financial Connections-Konten mit TANs und deren Status identifizieren

Verwenden Sie die Financial Connections API, um festzustellen, ob ein Bankkonto eine TAN oder eine echte Kontonummer hat und ob diese TAN für ACH-Transaktionen verwendet werden kann.

Um festzustellen, ob ein Financial Connections-Konto eine TAN hat, sehen Sie im Feld identifier_type der Objekte im Array account_numbers nach. Dieses Feld ist auf tokenized_account_number gesetzt, wenn es sich bei der Kontonummer um eine TAN handelt. Der identifier_type einer echten Kontonummer ist auf account_number gesetzt.

curl https://api.stripe.com/v1/financial_connections/accounts/fca_zbyrdjTrwcYZJZc6WBs6GPid \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Diese Beispielanfrage gibt ein Financial Connections-Konto mit Informationen zu einer TAN zurück.

{
  "id": "fca_zbyrdjTrwcYZJZc6WBs6GPid",
  "object": "financial_connections.account",
  "account_holder": {
    "customer": "cus_NfjonN9919dELB",
    "type": "customer"
  },
  "institution_name": "PNC Bank",
  "status": "active",
  "account_numbers": [
    {
        "identifier_type": 'tokenized_account_number,
        "expected_expiry_date": null,
        "status": "transactable",
        "supported_networks" : ["ach"]
    }
  ]
}

Prüfen Sie in der Anfrage den Status der TAN. Der Status einer TAN kann folgendermaßen lauten:

Es kann vorkommen, dass ein Financial Connections-Konto auch dann einen aktiven Status hat, wenn seine TAN deaktiviert ist, sofern das Konto weiterhin für Bankdatenaktualisierungen nutzbar ist.

Banken können zu TANs zeitbasierte Ablaufregeln hinzufügen. Wenn für TANs von einer Bank ein Ablaufdatum festgelegt wurde, können Sie Folgendes tun:

1. Überprüfen Sie das Feld expected_expiry_date. Es zeigt das Ablaufdatum an.
2. Überwachen Sie das Webhook-Ereignis financial_connections.account.upcoming_account_number_expiry, das Stripe 30 Tage vor Ablauf der TAN sendet.

Deaktivierte TANs verwalten

In diesem Leitfaden wird beschrieben, wie Sie die Deaktivierung von TANs in folgenden Fällen handhaben:

• ACH-Lastschriftzahlungen
• Externe Bankkonten, die für Auszahlungen verwendet werden

ACH-Lastschriftzahlungen

ACH Direct Debit PaymentMethods werden bei Deaktivierung der zum Konto gehörenden TAN unbrauchbar. Bearbeiten Sie TAN-Deaktivierungen in Ihrer ACH Direct Debit-Integration, um fehlgeschlagene Zahlungen zu vermeiden.

Wenn ein Bankkonto mit einer für eine ACH Direct Debit PaymentMethod verwendeten TAN deaktiviert wird, sendet Stripe das Ereignis payment_method.automatically_updated.

Um PaymentMethods mit deaktivierten TANs in Ihrem Webhook-Handler zu identifizieren, überprüfen Sie, ob das Feld payment_method.us_bank_account.status_details.blocked.reason der PaymentMethod auf tokenized_account_number_deactivated gesetzt ist.

Wenn Sie versuchen, eine Zahlung per ACH Direct Debit mit einer deaktivierten TAN zu bestätigen, gibt Stripe eventuell die Fehlermeldung bank_account_unusable zurück. Wenn dieser Fehler auftritt, während Ihre Kundin oder Ihr Kunde in der Sitzung ist, müssen Sie eine neue Zahlungsmethode erfassen. Wenn Stripe erwartet, dass die Transaktion aufgrund einer deaktivierten TAN fehlschlägt, versucht es anders als bei einer ACH-Rückgabe, die Zahlung vor dem Übermitteln der ACH-Transaktion an das Netzwerk zu blockieren. Die Zahlung schlägt also bereits zum Zahlungszeitpunkt fehl und nicht erst 2 bis 3 Tage später. Dadurch vermeiden Sie Gebühren für fehlgeschlagene Zahlungen.

Um sicherzustellen, dass zukünftige Zahlungen erfolgreich sind, erfassen Sie das Bankkonto erneut oder erfassen Sie ein neues Bankkonto Ihrer Kundin oder Ihres Kunden und erstellen Sie eine neue PaymentMethod.

Externe Bankkonten

Externe Bankkonten, die mit Financial Connections verknüpft wurden, werden durch das Deaktivieren einer TAN unbrauchbar. Bearbeiten Sie TAN-Deaktivierungen in Ihrer Auszahlungsintegration, um fehlgeschlagene Auszahlungen zu vermeiden.

Wenn ein Bankkonto mit einer TAN für ein externes Bankkonto deaktiviert wird, sendet Stripe das Webhook-Ereignis account.external_account.updated.

Um festzustellen, ob Stripe das Ereignis account.external_account.updated aufgrund einer deaktivierten TAN gesendet hat, überprüfen Sie in Ihrem Webhook Handler, ob das Feld status für den Status des externen Bankkontos auf "tokenized_account_number_deactivated" festgelegt ist.

Um sicherzustellen, dass zukünftige Auszahlungen erfolgreich sind, erfassen Sie das Bankkonto erneut oder erfassen Sie ein neues Bankkonto Ihrer Kundin oder Ihres Kunden und erstellen Sie ein neues externes Bankkonto.

TAN-Details nach Banken

Die folgenden Institutionen geben TANs zurück, wenn Ihre Kundinnen und Kunden Konten über Financial Connections verknüpfen:

Mehr erfahren

• So testen Sie das TAN-Verhalten