Enregistrer les informations pour les paiements futurs par prélèvement automatique BECS néo-zélandais

Comment enregistrer les informations du moyen de paiement pour les futurs paiements par prélèvement sur un compte bancaire néo-zélandais.

Vous pouvez utiliser l’API Setup Intents pour collecter à l’avance les données d’un moyen de paiement, en vue d’un paiement dont la date et le montant seront déterminés ultérieurement. Cette possibilité est utile pour :

Enregistrement des moyens de paiement dans un portefeuille pour faciliter les achats ultérieurs
Encaissement de suppléments de facturation après la prestation d’un service
Mise en place d’une période d’essai gratuite pour un abonnement

Configurer Stripe
Côté serveur

Pour commencer, vous devez créer un compte Stripe.

Utilisez nos bibliothèques officielles pour accéder à l’API Stripe à partir de votre application :

Créer ou récupérer un objet Customer
Côté serveur

Pour réutiliser un compte bancaire à l’occasion de paiements ultérieurs, associez-le à un objet Customer.

Lorsque votre client crée un compte auprès de votre entreprise, créez-lui un objet Customer. En associant l’ID de l’objet Customer à votre propre représentation interne d’un client, vous pourrez récupérer et utiliser ultérieurement les informations du moyen de paiement sauvegardées. Si votre client n’a pas encore créé de compte, vous pouvez toujours créer un objet Customer dès maintenant et l’associer ultérieurement à votre représentation interne du compte de ce client.

Créez ou récupérez un objet Customer afin de l’associer à ces informations de paiement. Ajoutez le code suivant à votre serveur pour créer un objet Customer.

Créer un SetupIntent
Côté serveur

Un SetupIntent est un objet qui représente votre intention de configurer le moyen de paiement d’un client en vue de futurs paiements. Le SetupIntent suit les étapes de ce processus de configuration.

Créez un SetupIntent sur votre serveur en définissant payment_method_types sur nz_bank_account et indiquez l’id du client.

Récupérer la clé secrète du client

Le SetupIntent contient une clé secrète à utiliser côté client pour finaliser le processus de paiement en toute sécurité. Vous pouvez adopter différentes approches pour transmettre cette clé secrète côté client.

Récupérez la clé secrète du client à partir d’un endpoint sur votre serveur, à l’aide de la fonction fetch du navigateur. Cette approche est recommandée si votre côté client est une application d’une seule page, en particulier si elle repose sur un framework front-end moderne tel que React. Créez l’endpoint de serveur qui gère la clé secrète du client :

Récupérez ensuite la clé secrète du client à l’aide JavaScript côté client :

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

Collecter les informations du moyen de paiement et obtenir un accusé de réception du mandat
Côté client

Configurer Stripe Elements

Incluez le script Stripe.js sur votre page de paiement en l’ajoutant au head de votre fichier HTML. Chargez toujours Stripe.js directement à partir de js.stripe.com. Vous ne devez pas inclure le script dans un lot ni en héberger de copie.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/v3/"></script>
</head>

Créez une instance de l’objet Stripe en indiquant comme premier paramètre votre clé API publiable et en transmettant l’indicateur bêta nz_bank_account_beta_2 pour accéder aux Elements :

checkout.js
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  betas: ['nz_bank_account_beta_2'],
  apiVersion: "2025-05-28.basil;nz_bank_account_beta=v2"
});

Ajouter le composant Payment Element à votre page de paiement

Sur votre page de paiement, créez un nœud DOM vide avec un ID unique pour y afficher le Payment Element.

checkout.html
<form id="payment-form">
  <h3>Payment</h3>
  <div id="payment-element"></div>

  <button id="submit">Submit</button>
</form>

Une fois que le formulaire ci-dessus a été chargé, créez un nouveau groupe Elements et transmettez la clé secrète du client de l’étape précédente dans le cadre de la configuration. Vous pouvez également transmettre l’option appearance pour personnaliser les Elements et les adapter au design de votre site.

Ensuite, créez une instance du composant Payment Element et intégrez-la au nœud DOM correspondant :

checkout.js
// Customize the appearance of Elements using the Appearance API.
const appearance = { /* ... */ };

// Create an elements group from the Stripe instance, passing the clientSecret (obtained in step 2) and appearance (optional).
const elements = stripe.elements({clientSecret, appearance});

// Create Payment Element instance.
const paymentElement = elements.create("payment");

// Mount the Payment Element to its corresponding DOM node.
paymentElement.mount("#payment-element");

Le composant Payment Element affiche un formulaire dynamique qui permet à votre client de choisir un type de moyen de paiement. Le formulaire recueillera automatiquement toutes les informations de paiement nécessaires pour le type de moyen de paiement sélectionné par le client. Pour les paiements par prélèvement automatique BECS en Nouvelle-Zélande, ces informations comprennent le nom du client, son adresse e-mail et son numéro de compte bancaire.

Confirmation du mandat

Le composant Payment Element affiche également les conditions générales du service de prélèvement automatique BECS néo-zélandais à votre client et recueille son accord avec ces conditions. Vous n’avez rien d’autre à faire.

Si vous n’utilisez pas le composant Payment Element, vous devez afficher séparément ces conditions générales à votre client et confirmer son acceptation.

Remarque

En fournissant vos coordonnées bancaires et en confirmant ce paiement, vous autorisez Stripe New Zealand Limited (code d’autorisation 3143978), à débiter votre compte bancaire des montants des prélèvements automatiques de Rocket Rides (« nous », « notre », « nos » ou « le Marchand »), conformément à la présente autorisation.

Vous acceptez que la présente autorisation soit soumise aux :

Conditions générales de votre banque qui se rapportent à votre compte, et
the Direct Debit Service Terms and Conditions

Vous confirmez être l’unique titulaire du compte susmentionné ou être un signataire autorisé à gérer ce compte bancaire individuellement.

Nous vous enverrons une confirmation par e-mail sous 5 jours ouvrables une fois que vous aurez confirmé cette autorisation de prélèvement automatique.

Si nous vous le demandons, vous devez fournir rapidement à Stripe un enregistrement des mandats.

FacultatifPersonnaliser l'apparence
Côté client

Envoyer les informations du moyen de paiement à Stripe
Côté client

Utilisez stripe.confirmSetup pour recueillir les coordonnées du compte bancaire, créer un PaymentMethod et rattacher ce PaymentMethod au SetupIntent.

Pour certains autres types de moyens de paiement, votre client peut d’abord être redirigé vers un site intermédiaire, comme une page d’autorisation bancaire, avant d’être redirigé vers le return_url. Fournissez un return_url à cette fonction pour indiquer où Stripe doit rediriger le client après s’être acquitté du paiement.

Les prélèvements automatiques BECS néo-zélandais ne nécessitent pas de redirection, vous pouvez donc également définir redirect sur if_required au lieu de fournir un return_url. Un return_url ne sera nécessaire que si vous ajoutez plus tard un autre moyen de paiement avec redirection.

script.js
confirmationForm.addEventListener('submit', (ev) => {
  ev.preventDefault();
  stripe.confirmSetup({elements, redirect: "if_required"})
  .then(({setupIntent, error}) => {
    if (error) {
      console.error(error.message);
      // The confirmation failed for some reason.
    } else if (setupIntent.status === "requires_payment_method") {
      // Confirmation failed. Attempt again with a different payment method.
    } else if (setupIntent.status === "succeeded") {
      // Confirmation succeeded! The account is now saved.
      // Display a message to the customer.
    }
  });
});

Sauf échec de l’opération, Stripe renvoie un objet PaymentIntent présentant l’état succeeded. Le PaymentMethod associé est désormais prêt à être utilisé pour les futurs paiements.

E-mails de notification des clients

Vous devez envoyer un e-mail de confirmation du mandat et les coordonnées bancaires recueillies à votre client après avoir confirmé le SetupIntent.

En outre, pour chaque paiement encaissé, vous devez envoyer à votre client une notification par e-mail de la date et du montant du débit au plus tard le jour de celui-ci.

Stripe gère l’envoi de ces e-mails pour vous par défaut, mais vous pouvez choisir d’envoyer des notifications personnalisées.

Acceptation des futurs paiements
Côté serveur

Lorsque le SetupIntent aboutit, il crée un nouvel objet PaymentMethod associé à un objet Customer. Vous pouvez utiliser ces objets pour initier des paiements ultérieurs sans avoir à redemander ses informations de paiement au client.

Tester votre intégration

Numéros de comptes de test

In a sandbox, you can use the following parameters to simulate specific errors.

Testez votre formulaire en utilisant le code de banque 11, le code d’agence 0000 et l’un des numéros de compte suivants.

Numéro de compte	Description
`0000000010`	Les PaymentIntents confirmés avec le PaymentMethod résultant passent de `processing` à `succeeded`. L’état du mandat reste `active`.
`2222222027`	Les PaymentIntents confirmés avec le PaymentMethod résultant passent de `processing` à `requires_payment_method` avec un code d’échec `insufficient_funds`. L’état du mandat reste `active`.
`8888888000`	Les PaymentIntents confirmés avec le PaymentMethod résultant passent de `processing` à `requires_payment_method` avec un code d’échec `refer_to_customer`. L’état du mandat reste `active`.
`1111111016`	Les PaymentIntents confirmés avec le PaymentMethod résultant passent de `processing` à `requires_payment_method` avec un code d’échec `no_account`. L’état du mandat devient `inactive`.
`5555555059`	Les PaymentIntents confirmés avec le PaymentMethod résultant passent de `processing` à `requires_payment_method` avec un code d’échec `debit_not_authorized`. L’état du mandat devient `inactive`.
`9999999000`	Les PaymentIntents confirmés avec le PaymentMethod résultant passent à `processing` et y restent. Pour poursuivre la transition, utilisez une requête API comme décrit ci-dessous.