Render Billing Address in Payment Form

Some merchants prefer to streamline their checkout process by consolidating billing information directly within the payment form rather than displaying separate billing fields on the checkout page. This approach can reduce form complexity and provide a more cohesive payment experience by keeping all payment-related information in one location.

This code sample shows how to configure the Stripe payment form to automatically render billing address fields, allowing you to hide the standard WooCommerce billing fields while still collecting all necessary customer information.

When would you use this?

This approach is particularly useful for merchants who want to simplify their checkout page design or create a more streamlined payment flow. Instead of having billing address fields scattered across the checkout page, everything is contained within the Stripe payment element.

Common use cases include creating a minimalist checkout design where the payment form handles all billing details, reducing visual clutter on mobile devices by consolidating form fields, or maintaining consistency when the payment form is the primary focus of the checkout experience.

The Code

This example configures both the credit card payment form and the unified payment method checkout to render billing address fields automatically within the Stripe payment element:

/**
 * Configure credit card payment form to show billing address fields
 * @param array $data Localized script data for credit card payments
 * @return array Modified script data
 */
add_filter('wc_stripe_localize_script_credit-card', function($data){
	$data['paymentElementOptions'] = [
		'fields' => [
			'billingDetails' => [
				'address' => 'auto'
			]
		]
	];
	return $data;
});

/**
 * Configure unified payment method checkout to show billing address fields
 * @param array $data Localized script data for UPM checkout
 * @return array Modified script data
 */
add_filter('wc_stripe_localize_script_upm-checkout', function($data){
	$data['paymentElementOptions']['fields'] = [
		'billingDetails' => [
			'address' => 'auto'
		]
	];
	return $data;
});

Payment form showing billing address fields rendered within the Stripe payment element

How the Code Works

The code uses two different filters to configure billing address rendering for different Stripe payment scenarios. The first filter (wc_stripe_localize_script_credit-card) applies to traditional credit card payments, while the second filter (wc_stripe_localize_script_upm-checkout) handles the unified payment method checkout that supports multiple payment types.

Both filters modify the paymentElementOptions configuration that gets passed to Stripe's JavaScript SDK. The billingDetails.address setting is set to 'auto', which tells Stripe to automatically determine when to show billing address fields based on the payment method requirements and merchant configuration.

When enabled, Stripe will render billing address fields directly within the payment form, including fields for street address, city, state/province, postal code, and country. The fields will automatically adapt based on the customer's selected country to show the appropriate format and required fields.

Customizing Address Field Behavior

You can customize how billing address fields appear and behave by modifying the configuration options:

Always show address fields:

$data['paymentElementOptions'] = [
	'fields' => [
		'billingDetails' => [
			'address' => 'required'
		]
	]
];

Never show address fields:

$data['paymentElementOptions'] = [
	'fields' => [
		'billingDetails' => [
			'address' => 'never'
		]
	]
];

Include additional billing details:

$data['paymentElementOptions'] = [
	'fields' => [
		'billingDetails' => [
			'address' => 'auto',
			'name' => 'auto',
			'email' => 'auto',
			'phone' => 'auto'
		]
	]
];

Testing Your Implementation

To verify the billing address fields are appearing correctly, test the checkout process with different payment methods and customer scenarios. The fields should appear automatically when required and remain hidden when not needed.

Check your order details after completing test transactions to ensure billing address information is being captured and stored correctly, even though it's collected through the Stripe payment form rather than standard WooCommerce fields.

Consider testing with international addresses to verify that the fields adapt appropriately for different countries and address formats.