Skip to content

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. For a new shopper (userId unset), validates shopper details from onGetShopper. For a returning shopper, looks up userId instead.
  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:

StageError behaviour
Component creationpxpCheckout.create(.aeropayButton, componentConfig:) throws an SDK exception.
Custom validation returns falseThe flow stops and the popup doesn't open. No SDK error is raised.
Shopper data returned by onGetShopperThe component calls onError with SDK1300 and doesn't open the popup.
Consumer form or OTP inputThe component shows an inline validation message and prevents progression.
Aeropay user, bank, or provider validationRecognised account and provider-processing failures call onError, and often show popup feedback.
Transaction submissionAfter an attempted submission returns a failed response, the component calls onSubmitError. Returning false or omitting onPreAuthorisation stops before submission without calling it.

Aeropay runtime error codes

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

Error codeRuntime failureBehaviour
SDK1300Shopper data returned by onGetShopper is invalid.Calls onError and prevents the popup from opening.
SDK1301Aeropay user creation fails.Calls onError. Feedback is shown only if the popup is already open.
SDK1302Aeropay 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.
SDK1303Missing 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.
SDK1304The Aerosync widget flow fails.Calls onError and emits AerosyncFailed.
SDK1305Linking the selected bank account fails.Calls onError and shows account-linking feedback in the popup.
SDK1306Retrieving linked bank accounts fails.Calls onError and shows bank-account feedback in the popup.
SDK1307The Aeropay user exists but isn't active.Calls onError and stops the returning-shopper flow.
SDK1308Retrieving the Aeropay user fails.Calls onError and stops the returning-shopper flow.
SDK1311AeropayAerosyncConfigMissingException (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.
SDK1319Aeropay aggregator credentials lookup fails.Calls onError.
SDK1326Unity 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.

Component creation validation

Before creating the Aeropay button, the SDK checks that:

  • transactionData.intent.aeropay is present and supported.
  • session.allowedFundingTypes.payByBanks.aeropay.externalMerchantId is present and non-empty.
  • session.allowedFundingTypes.payByBanks.aeropay.configurationId is present and non-empty.
  • transactionData.entryType is .ecom.
  • transactionData.currency is "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 codeDescriptionCommon cause
SDK0106The 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.
SDK0113Aeropay is missing from the allowed funding types.externalMerchantId or configurationId is missing from the session.
SDK0114Aeropay supports only the Ecom entry type.transactionData.entryType contains another value.
SDK0115The Aeropay intent is missing.transactionData.intent.aeropay isn't set.
SDK0116Aeropay 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.

Shopper data validation

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:

FieldRule
First nameUnicode letters and spaces only. Maximum 100 characters.
Last nameUnicode letters and spaces only. Maximum 100 characters.
EmailValid email format. Maximum 128 characters.
Phone numberUS 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.

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. 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.

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 value, the SDK retrieves the Aeropay user before opening the Aerosync bank-selection screen:

OutcomeBehaviour
User is activeOpens the Aerosync bank-selection screen and skips consumer data and OTP.
User exists but isn't activeCalls onError with SDK1307.
User lookup failsCalls onError with 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.

ConditionBehaviour
Callback returns trueThe SDK submits the pay-by-bank transaction.
Callback returns false or is omittedThe SDK doesn't submit the transaction and leaves the popup open.
Submission returns a mapped failed Unity responseThe SDK calls onSubmitError and emits ComponentError analytics with SDK1326.
Submission fails with a network or transport errorThe SDK calls onSubmitError. ComponentError analytics can use a different code.