Save Australia BECS Direct Debit details for future payments

Use the Setup Intents API to save payment method details for future Australia BECS Direct Debit payments.

Use Stripe Elements, our prebuilt UI components, to create a payment form that lets you securely collect bank details without handling the sensitive data. You can use the Setup Intents API to collect BECS Direct Debit payment method details in advance, and determine the final amount or payment date later. Use it to:

Save payment methods to a wallet to streamline future purchases
Collect surcharges after fulfilling a service
Start a free trial for a subscription

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 SetupIntent
Server-side

A SetupIntent is an object that represents your intent to set up a customer’s payment method for future payments. The SetupIntent will track the steps of this set-up process. For BECS Direct Debit, this includes collecting a mandate from the customer and tracking its validity throughout its lifecycle.

Create a SetupIntent on your server with payment_method_types set to au_becs_debit and specify the Customer’s id:

After creating a SetupIntent on your server, you can associate the SetupIntent ID with the current session’s customer in your application’s data model. Doing so allows you to retrieve the information after you have successfully collected a payment method.

The returned SetupIntent object contains a client_secret property. Pass the client secret to the client-side application to continue with the setup process.

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

payment_setup.html
<head>
  <title>Payment Setup</title>
  <script src="https://js.stripe.com/v3/"></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 our BECS Direct Debit Terms and 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, and identifying it as the “DDR service agreement.”
Make sure the accepted DDR and its accompanying DDR service agreement can be shared with your customer at all times, either as a printed or non-changeable electronic copy (such as email). Stripe hosts this for you.
Display the following standard authorization text for your customer to accept the BECS DDR, where you replace Rocketship Inc with your company name. Their acceptance authorizes you to initiate BECS Direct Debit payments from their bank account.

Note

By providing your bank account details, you agree to this Direct Debit Request and the Direct Debit Request service agreement, and authorize 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 Rocketship Inc (the “Merchant”) for any amounts separately communicated to you by the Merchant. You certify that you’re either an account holder or an authorized 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 will help you collect and validate both the BSB number and the account number. It needs a place to live in your payment form. Create empty DOM nodes (containers) with unique IDs in your payment form. Additionally, your customer must read and accept the Direct Debit Request service agreement.

payment_setup.html
HTML
<form action="/setup" method="post" id="setup-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, 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 SetupIntent as a data attribute -->
  <button id="submit-button" data-secret="{{CLIENT_SECRET}}">Set up BECS Direct Debit</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 method details to Stripe
Client-side

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

The client secret should be handled carefully because it can complete the setup. Do not log it, embed it in URLs, or expose it to anyone but the customer.

Use stripe.confirmAuBecsDebitSetup to complete the setup when the user submits the form. A successful setup returns a succeeded value for the SetupIntent’s status property. If the setup isn’t successful, inspect the returned error to determine the cause.

As customer was set, the PaymentMethod is attached to the provided Customer object after a successful setup. At this point, you can associate the ID of the Customer object with your internal representation of a customer. This allows you to use the stored PaymentMethod to collect future payments without prompting for your customer’s payment method details.

const form = document.getElementById('setup-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', async (event) => {
  event.preventDefault();
  stripe.confirmAuBecsDebitSetup(
    clientSecret,
    {
      payment_method: {
        au_becs_debit: auBankAccount,
        billing_details: {
          name: accountholderName.value,
          email: email.value
        }
      }
    }
  );
});

After successfully confirming the SetupIntent, you should share the mandate URL from the Mandate object with your customer. We also recommend including the following details to your customer 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

The Mandate object’s ID is accessible from the mandate on the SetupIntent object, which is sent as part of the setup_intent.succeeded event sent after confirmation, but can also be retrieved through the API.

Test the integration

You can test your form using the test BSB number 000-000 and one of the test account numbers below with your confirmAuBecsDebitSetup request.

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

Save Australia BECS Direct Debit details for future payments

Use the Setup Intents API to save payment method details for future Australia BECS Direct Debit payments.

Set up Stripe
Server-side

Create or retrieve a Customer
Server-side

Create a SetupIntent
Server-side

Collect payment method details and mandate acknowledgment
Client-side

Set up Stripe Elements

Direct Debit Requests

Note

Add and configure an Australia Bank Account Element

Submit the payment method details to Stripe
Client-side

Test the integration

OptionalValidate the Australia Bank Account Element
Client-side

OptionalAccepting future payments
Client-side

See also

Save Australia BECS Direct Debit details for future payments

Use the Setup Intents API to save payment method details for future Australia BECS Direct Debit payments.

Set up StripeServer-side

Create or retrieve a CustomerServer-side

Create a SetupIntentServer-side

Collect payment method details and mandate acknowledgmentClient-side

Set up Stripe Elements

Direct Debit Requests

Note

Add and configure an Australia Bank Account Element

Submit the payment method details to StripeClient-side

Test the integration

OptionalValidate the Australia Bank Account ElementClient-side

OptionalAccepting future paymentsClient-side

See also

Set up Stripe
Server-side

Create or retrieve a Customer
Server-side

Create a SetupIntent
Server-side

Collect payment method details and mandate acknowledgment
Client-side

Submit the payment method details to Stripe
Client-side

OptionalValidate the Australia Bank Account Element
Client-side

OptionalAccepting future payments
Client-side