Billing address

Learn how to configure the billing address component.

Basic usage

Minimal configuration

The billing address component is a pre-built form that collects country, postcode, and street address. At minimum, you can create it with default settings:

import SwiftUI
import PXPCheckoutSDK

let pxpCheckout = try PxpCheckout.initialize(config: checkoutConfig)

let config = BillingAddressComponentConfig()
let billing = try pxpCheckout.create(.billingAddress, componentConfig: config) as! BillingAddressComponent

billing.buildContent()

By default, the component includes a checkbox that allows customers to use their shipping address for billing. To enable this, implement CheckoutConfig.onGetShippingAddress to provide the shipping address. See Pre-fill billing address checkbox.

Advanced configuration

You can customise the container styling, field appearance, and individual field configurations:

var countryConfig = CountrySelectionComponentConfig(
    label: "Country",
    placeholder: "Select country",
    accessibilityLabel: "Billing country"
)
countryConfig.validationOnBlur = true

var postcodeConfig = PostcodeComponentConfig(
    label: "Postcode",
    placeholder: "Enter postcode"
)

var addressConfig = AddressComponentConfig(
    label: "Street address",
    placeholder: "123 Main St",
    guideText: "Include unit or flat if needed"
)

var prefillConfig = PrefillBillingAddressCheckboxComponentConfig(
    label: "Use shipping address for billing",
    checked: false
)

let config = BillingAddressComponentConfig(
    styles: ContainerStyle(
        backgroundColor: Color(.secondarySystemBackground),
        borderRadius: 12,
        padding: EdgeInsets(top: 16, leading: 16, bottom: 16, trailing: 16)
    ),
    inputStyles: FieldInputStateStyles(
        base: FieldInputStyle(
            fontSize: 16,
            borderColor: Color(.separator),
            borderWidth: 1,
            cornerRadius: 8
        ),
        active: FieldInputStyle(borderColor: .accentColor, borderWidth: 2)
    ),
    labelStyles: FieldLabelStateStyles(
        base: FieldLabelStyle(font: .subheadline.weight(.semibold))
    ),
    fields: BillingAddressComponentFields(
        countrySelection: countryConfig,
        postcode: postcodeConfig,
        address: addressConfig,
        prefillBillingAddressCheckbox: prefillConfig
    ),
    allowPrefillBillingAddress: true,
    displayRequiredIcon: true
)

let billing = try pxpCheckout.create(.billingAddress, componentConfig: config) as! BillingAddressComponent

Property	Description
`styles` ContainerStyle?	The container styling for the billing address form. Defaults to `nil`. Properties: `backgroundColor` (Color?), `borderColor` (Color?), `borderWidth` (CGFloat?), `cornerRadius` (CGFloat?), `padding` (EdgeInsets?), `margin` (EdgeInsets?), `opacity` (Double? - 0.0 to 1.0), `shadow` (ShadowStyle?).
`inputStyles` FieldInputStateStyles?	The shared input styling applied to country, postcode, and address fields when not individually configured. Defaults to `nil`. States: `base` (default unfocused), `active` (focused), `valid` (has valid value), `invalid` (has invalid value). Each state supports: `color`, `placeholderColor`, `fontWeight`, `fontSize`, `backgroundColor`, `borderColor`, `borderWidth`, `cornerRadius`, `padding`, `minHeight`.
`labelStyles` FieldLabelStateStyles?	The shared label styling applied to country, postcode, and address fields when not individually configured. Defaults to `nil`. States: `base` (default), `active` (focused), `valid` (has valid value), `invalid` (has invalid value). Each state supports: `color`, `font`. Additional property: `minWidth` (CGFloat? - default: 80).
`fields` BillingAddressComponentFields?	The configuration for individual child components (country, postcode, address, and pre-fill checkbox). Defaults to `nil`.
`fields.countrySelection` CountrySelectionComponentConfig?	The country dropdown configuration. See Country selection. Defaults to `nil`.
`fields.postcode` PostcodeComponentConfig?	The postcode or ZIP field configuration. See Postcode. Defaults to `nil`.
`fields.address` AddressComponentConfig?	The street address line configuration. See Address. Defaults to `nil`.
`fields.prefillBillingAddressCheckbox` PrefillBillingAddressCheckboxComponentConfig?	The pre-fill checkbox configuration. See Pre-fill billing address checkbox. Defaults to `nil`.
`allowPrefillBillingAddress` Bool?	Whether to include the pre-fill checkbox. Set to `false` to hide it. Defaults to `true`.
`displayRequiredIcon` Bool?	Whether to display the required indicators on child fields. Defaults to `nil`.

Individual field configurations take precedence over shared styling. For example, if you set inputStyles on a specific field config, it will override the billing address component's inputStyles for that field.

Styling

You can customise the appearance of the billing address component and its child fields:

config.styles = ContainerStyle(
    backgroundColor: Color(.secondarySystemBackground),
    borderRadius: 12,
    padding: EdgeInsets(top: 16, leading: 16, bottom: 16, trailing: 16)
)

config.inputStyles = FieldInputStateStyles(
    base: FieldInputStyle(
        fontSize: 16,
        borderColor: Color(.separator),
        borderWidth: 1,
        cornerRadius: 8
    ),
    active: FieldInputStyle(borderColor: .accentColor, borderWidth: 2)
)

config.labelStyles = FieldLabelStateStyles(
    base: FieldLabelStyle(font: .subheadline.weight(.semibold))
)

Event handling

The billing address component doesn't have its own event handlers. Instead, configure event handlers on individual child fields through the fields property:

var countryConfig = CountrySelectionComponentConfig()
countryConfig.onChange = { /* handle country change */ }
countryConfig.onValidationPassed = { _ in /* handle validation */ }

var postcodeConfig = PostcodeComponentConfig()
postcodeConfig.onChange = { /* handle postcode change */ }

var addressConfig = AddressComponentConfig()
addressConfig.onChange = { /* handle address change */ }

config.fields = BillingAddressComponentFields(
    countrySelection: countryConfig,
    postcode: postcodeConfig,
    address: addressConfig
)

For more information about event patterns, see Events.

Methods

`buildContent()`

Returns SwiftUI content for the billing address form:

billing.buildContent()

Examples

Disable pre-fill

Hide the pre-fill checkbox:

var config = BillingAddressComponentConfig()
config.allowPrefillBillingAddress = false
let billing = try pxpCheckout.create(.billingAddress, componentConfig: config) as! BillingAddressComponent

With shipping callback for pre-fill

Configure the checkout with a shipping address callback to enable pre-fill:

let checkoutConfig = CheckoutConfig(
    environment: .test,
    session: sessionData,
    transactionData: transactionData,
    merchantShopperId: "shopper-1",
    ownerId: "owner-id",
    onGetShippingAddress: {
        ShippingAddress(
            countryCode: "GB",
            postalCode: "SW1A 1AA",
            address: "10 Downing Street"
        )
    }
)

let pxpCheckout = try PxpCheckout.initialize(config: checkoutConfig)
let billing = try pxpCheckout.create(.billingAddress, componentConfig: BillingAddressComponentConfig()) as! BillingAddressComponent

With card submit (AVS)

Integrate billing address with card submit for address verification:

var billingConfig = BillingAddressComponentConfig()
let billing = try pxpCheckout.create(.billingAddress, componentConfig: billingConfig) as! BillingAddressComponent

var submitConfig = CardSubmitComponentConfig()
submitConfig.avsRequest = true
submitConfig.billingAddressComponents = BillingAddressComponents(
    billingAddressComponent: billing
)
submitConfig.onPreAuthorisation = { _ in TransactionInitiationData() }
submitConfig.onPostAuthorisation = { _ in }

let submit = try pxpCheckout.create(.cardSubmit, componentConfig: submitConfig) as! CardSubmitComponent

VStack(spacing: 16) {
    billing.buildContent()
    submit.buildContent()
}

For validation details on the child fields, see Data validation and Implementation.