Accept a BECS Direct Debit payment

    Use the Payment Intents and Payment Methods APIs to accept BECS Direct Debit payments in Australia.

    Overview

    Use Stripe Elements, our prebuilt UI components, to create a payment form that lets you securely collect a customer’s 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.

    1 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:

    # Available as a gem sudo gem install stripe
    # If you use bundler, you can add this line to your Gemfile gem 'stripe'
    # Install through pip pip install --upgrade stripe
    # Or find the Stripe package on http://pypi.python.org/pypi/stripe/
    # Install the PHP library via Composer composer require stripe/stripe-php
    # Or download the source directly: https://github.com/stripe/stripe-php/releases
    /* For Gradle, add the following dependency to your build.gradle and replace {VERSION} with the version number you want to use from - https://mvnrepository.com/artifact/com.stripe/stripe-java or - https://github.com/stripe/stripe-java/releases/latest */ implementation "com.stripe:stripe-java:{VERSION}"
    <!-- For Maven, add the following dependency to your POM and replace {VERSION} with the version number you want to use from - https://mvnrepository.com/artifact/com.stripe/stripe-java or - https://github.com/stripe/stripe-java/releases/latest --> <dependency> <groupId>com.stripe</groupId> <artifactId>stripe-java</artifactId> <version>{VERSION}</version> </dependency>
    # For other environments, manually install the following JARs: # - The Stripe JAR from https://github.com/stripe/stripe-java/releases/latest # - Google Gson from https://github.com/google/gson
    # Install via npm npm install --save stripe
    # Install via go go get github.com/stripe/stripe-go
    // Then import the package import ( "github.com/stripe/stripe-go" )
    # Install via dotnet dotnet add package Stripe.net dotnet restore
    # Or install via NuGet PM> Install-Package Stripe.net

    2 Create or retrieve a Customer Server-side

    To reuse a BECS Direct Debit account for future payments, it must be attached to a Customer.

    You should create a Customer object when your customer creates an account on your business. Associating the ID of the Customer object with your own internal representation of a customer will enable you to retrieve and use the stored payment method details later. If your customer is making a payment as a guest, you can still create a Customer object before payment and associate it with your internal representation of the customer’s account 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.

    curl https://api.stripe.com/v1/customers \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -X POST
    # Set your secret key. Remember to switch to your live secret key in production! # See your keys here: https://dashboard.stripe.com/account/apikeys Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc' customer = Stripe::Customer.create
    # Set your secret key. Remember to switch to your live secret key in production! # See your keys here: https://dashboard.stripe.com/account/apikeys stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc' customer = stripe.Customer.create()
    // Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys \Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc'); $customer = \Stripe\Customer::create();
    // Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; CustomerCreateParams params = CustomerCreateParams.builder() .build(); Customer customer = Customer.create(params);
    // Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc'); const customer = await stripe.customers.create();
    // Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc" params := &stripe.CustomerParams{} c, _ := customer.New(params)
    // Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; var options = new CustomerCreateOptions{}; var service = new CustomerService(); var customer = service.Create(options);

    3 Create a PaymentIntent Server-side

    A PaymentIntent is an object that represents your intent to collect a payment from a customer. 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 does not 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.

    curl https://api.stripe.com/v1/payment_intents \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d amount=1099 \ -d setup_future_usage=off_session \ -d currency=aud \ -d customer="{{CUSTOMER_ID}}" \ -d "payment_method_types[]"=au_becs_debit
    require 'sinatra' require 'json' require 'stripe' # Set your secret key. Remember to switch to your live secret key in production! # See your keys here: https://dashboard.stripe.com/account/apikeys Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc' get '/pay' do payment_intent = Stripe::PaymentIntent.create({ amount: 1099, currency: 'aud', setup_future_usage: 'off_session', customer: customer['id'], payment_method_types: ['au_becs_debit'], }) client_secret = payment_intent['client_secret'] # Pass the client secret to the client end
    import stripe import json from flask import request, render_template app = Flask(__name__, static_folder=".", static_url_path="", template_folder=".") # Set your secret key. Remember to switch to your live secret key in production! # See your keys here: https://dashboard.stripe.com/account/apikeys stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc' @app.route('/pay') def pay(): payment_intent = stripe.PaymentIntent.create( amount=1099, currency='aud', setup_future_usage='off_session', customer=customer['id'], payment_method_types=['au_becs_debit'] ) client_secret = payment_intent.client_secret # Pass the client secret to the client if __name__ == '__main__': app.run()
    // Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys \Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc'); # vendor using composer require_once('vendor/autoload.php'); $payment_intent = \Stripe\PaymentIntent::create([ 'amount' => 1099, 'currency' => 'aud', 'setup_future_usage' => 'off_session', 'customer' => $customer->id, 'payment_method_types' => ['au_becs_debit'], ]); $client_secret = $payment_intent->client_secret // Pass the client secret to the client
    import java.util.HashMap; import java.util.Map; import com.stripe.Stripe; import com.stripe.model.PaymentIntent; public class StripeJavaQuickStart { public static void main(String[] args) { // Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; Map<String, Object> paymentIntentParams = new HashMap<String, Object>(); paymentIntentParams.put("amount", 1099); paymentIntentParams.put("currency", "aud"); paymentIntentParams.put("setup_future_usage", "off_session"); params.put("customer", customer.getId()); paymentIntentParams.put("payment_method_types", Arrays.asList("au_becs_debit")); PaymentIntent paymentIntent = PaymentIntent.create(paymentIntentParams); String clientSecret = paymentIntent.getClientSecret(); // Pass the client secret to the client } }
    // Using Express const express = require('express'); const app = express(); app.use(express.json()); const { resolve } = require("path"); // Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc'); (async () => { const paymentIntent = await stripe.paymentIntents.create({ amount: 1099, currency: 'aud', setup_future_usage: 'off_session', customer: customer.id, payment_method_types: ['au_becs_debit'], }); const clientSecret = paymentIntent.client_secret; // Pass the client secret to the client })();
    package main import ( "encoding/json" "log" "net/http" "github.com/stripe/stripe-go" "github.com/stripe/stripe-go/paymentintent" ) func main() { // Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc" paymentIntentParams := &stripe.PaymentIntentParams{ Amount: stripe.Int64(1099), Currency: stripe.String(string(Stripe.CurrencyAUD)), SetupFutureUsage: stripe.String("off_session"), Customer: stripe.String(customer.ID), PaymentMethodTypes: stripe.StringSlice([]string{ "au_becs_debit", }), } paymentIntent, err := paymentintent.New(paymentIntentParams) clientSecret := paymentIntent.ClientSecret // Pass the client secret to the client }
    // Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; using System; using Microsoft.AspNetCore.Mvc; using Stripe; namespace StripeExampleApi.Controllers { [Route("/pay")] public class PayController : Controller { public IActionResult Index() { var service = new PaymentIntentService(); var options = new PaymentIntentCreateOptions { Amount = 1099, Currency = "aud", SetupFutureUsage = "off_session", Customer = "{{CUSTOMER_ID}}", PaymentMethodTypes = new List<string> { "au_becs_debit", }, }; var paymentIntent = service.Create(options); var clientSecret = paymentIntent.ClientSecret; // Pass the client secret to the client } } }

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

    4 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 a 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. Do not include the script in a bundle or host a copy of it yourself.

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

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

    var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'); var elements = stripe.elements();
    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 a customer has given you to debit their payment method corresponding to this Direct Debit Request.

    For online mandate acceptance, you can create a form to collect the necessary information. The form should be served 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 (eg. 123-456)
    Account number The bank account number (eg. 87654321)

    When collecting a Direct Debit Request, you should 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”
    • 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.

    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 via email). Stripe hosts this for you under the url property of the Mandate object linked to the PaymentMethod. You can review an example of how this looks.

    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 (container) with unique IDs in your payment form. Additionally, your customer must read and accept the Direct Debit Request service agreement.

    <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="https://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 Rocketship Inc. (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>
    /** * Shows how you can use CSS to style your Element's container. * These classes are added to your Stripe Element by default. * You can override these classNames by using the options passed * to the `iban` element. * https://stripe.com/docs/js/elements_object/create_element?type=iban#elements_create-options-classes */ input, .StripeElement { height: 40px; padding: 10px 12px; color: #32325d; background-color: white; border: 1px solid transparent; border-radius: 4px; box-shadow: 0 1px 3px 0 #e6ebf1; -webkit-transition: box-shadow 150ms ease; transition: box-shadow 150ms ease; } input:focus, .StripeElement--focus { box-shadow: 0 1px 3px 0 #cfd7df; } .StripeElement--invalid { border-color: #fa755a; } .StripeElement--webkit-autofill { background-color: #fefde5 !important; }

    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 var style = { base: { color: '#32325d', fontSize: '16px', '::placeholder': { color: '#aab7c4' }, ':-webkit-autofill': { color: '#32325d', }, }, invalid: { color: '#fa755a', iconColor: '#fa755a', ':-webkit-autofill': { color: '#fa755a', }, } }; var options = { style: style, disabled: false, hideIcon: false, iconStyle: "default", // or "solid" } // Create an instance of the auBankAccount Element. var 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');
    // 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');

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

    var form = document.getElementById('payment-form'); var accountholderName = document.getElementById('accountholder-name'); var email = document.getElementById('email'); var submitButton = document.getElementById('submit-button'); var clientSecret = submitButton.dataset.secret; form.addEventListener('submit', function(event) { event.preventDefault(); stripe.confirmAuBecsDebitPayment( clientSecret, { payment_method: { au_becs_debit: auBankAccount, billing_details: { name: accountholderName.value, email: email.value } } } ); });
    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 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 payment_method_details on the charge object of the PaymentIntent, which is sent as part of the payment_intent.processing event sent after confirmation but can also be retrieved through the API.

    6 Confirm the PaymentIntent succeeded Server-side

    BECS Direct Debit is a delayed notification payment method, which means that funds are not immediately available. A BECS Direct Debit PaymentIntent typically remains in a processing state for 3 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 the customer purchased.
    payment_intent.payment_failed The customer’s payment was declined.
    Please refer to failed payments for more details.
    Contact the customer via email or push notification and request another payment method.

    Note that because setup_future_usage and customer were set, the PaymentMethod will be attached to the Customer object once 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 case of a final failure, Stripe revokes the mandate to prevent additional failure costs. When this happens, and you need your customer to pay, it is your responsibility to reach out to 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 reach out to your customer. inactive
    account_closed There’s a permanent failure because the account has been closed and you should reach out to your customer. inactive
    no_account There’s a permanent failure because there’s no account for the provided bank information and you should reach out to your customer. inactive
    refer_to_customer There’s a transient failure (e.g. insufficient funds) and you can re-attempt to debit without collecting a new mandate. active

    We recommend using webhooks to confirm the charge has succeeded or failed, and to notify the customer that mandate establishment and/or payment are complete or require additional attention.

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

    Account Number Description
    000123456 The PaymentIntent status transitions from processing to succeeded. The mandate status remains active.
    900123456 The PaymentIntent status transitions from processing to succeeded (with a three-minute delay). The mandate status remains active.
    111111113 The PaymentIntent status transitions from processing to requires_payment_method with an account_closed failure code. The mandate status will become inactive.
    111111116 The PaymentIntent status transitions from processing to requires_payment_method with a no_account failure code. The mandate status will become inactive.
    222222227 The PaymentIntent status transitions from processing to requires_payment_method with a refer_to_customer failure code. The mandate status will remain active.
    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 will remain active.
    333333335 The PaymentIntent status transitions from processing to requires_payment_method with a debit_not_authorized failure code. The mandate status will become inactive.

    Webhook events are triggered when using test account numbers. In test mode, 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.

    Optional Validate the Australia Bank Account Element Client-side

    The Australia Bank Account Element validates user input as it is 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', function(event) { var displayError = document.getElementById('error-message'); if (event.error) { displayError.textContent = event.error.message; } else { displayError.textContent = ''; } });
    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.

    See also

    Congrats, you are done with your integration! You can learn about saving bank account details without a payment and integrating with Connect.

    Was this page helpful?

    Feedback about this page?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    On this page