Accept an Australia BECS Direct Debit payment

Learn to accept Australia BECS Direct Debit payments.

Web

Mobile

Stripe users in Australia can use the Payment Element and a Payment Intent to initiate BECS Direct Debit payments from customers with an AU bank account.

Caution

The content of this section refers to a Legacy product. You should use the Accept a payment guide for the most recent integration path instead. While Stripe still supports this product, this support might end if the product is deprecated.

Use Stripe Elements, our pre-built UI components, to create a payment form that lets you securely collect bank details without handling the sensitive data. Accepting 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 this payment object, the PaymentIntent, to track and handle all the states of the payment until the payment completes.

Stripe users in Australia can use the Australia Bank Account Element and a PaymentIntent to accept BECS Direct Debit payments from customers with an Australian bank account.

Set up Stripe
Server-side

First, you need a Stripe account. Register now.

Use our official libraries for access to the Stripe API from your application:

Create or retrieve a Customer
Server-side

To reuse a BECS Direct Debit account for future payments, you must 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 them 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.

Create a PaymentIntent
Server-side

A PaymentIntent is an object that represents your intent to collect a payment. The PaymentIntent 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 aud currency (BECS Direct Debit doesn’t support other currencies). If you already have an integration using the Payment Intents API, add au_becs_debit to the list of payment method types for your PaymentIntent.

To save the BECS Direct Debit account for reuse, set the setup_future_usage parameter to off_session. BECS Direct Debit only accepts an off_session value for this parameter.

After creating a PaymentIntent, Stripe returns a PaymentIntent object containing a client_secret property. Pass the client secret to the client side.

Warning

Use the client secret to charge the customer the amount specified on the PaymentIntent. Don’t log it, embed it in URLs, or expose it to anyone other than your customer.

Collect payment method details and mandate acknowledgment
Client-side

You’re ready to collect payment information on the client with Stripe Elements. Elements is a set of pre-built UI components for collecting payment details.

A Stripe Element contains an iframe that securely sends the payment information to Stripe over an HTTPS connection. The checkout page address must also start with https:// rather than http:// for your integration to work.

You can test your integration without using HTTPS. Enable it when you’re ready to accept live payments.

Set up Stripe Elements

Stripe Elements is automatically available as a feature of Stripe.js. Include the Stripe.js script on your payment page by adding it to the head of your HTML file. Always load Stripe.js directly from js.stripe.com to remain PCI compliant. Don’t include the script in a bundle or host a copy of it yourself.

submit_payment.html
<head>
  <title>Submit Payment</title>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>

Create an instance of Elements with the following JavaScript on your payment page:

const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);
const elements = stripe.elements();

Direct Debit Requests

Before you can create a BECS Direct Debit payment, your customer must agree with the Direct Debit Request Service Agreement. They do so by submitting a completed Direct Debit Request (DDR). The approval gives you a mandate to debit their account. The Mandate is a record of the permission to debit a payment method.

For online mandate acceptance, you can create a form to collect the necessary information. Serve the form over HTTPS and capture the following information:

Information	Description
Account name	The full name of the account holder
BSB number	The Bank-State-Branch number of the bank account (for example, `123-456`)
Account number	The bank account number (for example, `87654321`)

When collecting a Direct Debit Request, follow the BECS Direct Debit Terms. As part of your checkout form:

Display the exact terms of Stripe’s DDR service agreement either inline on the form, or on a page linked from the form identifying it as the “DDR service agreement”.
Display the following standard authorization text for your customer to accept the BECS DDR. Their acceptance authorizes you to initiate BECS Direct Debit payments from their bank account.

Note

By providing your bank account details and confirming this payment, you agree to this Direct Debit Request and the Direct Debit Request service agreement and authorise Stripe Payments Australia Pty Ltd ACN 160 180 343 Direct Debit User ID number 507156 (“Stripe”) to debit your account through the Bulk Electronic Clearing System (BECS) on behalf of (the “Merchant”) for payments as per the terms of your agreement with the Merchant. You certify that you’re either an account holder or an authorised signatory on the account listed above.

The details of the accepted mandate are generated when setting up a PaymentMethod or confirming a PaymentIntent. At all times, you should be able to share this mandate – the accepted DDR and its accompanying DDR service agreement – with your customer, either in print or as a non-changeable electronic copy (such as email). Stripe hosts this for you under the url property of the Mandate object linked to the PaymentMethod.

Add and configure an Australia Bank Account Element

The Australia Bank Account Element helps you collect and validate both the BSB number and the account number. Include it in your payment form by creating empty DOM nodes (containers) with unique IDs. Additionally, your customer must read and accept the Direct Debit Request service agreement.

submit_payment.html
Select a languageHTML
CSS
 No results
<form action="/charge" method="post" id="payment-form">
  <div class="form-row inline">
    <div class="col">
      <label for="accountholder-name">
        Name
      </label>
      <input
        id="accountholder-name"
        name="accountholder-name"
        placeholder="John Smith"
        required
      />
    </div>
    <div class="col">
      <label for="email">
        Email Address
      </label>
      <input
        id="email"
        name="email"
        type="email"
        placeholder="john.smith@example.com"
        required
      />
    </div>
  </div>

  <div class="form-row">
    <!--
    Using a label with a for attribute that matches the ID of the
    Element container enables the Element to automatically gain focus
    when the customer clicks on the label.
    -->
    <label for="au-bank-account-element">
      Bank Account
    </label>
    <div id="au-bank-account-element">
      <!-- A Stripe Element will be inserted here. -->
    </div>
  </div>

  <!-- Used to display bank (branch) name associated with the entered BSB -->
  <div id="bank-name"></div>

  <!-- Used to display form errors. -->
  <div id="error-message" role="alert"></div>

  <!-- Display mandate acceptance text. -->
  <div class="col" id="mandate-acceptance">
    By providing your bank account details and confirming this payment,
    you agree to this Direct Debit Request and the
    <a href="stripe.com/au-becs-dd-service-agreement/legal">Direct Debit Request service agreement</a>,
    and authorise Stripe Payments Australia Pty Ltd ACN 160 180 343
    Direct Debit User ID number 507156 (“Stripe”) to debit your account
    through the Bulk Electronic Clearing System (BECS) on behalf of
    Rocket Rides (the "Merchant") for any amounts separately
    communicated to you by the Merchant. You certify that you are either
    an account holder or an authorised signatory on the account listed above.
  </div>

  <!-- Add the client_secret from the PaymentIntent as a data attribute -->
  <button id="submit-button" data-secret="{{CLIENT_SECRET}}">Confirm Payment</button>

</form>

When the form loads, you can create an instance of the Australia Bank Account Element and mount it to the Element container:

// Custom styling can be passed to options when creating an Element
const style = {
  base: {
    color: '#32325d',
    fontSize: '16px',
    '::placeholder': {
      color: '#aab7c4'
    },
    ':-webkit-autofill': {
      color: '#32325d',
    },
  },
  invalid: {
    color: '#fa755a',
    iconColor: '#fa755a',
    ':-webkit-autofill': {
      color: '#fa755a',
    },
  }
};

const options = {
    style: style,
    disabled: false,
    hideIcon: false,
    iconStyle: "default", // or "solid"
}

// Create an instance of the auBankAccount Element.
const auBankAccount = elements.create('auBankAccount', options);

// Add an instance of the auBankAccount Element into
// the `au-bank-account-element` <div>.
auBankAccount.mount('#au-bank-account-element');

Submit the payment to Stripe
Client-side

Rather than sending the entire PaymentIntent object to the client, use its client secret from step 2. This is different from your API keys that authenticate Stripe API requests.

Use stripe.confirmAuBecsDebitPayment to both collect the mandate and complete the payment when the user submits the form. Including the customer’s email address and the account holder’s name in the billing_details property of the payment_method parameter is required to create a BECS Direct Debit PaymentMethod.

const form = document.getElementById('payment-form');
const accountholderName = document.getElementById('accountholder-name');
const email = document.getElementById('email');
const submitButton = document.getElementById('submit-button');
const clientSecret = submitButton.dataset.secret;

form.addEventListener('submit', (event) => {
  event.preventDefault();
  stripe.confirmAuBecsDebitPayment(
    clientSecret,
    {
      payment_method: {
        au_becs_debit: auBankAccount,
        billing_details: {
          name: accountholderName.value,
          email: email.value
        }
      }
    }
  );
});

After confirming the PaymentIntent, you should share the mandate URL from the Mandate object with your customer. We also recommend including the following details when you confirm their mandate has been established:

An explicit confirmation message that indicates a Direct Debit arrangement has been set up
The business name that will appear on the customer’s bank statement whenever their account gets debited
The payment amount and schedule (if applicable)
A link to the generated DDR mandate URL
You can access the Mandate object’s ID from the payment_method_details on the latest_charge of the PaymentIntent by retrieving it.

Users on API version 2022-08-01 or older:

You can access the Mandate object’s ID from the payment_method_details on the charge object of the PaymentIntent (included with the payment_intent.processing event sent after confirmation) or you can retrieve it.

Confirm the PaymentIntent succeeded
Server-side

BECS Direct Debit is a delayed notification payment method, which means that funds aren’t immediately available. A BECS Direct Debit PaymentIntent typically remains in a processing state for 2 business days after submission to the BECS network. This submission happens once per day. Once the payment succeeds, the associated PaymentIntent status updates from processing to succeeded.

The following events are sent when the PaymentIntent status is updated:

Event	Description	Next steps
`payment_intent.processing`	The customer’s payment was submitted to Stripe successfully.	Wait for the initiated payment to succeed or fail.
`payment_intent.succeeded`	The customer’s payment succeeded.	Fulfill the goods or services that were purchased.
`payment_intent.payment_failed`	The customer’s payment was declined.	Contact the customer via email or push notification and request another payment method.

Because setup_future_usage and customer were set, the PaymentMethod will be attached to the Customer object when the payment enters the processing state. This attachment happens regardless of whether payment eventually succeeds or fails.

When a Direct Debit attempt fails, Stripe sends a payment_intent.payment_failed event containing a PaymentIntent object. The last_payment_error attribute on the PaymentIntent contains a code and message describing details of the failure.

The failures can be transient or final for the mandate associated with the failed PaymentIntent. In the event of a final failure, Stripe revokes the mandate to prevent additional failure costs. When this happens, and you need your customer to pay, it’s your responsibility to contact your customer to establish a new mandate by re-collecting the bank account information.

For the following failure codes returned, Stripe updates the mandate status as follows:

Failure Code	Description	Mandate Status
`debit_not_authorized`	There’s a permanent failure due to a restriction or block to debit the account and you should contact your customer.	`inactive`
`account_closed`	There’s a permanent failure because the account has been closed and you should contact your customer.	`inactive`
`no_account`	There’s a permanent failure because there’s no account for the provided bank information and you should contact your customer.	`inactive`
`refer_to_customer`	There’s a transient failure (for example, insufficient funds) and you can re-attempt to debit without collecting a new mandate.	`active`

We recommend using webhooks to confirm the charge succeeds or fails, and to notify the customer whether mandate establishment and payment are complete or if they require additional attention.

Test the integration

You can test your form using the test BSB number 000000 and one of the test account numbers below with your confirmAuBecsDebitPayment request.

BSB Number	Account Number	Description

`000000`	`000123456`	The PaymentIntent status transitions from `processing` to `succeeded`. The mandate status remains `active`.
`000000`	`900123456`	The PaymentIntent status transitions from `processing` to `succeeded` (with a three-minute delay). The mandate status remains `active`.
`000000`	`111111113`	The PaymentIntent status transitions from `processing` to `requires_payment_method` with an `account_closed` failure code. The mandate status becomes `inactive`.
`000000`	`111111116`	The PaymentIntent status transitions from `processing` to `requires_payment_method` with a `no_account` failure code. The mandate status becomes `inactive`.
`000000`	`222222227`	The PaymentIntent status transitions from `processing` to `requires_payment_method` with a `refer_to_customer` failure code. The mandate status remains `active`.
`000000`	`922222227`	The PaymentIntent status transitions from `processing` to `requires_payment_method` with a `refer_to_customer` failure code (with a three-minute delay). The mandate status remains `active`.
`000000`	`333333335`	The PaymentIntent status transitions from `processing` to `requires_payment_method` with a `debit_not_authorized` failure code. The mandate status becomes `inactive`.
`000000`	`666666660`	The PaymentIntent status transitions from `processing` to `succeeded`, but a dispute is immediately created.
`000000`	`343434343`	The PaymentIntent fails with a `charge_exceeds_source_limit` error due to the payment amount causing the account to exceed its weekly payment volume limit.
`000000`	`121212121`	The PaymentIntent fails with a `charge_exceeds_transaction_limit` error due to the payment amount exceeding the account’s transaction volume limit.

Using test account numbers triggers webhook events. In a sandbox, PaymentIntents succeed and fail immediately, and as a result, the respective payment_intent.succeeded and payment_intent.payment_failed events trigger immediately as well. In live mode, the webhooks get triggered with the same delays as those of their related PaymentIntent successes and failures.

OptionalValidate the Australia Bank Account Element
Client-side

The Australia Bank Account Element validates user input as it’s typed. To help your customers fix mistakes, you should listen to change events on the Australia Bank Account Element and display any errors:

auBankAccount.on('change', (event) => {
  const displayError = document.getElementById('error-message');
  if (event.error) {
    displayError.textContent = event.error.message;
  } else {
    displayError.textContent = '';
  }
});

The change event contains other parameters that can help to build a richer user experience. Refer to the Stripe.js reference for more details.

OptionalConfigure 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.

Accept an Australia BECS Direct Debit payment

Learn to accept Australia BECS Direct Debit payments.

Caution

Set up StripeServer-side

Create or retrieve a CustomerServer-side

Create a PaymentIntentServer-side