Gérer les comptes bancaires avec des numéros de compte tokenisés

Avant de commencer

1. Comprendre les principes de base de Financial Connections.
2. Lisez la documentation sur les événements webhook des comptes Financial Connections pour comprendre comment recevoir les mises à jour concernant les modifications de ces comptes.

Les numéros de compte tokenisés (TAN) sont des identifiants bancaires temporaires émis par les institutions financières à la place des numéros de compte réels. Aujourd’hui, Chase et PNC Bank émettent des TAN, et US Bank commencera à en émettre le 30 novembre 2025.

Les TAN se comportent de la même manière que les numéros de compte et de routage réels, et vous pouvez les utiliser pour accepter des paiements ACH et envoyer des paiements uniquement lorsque leur état est actif. Contrairement aux numéros de compte réels, un TAN peut être désactivé, ce qui peut entraîner l’échec des transactions ACH ultérieures sur le compte Financial Connections.

Voici les différences entre les numéros de compte réels et les TAN :

Les TAN sont désactivés dans deux cas de figure :

• Révocation : lorsqu’un client révoque activement l’accès à ses données de compte via le portail bancaire en ligne de son institution financière (par exemple, via le Chase Security Center). Cette option est disponible pour le client à tout moment.
• Expiration : le TAN expire après une certaine période de temps fixée par l’établissement.

Une fois le TAN désactivé, votre client doit associer à nouveau son compte bancaire ou associer un autre compte bancaire afin de pouvoir continuer à effectuer des paiements ou à recevoir des versements.

Comment gérer les TAN

Affichez les informations du compte réel à votre client dans votre interface utilisateur.

Si vous affichez des identificateurs de compte pour aider les clients à reconnaître et à sélectionner un compte bancaire dans votre application, affichez le champ last4 de l’objet compte Financial Connections. Ce champ affiche les quatre derniers chiffres du numéro de compte réel, que l’établissement utilise des numéros TAN ou des numéros de compte réels.

Identifier les comptes Financial Connections avec des TAN et leur état

Utilisez l’API Financial Connections pour déterminer si un compte bancaire dispose d’un numéro TAN ou d’un numéro de compte réel, et si ce numéro TAN peut être utilisé pour les transactions ACH.

Pour déterminer si un compte Financial Connections a un TAN, référencez le champ identifier_type sur les objets de la fonction account_numbers, qui sera défini sur "tokenized_account_number" si le numéro de compte est un TAN. Le paramètre identifier_type d’un numéro de compte réel est défini sur "account_number".

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

Cette exemple de requête renvoie un compte Financial Connections contenant des informations sur un TAN.

{
  "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"]
    }
  ]
}

Dans la requête, cochez l’icôneétat du TAN. L’état d’un TAN peut être :

Il est possible qu’un compte Financial Connections ait un status actif, même si son TAN est désactivé, si le compte est toujours utilisable pour les mises à jour des données bancaires.

Les banques peuvent ajouter des règles d’expiration basées sur le temps aux TAN. Si les TAN sont configurés pour expirer par une banque, vous pouvez :

1. Reportez-vous au champ expected_expiry_date. Il affiche la date d’expiration.
2. Écoutez l’événement webhook financial_connections.account.upcoming_account_number_expiry que Stripe envoie 30 jours avant l’expiration du TAN.

Gérer les TAN désactivés

Ce guide décrit comment gérer la désactivation des TAN pour :

• Paiements par ACH Direct Debit
• Comptes bancaires externes utilisés pour les virements

Paiements par ACH Direct Debit

ACH Direct Debit PaymentMethods devient inutilisable lorsque le TAN associé au compte est désactivé. Gérez les désactivations TAN dans votre intégration ACH Direct Debits pour éviter les échecs de paiement.

Lorsqu’un compte bancaire avec un TAN utilisé pour un PaymentMethod ACH Direct Debit est désactivé, Stripe envoie un événement payment_method.automatically_updated.

Pour identifier les PaymentMethods dont les TAN sont désactivés dans votre gestionnaire de webhook, vérifiez si la valeur du payment_method.us_bank_account.status_details.blocked.reason est définie sur tokenized_account_number_deactivated.

Si vous tentez de confirmer un paiement par prélèvement automatique ACH avec un TAN désactivé, Stripe peut renvoyer une erreur bank_account_unusable. Si cette erreur se produit pendant la session du client, vous devez collecter un nouveau moyen de paiement. Contrairement à un retour ACH classique, Stripe bloque le paiement avant que la transaction ACH ne soit soumise au réseau si nous prévoyons que la transaction échouera à cause d’un TAN désactivé. Cela signifie que le paiement échoue au moment de sa soumission, plutôt que 2 à 3 jours plus tard, ce qui vous aide à éviter des frais de paiement échoué.

Pour garantir le bon déroulement des paiements futurs, récupérez les coordonnées bancaires de votre client ou demandez-lui de vous en fournir de nouvelles, puis créez un nouveau moyen de paiement.

Comptes bancaires externes

Les comptes bancaires externes qui ont été associés à Financial Connections deviennent inutilisables lorsqu’un TAN est désactivé. Gérez les désactivations de TAN dans votre intégration de paiements afin d’éviter tout échec de paiement.

Lorsqu’un compte bancaire avec un TAN est désactivé pour un compte bancaire externe, Stripe envoie un événement webhook account.external_account.updated.

Pour déterminer si Stripe a envoyé l’événement account.external_account.updateden raison d’un TAN désactivé, vérifiez que le status est défini surtokenized_account_number_deactivated, dans votre gestionnaire de webhook.

Pour garantir le bon déroulement des futurs paiements, demandez à votre client de vous communiquer à nouveau ses coordonnées bancaires ou celles d’un nouveau compte bancaire, puis créez un nouveau compte bancaire externe.

Détails TAN par banque

Les institutions suivantes renvoient les TAN lorsque vos clients lient des comptes via Financial Connections :

En savoir plus

• Découvrez comment tester le comportement des TAN