Learn how the Aeropay component validates configuration, shopper details, OTPs, users, and transactions.
The Aeropay component validates data at several stages of the payment or payout flow:
- Component creation: Validates the session funding configuration, transaction intent, entry type, and currency.
- Button tap: Runs optional
onCustomValidation. For a new shopper (userIdunset), validates shopper details fromonGetShopper. For a returning shopper, looks upuserIdinstead. - Consumer data collection: Requires valid first name, last name, email address, and phone number values.
- OTP verification: Requires a six-digit code and handles provider verification failures.
- Returning-shopper lookup: Confirms that
userIdbelongs to an active Aeropay user. - 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 | pxpCheckout.create(.aeropayButton, componentConfig:) 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 submission without calling it. |
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. |
SDK1301 | Aeropay user creation fails. | Calls onError. Feedback is shown only if the popup is already open. |
SDK1302 | Aeropay user verification fails. | 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 | Missing or invalid Aerosync payload on the bank-selection screen when no verified Aeropay user ID is available (primary live UI signal), or the SDK can't parse a valid account-linking payload from the Aerosync success result. | Calls onError in most cases and shows popup feedback where applicable. Some link-bank / credentials paths surface only inline or alert feedback without onError. Prefer this over SDK1311 for missing verification on the current Aerosync screen. |
SDK1304 | The Aerosync widget flow fails. | Calls onError and emits AerosyncFailed. |
SDK1305 | Linking the selected bank account fails. | Calls onError and shows account-linking feedback in the popup. |
SDK1306 | Retrieving linked bank accounts fails. | 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. | Calls onError and stops the returning-shopper flow. |
SDK1311 | AeropayAerosyncConfigMissingException (fixed message: Aeropay Aerosync token and deeplink are required.). Still present in the SDK but not the merchant-facing signal from the current Aerosync screen callbacks for a missing user ID. | Don't diagnose missing verification primarily via SDK1311. Prefer SDK1303. |
SDK1319 | Aeropay aggregator credentials lookup fails. | 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. |
Network or transport failures during Aeropay service calls typically call onError with SDK0500 (NetworkSdkException). Other mapped API or provider failures use the Aeropay-specific codes in the table.
Before creating the Aeropay button, the SDK checks that:
transactionData.intent.aeropayis present and supported.session.allowedFundingTypes.payByBanks.aeropay.externalMerchantIdis present and non-empty.session.allowedFundingTypes.payByBanks.aeropay.configurationIdis present and non-empty.transactionData.entryTypeis.ecom.transactionData.currencyis"USD".
The supported Aeropay intents are .authorisation, .purchase, .estimatedAuthorisation, and .payout.
Catch creation errors around create:
do {
let config = AeropayButtonComponentConfig()
config.onPreAuthorisation = { true }
let aeropayButton = try pxpCheckout.create(
.aeropayButton,
componentConfig: config
)
} catch let error as BaseSdkException {
// Inspect error.errorCode and error.errorMessage
showAlternativePaymentMethods()
}Creation validation can produce these errors:
| Error code | Description | Common cause |
|---|---|---|
SDK0106 | The Aeropay button doesn't support the configured intent. | transactionData.intent.aeropay contains an unsupported value. With the current public AeropayIntentType cases, typed Aeropay creation won't hit this path. |
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 iOS app yourself.
When userId isn't set, tapping the button calls onGetShopper. The SDK trims and validates any returned firstName, lastName, email, and phoneNumber values before opening the popup.
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.
Return shopper data in the expected formats:
onGetShopper: { TransactionShopper(
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. |
| 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 additionally requires all four consumer data values to be non-empty. An empty phone number from onGetShopper prevents the skip even when the flag is true.
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. Field length is limited by the input max length rather than a separate FN03, LN03, or EA03 inline message.
FN03, LN03, and EA03 can appear in SDK1300 details when onGetShopper returns values that fail the shopper pre-check, for example names or email addresses that exceed the maximum length.
The shopper can't continue until all four fields pass 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.
When userId is set to a non-empty value, the SDK retrieves the Aeropay user before opening the Aerosync bank-selection screen:
| Outcome | Behaviour |
|---|---|
| User is active | Opens the Aerosync bank-selection screen and skips consumer data and OTP. |
| User exists but isn't active | Calls onError with SDK1307. |
| User lookup fails | Calls onError with SDK1308. |
Empty or blank userId values don't start the returning-shopper path. The SDK continues with the new-shopper flow instead.
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. |