# Configuration

Learn how to configure the Aeropay button component for Web.

## 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:

```typescript
import { PxpCheckout, IntentType, AeropayButtonComponent, AeropayButtonComponentConfig } from '@pxpio/web-components-sdk';

const config: AeropayButtonComponentConfig = {
  onPreAuthorisation: () => true,
  onPostAuthorisation: (result) => {
    const submitResult = result as {
      merchantTransactionId: string;
      systemTransactionId: string;
    };
    verifyPaymentOnBackend({
      merchantTransactionId: submitResult.merchantTransactionId,
      systemTransactionId: submitResult.systemTransactionId
    });
  },
  onError: (error) => {
    console.error('Aeropay error:', error);
  }
};

const aeropayButton = pxpSdk.create('aeropay-button', config);
```

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

### Related SDK configuration

Configure the session and transaction before creating the Aeropay button:

```typescript
const pxpSdk = PxpCheckout.initialize({
  environment: 'test',
  session: sessionData,
  ownerId: 'MERCHANT_GROUP_1',
  ownerType: 'MerchantGroup',
  transactionData: {
    currency: 'USD',
    amount: 25,
    entryType: 'Ecom',
    intent: {
      aeropay: IntentType.Authorisation
    },
    merchantTransactionId: crypto.randomUUID(),
    merchantTransactionDate: () => new Date().toISOString()
  },
  onGetShopper: () => Promise.resolve({
    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`SessionData | Session data from your backend. It must include Aeropay in `allowedFundingTypes`. |
| `ownerId`string | Your merchant group identifier. |
| `transactionData.currency`string | Transaction currency. Aeropay supports `USD`. |
| `transactionData.entryType`string | Transaction entry type. Set this to `Ecom`. |
| `transactionData.intent.aeropay`IntentType | Aeropay transaction intent. Supported values are `Authorisation`, `Purchase`, `EstimatedAuthorisation`, and `Payout`. |
| `onGetShopper`() => Promise<Shopper> | Supplies shopper details for the new-shopper flow. The component can prefill `firstName`, `lastName`, `email`, and `phoneNumber`. |


## Component properties

Use these properties when calling `pxpSdk.create('aeropay-button', config)`:

| 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 or empty. Defaults to `false`. |
| `label`string | Custom text for the payment button on Authorisation, Purchase, and EstimatedAuthorisation intents. If omitted, the SDK uses the localised default payment label (e.g., `Pay by bank`). For `Payout`, the SDK uses the localised payout label (e.g., `Withdraw by Bank`) and ignores `label`. |
| `disabled`boolean | Whether the payment button is disabled. Defaults to `false`. |
| `className`string | A custom CSS class applied to the payment button. |
| `styles`ButtonComponentStyles | Styles for the payment button. See [Button styles](#button-styles). |
| `popupConfig`AeropayPopupConfig | Styles and CSS configuration for the popup container. |
| `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. |


## Shopper flow configuration

### New shoppers

Don't set `userId` when the shopper doesn't have a verified Aeropay account. The SDK uses `onGetShopper` to prefill the consumer data screen:

```typescript
import { PxpCheckout, IntentType, AeropayButtonComponent, AeropayButtonComponentConfig } from '@pxpio/web-components-sdk';

const config: AeropayButtonComponentConfig = {
  onUserVerificationSuccess: (user) => {
    saveAeropayUserId(user.id);
  }
};

const aeropayButton = pxpSdk.create('aeropay-button', config);
```

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:

```typescript
const pxpSdk = PxpCheckout.initialize({
  // ...session and transaction configuration
  onGetShopper: () => Promise.resolve({
    firstName: 'John',
    lastName: 'Doe',
    email: 'john.doe@example.com',
    phoneNumber: '+14155550123'
  })
});

const aeropayButton = pxpSdk.create('aeropay-button', {
  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 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:

```typescript
const aeropayButton = pxpSdk.create('aeropay-button', {
  userId: 'c7582e95-d9a1-42c3-b0e3-ee6bc98764ec'
});
```

If the user doesn't exist or isn't active, the component calls `onError` and doesn't open the popup.

## Popup configuration

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

```typescript
const aeropayButton = pxpSdk.create('aeropay-button', {
  popupConfig: {
    className: 'checkout-popup',
    styles: {
      backgroundColor: '#ffffff'
    },
    actionButtonStyles: {
      base: {
        backgroundColor: '#2f3bff',
        color: '#ffffff'
      },
      hover: {
        opacity: 0.9
      }
    }
  }
});
```

Configure the popup with these properties:

| Property | Description |
|  --- | --- |
| `styles`CSSProperties | Inline styles applied to the popup container. |
| `className`string | A custom CSS class applied to the popup. |
| `actionButtonStyles`ButtonComponentStyles | Shared styles for action buttons on all popup screens. Screen-level button styles override these values. |


## Consumer data configuration

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

```typescript
const aeropayButton = pxpSdk.create('aeropay-button', {
  consumerDataCollectionConfig: {
    editableFields: ['email', 'phoneNumber'],
    fieldConfig: {
      labelStyles: {
        base: { color: '#333333' }
      },
      inputStyles: {
        base: { borderColor: '#cccccc' },
        invalid: { borderColor: '#d32f2f' }
      },
      invalidTextStyles: {
        color: '#d32f2f'
      },
      phoneNumberGuideTextStyle: {
        fontSize: '12px'
      }
    },
    buttonStyles: {
      base: { backgroundColor: '#2f3bff' }
    }
  }
});
```

The consumer data screen supports these properties:

| Property | Description |
|  --- | --- |
| `editableFields`ConsumerDataField[] | Prefilled fields that the shopper can edit. Possible values are `firstName`, `lastName`, `email`, and `phoneNumber`. |
| `fieldConfig.labelStyles`StateStyles | Label styles for the base, valid, and invalid states. |
| `fieldConfig.inputStyles`StateStyles | Input styles for the base, valid, and invalid states. |
| `fieldConfig.invalidTextStyles`CSSProperties | Styles for validation messages. |
| `fieldConfig.phoneNumberPrefixStyle`CSSProperties | Styles for the phone number country prefix. |
| `fieldConfig.phoneNumberGuideTextStyle`CSSProperties | Styles for the phone number guidance text. |
| `buttonStyles`ButtonComponentStyles | 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:

```typescript
const aeropayButton = pxpSdk.create('aeropay-button', {
  otpVerificationConfig: {
    inputStyles: {
      base: {
        borderColor: '#cccccc',
        fontSize: '20px'
      },
      invalid: {
        borderColor: '#d32f2f'
      }
    },
    invalidTextStyles: {
      color: '#d32f2f'
    },
    buttonStyles: {
      base: {
        backgroundColor: '#2f3bff'
      }
    }
  }
});
```

Configure the OTP verification screen with these properties:

| Property | Description |
|  --- | --- |
| `inputStyles`StateStyles | Styles for each OTP input in the base, valid, and invalid states. |
| `invalidTextStyles`CSSProperties | Styles for the validation message below the OTP inputs. |
| `buttonStyles`ButtonComponentStyles | Styles for the verification button. |


## Bank selection configuration

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

```typescript
const aeropayButton = pxpSdk.create('aeropay-button', {
  bankSelectionConfig: {
    payButtonStyles: {
      base: { backgroundColor: '#2f3bff' }
    },
    linkBankButtonStyles: {
      base: {
        backgroundColor: '#ffffff',
        color: '#2f3bff'
      }
    },
    bankSelectedIndicatorColor: '#2f3bff',
    bankItemClassName: 'checkout-bank-item',
    excludedBankAccountIds: ['1895542', 1895543],
    allowLinkBankOnPayout: false,
    aerosyncTheme: 'light'
  }
});
```

Configure the bank selection screen with these properties:

| Property | Description |
|  --- | --- |
| `payButtonStyles`ButtonComponentStyles | Styles for the pay or withdraw button. |
| `linkBankButtonStyles`ButtonComponentStyles | Styles for the link-bank button. |
| `bankSelectedIndicatorColor`string | CSS colour for the selected-bank indicator. |
| `bankItemClassName`string | A custom CSS class applied to each bank account item. |
| `excludedBankAccountIds`Array<string | number> | Bank account IDs to hide from the bank selection screen. Values can be strings or numbers (for example `"1895542"` or `1895542`). Matching is by string equality after normalisation. |
| `allowLinkBankOnPayout`boolean | Whether to show the link-bank button for `Payout` transactions. Defaults to `false`. |
| `aerosyncTheme`"light" | "dark" | Theme for the embedded Aerosync widget. Defaults to `"light"`. |


## Button styles

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

```typescript
const buttonStyles = {
  base: {
    backgroundColor: '#2f3bff',
    color: '#ffffff'
  },
  hover: {
    opacity: 0.9
  },
  disabled: {
    opacity: 0.5
  },
  loading: {
    spinnerColor: '#ffffff'
  }
};
```

Configure button states with these properties:

| Property | Description |
|  --- | --- |
| `base`CSSProperties | Styles for the default state. |
| `hover`CSSProperties | Styles applied when the shopper points to the button. |
| `disabled`CSSProperties | Styles applied when the button is disabled. |
| `loading.spinnerColor`string | CSS colour for the loading spinner. |


## Field state styles

Consumer data fields and OTP inputs use `StateStyles`:

| Property | Description |
|  --- | --- |
| `base`CSSProperties | Styles for the default state. |
| `valid`CSSProperties | Styles applied after successful validation. |
| `invalid`CSSProperties | Styles applied after failed validation. |


## Event handling

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

```typescript
import { PxpCheckout, IntentType, AeropayButtonComponent, AeropayButtonComponentConfig } from '@pxpio/web-components-sdk';

const config: AeropayButtonComponentConfig = {
  onClick: (event) => {
    console.log('Aeropay button clicked', event);
  },
  onCustomValidation: async () => {
    return true;
  },
  onUserVerificationSuccess: (user) => {
    saveAeropayUserId(user.id);
  },
  onCancel: () => {
    resetCheckoutState();
  },
  onPreAuthorisation: () => true,
  onPostAuthorisation: (result) => {
    const submitResult = result as {
      merchantTransactionId: string;
      systemTransactionId: string;
    };
    verifyPaymentOnBackend({
      merchantTransactionId: submitResult.merchantTransactionId,
      systemTransactionId: submitResult.systemTransactionId
    });
  },
  onSubmitError: (error) => {
    console.error('Transaction submission failed', error);
  },
  onError: (error) => {
    console.error('Aeropay error', error);
  }
};

const aeropayButton = pxpSdk.create('aeropay-button', config);
```

The component supports these callbacks:

| Callback | Description |
|  --- | --- |
| `onClick`(event: MouseEvent) => void | Called when the shopper clicks the Aeropay button. Does not control whether the popup opens. |
| `onCustomValidation`() => Promise<boolean> | Called when the shopper clicks the Aeropay button, before the popup opens. Return `true` to continue or `false` to stop the flow. |
| `onUserVerificationSuccess`(user: AeropayUser) => void | Called after OTP verification succeeds. Store `user.id` for returning-shopper flows. |
| `onCancel`() => void | Called only when the shopper selects the popup's close button. Pressing `Escape` or programmatically unmounting the component doesn't invoke it. |
| `onPreAuthorisation`() => boolean | Promise<boolean> | Called before transaction submission. Return `true` to proceed or `false` to stop. |
| `onPostAuthorisation`(result: BaseSubmitResult) => void | Called after the transaction is submitted successfully. |
| `onSubmitError`(error: unknown) => void | Called when transaction submission fails. At runtime, failed responses use `FailedSubmitResult`, network failures use `NetworkSdkException`, and other thrown values can pass through unchanged. |
| `onError`(error: unknown) => void | Called when an SDK or API error occurs during the Aeropay flow. Recognised failures use `BaseSdkException`, but unexpected values can pass through unchanged. |


The exported `AeropayButtonComponentConfig` declaration types `onSubmitError` as `BaseSubmitResult` and `onError` as `BaseSdkException`. Treat both callback values defensively at runtime and check their shape before reading properties.

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

## Methods

### `mount()`

Render the Aeropay button in a container by passing its element ID:

```typescript
import { PxpCheckout, IntentType, AeropayButtonComponent, AeropayButtonComponentConfig } from '@pxpio/web-components-sdk';

const aeropayButton = pxpSdk.create(
  'aeropay-button',
  config
) as AeropayButtonComponent;
aeropayButton.mount('aeropay-button-container');
```

### `unmount()`

Remove the Aeropay button and its resources when your view is destroyed:

```typescript
aeropayButton.unmount();
```

## Configuration interfaces

### `AeropayButtonComponentConfig`

The component configuration has the following TypeScript interface:

```typescript
interface AeropayButtonComponentConfig extends ButtonComponentConfig {
  userId?: string;
  popupConfig?: AeropayPopupConfig;
  consumerDataCollectionConfig?: ConsumerDataCollectionConfig;
  skipConsumerDataCollection?: boolean;
  otpVerificationConfig?: OtpVerificationConfig;
  bankSelectionConfig?: BankSelectionConfig;
  onUserVerificationSuccess?: (user: AeropayUser) => void;
  onError?: (error: BaseSdkException) => void;
  onCancel?: () => void;
  onCustomValidation?: () => Promise<boolean>;
  onPreAuthorisation?: () => boolean | Promise<boolean>;
  onPostAuthorisation?: (result: BaseSubmitResult) => void;
  onSubmitError?: (error: BaseSubmitResult) => void;
}
```

### `ButtonComponentStyles`

Button configuration uses the following TypeScript interface:

```typescript
interface ButtonComponentStyles {
  base?: CSSProperties;
  hover?: CSSProperties;
  disabled?: CSSProperties;
  loading?: {
    spinnerColor?: string;
  };
}
```

### `StateStyles`

Field configuration uses the following TypeScript interface:

```typescript
interface StateStyles {
  base?: CSSProperties;
  valid?: CSSProperties;
  invalid?: CSSProperties;
}
```