# Collect physical addresses and phone numbers Learn how to collect customer addresses and phone numbers in your mobile app with the Address Element. # Android To collect complete addresses for billing or shipping, use the [Address Element](https://docs.stripe.com/payments/mobile/address-element.md). You can also use the Address Element to: - Collect customer [phone numbers](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet.addresselement/-address-launcher/-additional-fields-configuration/index.html) - Enable [autocomplete](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet.addresselement/-address-launcher/-configuration/index.html) - Prefill billing information in the Payment Element by passing in a shipping address Stripe combines the collected address information and the payment method to create a *PaymentIntent* (API object that represents your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process). ![Examples of a checkout process where a user selects the Add Shipping Address option. They're then taken to a new screen to add their shipping address into a form (they see auto-complete suggestions as they type in their address).](https://b.stripecdn.com/docs-statics-srv/assets/android-overview.6061212dc737aa700b79242cb5f77782.png) ## Set up Stripe [Server-side] [Client-side] First, you need a Stripe account. [Register now](https://dashboard.stripe.com/register). 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.12.0") // Include the financial connections SDK to support US bank account as a payment method implementation("com.stripe:financial-connections:23.12.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. ## Set up address autocomplete suggestions The address element uses the [Google Places SDK](https://developers.google.com/maps/documentation/places/android-sdk/overview) to fetch address autocomplete suggestions. To enable autocomplete suggestions, you need to include the Google Places SDK dependency to your app’s `build.gradle`. #### Groovy ```groovy dependencies { implementation 'com.google.android.libraries.places:places:2.6.0' } ``` Address autocomplete suggestions requires a Google Places API key. Follow the [Google Places SDK setup guide](https://developers.google.com/maps/documentation/places/android-sdk/cloud-setup) to generate your API key. ## Configure the Address Element You can configure the Address Element with details such as displaying default values, setting allowed countries, customising the appearance, and so on. Refer to [AddressLauncher.Configuration](https://github.com/stripe/stripe-android/blob/master/paymentsheet/src/main/java/com/stripe/android/paymentsheet/addresselement/AddressLauncher.kt#L72) for the complete list of configuration options. ```kotlin val addressConfiguration = AddressLauncher.Configuration.Builder() .additionalFields( AddressLauncher.AdditionalFieldsConfiguration( phone = AddressLauncher.AdditionalFieldsConfiguration.FieldConfiguration.REQUIRED ) ) .allowedCountries(setOf("US", "CA", "GB")) .title("Shipping Address") .googlePlacesApiKey("(optional) YOUR KEY HERE") .build() ``` ## Retrieve address details Retrieve the address details by creating an instance of `AddressLauncher` in the `onCreate` lifecycle method of your `Activity` or `Fragment` and creating a callback method that implements the `AddressLauncherResultCallback` interface. ```kotlin private lateinit var addressLauncher: AddressLauncher private var shippingDetails: AddressDetails? = null override fun onCreate(savedInstanceState: Bundle?) { addressLauncher = AddressLauncher(this, ::onAddressLauncherResult) } private fun onAddressLauncherResult(result: AddressLauncherResult) { // TODO: Handle result and update your UI when (result) { is AddressLauncherResult.Succeeded -> { shippingDetails = result.address } is AddressLauncherResult.Canceled -> { // TODO: Handle cancel } } } ``` The `AddressLauncherResult` can be `Succeeded` or `Canceled`. See more [implementation details](https://github.com/stripe/stripe-android/blob/master/paymentsheet/src/main/java/com/stripe/android/paymentsheet/addresselement/AddressLauncherResult.kt). > Stripe requires that you instantiate the `AddressLauncher` during the `onCreate` lifecycle event and not after. Otherwise, the callback can’t be registered properly, and your app will crash. ## Present the Address Element Present the address element using the address launcher and configuration from the previous steps. ```kotlin addressLauncher.present( publishableKey = publishableKey, configuration = addressConfiguration ) ``` ## Optional: Pre-fill shipping addresses in the Payment Element If you use the mobile Payment Element, set [PaymentSheet.Configuration.shippingDetails](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html) to the address collected by the address element. When `shippingDetails` is populated, users have their billing address prefilled and they see a **Billing address is the same as shipping** tick box. Confirmed PaymentIntents with `shippingDetails` populated also have the [shipping](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-shipping) intent property populated when the PaymentIntent is confirmed ```kotlin val configuration = PaymentSheet.Configuration.Builder("Example, Inc.") // ... .shippingDetails(shippingDetails) .build() ``` ## Optional: Customise the appearance Now that you’ve added the Address Element to your app, you can customise the appearance to fit with the design of the rest of your app. You can configure the appearance with the [Appearance API](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=android) using [AddressLauncher.Configuration.appearance](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet.addresselement/-address-launcher/-configuration/index.html). ## Optional: Set default billing details To set default values for billing details collected in the payment sheet, configure the `defaultBillingDetails` property. The `PaymentSheet` pre-populates its fields with the values that you provide. #### Kotlin ```kotlin val address = PaymentSheet.Address(country = "US") val billingDetails = PaymentSheet.BillingDetails( address = address, email = "foo@bar.com" ) val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "Merchant, Inc.") .defaultBillingDetails(billingDetails) .build() ``` ## Optional: Customise billing details collection ### Configure collection of billing details Use `BillingDetailsCollectionConfiguration` to specify how you want to collect billing details in the PaymentSheet. You can collect your customer’s name, email, phone number, and address. If you want to attach default billing details to the PaymentMethod object even when those fields aren’t collected in the UI, set `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` to `true`. #### Kotlin ```kotlin val billingDetails = PaymentSheet.BillingDetails( email = "foo@bar.com" ) val billingDetailsCollectionConfiguration = BillingDetailsCollectionConfiguration( attachDefaultsToPaymentMethod = true, name = BillingDetailsCollectionConfiguration.CollectionMode.Always, email = BillingDetailsCollectionConfiguration.CollectionMode.Never, address = BillingDetailsCollectionConfiguration.AddressCollectionMode.Full, ) val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "Merchant, Inc.") .defaultBillingDetails(billingDetails) .billingDetailsCollectionConfiguration(billingDetailsCollectionConfiguration) .build() ``` > Consult with your legal counsel regarding laws that apply to collecting information. Only collect phone numbers if you need them for the transaction.