Set up a subscription with BECS Direct Debit in Australia

Learn how to create and charge for a subscription with BECS Direct Debit.

Note

If you’re a new user, use the Payment Element instead of using Stripe Elements as described in this guide. The Payment Element provides a low-code integration path with built-in conversion optimisations. For instructions, see Build a subscription.

Use this guide to set up a subscription using BECS Direct Debit as a payment method.

Create a product and price
Dashboard

Products represent the item or service you’re selling. Prices define how much and how frequently you charge for a product. This includes how much the product costs, what currency you accept, and whether it’s a one-off or recurring charge. If you only have a few products and prices, create and manage them in the Dashboard.

This guide uses a stock photo service as an example and charges customers a 15 AUD monthly subscription. To model this:

Navigate to the Add a product page.
Enter a Name for the product.
Enter 15 for the price.
Select AUD as the currency.
Click Save product.

After you create the product and the price, record the price ID so you can use it in subsequent steps. The pricing page displays the ID and it looks similar to this: price_G0FvDp6vZvdwRZ.

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:

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

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

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.

Create a customer with a PaymentMethod
Server-side

Creating subscriptions requires a customer, which represents the customer purchasing your product. Because the price you created charges on a monthly basis, you need to add a stored payment method to the customer so future payments are successful. You do this by setting the payment method you just collected at the top level of the Customer object and as the default payment method for invoices:

This returns a Customer object. You can see the default payment method in the invoice_settings object:

{
  "id": "cus_Gk0uVzT2M4xOKD",
  "object": "customer",
  "address": null,
  "balance": 0,
  "created": 1581797088,
  "currency": null,
  "default_source": null,
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "jenny.rosen@example.com",
  "invoice_prefix": "11D0B3D7",
  "invoice_settings": {
    "custom_fields": null,
    "default_payment_method": "pm_1FU2bgBF6ERF9jhEQvwnA7sX",
    "footer": null
  },

After creating the customer, store the id value in your own database so you can use it later. The next step also requires this ID.

Create the subscription
Server-side

Create a subscription with the price and customer:

Creating subscriptions automatically charges customers because the default payment method is set. After a successful payment, the status in the Stripe Dashboard changes to Active. The price you created earlier determines subsequent billings.

Manage subscription status
Client-side

Assuming the initial payment succeeds, the state of the subscription is active and no further action is needed. When payments fail, the status is changed to the Subscription status configured in your automatic collection settings. You should notify the customer on failure and charge them with a different payment method.

Note

BECS Direct Debit payments are never automatically retried, even if you have a retry schedule configured for other payment methods.

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.

Set up a subscription with BECS Direct Debit in Australia

Learn how to create and charge for a subscription with BECS Direct Debit.

Note

Create a product and price
Dashboard

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

Create a customer with a PaymentMethod
Server-side

Create the subscription
Server-side

Manage subscription status
Client-side

Note

Test the integration

OptionalSetting the billing cycle

OptionalSubscription trials

Set up a subscription with BECS Direct Debit in Australia

Learn how to create and charge for a subscription with BECS Direct Debit.

Note

Create a product and priceDashboard

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

Create a customer with a PaymentMethodServer-side

Create the subscriptionServer-side

Manage subscription statusClient-side

Note

Test the integration

OptionalSetting the billing cycle

OptionalSubscription trials

Create a product and price
Dashboard

Create a SetupIntent
Server-side

Collect payment method details and mandate acknowledgment
Client-side

Submit the payment method details to Stripe
Client-side

Create a customer with a PaymentMethod
Server-side

Create the subscription
Server-side

Manage subscription status
Client-side