# 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.414fc754c90afc0ec42840299c12022d.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.15.0") // Include the financial connections SDK to support US bank account as a payment method implementation("com.stripe:financial-connections:23.15.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. ## Configure the Address Element You can configure the Address Element with details such as displaying default values, setting allowed countries, customizing 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") .build() ``` The Address Element initially displays a single address field. As your customer types, matching suggestions appear inline. When they select a suggestion, the Address Element populates the address form. ## 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: Prefill 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** checkbox. 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: Customize the appearance Now that you’ve added the Address Element to your app, you can customize 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: Customize 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. ## Optional: Customize autocomplete countries By default, autocomplete suggestions are available for all Stripe-supported countries. To limit autocomplete to specific countries, provide their two-letter country codes with `autocompleteCountries`: ```kotlin val addressConfiguration = AddressLauncher.Configuration.Builder() .autocompleteCountries(setOf("US", "CA", "GB")) .build() ``` This setting only controls where autocomplete suggestions appear. It doesn’t limit the countries customers can select in the address form. To limit country selection, use `allowedCountries`. Customers can enter their address manually when autocomplete isn’t available.