Accept a New Zealand BECS Direct Debit payment

Build a custom payment form to accept payments with New Zealand bank account debits.

Accepting New Zealand BECS Direct Debit payments on your website consists of creating an object to track a payment, collecting payment method information and mandate acknowledgement, and submitting the payment to Stripe for processing.

Stripe uses a payment object, the Payment Intent, to track and handle all the states of the payment until the payment completes.

Configura Stripe
Lado del servidor

Primero, necesitas una cuenta de Stripe. Regístrate ahora.

Usa nuestras bibliotecas oficiales para acceder a la API de Stripe desde tu aplicación:

Crear o recuperar un cliente
Lado del servidor

To reuse a bank account for future payments, attach it to a Customer.

Create a Customer object when your customer creates an account with your business. Associating the ID of the Customer object with your own internal representation of a customer enables you to retrieve and use the stored payment method details later.

Create a new Customer or retrieve an existing Customer to associate with this payment. Include the following code on your server to create a new Customer.

Crear un PaymentIntent
Lado del servidor

A PaymentIntent is an object that represents your intent to collect payment from a customer and tracks the lifecycle of the payment process through each stage.

First, create a PaymentIntent on your server and specify the amount to collect and the nzd currency. If you already have an integration using the Payment Intents API, add nz_bank_account to the list of payment method types for your PaymentIntent. Specify the id of the Customer.

Also provide the setup_future_usage parameter with the value off_session to save the payment method to the Customer for future use.

Included in the returned PaymentIntent is a client secret, which the client side uses to securely complete the payment process instead of passing the entire PaymentIntent object. You can use different approaches to pass the client secret to the client side.

Recupera el secreto del cliente

El PaymentIntent incluye un secreto de cliente que el lado del cliente utiliza para completar el proceso de pago de forma segura. Puedes usar diferentes métodos para pasar el secreto del cliente al lado del cliente.

Recupera el secreto de cliente de un punto de conexión en tu servidor, utilizando la función fetch del navegador. Este enfoque es mejor si tu lado del cliente es una aplicación de una sola página, en particular una construida con un marco de front-end moderno como React. Crea el punto de conexión del servidor que se utiliza para el secreto de cliente:

Y luego busca el secreto del cliente con JavaScript del lado del cliente:

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

Collect payment method details and mandate acknowledgement
Lado del cliente

Set up Stripe Elements

Include the Stripe.js script on your checkout page by adding it to the head of your HTML file. Always load Stripe.js directly from js.stripe.com. Don’t include the script in a bundle or host a copy of it yourself.

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

Create an instance of the Stripe object by providing your publishable API key:

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

Add the Payment Element to your checkout page

On your checkout page, create an empty DOM node with a unique ID for the Payment Element to render into.

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

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

When the form above finishes loading, create a new Elements group, passing the client secret from the previous step as configuration. You can also pass in the appearance option, customizing the Elements to match the design of your site.

Then, create an instance of the Payment Element and mount it to its corresponding DOM node:

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

The Payment Element renders a dynamic form that allows your customer to pick a payment method type. The form automatically collects all necessary payments details for the payment method type that they select. For New Zealand BECS Diret Debit payments, that includes the customer’s name, email address, and bank account number.

Mandate acknowledgement

The Payment Element also displays the New Zealand BECS Direct Debit Service Terms and Conditions to your customer and collects their agreement with those terms. You’re not required to do anything else.

If you don’t use the Payment Element, you must separately display these terms and conditions to your customer and confirm their acceptance.

Nota

By providing your bank account details and confirming this payment, you authorise Stripe New Zealand Limited (authorisation code 3143978), to debit your account with the amounts of direct debits payable to Rocket Rides (“we”, “us” or “Merchant”) in accordance with this authority.

You agree that this authority is subject to:

your bank’s terms and conditions that relate to your account, and
the Direct Debit Service Terms and Conditions

You certify that you are either the sole account holder on the bank account listed above or that you are an authorised signatory on, and have authority to operate, this bank account severally.

We will send you an email confirmation no later than 5 business days after your confirmation of this Direct Debit Authority.

If we request you to do so, you must promptly provide Stripe with a record of the mandates.

OpcionalPersonaliza el diseño
Lado del cliente

Ahora que has añadido estos Elements a tu página, puedes personalizar el aspecto para que se ajuste al diseño del resto de tu página:

Read about the Appearance API

Envía el pago a Stripe
Lado del cliente

Use stripe.confirmPayment to collect bank account details, create a PaymentMethod, and attach that PaymentMethod to the PaymentIntent.

For some other payment method types, your customer might be first redirected to an intermediate site, like a bank authorization page, before being redirected to the return_url. Provide a return_url to this function to indicate where Stripe should redirect the customer after they complete the payment.

Since New Zealand BECS Direct Debits don’t require a redirect, you can also set redirect to if_required in place of providing a return_url. A return_url will only be required if you add another redirect-based payment method later.

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

If successful, Stripe returns a PaymentIntent object with the status processing. See the next step for information on how to confirm success of the PaymentIntent.

Customer notification emails

You must send an email confirmation of the mandate and collected bank account details to your customer after successfully confirming the PaymentIntent.

In addition, for every payment collected, including this one, you must send your customer an email notification of the debit date and amount at latest on the day the debit takes place.

Stripe handles sending these emails for you by default, but you can choose to send custom notifications.

Confirmar el PaymentIntent realizado correctamente
Lado del servidor

New Zealand BECS Direct Debit are a delayed notification payment method. In addition, they require notifying your customer of any debit from their bank account, at latest, on the date of the debit.

Notification of success or failure of the PaymentIntent comes within 3 business days thereafter. When the payment succeeds, the PaymentIntent status changes from processing to succeeded.

The following events are sent when the PaymentIntent status changes:

Evento	Descripción	Next Step
`payment_intent.processing`	The customer successfully submitted their payment to Stripe.	Espera hasta saber si el pago iniciado se ha hecho efectivo o no.
`payment_intent.succeeded`	El pago del cliente se ha realizado correctamente.	Fulfill the goods or services that were purchased.
`payment_intent.payment_failed`	The customer’s payment was declined.	Send the customer an email or push notification and request another payment method.

We recommend using webhooks to confirm the charge succeeds and to notify the customer that the payment is complete. You can also view events on the Stripe Dashboard.

Accepting future payments
Lado del servidor

After the PaymentIntent succeeds with a Customer provided and the setup_future_usage parameter set to off_session, the PaymentMethod PaymentMethod is attached to the Customer. You can use these to initiate future payments without having to prompt the customer for their bank account a second time.

Prueba tu integración

Números de cuenta de prueba

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

Test your form using bank code 11, branch code 0000 and one of the following account numbers.

Account number	Descripción
`0000000010`	El estado de PaymentIntent pasa de `processing` a `succeeded`. El estado del mandato permanece `active`.
`2222222027`	The PaymentIntent status transitions from `processing` to `requires_payment_method` with a `insufficient_funds` failure code. The mandate status remains `active`.
`8888888000`	El estado de PaymentIntent pasa de `processing` a `requires_payment_method` con un código de error `refer_to_customer`. El estado del mandato permanece `active`.
`1111111016`	The PaymentIntent status transitions from `processing` to `requires_payment_method` with an `no_account` failure code. The mandate status becomes `inactive`.
`5555555059`	El estado del PaymentIntent pasa de `processing` a `requires_payment_method` con un código de error `debit_not_authorized`. El estado del mandato pasa a `inactive`.
`9999999000`	The PaymentIntent status transitions to `processing` and remains there. To transition it further, use an API request as described below.

OpcionalConfigure customer debit date

You can control the date that Stripe debits a customer’s bank account using the target date. The target date must be at least three days in the future and no more than 15 days from the current date.

The target date schedules money to leave the customer’s account on the target date. You can cancel a PaymentIntent created with a target date up to three business days before the configured date.

Target dates that meet one of the following criteria delay the debit until next available business day:

Target date falls on a weekend, a bank holiday, or other non-business day.
Target date is fewer than three business days in the future.

This parameter operates on a best-effort basis. Each customer’s bank might process debits on different dates, depending on local bank holidays or other reasons.