# Data validation

Learn how the Aeropay component validates configuration, shopper details, OTPs, users, and transactions.

## Overview

The Aeropay component validates data at several stages of the payment or payout flow:

1. **Component creation:** Validates the session funding configuration, transaction intent, entry type, and currency.
2. **Button tap:** Runs optional `onCustomValidation`, then validates shopper details if `onGetShopper` is configured and returns values.
3. **Consumer data collection:** Requires valid first name, last name, email address, and phone number values.
4. **OTP verification:** Requires a six-digit code and handles provider verification failures.
5. **Returning-shopper lookup:** Confirms that `userId` belongs to an active Aeropay user.
6. **Transaction submission:** Lets you approve or stop the transaction through `onPreAuthorisation`, then reports failures only if submission is attempted.


How you receive an error depends on the validation stage:

| Stage | Error behaviour |
|  --- | --- |
| Component creation | `checkout.createComponent()` throws an SDK exception. |
| Custom validation returns `false` | The flow stops and the popup doesn't open. No SDK error is raised. |
| Shopper data returned by `onGetShopper` | The component calls `onError` with `SDK1300` and doesn't open the popup. |
| Consumer form or OTP input | The component shows an inline validation message and prevents progression. |
| Aeropay user, bank, or provider validation | Recognised account and provider-processing failures call `onError`, and often show popup feedback. |
| Transaction submission | After an attempted submission returns a failed response, the component calls `onSubmitError`. Returning `false` or omitting `onPreAuthorisation` stops before Unity submission; `onSubmitError` isn't called. |


## Aeropay runtime error codes

The Aeropay component maps recognised runtime failures to these SDK codes:

| Error code | Runtime failure | Behaviour |
|  --- | --- | --- |
| `SDK1300` | Shopper data returned by `onGetShopper` is invalid. | Calls `onError` and prevents the popup from opening. Inspect `error.details` for field keys and localised validation messages. |
| `SDK1301` | Aeropay user creation fails with a recognised API failure response. | Always calls `onError`. Inline or alert feedback in the popup is shown only when the popup is already open (or when create-user fails on the consumer data screen inside the popup). |
| `SDK1302` | Aeropay user verification fails with a recognised API failure response. | Calls `onError`. Provider code `AP112` still surfaces as `SDK1302`; the SDK doesn't currently change OTP UI state for a dedicated max-attempts mode. |
| `SDK1303` | The SDK can't parse a valid account-linking payload from the Aerosync success result. | Calls `onError` and shows account-linking feedback in the popup. |
| `SDK1304` | The Aerosync widget flow fails. | Calls `onError` and emits `AerosyncFailed`. |
| `SDK1305` | Linking the selected bank account fails with a recognised API failure response. | Calls `onError` and shows account-linking feedback in the popup. |
| `SDK1306` | Retrieving linked bank accounts fails with a recognised API failure response. | Calls `onError` and shows bank-account feedback in the popup. |
| `SDK1307` | The Aeropay user exists but isn't active. | Calls `onError` and stops the returning-shopper flow. |
| `SDK1308` | Retrieving the Aeropay user fails with a recognised API failure response. | Calls `onError` and stops the returning-shopper flow. |
| `SDK1311` | The SDK can't launch Aerosync because no host Activity is available. | Calls `onError`. |
| `SDK1319` | Aeropay aggregator credentials lookup fails with a recognised API failure response. | Calls `onError`. |
| `SDK1326` | Unity transaction submission returns a failed response that maps to `FailedSubmitResult`. | Calls `onSubmitError` and emits `ComponentError` analytics with `SDK1326`. Doesn't call `onError`. Network or transport failures also call `onSubmitError`, but their analytics error code can differ. |


`SDK1301`, `SDK1302`, `SDK1305`, `SDK1306`, `SDK1308`, and `SDK1319` apply to recognised API or provider failure responses. Network or transport errors on the same operations call `onError` with `SDK0500` or `SDK0000` instead.

## Component creation validation

Before creating the Aeropay button, the SDK checks that:

* `transactionData.intent.aeropay` is present.
* `session.allowedFundingTypes.payByBanks.aeropay.externalMerchantId` is present and non-blank.
* `session.allowedFundingTypes.payByBanks.aeropay.configurationId` is present and non-blank.
* `transactionData.entryType` is `EntryType.Ecom`.
* `transactionData.currency` is `"USD"`.


The supported Aeropay intents are `Authorisation`, `Purchase`, `EstimatedAuthorisation`, and `Payout`. In Kotlin these values are represented by the sealed `AeropayIntentType` class.

Catch creation errors around `createComponent()`:

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

try {
    val aeropayButton = checkout.createComponent(
        ComponentType.AERO_PAY_BUTTON,
        AeropayButtonComponentConfig().apply {
            // Required for payment submission — return true to proceed.
            // If omitted or returns false, the SDK does not submit.
            onPreAuthorisation = { true }
        },
    )
} catch (error: BaseSdkException) {
    // Inspect error.errorCode and error.message
    showAlternativePaymentMethods()
}
```

Creation validation can produce these errors:

| Error code | Description | Common cause |
|  --- | --- | --- |
| `SDK0113` | Aeropay is missing from the allowed funding types. | `externalMerchantId` or `configurationId` is missing from the session. |
| `SDK0114` | Aeropay supports only the `Ecom` entry type. | `transactionData.entryType` contains another value. |
| `SDK0115` | The Aeropay intent is missing. | `transactionData.intent.aeropay` isn't set. |
| `SDK0116` | Aeropay supports only `USD`. | `transactionData.currency` contains another currency. |


The session gets `externalMerchantId` and `configurationId` from the Aeropay service configured in the Unity Portal. Don't add these values in the Android app yourself.

## Shopper data validation

When `userId` isn't set, tapping the button runs shopper pre-validation only if `onGetShopper` is configured. The SDK trims and validates any returned `firstName`, `lastName`, `email`, and `phoneNumber` values before opening the popup.

Configure `onGetShopper` on `PxpSdkConfig` when you want to prefill or pre-validate shopper data before the popup opens. If you omit it, shoppers enter details on the consumer data screen. Don't rely on `transactionData.shopper` alone for Aeropay prefill or pre-check.

You can omit fields or return empty strings. The component treats them as missing and lets the shopper enter them on the consumer data screen. If you return a non-empty invalid value, the component calls `onError` with `SDK1300`. Invalid formats in the pre-check map to `FN02`, `LN02`, `EA02`, and `PN02`. Length violations map to `FN03`, `LN03`, and `EA03`.

Inspect `error.details` on the `BaseSdkException` passed to `onError` for field keys and localised validation messages when debugging invalid prefilled shopper data.

Return shopper data in the expected formats:

```kotlin
import com.pxp.checkout.services.models.transaction.Shopper

onGetShopper = {
    Shopper(
        id = "shopper-123",
        firstName = "John",
        lastName = "Doe",
        email = "john.doe@example.com",
        phoneNumber = "+14155550123",
    )
}
```

Validation rules for values returned by `onGetShopper`:

| Field  | Rule |
|  --- | --- |
| First name | Unicode letters and spaces only. Maximum 100 characters. |
| Last name | Unicode letters and spaces only. Maximum 100 characters. |
| Email | Valid email format. Maximum 128 characters. |
| Phone number | US E.164 with `+1` prefix (`^\+1\d{10}$`). Empty or missing values pass the pre-check and remain available for the form. |


`skipConsumerDataCollection` requires all four consumer data values to be non-empty and `consumerDataCollectionConfig.editableFields` to be empty. If any field is listed in `editableFields`, the consumer data screen still appears. An empty phone number from `onGetShopper` also prevents the skip even when the flag is `true`.

## Consumer form validation

On the consumer data screen, empty required fields show inline messages such as FN01, LN01, EA01, and PN01. Invalid formats show FN02, LN02, EA02, and PN02.

The shopper can't continue until all four fields pass validation.

## OTP validation

The OTP screen requires a six-digit code. Non-digit characters are filtered out. Verification remains unavailable until all six digits are present.

When OTP verification fails, the component calls `onError` with `SDK1302`. If the provider returns code `AP112`, the SDK still reports `SDK1302`. Treat this as a verification failure and let the shopper retry or use **Resend** when the countdown allows it.

## Returning-shopper validation

When `userId` is set to a non-empty trimmed value, the SDK retrieves the Aeropay user before opening bank selection:

| Outcome | Behaviour |
|  --- | --- |
| User is active | Opens bank selection and skips consumer data and OTP. |
| User exists but isn't active | Calls `onError` with `SDK1307`. |
| User lookup fails | Calls `onError` with `SDK1308` for recognised API failure responses. Network or transport errors on user lookup call `onError` with `SDK0500` or `SDK0000`, not `SDK1308`. |


Empty or blank `userId` values don't start the returning-shopper path. The SDK continues with the new-shopper flow instead.

## Transaction submission validation

Before submitting the transaction, the SDK calls `onPreAuthorisation`.

| Condition | Behaviour |
|  --- | --- |
| Callback returns `true` | The SDK submits the pay-by-bank transaction. |
| Callback returns `false` or is omitted | The SDK doesn't submit the transaction and leaves the popup open. |
| Submission returns a mapped failed Unity response | The SDK calls `onSubmitError` and emits `ComponentError` analytics with `SDK1326`. |
| Submission fails with a network or transport error | The SDK calls `onSubmitError`. `ComponentError` analytics can use a different code, such as `SDK0500`. |