# 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. # Elements > This is a Elements for when payment-ui is elements. View the full page at https://docs.stripe.com/payments/au-becs-debit/set-up-payment?payment-ui=elements. Use [Stripe Elements](https://docs.stripe.com/payments/elements.md), 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](https://docs.stripe.com/payments/setup-intents.md) 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](https://docs.stripe.com/billing/subscriptions/trials.md) ## Set up Stripe [Server-side] First, you need a Stripe account. [Register now](https://dashboard.stripe.com/register). Use our official libraries for access to the Stripe API from your application: #### Ruby ```bash # Available as a gem sudo gem install stripe ``` ```ruby # If you use bundler, you can add this line to your Gemfile gem 'stripe' ``` ## Create or retrieve a Customer [Server-side] To reuse a BECS Direct Debit account for future payments, you must attach it to a *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments). 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. ```curl curl -X POST https://api.stripe.com/v1/customers \ -u "<>:" ``` ## Create a SetupIntent [Server-side] A [SetupIntent](https://docs.stripe.com/api/setup_intents.md) 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](https://docs.stripe.com/api/setup_intents.md) on your server with [payment_method_types](https://docs.stripe.com/api/setup_intents/create.md#create_setup_intent-payment_method_types) set to `au_becs_debit` and specify the *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments)’s [id](https://docs.stripe.com/api/customers/object.md#customer_object-id): #### curl ```bash curl https://api.stripe.com/v1/setup_intents \ -u <>: \ -d "payment_method_types[]"="au_becs_debit" \ -d "customer"="{{CUSTOMER_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’ve 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](https://docs.stripe.com/payments/elements.md). 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](https://docs.stripe.com/security/guide.md#tls) when you’re ready to accept live payments. ### Set up Stripe Elements #### HTML + JS 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. ```html Payment Setup ``` Create an instance of [Elements](https://docs.stripe.com/js.md#stripe-elements) with the following JavaScript on your payment page: ```javascript const stripe = Stripe('<>'); 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](https://docs.stripe.com/security/guide.md#tls) 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](https://stripe.com/au-becs/legal) and as part of your checkout form: - Display the exact terms of [Stripe’s DDR service agreement](https://stripe.com/au-becs-dd-service-agreement/legal) 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](https://stripe.com/au-becs-dd-service-agreement/legal) 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. > By providing your bank account details, you agree to this Direct Debit Request and the [Direct Debit Request service agreement](https://stripe.com/au-becs-dd-service-agreement/legal), 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 payments as per the terms of your agreement with 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](https://docs.stripe.com/payments/payment-methods.md) 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](https://stripe.com/au-becs-dd-service-agreement/legal). #### HTML ```html
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 ofRocket 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.
``` When the form loads, you can [create an instance](https://docs.stripe.com/js/elements_object/create_element?type=au_bank_account) of the Australia Bank Account Element and mount it to the Element container: ```javascript // 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`
. auBankAccount.mount('#au-bank-account-element'); ``` #### React #### npm Install [React Stripe.js](https://www.npmjs.com/package/@stripe/react-stripe-js) and the [Stripe.js loader](https://www.npmjs.com/package/@stripe/stripe-js) from the npm public registry. ```bash npm install --save @stripe/react-stripe-js @stripe/stripe-js ``` #### umd We also provide a UMD build for sites that don’t use npm or modules. Include the Stripe.js script, which exports a global `Stripe` function, and the UMD build of React Stripe.js, which exports a global `ReactStripe` object. Always load the Stripe.js script directly from **js.stripe.com** to remain PCI compliant. Don’t include the script in a bundle or host a copy of it yourself. ```html ``` > The [demo in CodeSandbox](https://codesandbox.io/s/react-stripe-official-q1loc?fontsize=14&hidenavigation=1&theme=dark) lets you try out React Stripe.js without having to create a new project. ### Add Stripe.js and Elements to your page To use Element components, wrap your checkout page component in an [Elements provider](https://docs.stripe.com/sdks/stripejs-react.md#elements-provider). Call `loadStripe` with your publishable key and pass the returned `Promise` to the `Elements` provider. ```jsx import React from 'react'; import ReactDOM from 'react-dom'; import {Elements} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; import PaymentSetupForm from './PaymentSetupForm'; // Make sure to call `loadStripe` outside of a component's render to avoid // recreating the `Stripe` object on every render. const stripePromise = loadStripe('<>'); function App() { return ( ); }; ReactDOM.render(, document.getElementById('root')); ``` ### 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](https://docs.stripe.com/security/guide.md#tls) 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](https://stripe.com/au-becs/legal) and as part of your checkout form: - Display the exact terms of [Stripe’s DDR service agreement](https://stripe.com/au-becs-dd-service-agreement/legal) 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](https://stripe.com/au-becs-dd-service-agreement/legal) 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. > By providing your bank account details, you agree to this Direct Debit Request and the [Direct Debit Request service agreement](https://stripe.com/au-becs-dd-service-agreement/legal), 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 payments as per the terms of your agreement with 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](https://docs.stripe.com/payments/payment-methods.md) 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 AuBankAccountElement component The `AuBankAccountElement` component will help you collect and validate both the BSB number and the account number. Additionally, your customer must read and accept the [Direct Debit Request service agreement](https://stripe.com/au-becs-dd-service-agreement/legal). #### JSX ```jsx /** * Use the CSS tab above to style your Element's container. */ import React from 'react'; import {AuBankAccountElement} from '@stripe/react-stripe-js'; import './BecsFormStyles.css' // Custom styling can be passed as options when creating an Element. const AU_BANK_ACCOUNT_STYLE = { base: { color: '#32325d', fontSize: '16px', '::placeholder': { color: '#aab7c4' }, ':-webkit-autofill': { color: '#32325d', }, }, invalid: { color: '#fa755a', iconColor: '#fa755a', ':-webkit-autofill': { color: '#fa755a', }, } }; const AU_BANK_ACCOUNT_ELEMENT_OPTIONS = { style: AU_BANK_ACCOUNT_STYLE, disabled: false, hideIcon: false, iconStyle: "default", // or "solid" }; export default function BecsForm({onSubmit, disabled}) { return (
{/* Display mandate acceptance text. */}
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 ofRocket 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.
``` Elements are completely customizable. You can [style Elements](https://docs.stripe.com/js/elements_object/create_element?type=au_bank_account#elements_create-options) to match the look and feel of your site, providing a seamless checkout experience for your customers. It’s also possible to style various input states, for example when the Element has focus. ## Submit the payment method details to Stripe [Client-side] Rather than sending the entire `SetupIntent` object to the client, use its [client secret](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-client_secret) from [step 2](https://docs.stripe.com/payments/au-becs-debit/set-up-payment.md#web-create-setup-intent). 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. Don’t log it, embed it in URLs, or expose it to anyone but the customer. #### HTML + JS Use [stripe.confirmAuBecsDebitSetup](https://docs.stripe.com/js/setup_intents/confirm_au_becs_debit_setup) 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](https://docs.stripe.com/api/setup_intents/create.md#create_setup_intent-customer) was set, the *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) 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. ```javascript 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](https://docs.stripe.com/api/mandates/object.md#mandate_object-payment_method_details-au_becs_debit-url) from the [Mandate object](https://docs.stripe.com/api/mandates.md) 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](https://docs.stripe.com/payments/au-becs-debit/set-up-payment.md#statement-descriptors) 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](https://docs.stripe.com/api/setup_intents/retrieve.md). ```curl curl -G https://api.stripe.com/v1/setup_intents/{{SETUP_INTENT_ID}} \ -u "<>:" \ -d "expand[]=mandate" ``` #### React Use [stripe.confirmAuBecsDebitSetup](https://docs.stripe.com/js/setup_intents/confirm_au_becs_debit_setup) to complete the mandate collection 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`. To call `stripe.confirmAuBecsDebitSetup` from your payment form component, use the [useStripe](https://docs.stripe.com/sdks/stripejs-react.md#usestripe-hook) and [useElements](https://docs.stripe.com/sdks/stripejs-react.md#useelements-hook) hooks. If you prefer traditional class components over hooks, you can instead use an [ElementsConsumer](https://docs.stripe.com/sdks/stripejs-react.md#elements-consumer). #### Hooks ```jsx import React from 'react'; import {useStripe, useElements, AuBankAccountElement} from '@stripe/react-stripe-js'; import BecsForm from './BecsForm'; export default function PaymentSetupForm() { const stripe = useStripe(); const elements = useElements(); const handleSubmit = async (event) => { // We don't want to let default form submission happen here, // which would refresh the page. event.preventDefault(); if (!stripe || !elements) { // Stripe.js hasn't yet loaded. // Make sure to disable form submission until Stripe.js has loaded. return; } const auBankAccount = elements.getElement(AuBankAccountElement); // For brevity, this example is using uncontrolled components for // the accountholder's name and email. In a real world app you will // probably want to use controlled components. // https://reactjs.org/docs/uncontrolled-components.html // https://reactjs.org/docs/forms.html#controlled-components const accountholderName = event.target['accountholder-name']; const email = event.target.email; const result = await stripe.confirmAuBecsDebitSetup('{{CLIENT_SECRET}}', { payment_method: { au_becs_debit: auBankAccount, billing_details: { name: accountholderName.value, email: email.value, }, } }); if (result.error) { // Show error to your customer. console.log(result.error.message); } else { // Show a confirmation message to your customer. // The SetupIntent is in the 'succeeded' state. } }; return ( ); } ``` #### Class Components ```jsx import React from 'react'; import {ElementsConsumer, AuBankAccountElement} from '@stripe/react-stripe-js'; import BecsForm from './BecsForm'; class PaymentSetupForm extends React.Component { handleSubmit = async (event) => { // We don't want to let default form submission happen here, // which would refresh the page. event.preventDefault(); const {stripe, elements} = this.props; if (!stripe || !elements) { // Stripe.js hasn't yet loaded. // Make sure to disable form submission until Stripe.js has loaded. return; } const auBankAccount = elements.getElement(AuBankAccountElement); // For brevity, this example is using uncontrolled components for // the accountholder's name and email. In a real world app you will // probably want to use controlled components. // https://reactjs.org/docs/uncontrolled-components.html // https://reactjs.org/docs/forms.html#controlled-components const accountholderName = event.target['accountholder-name']; const email = event.target.email; const result = await stripe.confirmAuBecsDebitSetup('{{CLIENT_SECRET}}', { payment_method: { au_becs_debit: auBankAccount, billing_details: { name: accountholderName.value, email: email.value, }, } }); if (result.error) { // Show error to your customer. console.log(result.error.message); } else { // Show a confirmation message to your customer. // The SetupIntent is in the 'succeeded' state. } }; render() { const {stripe} = this.props; return ( ); } } export default function InjectedPaymentSetupForm() { return ( {({stripe, elements}) => ( )} ); } ``` After successfully confirming the `SetupIntent`, you should share the [mandate URL](https://docs.stripe.com/api/mandates/object.md#mandate_object-payment_method_details-au_becs_debit-url) from the [Mandate object](https://docs.stripe.com/api/mandates.md) 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](https://docs.stripe.com/payments/au-becs-debit/set-up-payment.md#statement-descriptors) 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](https://docs.stripe.com/api/setup_intents/retrieve.md). ```curl curl -G https://api.stripe.com/v1/setup_intents/{{SETUP_INTENT_ID}} \ -u "<>:" \ -d "expand[]=mandate" ``` ## Test the integration You can test your form using the test BSB number `000000` and one of the test account numbers below with your [confirmAuBecsDebitSetup](https://docs.stripe.com/js/setup_intents/confirm_au_becs_debit_setup) request. | BSB Number | Account Number | Description | | ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `000000` | `000123456` | The PaymentIntent created with the resulting PaymentMethod transitions from `processing` to `succeeded`. The mandate status remains `active`. | | `000000` | `900123456` | The PaymentIntent created with the resulting PaymentMethod transitions from `processing` to `succeeded` (with a three-minute delay). The mandate status remains `active`. | | `000000` | `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. | | `000000` | `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. | | `000000` | `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`. | | `000000` | `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`. | | `000000` | `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. | | `000000` | `666666660` | The PaymentIntent created with the resulting PaymentMethod transitions from `processing` to `succeeded`, but a dispute is immediately created. | | `000000` | `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. | | `000000` | `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. | ## Optional: Validate 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: #### HTML + JS ```javascript auBankAccount.on('change', (event) => { const displayError = document.getElementById('error-message'); if (event.error) { displayError.textContent = event.error.message; } else { displayError.textContent = ''; } }); ``` #### React ```jsx { if (event.error) { // Store event.error.message in state and display it. } else { // Remove existing error from state. } }}> ``` The change event contains other parameters that can help to build a richer user experience. Refer to the [Stripe.js reference](https://docs.stripe.com/js/element/events/on_change?type=auBankAccountElement#element_on_change-handler) for more details. ## Optional: Accepting future payments [Client-side] When the SetupIntent succeeds, it will create a new *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) and a [Mandate object](https://docs.stripe.com/api/mandates.md). These can be used to initiate future payments without having to prompt the customer for information information. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1000 \ -d currency=aud \ -d "payment_method_types[]=au_becs_debit" \ -d "customer={{CUSTOMER_ID}}" \ -d "payment_method={{PAYMENTMETHOD_ID}}" \ -d confirm=true ``` # iOS > This is a iOS for when payment-ui is mobile and platform is ios. View the full page at https://docs.stripe.com/payments/au-becs-debit/set-up-payment?payment-ui=mobile&platform=ios. Use STPAUBECSFormView, Stripe’s prebuilt BECS payment details collection UI, to create a payment form that lets you securely collect bank details without handling sensitive customer data. You can use the [Setup Intents API](https://docs.stripe.com/payments/setup-intents.md) 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](https://docs.stripe.com/billing/subscriptions/trials.md) ## Set up Stripe [Server-side] [Client-side] First, you need a Stripe account. [Register now](https://dashboard.stripe.com/register). ### Server-side This integration requires endpoints on your server that talk to the Stripe API. Use the official libraries for access to the Stripe API from your server: #### Ruby ```bash # Available as a gem sudo gem install stripe ``` ```ruby # If you use bundler, you can add this line to your Gemfile gem 'stripe' ``` ### Client-side The [Stripe iOS SDK](https://github.com/stripe/stripe-ios) is open source, [fully documented](https://stripe.dev/stripe-ios/index.html), and compatible with apps supporting iOS 13 or above. #### Swift Package Manager To install the SDK, follow these steps: 1. In Xcode, select **File** > **Add Package Dependencies…** and enter `https://github.com/stripe/stripe-ios-spm` as the repository URL. 1. Select the latest version number from our [releases page](https://github.com/stripe/stripe-ios/releases). 1. Add the **StripePaymentsUI** product to the [target of your app](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app). #### CocoaPods 1. If you haven’t already, install the latest version of [CocoaPods](https://guides.cocoapods.org/using/getting-started.html). 1. If you don’t have an existing [Podfile](https://guides.cocoapods.org/syntax/podfile.html), run the following command to create one: ```bash pod init ``` 1. Add this line to your `Podfile`: ```podfile pod 'StripePaymentsUI' ``` 1. Run the following command: ```bash pod install ``` 1. Don’t forget to use the `.xcworkspace` file to open your project in Xcode, instead of the `.xcodeproj` file, from here on out. 1. In the future, to update to the latest version of the SDK, run: ```bash pod update StripePaymentsUI ``` #### Carthage 1. If you haven’t already, install the latest version of [Carthage](https://github.com/Carthage/Carthage#installing-carthage). 1. Add this line to your `Cartfile`: ```cartfile github "stripe/stripe-ios" ``` 1. Follow the [Carthage installation instructions](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos). Make sure to embed all of the required frameworks listed [here](https://github.com/stripe/stripe-ios/tree/master/StripePaymentsUI/README.md#manual-linking). 1. In the future, to update to the latest version of the SDK, run the following command: ```bash carthage update stripe-ios --platform ios ``` #### Manual Framework 1. Head to our [GitHub releases page](https://github.com/stripe/stripe-ios/releases/latest) and download and unzip **Stripe.xcframework.zip**. 1. Drag **StripePaymentsUI.xcframework** to the **Embedded Binaries** section of the **General** settings in your Xcode project. Make sure to select **Copy items if needed**. 1. Repeat step 2 for all required frameworks listed [here](https://github.com/stripe/stripe-ios/tree/master/StripePaymentsUI/README.md#manual-linking). 1. In the future, to update to the latest version of our SDK, repeat steps 1–3. > For details on the latest SDK release and past versions, see the [Releases](https://github.com/stripe/stripe-ios/releases) page on GitHub. To receive notifications when a new release is published, [watch releases](https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository#watching-releases-for-a-repository) for the repository. Configure the SDK with your Stripe [publishable key](https://dashboard.stripe.com/test/apikeys) on app start. This enables your app to make requests to the Stripe API. #### Swift ```swift import UIKitimportStripePaymentsUI @main class AppDelegate: UIResponder, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {StripeAPI.defaultPublishableKey = "<>" // do any other necessary launch configuration return true } } ``` > Use your [test keys](https://docs.stripe.com/keys.md#obtain-api-keys) while you test and develop, and your [live mode](https://docs.stripe.com/keys.md#test-live-modes) keys when you publish your app. ## Create or retrieve a Customer [Server-side] To reuse a BECS Direct Debit account for future payments, you must attach it to a *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments). 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. ```curl curl -X POST https://api.stripe.com/v1/customers \ -u "<>:" ``` ## Collect payment method details and mandate acknowledgment [Client-side] You can securely collect BECS Debit payment information with [STPAUBECSFormView](https://stripe.dev/stripe-ios/stripe-payments-ui/Classes/STPAUBECSDebitFormView.html), a drop-in UI component provided by the SDK. `STPAUBECSFormView​` provides a UI for customers to enter their name, email, BSB number, and account number—in addition to displaying the [BECS Direct Debit Terms](https://stripe.com/au-becs/legal). Create an instance of `STPAUBECSFormView​` configured with your company name and set up a delegate for the SDK to notify after the customer enters the required details to create an instance of `STPPaymentMethodParams`​. You can also customize `STPAUBECSFormView​` to match the look and feel of your app by providing values to `STPAUBECSFormView​'s` public properties. #### Swift ```swift import UIKit import StripePaymentsUI class CheckoutViewController: UIViewController { private var becsFormView = STPAUBECSDebitFormView(companyName: "Example Company Inc.") private let saveButton = UIButton() private var setupIntentClientSecret: String? override func viewDidLoad() { super.viewDidLoad() view.backgroundColor = .secondarySystemBackground saveButton.layer.cornerRadius = 5 saveButton.contentEdgeInsets = UIEdgeInsets(top: 4, left: 8, bottom: 4, right: 8) saveButton.backgroundColor = .systemGray3 saveButton.titleLabel?.font = UIFont.systemFont(ofSize: 18) saveButton.setTitle("Save", for: .normal) saveButton.addTarget(self, action: #selector(save), for: .touchUpInside) saveButton.isEnabled = false saveButton.translatesAutoresizingMaskIntoConstraints = false view.addSubview(saveButton) becsFormView.becsDebitFormDelegate = self becsFormView.translatesAutoresizingMaskIntoConstraints = false view.addSubview(becsFormView) NSLayoutConstraint.activate([ becsFormView.leadingAnchor.constraint(equalTo: view.leadingAnchor), view.trailingAnchor.constraint(equalTo: becsFormView.trailingAnchor), becsFormView.topAnchor.constraint(equalToSystemSpacingBelow: view.safeAreaLayoutGuide.topAnchor, multiplier: 2), saveButton.centerXAnchor.constraint(equalTo: view.centerXAnchor), saveButton.topAnchor.constraint(equalToSystemSpacingBelow: becsFormView.bottomAnchor, multiplier: 2), ]) } @objc func save() { // ... } } extension CheckoutViewController: STPAUBECSDebitFormViewDelegate { func auBECSDebitForm(_ form: STPAUBECSDebitFormView, didChangeToStateComplete complete: Bool) { saveButton.isEnabled = complete saveButton.backgroundColor = complete ? .systemBlue : .systemGray3 } } ``` ## Create a SetupIntent [Server-side] A [SetupIntent](https://docs.stripe.com/api/setup_intents.md) 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](https://docs.stripe.com/api/setup_intents.md) on your server with [payment_method_types](https://docs.stripe.com/api/setup_intents/create.md#create_setup_intent-payment_method_types) set to `au_becs_debit` and specify the *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments)’s [id](https://docs.stripe.com/api/customers/object.md#customer_object-id): #### curl ```bash curl https://api.stripe.com/v1/setup_intents \ -u <>: \ -d "payment_method_types[]"="au_becs_debit" \ -d "customer"="{{CUSTOMER_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’ve 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. ## Submit the payment method details to Stripe [Client-side] After the user enters their payment details, confirm the `SetupIntent` to complete saving the debit information. First, assemble a STPSetupIntentConfirmParams object with: 1. The [STPAUBECSFormView’s](https://stripe.dev/stripe-ios/stripe-payments-ui/Classes/STPAUBECSDebitFormView.html) `paymentMethodParams` property 1. The `SetupIntent` client secret from your server Rather than sending the entire `SetupIntent` object to the client, use its [client secret](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-client_secret) from [step 4](https://docs.stripe.com/payments/au-becs-debit/set-up-payment.md#ios-create-setup-intent). This is different from your API keys that authenticate Stripe API requests. The client secret should still be handled carefully because it can complete the setup. Don’t log it, embed it in URLs, or expose it to anyone but the customer. Next, complete the payment by calling the [STPPaymentHandler confirmSetupIntent](https://stripe.dev/stripe-ios/stripe-payments/Classes/STPPaymentHandler.html#/c:objc\(cs\)STPPaymentHandler\(im\)confirmSetupIntent:withAuthenticationContext:completion:) method. Because [customer](https://docs.stripe.com/api/setup_intents/create.md#create_setup_intent-customer) was set, the *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) will be attached to the provided *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) object after a successful setup. This allows you to use the stored PaymentMethod to collect future payments without prompting the customer for payment method details. #### Swift ```swift import UIKit import StripePaymentsUI class CheckoutViewController: UIViewController { // ... @objc func save() { guard let setupIntentClientSecret = setupIntentClientSecret, let paymentMethodParams = becsFormView.paymentMethodParams else { return; } let setupIntentParams = STPSetupIntentConfirmParams(clientSecret: setupIntentClientSecret) setupIntentParams.paymentMethodParams = paymentMethodParams STPPaymentHandler.shared().confirmSetupIntent(withParams: setupIntentParams, authenticationContext: self) { (handlerStatus, setupIntent, error) in switch (handlerStatus) { case .failed: // Setup failed break case .canceled: // Setup canceled break case .succeeded: // Setup succeeded break @unknown default: fatalError() break } } } } extension CheckoutViewController: STPAuthenticationContext { func authenticationPresentingViewController() -> UIViewController { return self } } ``` After confirming the `SetupIntent`​, share the [mandate URL](https://docs.stripe.com/api/mandates/object.md#mandate_object-payment_method_details-au_becs_debit-url) from the [Mandate object](https://docs.stripe.com/api/mandates.md) 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](https://docs.stripe.com/payments/au-becs-debit/accept-a-payment.md) 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 `mandate` on the [SetupIntent object](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-mandate) (included with the `setup_intent.succeeded` event sent after confirmation) or you can [retrieve it through the API](https://docs.stripe.com/api/setup_intents/retrieve.md). ## Test the integration You can test your form using the test BSB number `000000` and one of the test account numbers below with your [STPPaymentHandler confirmSetupIntent](https://stripe.dev/stripe-ios/stripe-payments/Classes/STPPaymentHandler.html#/c:objc\(cs\)STPPaymentHandler\(im\)confirmSetupIntent:withAuthenticationContext:completion:) method call. | BSB Number | Account Number | Description | | ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `000000` | `000123456` | The PaymentIntent created with the resulting PaymentMethod transitions from `processing` to `succeeded`. The mandate status remains `active`. | | `000000` | `900123456` | The PaymentIntent created with the resulting PaymentMethod transitions from `processing` to `succeeded` (with a three-minute delay). The mandate status remains `active`. | | `000000` | `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. | | `000000` | `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. | | `000000` | `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`. | | `000000` | `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`. | | `000000` | `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. | | `000000` | `666666660` | The PaymentIntent created with the resulting PaymentMethod transitions from `processing` to `succeeded`, but a dispute is immediately created. | | `000000` | `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. | | `000000` | `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. | # Android > This is a Android for when payment-ui is mobile and platform is android. View the full page at https://docs.stripe.com/payments/au-becs-debit/set-up-payment?payment-ui=mobile&platform=android. Use [BecsDebitWidget](https://stripe.dev/stripe-android/payments-core/com.stripe.android.view/-becs-debit-widget/index.html), Stripe’s prebuilt BECS payment details collection UI, to create a payment form that lets you securely collect bank details without handling sensitive customer data. You can use the [Setup Intents API](https://docs.stripe.com/payments/setup-intents.md) 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](https://docs.stripe.com/billing/subscriptions/trials.md) ## Set up Stripe [Server-side] [Client-side] First, you need a Stripe account. [Register now](https://dashboard.stripe.com/register). ### Server-side This integration requires endpoints on your server that talk to the Stripe API. Use the official libraries for access to the Stripe API from your server: #### Ruby ```bash # Available as a gem sudo gem install stripe ``` ```ruby # If you use bundler, you can add this line to your Gemfile gem 'stripe' ``` ### Client-side The [Stripe Android SDK](https://github.com/stripe/stripe-android) is open source and [fully documented](https://stripe.dev/stripe-android/). To install the SDK, add `stripe-android` to the `dependencies` block of your [app/build.gradle](https://developer.android.com/studio/build/dependencies) file: #### Kotlin ```kotlin plugins { id("com.android.application") } android { ... } dependencies { // ... // Stripe Android SDK implementation("com.stripe:stripe-android:23.5.0") // Include the financial connections SDK to support US bank account as a payment method implementation("com.stripe:financial-connections:23.5.0") } ``` > For details on the latest SDK release and past versions, see the [Releases](https://github.com/stripe/stripe-android/releases) page on GitHub. To receive notifications when a new release is published, [watch releases for the repository](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository). Configure the SDK with your Stripe [publishable key](https://dashboard.stripe.com/apikeys) so that it can make requests to the Stripe API, such as in your `Application` subclass: #### Kotlin ```kotlin import com.stripe.android.PaymentConfiguration class MyApp : Application() { override fun onCreate() { super.onCreate() PaymentConfiguration.init( applicationContext, "<>" ) } } ``` > Use your [test keys](https://docs.stripe.com/keys.md#obtain-api-keys) while you test and develop, and your [live mode](https://docs.stripe.com/keys.md#test-live-modes) keys when you publish your app. Stripe samples also use [OkHttp](https://github.com/square/okhttp) and [GSON](https://github.com/google/gson) to make HTTP requests to a server. ## Create or retrieve a Customer [Server-side] To reuse a BECS Direct Debit account for future payments, you must attach it to a *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments). 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. ```curl curl -X POST https://api.stripe.com/v1/customers \ -u "<>:" ``` ## Collect payment method details and mandate acknowledgment [Client-side] You can securely collect BECS Debit payment information with [BecsDebitWidget](https://stripe.dev/stripe-android/payments-core/com.stripe.android.view/-becs-debit-widget/index.html), a drop-in UI component provided by the SDK. `BecsDebitWidget` provides a UI for customers to enter their name, email, BSB number, and account number. It also displays the [BECS Direct Debit Terms](https://stripe.com/au-becs/legal). ### Add BecsDebitWidget to your layout Add `BecsDebitWidget` to your layout and configure the `app:companyName` attribute with your company name. ```xml