# Configuration

Learn how to configure the Aeropay button component for Android.

## Basic usage

### Minimal configuration

At minimum, the Aeropay button requires an Aeropay-enabled session and valid transaction data on SDK initialisation. You can then create the component with its default presentation.

Configure `onPreAuthorisation` and return `true` when the transaction can proceed so shoppers can complete payment. If you omit the callback, submission doesn't proceed and the popup stays open.

```kotlin
import com.pxp.checkout.components.aeropaybutton.types.AeropayButtonComponentConfig
import com.pxp.checkout.types.ComponentType

val config = AeropayButtonComponentConfig().apply {
    onPreAuthorisation = { true }
    onPostAuthorisation = { result ->
        verifyPaymentOnBackend(result)
    }
    onError = { error ->
        // Handle flow errors using error.errorCode and error.message
    }
}

val aeropayButton = checkout.createComponent(
    ComponentType.AERO_PAY_BUTTON,
    config,
)
```

Always verify the transaction on your backend before fulfilling an order or confirming a payout. Client callbacks can be manipulated by malicious users.

### Related SDK configuration

Configure the session and transaction before creating the Aeropay button:

```kotlin
import com.pxp.checkout.models.Environment
import com.pxp.checkout.models.EntryType
import com.pxp.checkout.models.PxpSdkConfig
import com.pxp.checkout.models.TransactionData
import com.pxp.checkout.models.TransactionIntentData
import com.pxp.checkout.models.AeropayIntentType
import com.pxp.checkout.services.models.transaction.Shopper
import java.time.Instant

val sdkConfig = PxpSdkConfig(
    environment = Environment.TEST,
    session = sessionConfig,
    transactionData = TransactionData(
        amount = 25.00,
        currency = "USD",
        entryType = EntryType.Ecom,
        intent = TransactionIntentData(aeropay = AeropayIntentType.Authorisation),
        merchant = "your-merchant-id",
        merchantTransactionId = java.util.UUID.randomUUID().toString(),
        merchantTransactionDate = { Instant.now().toString() },
    ),
    clientId = "your-client-id",
    ownerType = "MerchantGroup",
    ownerId = "MERCHANT_GROUP_1",
    onGetShopper = {
        Shopper(
            id = "shopper-123",
            firstName = "John",
            lastName = "Doe",
            email = "john.doe@example.com",
            phoneNumber = "+14155550123",
        )
    },
)
```

The following SDK options affect the Aeropay component:

| Property | Description |
|  --- | --- |
| `session`SessionConfig | Session data from your backend. It must include `allowedFundingTypes.payByBanks.aeropay` with non-blank `externalMerchantId` and `configurationId`. |
| `ownerId`string | Your merchant group identifier. |
| `transactionData.currency`string | The transaction currency. Aeropay supports `USD`. |
| `transactionData.entryType`EntryType | The transaction entry type. Set this to `EntryType.Ecom`. |
| `transactionData.intent.aeropay`AeropayIntentType | Aeropay transaction intent. Possible values:- `Authorisation`
- `Purchase`
- `EstimatedAuthorisation`
- `Payout`

 |
| `onGetShopper`() -> Shopper? | Optional. When set, supplies shopper details to prefill the consumer data screen (`firstName`, `lastName`, `email`, `phoneNumber`). Required for `skipConsumerDataCollection`. |


## Component properties

Use these properties when configuring `AeropayButtonComponentConfig`:

| Property | Description |
|  --- | --- |
| `userId`String? | A verified Aeropay user ID. The SDK validates that the user is active, then skips consumer data collection and OTP verification. |
| `skipConsumerDataCollection`Boolean | When `true`, skips the consumer data screen if `onGetShopper` supplies all four required fields and `editableFields` is omitted, `null`, or empty. Defaults to `false`. |
| `label`String? | Custom text for the payment button when the intent isn't `Payout`. If omitted, the SDK uses `PxpSdkConfig.localisation?.aeropay?.payByBankButton?.label`, or the default (en-US: `Pay by bank`). For `Payout`, `label` is ignored. Override payout text with `PxpSdkConfig.localisation?.aeropay?.payByBankButton?.labelPayout` (en-US default: `Withdraw by Bank`). |
| `disabled`Boolean | Whether the payment button starts disabled. Defaults to `false`. After creation, call `setDisabled()` to change the button state. |
| `styles`ButtonStateStyles? | Styles for the payment button. See [Button styles](#button-styles). |
| `popupConfig`AeropayPopupConfig? | Styles for the popup container, shared action buttons, and intro cards. |
| `consumerDataCollectionConfig`ConsumerDataCollectionConfig? | Field behaviour and styling for the consumer data screen. |
| `otpVerificationConfig`OtpVerificationConfig? | Styling for the OTP verification screen. |
| `bankSelectionConfig`BankSelectionConfig? | Behaviour and styling for bank selection and the Aerosync experience. |


To override pay or payout button text through localisation:

```kotlin
localisation = LocalisationConfig(
    aeropay = AeropayLocalisation(
        payByBankButton = AeropayPayByBankButtonLocalisation(
            label = "Pay with my bank",
            labelPayout = "Withdraw to bank",
        ),
    ),
)
```

## Shopper flow configuration

### New shoppers

Don't set `userId` when the shopper doesn't have a verified Aeropay account. `onGetShopper` is optional on `PxpSdkConfig`. When omitted, the consumer data screen opens with empty fields. When set, the SDK can prefill `firstName`, `lastName`, `email`, and `phoneNumber`. Prefill and `skipConsumerDataCollection` depend on `onGetShopper` returning those four values.

```kotlin
val config = AeropayButtonComponentConfig().apply {
    onUserVerificationSuccess = { user ->
        saveAeropayUserId(user.id)
    }
}
```

Store `user.id` securely after verification so you can identify the shopper on future visits.

### Skip consumer data collection

Set `skipConsumerDataCollection` to `true` to start the new-shopper flow at OTP verification:

```kotlin
val sdkConfig = PxpSdkConfig(
    // ...session and transaction configuration
    onGetShopper = {
        Shopper(
            firstName = "John",
            lastName = "Doe",
            email = "john.doe@example.com",
            phoneNumber = "+14155550123",
        )
    },
)

val config = AeropayButtonComponentConfig().apply {
    skipConsumerDataCollection = true
}
```

The component skips the consumer data screen only when all of these conditions are met:

* `onGetShopper` returns valid, non-empty `firstName`, `lastName`, `email`, and `phoneNumber` values.
* `skipConsumerDataCollection` is `true`.
* `consumerDataCollectionConfig.editableFields` is omitted, `null`, or empty.


If a value is missing or empty, or `editableFields` contains a field, the component shows the consumer data screen. If a supplied non-empty value is invalid, the SDK calls `onError` with `SDK1300` and doesn't open the popup.

### Returning shoppers

Pass a verified Aeropay user ID to skip data collection and OTP verification:

```kotlin
val config = AeropayButtonComponentConfig().apply {
    userId = "c7582e95-d9a1-42c3-b0e3-ee6bc98764ec"
}
```

If the user isn't active, `onError` receives `SDK1307`. If the get-user API returns a recognised failure (including user not found), `onError` receives `SDK1308`. Network or transport errors on the same call use `SDK0500` or `SDK0000`. The popup doesn't open in these cases. See [Returning-shopper validation](/guides/checkout/components/android/aeropay/data-validation#returning-shopper-validation).

## Popup configuration

Use `popupConfig` to customise the popup container, shared action buttons, and intro cards:

```kotlin
config.popupConfig = AeropayPopupConfig(
    styles = AeropayViewStyleConfig(
        fontFamily = "Source Code Pro",
        foregroundColor = Color.Black,
        backgroundColor = Color.White,
        cornerRadius = 20.dp,
        padding = PaddingValues(16.dp),
    ),
    actionButtonStyles = ButtonStateStyles(
        base = FieldStyle(
            backgroundColor = Color(0xFF2F3BFF),
            color = Color.White,
        ),
    ),
    introStyles = ScreenIntroStyleConfig(
        backgroundColor = Color(0xFFDBEDFA),
        cornerRadius = 12.dp,
    ),
)
```

Configure the popup with these properties:

| Property | Description |
|  --- | --- |
| `styles`AeropayViewStyleConfig? | Popup container styles for font, colours, border, corner radius, and padding. |
| `actionButtonStyles`ButtonStateStyles? | Shared styles for action buttons on popup screens. Screen-level button styles override these values. |
| `introStyles`ScreenIntroStyleConfig? | Styles for the intro card on the consumer data and OTP screens. |


## Consumer data configuration

Use `consumerDataCollectionConfig` to control which prefilled fields remain editable and to customise the form:

```kotlin
config.consumerDataCollectionConfig = ConsumerDataCollectionConfig(
    editableFields = listOf(
        ConsumerDataField.EMAIL,
        ConsumerDataField.PHONE_NUMBER,
    ),
    fieldConfig = ConsumerDataFieldConfig(
        labelStyles = FieldLabelStateStyles(
            base = FieldLabelStyle(color = Color(0xFF333333)),
        ),
        inputStyles = FieldInputStateStyles(
            base = FieldInputStyle(borderColor = Color(0xFFCCCCCC)),
            invalid = FieldInputStyle(borderColor = Color(0xFFD32F2F)),
        ),
        invalidTextStyle = FieldMessageStyle(color = Color(0xFFD32F2F)),
        phoneNumberGuideTextStyle = FieldMessageStyle(fontSize = 12f),
    ),
    buttonStyles = ButtonStateStyles(
        base = FieldStyle(backgroundColor = Color(0xFF2F3BFF)),
    ),
)
```

The consumer data screen supports these properties:

| Property | Description |
|  --- | --- |
| `editableFields`List<ConsumerDataField>? | Prefilled fields that the shopper can edit. When `null` or empty, prefilled fields are read-only. Possible values:- `FIRST_NAME`
- `LAST_NAME`
- `EMAIL`
- `PHONE_NUMBER`

 |
| `fieldConfig.labelStyles`FieldLabelStateStyles? | Label styles for the base, valid, and invalid states. |
| `fieldConfig.inputStyles`FieldInputStateStyles? | Input styles for the base, valid, and invalid states. |
| `fieldConfig.invalidTextStyle`FieldMessageStyle? | Styles for validation messages. |
| `fieldConfig.phoneNumberGuideTextStyle`FieldMessageStyle? | Styles for the phone number guidance text. |
| `buttonStyles`ButtonStateStyles? | Styles for the screen's action button. |


Fields returned by `onGetShopper` are disabled by default. Add a field to `editableFields` if the shopper needs to change its value.

## OTP verification configuration

Use `otpVerificationConfig` to customise the OTP inputs, validation message, and action button:

```kotlin
config.otpVerificationConfig = OtpVerificationConfig(
    inputStyles = FieldInputStateStyles(
        base = FieldInputStyle(
            borderColor = Color.Gray,
            cornerRadius = 8.dp,
        ),
        active = FieldInputStyle(
            borderColor = Color.Blue,
            borderWidth = 2.dp,
        ),
        invalid = FieldInputStyle(borderColor = Color.Red),
    ),
    invalidTextStyles = FieldMessageStyle(color = Color(0xFFD32F2F)),
    buttonStyles = ButtonStateStyles(
        base = FieldStyle(backgroundColor = Color(0xFF2F3BFF)),
    ),
)
```

Configure the OTP verification screen with these properties:

| Property | Description |
|  --- | --- |
| `inputStyles`FieldInputStateStyles? | Styles for each OTP input in the base, active, and invalid states. |
| `invalidTextStyles`FieldMessageStyle? | Styles for the validation message below the OTP inputs. |
| `buttonStyles`ButtonStateStyles? | Styles for the verification button. |


## Bank selection configuration

Use `bankSelectionConfig` to customise bank selection and the embedded Aerosync experience:

```kotlin
config.bankSelectionConfig = BankSelectionConfig(
    payButtonStyles = ButtonStateStyles(
        base = FieldStyle(backgroundColor = Color(0xFF2F3BFF)),
    ),
    linkBankButtonStyles = ButtonStateStyles(
        base = FieldStyle(
            backgroundColor = Color.White,
            color = Color(0xFF2F3BFF),
        ),
    ),
    bankSelectedIndicatorColor = Color(0xFF2F3BFF),
    bankItemStyles = BankItemStateStyles(
        base = BankItemStyle(
            bankNameStyle = BankItemTextStyle(fontSize = 16f),
        ),
        selected = BankItemStyle(
            containerStyle = BankItemContainerStyle(
                backgroundColor = Color(0xFFDBEDFA),
            ),
        ),
    ),
    excludedBankAccountIds = listOf(1895986, 1895988),
    allowLinkBankOnPayout = false,
    aerosyncTheme = AerosyncTheme.LIGHT,
)
```

Configure the bank selection screen with these properties:

| Property | Description |
|  --- | --- |
| `payButtonStyles`ButtonStateStyles? | Styles for the pay or withdraw button. |
| `linkBankButtonStyles`ButtonStateStyles? | Styles for the link-bank button. |
| `bankSelectedIndicatorColor`Color? | Accent colour for the selected-bank indicator. When `bankItemStyles` isn't set, the SDK can derive bank item styles from this colour. |
| `bankItemStyles`BankItemStateStyles? | Styles for funding bank list items in the base and selected states. |
| `excludedBankAccountIds`List<Number>? | Bank account IDs to hide from the linked-banks list (e.g., `listOf(1895986, 1895988)`). When omitted or empty, all linked accounts are shown. |
| `allowLinkBankOnPayout`Boolean | Whether to show the link-bank button for `Payout` transactions. Defaults to `false`. |
| `aerosyncTheme`AerosyncTheme? | Theme for the embedded Aerosync widget. Use `AerosyncTheme.LIGHT` or `AerosyncTheme.DARK`. When omitted, the SDK resolves light theme. |


## Button styles

The top-level `styles` property and each screen's button style property use `ButtonStateStyles`:

```kotlin
val buttonStyles = ButtonStateStyles(
    base = FieldStyle(
        backgroundColor = Color(0xFF2F3BFF),
        color = Color.White,
        cornerRadius = 8.dp,
        padding = PaddingValues(horizontal = 16.dp, vertical = 14.dp),
    ),
    disabled = FieldStyle(
        backgroundColor = Color(0xFF2F3BFF).copy(alpha = 0.5f),
    ),
)
```

Configure button states with these properties:

| Property | Description |
|  --- | --- |
| `base`FieldStyle? | Styles for the default state. |
| `disabled`FieldStyle? | Styles applied when the button is disabled. |
| `loading`FieldStyle? | Styles applied while the button is in a loading state. |


## Event handling

Configure callbacks on the component to respond to shopper actions, validation, verification, transaction submission, and errors:

```kotlin
val config = AeropayButtonComponentConfig().apply {
    onClick = {
        clearPaymentErrors()
    }
    onCustomValidation = {
        // Must return Boolean; e.g. a ready-state flag or a function that returns Boolean
        checkoutReady
    }
    onUserVerificationSuccess = { user ->
        saveAeropayUserId(user.id)
    }
    onCancel = {
        resetCheckoutState()
    }
    onPreAuthorisation = { true }
    onPostAuthorisation = { result ->
        verifyPaymentOnBackend(result)
    }
    onSubmitError = { error ->
        // Handle FailedSubmitResult from transaction submission
    }
    onError = { error ->
        // Handle BaseSdkException from the Aeropay flow
    }
}
```

The component supports these callbacks:

| Callback | Description |
|  --- | --- |
| `onClick`() -> Unit | Called when the shopper taps the Aeropay button, before custom validation and popup opening. |
| `onCustomValidation`suspend () -> Boolean | Called after `onClick`. Return `true` to continue or `false` to stop before the Aeropay flow starts. |
| `onUserVerificationSuccess`(AeropayUser) -> Unit | Called after OTP verification succeeds. Store `user.id` for returning-shopper flows. |
| `onCancel`() -> Unit | Called when the shopper dismisses the popup. Programmatic dismissal after a successful payment doesn't invoke it. |
| `onPreAuthorisation`suspend () -> Boolean | Called before transaction submission. Return `true` to submit, or `false` to stop. If the callback is omitted, submission doesn't proceed and the popup stays open. |
| `onPostAuthorisation`(MerchantSubmitResult) -> Unit | Called after the transaction is submitted successfully. |
| `onSubmitError`(BaseSubmitResult) -> Unit | Called when transaction submission fails. At runtime, failed responses typically use `FailedSubmitResult`. |
| `onError`(BaseSdkException) -> Unit | Called when an SDK or provider error occurs during the Aeropay flow outside successful or failed transaction submission. |


For callback payloads and handling guidance, see [Events](/guides/checkout/components/android/aeropay/events).

## Methods

### `Content()`

Render the Aeropay button in your Compose UI:

```kotlin
aeropayButton.Content(modifier = Modifier.fillMaxWidth())
```

Create the component through `checkout.createComponent(ComponentType.AERO_PAY_BUTTON, config)`. Direct instantiation isn't supported.