Speichern Sie Details für spätere Zahlungen mit dem BECS-Lastschriftverfahren in Neuseeland.

So speichern Sie Zahlungsmethodendaten für die künftige Verwendung für Bankkontolastschriften in Neuseeland.

Sie können die Setup Intents API verwenden, um Details zur Zahlungsmethode im Voraus zu erfassen, wobei der endgültige Betrag oder das Zahlungsdatum später festgelegt wird. Dies ist nützlich für Folgendes:

Speichern von Zahlungsmethoden in einer Geldbörse, um künftige Käufe zu optimieren
Einziehen von Zuschlägen nach Erbringung einer Dienstleistung
Neue Testversion eines Abonnements starten

Stripe einrichten
Serverseitig

Zunächst benötigen Sie ein Stripe-Konto. Jetzt registrieren.

Verwenden Sie unsere offiziellen Bibliotheken für den Zugriff auf die Stripe-API über Ihre Anwendung:

Kund/innen erstellen oder abrufen
Serverseitig

Um ein Bankkonto für zukünftige Zahlungen wiederzuverwenden, fügen Sie es einem/einer Kund/in hinzu.

Erstellen Sie ein Customer-Objekt, wenn Ihre Kund/innen ein Konto bei Ihrem Unternehmen anlegen. Wenn Sie die ID des Customer-Objekts mit Ihrer eigenen Darstellung einer Kundin/eines Kunden verknüpfen, können Sie später die gespeicherten Angaben zur Zahlungsmethode abrufen und verwenden. Wenn Ihre Kund/innen noch kein Konto erstellt haben, können Sie jetzt trotzdem ein Customer-Objekt erstellen und es zu einem späteren Zeitpunkt mit Ihrer eigenen internen Darstellung des Kundenkontos verknüpfen.

Legen Sie neue Kund/innen an oder rufen Sie bestehende Kund/innen ab, um sie mit diesen Kartendaten zu verknüpfen. Fügen Sie den folgenden Code auf Ihrem Server ein, um neue Kund/innen zu erstellen.

SetupIntent erstellen
Serverseitig

Ein SetupIntent ist ein Objekt, mit dem Sie eine Zahlungsmethode eines Kunden/einer Kundin für zukünftige Zahlungen einrichten können. Der SetupIntent verfolgt die Schritte dieses Einrichtungsvorgangs.

Erstellen Sie einen SetupIntent auf Ihrem Server. Setzen Sie dabei payment_method_types auf nz_bank_account und geben Sie die id der Kundin/des Kunden an.

Client-Geheimnis abrufen

Im SetupIntent ist ein Client-Geheimnis enthalten, das auf dem Client verwendet wird, um Zahlungen sicher abzuschließen. Es gibt verschiedene Verfahren zum Übergeben des Client-Geheimnisses an den Client.

Rufen Sie das Client-Geheimnis von einem Endpoint auf Ihrem Server ab, indem Sie die Browser-Funktion fetch verwenden. Diese Vorgehensweise funktioniert am besten, wenn es sich bei Ihrer Client-Seite um eine einseitige Anwendung handelt, insbesondere wenn sie mit einem modernen Frontend-Framework wie React erstellt wurde. Erstellen Sie den Server-Endpoint, der das Client-Geheimnis bereitstellt:

Und dann rufen Sie das Client-Geheimnis mit JavaScript auf der Client-Seite ab:

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

Angaben zur Zahlungsmethode und Mandatsbestätigung erfassen
Clientseitig

Stripe Elements einrichten

Fügen Sie das Stripe.js-Skript auf Ihrer Bezahlseite ein, indem sie es zum head Ihrer HTML-Datei hinzufügen. Laden Sie Stripe.js immer direkt von js.stripe.com. Fügen Sie das Skript nicht in ein Bundle ein und hosten Sie selbst keine Kopie davon.

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

Erstellen Sie eine Instanz des Stripe-Objekts und geben Sie dabei Ihren veröffentlichbaren API-Schlüssel als ersten Parameter an. Übergeben Sie zusätzlich das Beta-Flag nz_bank_account_beta_2, um auf die Elements zuzugreifen:

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-03-31.basil;nz_bank_account_beta=v2"
});

Payment Element zu Ihrer Checkout-Seite hinzufügen

Erstellen Sie auf Ihrer Bezahlseite einen leeren DOM-Knoten mit einer eindeutigen ID für das Payment Element, das gerendert werden soll.

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

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

Wenn das obige Formular geladen ist, erstellen Sie eine neue Elements-Gruppe, wobei Sie das Client-Geheimnis aus dem vorherigen Schritt als Konfiguration übergeben. Sie können auch die Erscheinungsbildoption übergeben und so die Elements an das Design Ihrer Website anpassen.

Erstellen Sie dann eine Instanz des Payment Element und verbinden Sie es mit dem entsprechenden DOM-Knoten.

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");

Das Payment Element stellt ein dynamisches Formular dar, mit dem Ihre Kundinnen/Kunden eine Zahlungsmethode auswählen können. Das Formular erfasst automatisch alle erforderlichen Zahlungsdaten für die von ihnen ausgewählte Zahlungsmethode. Bei BECS-Lastschriftzahlungen in Neuseeland sind dies der Kundenname, die E-Mail-Adresse und die Bankkontonummer.

Mandatsbestätigung

Das Payment Element zeigt Ihren Kundinnen/Kunden auch die allgemeinen Geschäftsbedingungen für Zahlungen über das BECS-Lastschriftverfahren in Neuseeland an und fordert ihre Zustimmung zu diesen Bedingungen an. Sie müssen nichts weiter tun.

Wenn Sie das Payment Element nicht verwenden, müssen Sie diese allgemeinen Geschäftsbedingungen Ihren Kundinnen/Kunden gesondert anzeigen und ihr Einverständnis einholen.

Notiz

Indem Sie Ihre Bankkontodaten bereitstellen und diese Zahlung bestätigen, ermächtigen Sie Stripe New Zealand Limited (Autorisierungscode 3143978), Ihr Konto gemäß dieser Einzugsermächtigung mit den an Rocket Rides („wir“, „uns“ oder „Händler“) zu zahlenden Lastschriftbeträgen zu belasten.

Sie stimmen zu, dass sich diese Ermächtigung auf Folgendes bezieht:

Die AGB Ihrer Bank Ihr Konto betreffend, und
the Direct Debit Service Terms and Conditions

Sie bestätigen, dass Sie entweder alleiniger Inhaber/alleinige Inhaberin des oben genannten Kontos sind oder ein autorisierter Zeichnungsberechtigter/eine autorisierte Zeichnungsberechtigte und die Berechtigung haben, als Einzelperson über dieses Bankkonto zu verfügen.

Wir senden Ihnen nach Ihrer Bestätigung dieser Einzugsermächtigung innerhalb von fünf Werktagen eine Bestätigung per E-Mail.

Wenn wir Sie dazu auffordern, müssen Sie Stripe unverzüglich einen Nachweis der Mandate vorlegen.

OptionalErscheinungsbild anpassen
Clientseitig

Angaben zur Zahlungsmethode an Stripe senden
Clientseitig

Verwenden Sie stripe.confirmSetup, um Bankkontodaten zu erfassen, eine PaymentMethod zu erstellen und diese PaymentMethod dem SetupIntent hinzuzufügen.

Bei einigen anderen Zahlungsmethoden wird Ihre Kundin/Ihr Kunde möglicherweise zuerst auf eine Zwischenseite (z. B. eine Bankautorisierungsseite) weitergeleitet, bevor die Weiterleitung zur return_url erfolgt. Geben Sie eine return_url für diese Funktion an, um zu signalisieren, wohin Stripe die Kundinnen/Kunden weiterleiten soll, nachdem die Zahlung abgeschlossen ist.

Da für BECS-Lastschriftzahlungen in Neuseeland keine Weiterleitung erforderlich ist, können Sie die Weiterleitung auch auf if_required festlegen, statt eine return_url anzugeben. Eine return_url müssen Sie nur angeben, wenn Sie später eine weitere Zahlungsmethode hinzufügen, die eine Weiterleitung erfordert.

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.
    }
  });
});

Bei Erfolg gibt Stripe ein SetupIntent-Objekt mit dem Status succeeded zurück. Die angehängte PaymentMethod kann nun für zukünftige Zahlungen verwendet werden.

Benachrichtigungs-E-Mails für Kundinnen/Kunden

Nach erfolgreicher Bestätigung des SetupIntent müssen Sie eine Bestätigung des Mandats und der erfassten Bankkontodaten per E-Mail an Ihre Kundin/Ihren Kunden senden.

Darüber hinaus müssen Sie Ihrer Kundin/Ihrem Kunden für jede eingezogene Zahlung, spätestens am Tag der Abbuchung eine Benachrichtigung mit dem Abbuchungsdatum und -betrag senden.

Stripe übernimmt standardmäßig das Versenden dieser E-Mails für Sie, aber Sie können nutzerdefinierte Benachrichtigungen senden.

Künftige Zahlungen annehmen
Serverseitig

Ist der SetupIntent erfolgreich, wird eine neue PaymentMethod erstellt, die an ein Kundenobjekt angehängt ist. Damit können künftige Zahlungen eingeleitet werden, ohne dass Kundinnen/Kunden ein zweites Mal nach Ihrem Bankkonto gefragt werden.

Integration testen

Testkontonummern

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

Testen Sie Ihr Formular mit der Bankleitzahl 11, dem Filialcode 0000 und einer der folgenden Kontonummern.

Kontonummer	Beschreibung
`0000000010`	Durch die resultierende PaymentMethod bestätigte PaymentIntents wechseln von `processing` zu `succeeded`. Der Mandatsstatus bleibt `active`.
`2222222027`	Durch die resultierende PaymentMethod bestätigte PaymentIntents wechseln von `processing` zu `requires_payment_method` mit dem Fehlercode `insufficient_funds`. Der Mandatsstatus verbleibt `active`.
`8888888000`	Der durch die resultierende PaymentMethod bestätigte PaymentIntent wechselt von `processing` zu `requires_payment_method` mit dem Fehlercode `refer_to_customer`. Der Mandatsstatus bleibt `active`.
`1111111016`	Durch die resultierende PaymentMethod bestätigte PaymentIntents wechseln von `processing` zu `requires_payment_method` mit dem Fehlercode `no_account`. Der Mandatsstatus ändert sich an dieser Stelle in `inactive`.
`5555555059`	Durch die resultierende PaymentMethod bestätigte PaymentIntents wechseln von `processing` zu `requires_payment_method` mit dem Fehlercode `debit_not_authorized`. Der Mandatsstatus ändert sich an dieser Stelle in `inactive`.
`9999999000`	Bestätigte PaymentIntents mit dem daraus resultierenden PaymentMethod wechseln zu `processing` und verbleiben dort. Verwenden Sie für weitere Übergänge eine API-Anfrage wie unten beschrieben.