Prélèvement automatique ACH avec l'API ChargesObsolète

Ancien guide relatif à l'acceptation des paiements ACH avec notre ancienne API Charges.

Ancien

Le contenu ci-dessous décrit une ancienne méthode pour la collecte des paiements ACH.

Si vous créez une nouvelle intégration, utilisez plutôt l’une de nos méthodes actuelles pour accepter les paiements ACH.

Si vous disposez d’une intégration existante qui accepte les paiements ACH en utilisant l’API Charges, nous vous recommandons sa migration vers l’API Payment Intents. L’API Payment Intents comprend une vérification instantanée intégrée.

Stripe vous permet d’accepter les paiements ACH quasiment comme des paiements par carte de crédit. Il suffit de fournir un compte bancaire vérifié comme argument source pour une demande de paiement. Cependant, l’acceptation des comptes bancaires nécessite un flux de vérification initial légèrement différent de celui employé pour accepter les cartes de crédit :

Les comptes bancaires doivent d’abord être vérifiés.
L’utilisation des comptes bancaires doit être autorisée par les clients.

Une fois ces deux étapes franchies, le client peut utiliser son compte bancaire comme tout autre moyen de paiement, y compris pour les paiements récurrents et les applications Connect. Les conditions d’utilisation d’un compte bancaire et d’une carte de crédit présentent deux différences essentielles :

La confirmation du succès ou de l’échec des paiements ACH peut nécessiter jusqu’à cinq jours ouvrables. Il faut donc prévoir jusqu’à sept jours ouvrables pour qu’ils soient reportés sur votre solde Stripe disponible.
Vous ne pouvez accepter que des fonds en USD et uniquement à partir de comptes bancaires américains. Par ailleurs, votre compte doit disposer d’un compte bancaire américain/en USD pour accepter les paiements ACH.

Collecte et vérification des comptes bancaires

Avant de pouvoir créer un paiement ACH, vous devez d’abord collecter et vérifier le compte bancaire et le numéro de routage de votre client. Pour identifier correctement le compte bancaire, vous devez également collecter le nom de la personne ou de l’entreprise qui en est titulaire, et savoir s’il appartient à un particulier ou à une société. Stripe propose deux méthodes à cet effet : l’encaissement et la vérification instantanés avec Plaid ou l’encaissement à l’aide de Stripe.js avec vérification différée à l’aide de micro-versements. Selon la taille de votre entreprise, vous pouvez encourir des frais supplémentaires lorsque vous utilisez Plaid. Tenez-en compte dans votre décision.

Comme seuls les comptes bancaires vérifiés et dont l’utilisation est autorisée par le client peuvent être débités, il est recommandé de conserver le compte bancaire dans un objet Customer de Stripe pour pouvoir le réutiliser.

Utilisation de Plaid

Plaid offre le moyen le plus rapide de collecter et de vérifier les informations bancaires de votre clientèle. Grâce à l’intégration Stripe + Plaid, vous disposez instantanément d’un compte bancaire vérifié qui vous permet de facturer immédiatement. Il suffit pour cela de suivre le lien vers Plaid afin de recevoir un token de compte bancaire Stripe directement à partir de Plaid.

Étape 1 : Créer votre compte Plaid

Si vous n’avez pas de compte Plaid, créez-en un. Votre compte est automatiquement activé pour pouvoir accéder à l’intégration. Pour vérifier que votre compte Plaid est bien activé pour intégrer Stripe, accédez à la section Intégrations du Dashboard du compte. Vérifiez que votre compte Stripe y est bien connecté.

Étape 2 : Récupérer un token Link

Un link_token est un token à usage unique qui sert à initialiser Plaid Link. Vous pouvez créer un link_token et le configurer pour votre propre flux Link en appelant l’endpoint Créer un token Link depuis votre serveur.

Étape 3 : Effectuer l’intégration avec Plaid Link

L’intégration avec Link ne nécessite que quelques lignes de JavaScript côté client et d’un petit gestionnaire côté serveur pour échanger le public_token de Link contre un access_token de Plaid et un token de compte bancaire de Stripe.

<button id="link-button">Link Account</button>

<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
<script type="text/javascript">
(async function() {

  const configs = {
    // Pass the link_token generated in step 2.
    token: '{{LINK_TOKEN}}',
    onLoad: function() {
      // The Link module finished loading.
    },
    onSuccess: function(public_token, metadata) {
      // The onSuccess function is called when the user has
      // successfully authenticated and selected an account to
      // use.
      //
      // When called, you will send the public_token
      // and the selected account ID, metadata.accounts,
      // to your backend app server.
      //
      // sendDataToBackendServer({
      //   public_token: public_token,
      //   account_id: metadata.accounts[0].id
      // });
      console.log('Public Token: ' + public_token);
      switch (metadata.accounts.length) {
        case 0:
          // Select Account is disabled: https://dashboard.plaid.com/link/account-select
          break;
        case 1:
          console.log('Customer-selected account ID: ' + metadata.accounts[0].id);
          break;
        default:
          // Multiple Accounts is enabled: https://dashboard.plaid.com/link/account-select
      }
    },
    onExit: async function(err, metadata) {
      // The user exited the Link flow.
      if (err != null) {
          // The user encountered a Plaid API error
          // prior to exiting.
      }
      // metadata contains information about the institution
      // that the user selected and the most recent
      // API request IDs.
      // Storing this information can be helpful for support.
    },
  };

  var linkHandler = Plaid.create(configs);

  document.getElementById('link-button').onclick = function() {
    linkHandler.open();
  };
})();
</script>

Étape 4 : Écrire un gestionnaire côté serveur

Le module Link gère l’ensemble du flux d’inscription de manière sécurisée et rapide, mais ne récupère pas réellement les données de compte d’un utilisateur. En effet, le module Link retourne un public_token et une table accounts, qui est une propriété de l’objet metadata, et une partie du rappel onSuccess.

Le tableau accounts contient des informations sur les comptes bancaires associés aux identifiants saisis par l’utilisateur. Il peut inclure plusieurs comptes si l’utilisateur possède plusieurs comptes bancaires dans l’établissement. Afin d’éviter toute confusion quant au compte que l’utilisateur souhaite employer avec Stripe, définissez Sélectionner un compte sur « Activé pour un compte » dans le Dashboard du développeur de Plaid. Lorsque ce paramètre est sélectionné, le tableau des comptes contiendra toujours un seul élément.

Lorsque votre serveur possède un public_token et un account_id, vous devez effectuer deux appels au serveur Plaid pour obtenir le token du compte bancaire Stripe ainsi que le access_token de Plaid à utiliser pour les autres requêtes d’API de Plaid.

La réponse contient un ID de token de compte bancaire Stripe vérifié. Vous pouvez associer ce token à un objet Customer de Stripe, ou créer un paiement directement sur celui-ci.

{
  "stripe_bank_account_token": "btok_d61mOosg2dsZwDm5gmG8",
  "request_id": "[Unique request ID]"
}

Étape 5 : Se préparer au mode production

Plaid emploie différents hôtes d’API pour gérer les requêtes de test et de production. La requête ci-dessus utilise l’environnement de test de Plaid, qui contient des données fictives. L’environnement de développement de Plaid vous permet de réaliser des essais avec des utilisateurs réels. Il prend en charge jusqu’à 100 objets, qui ne vous sont pas facturés. Au moment de passer en production, utilisez l’environnement de production de Plaid.

Collecte et vérification manuelles des comptes bancaires

Plaid prend en charge la vérification instantanée pour la plupart des banques les plus connues. Toutefois, si ce n’est pas le cas pour la banque de votre client ou si vous ne souhaitez pas réaliser l’intégration avec Plaid, collectez et vérifiez les données bancaires du client uniquement à l’aide de Stripe.

Tout d’abord, utilisez Stripe.js pour collecter de manière sécurisée les informations relatives au compte bancaire de votre client et recevez en retour un token représentatif. Lorsque vous disposez de ce token, associez-le à un client Stripe sur votre compte. Pour respecter les règles de Nacha, assurez-vous de fournir un nom de titulaire de compte valide pour le client.

Il est nécessaire de vérifier les comptes bancaires des clients. Lorsqu’il est utilisé sans Plaid, Stripe effectue automatiquement deux petits versements à cette fin. Ces versements apparaissent sur le relevé en ligne du client au bout d’un à deux jours ouvrables. Ce relevé comporte une description indiquant ACCTVERIFY. Votre client doit vous transmettre ces montants.

Lorsque vous acceptez ces montants, sachez que la limite est de trois tentatives de vérification infructueuses. Si cette limite est dépassée, il nous est impossible de vérifier le compte bancaire. Un message indiquant clairement en quoi consistent ces micro-versements et comment vous les utilisez peut aider vos clients à éviter des problèmes de vérification. Dès que vous disposez de ces montants, vous pouvez vérifier le compte bancaire.

Une fois le compte bancaire vérifié, vous pouvez y imputer des paiements.

Autorisation de paiement

Avant de créer un paiement ACH, demandez à votre client de vous autoriser à effectuer des prélèvements sur son compte. Cette démarche assure la conformité avec le réseau ACH et vous protège contre les litiges, les frais supplémentaires et les paiements annulés. Consultez la page d’assistance pour en savoir plus sur les conditions d’autorisation.

Création d’un paiement ACH

Pour créer un paiement sur un compte bancaire vérifié, utilisez l’objet Customer sauvegardé tout comme vous le feriez avec une carte bancaire.

Toute tentative de prélèvement d’un compte bancaire non vérifié entraîne une erreur assortie du message « La création d’un paiement ACH nécessite la vérification du compte bancaire du client ».

Si le client dispose de plusieurs sources sauvegardées (de tout type), indiquez le compte bancaire à utiliser en transmettant son ID en tant que paramètre source.

Test de cette intégration

Vous pouvez simuler des paiements ACH qui ont réussi ou échoué en utilisant les numéros de routage et de compte bancaires suivants :

Numéro de routage : 110000000
Numéro de compte :
- 000123456789 (succès de l’opération)
- 000111111116 (échec de l’opération)
- 000111111113(compte fermé)
- 000222222227 (NSF/fonds insuffisants)
- 000333333335 (débit non autorisé)
- 000444444440 (devise non valide)

Pour simuler les réussites et les échecs de la vérification des comptes bancaires, utilisez ces montants représentatifs :

[32, 45] (succès)
[toute autre combinaison de montants] (échec)

Flux de vérification de paiements ACH

La confirmation du succès ou de l’échec d’un paiement ACH peut demander jusqu’à cinq jours ouvrables.

Lors de leur création, les paiements ACH ont comme statut initial pending.
Une opération sur solde en attente est immédiatement créée avec le montant du paiement, déduction faite de nos frais.
Les paiements créés à partir de 22 h UTC sont actuellement traités le jour ouvrable suivant.
Au cours des quatre jours ouvrables suivants, le paiement prend l’état succeeded ou failed en fonction de la banque du client.
Les paiements ACH correctement exécutés sont reportés dans votre solde Stripe disponible après sept jours ouvrables, date à laquelle vous pouvez transférer automatiquement ou manuellement les fonds sur votre compte bancaire.
L’échec d’un paiement ACH entraîne l’annulation de l’opération sur solde en attente créée.
Le paiement apparaîtra sur le relevé bancaire de votre client un à deux jours après sa création. (Votre client sera informé de l’aboutissement du paiement avant que la banque ne le notifie à Stripe.)

Un paiement peut échouer pour différentes raisons : des fonds insuffisants, un numéro de compte erroné ou encore la décision du client de désactiver les prélèvements sur son compte bancaire.

Il peut parfois arriver que Stripe reçoive un échec de paiement ACH de la banque alors que le paiement est déjà passé à l’état succeeded. Quand cela se produit, Stripe créée un litige dont le paramètre reason (motif) peut être :

insufficient_funds
incorrect_account_details
bank_cannot_process

Dans ce cas de figure, Stripe prélève des frais d’échec de paiement.

Gestion des litiges dans cette intégration

Un litige sur un paiement ACH ne ressemble en rien à un litige portant sur un paiement par carte bancaire. Si la banque d’un client accepte de restituer les fonds correspondant à un paiement contesté, nous débitons immédiatement les fonds de votre compte Stripe. Contrairement à ce qu’il est possible de faire dans le cadre d’un litige sur un paiement par carte bancaire, vous ne pouvez pas contester une annulation ACH. Pour résoudre le problème, vous devez contacter votre client.

Le client dispose généralement de 60 jours calendaires pour contester un paiement auprès de sa banque si le prélèvement ACH a été effectué sur un compte personnel, ou de 2 jours ouvrables s’il s’agit d’un compte commercial. Les paiements par prélèvement peuvent parfois être contestés après ces délais.

Risque de versements en double en cas de remboursements et de litiges ACH

Si vous remboursez votre client de manière proactive alors que sa banque a parallèlement lancé une procédure de litige, il est possible que votre client reçoive deux virements pour la même transaction.

Lorsque vous effectuez un remboursement au titre d’un paiement ACH, vous devez en informer immédiatement votre client et lui préciser qu’il devra patienter entre deux et cinq jours ouvrables pour voir figurer les fonds sur son compte bancaire.

Remboursements

Vous pouvez rembourser les paiements ACH jusqu’à 90 jours à compter de la date du paiement initial à l’aide de l’endpoint de remboursement. Les délais et les risques associés à ces remboursements ACH diffèrent de ceux des remboursements par carte. Stripe ne vous informe pas des remboursements ACH réussis, mais envoie l’événement refund.failed si le traitement d’un remboursement ACH n’a pas été effectué. En cas d’échec, vous devez restituer les fonds à votre client en dehors de Stripe. Cette situation ne survient généralement que lorsqu’un blocage du compte intervient entre le paiement initial et la demande de remboursement.

Notifications webhook spécifiques à ACH

Avec ACH, vous recevrez la plupart des notifications webhook classiques relatives à des paiements, avec quelques différences notables :

Après avoir créé le paiement, vous recevez une notification charge.pending. Cependant, il faudra prévoir jusqu’à cinq jours ouvrables avant de recevoir la notification charge.succeeded ou charge.failed.
La notification charge.succeeded vous est envoyée une fois que le paiement est passé à l’état succeeded et que les fonds sont disponibles sur votre solde.
Une notification charge.failed est transmise en cas d’échec du transfert ACH, quelle qu’en soit la raison. Les attributs failure_code et failure_message correspondant au paiement sont définis et, à ce stade, les fonds sont retirés de votre solde Stripe en attente.
Une notification customer.source.updated est envoyée lorsque le compte bancaire a été dûment vérifié. L’attribut status du compte bancaire prend alors la valeur verified.
Si le compte bancaire n’a pas pu être vérifié à cause de l’échec de l’un des deux petits versements, la notification customer.source.updated vous est envoyée. L’attribut status du compte bancaire prend alors la valeur verification_failed.

Assistance Connect

Grâce à Connect, votre plateforme peut gagner de l’argent tout en traitant les paiements. Vous pouvez :

Créer le client sur le compte connecté, puis créer un paiement direct
Créer le client sur le compte de la plateforme, puis créer un paiement indirect en utilisant le paramètre transfer_data (comme dans le code ci-dessous)

Conditions d’utilisation du service

L’utilisation de l’API en mode production est régie par le Contrat d’utilisation du service de Stripe. Si vous avez des questions concernant ce contrat, veuillez nous en faire part.