Implement callbacks to customise your Aeropay payment flow for iOS.
Aeropay callbacks let your application respond to shopper interaction, custom validation, user verification, popup cancellation, transaction submission, and errors.
Use callbacks to:
- Block the flow when checkout isn't ready.
- Save the verified Aeropay user ID for returning-shopper flows.
- Validate business rules before submitting a transaction.
- Verify successful transactions on your backend.
- Restore your checkout interface when the shopper dismisses the popup.
- Log errors and show appropriate recovery options.
Configure onGetShopper on CheckoutConfig. Configure the other callbacks on AeropayButtonComponentConfig.
The following example implements the main Aeropay callbacks:
let checkoutConfig = CheckoutConfig(
// ...session and transaction configuration
onGetShopper: { TransactionShopper(
id: "shopper-123",
firstName: "John",
lastName: "Doe",
email: "john.doe@example.com",
phoneNumber: "+14155550123"
)
}
)
let config = AeropayButtonComponentConfig()
config.onClick = {
clearPaymentErrors()
}
config.onCustomValidation = {
await validateCheckoutReady()
}
config.onUserVerificationSuccess = { user in
saveAeropayUserId(user.id)
}
config.onCancel = {
resetCheckoutState()
}
config.onPreAuthorisation = {
await validateOrderOnBackend()
}
config.onPostAuthorisation = { result in
verifyPaymentOnBackend(result)
}
config.onSubmitError = { _ in
showAlternativePaymentMethods()
}
config.onError = { _ in
showPaymentError("Unable to complete the Aeropay flow.")
}Client callbacks aren't proof of payment. Verify every transaction on your backend before fulfilling an order or confirming a payout.
For a successful new-shopper transaction, callbacks run in this order:
onClickruns when the shopper taps the button.onCustomValidationruns. Returnfalseto stop before the flow starts.- The SDK requests available consumer details from
onGetShopper. - The component shows the consumer-data screen and then OTP, unless
skipConsumerDataCollectionistruewith complete valid shopper data (and empty/nileditableFields), in which case it skips consumer data and opens OTP after background user creation. onUserVerificationSuccessruns after successful OTP verification.onPreAuthorisationruns after the shopper selects a bank account and confirms the transaction.onGetShoppermay run again when the SDK builds the transaction request (afteronPreAuthorisationreturnstrueand before Unity submission).onPostAuthorisationruns after successful transaction submission.
If the shopper dismisses the popup, onCancel runs. Flow errors call onError, while transaction submission failures call onSubmitError.
When you provide userId, the SDK skips consumer data collection and OTP verification. A successful returning-shopper transaction follows this order:
onClickruns when the shopper taps the button.onCustomValidationruns. Returnfalseto stop before user lookup.- The SDK validates
userIdand opens the Aerosync bank-selection screen. onPreAuthorisationruns after the shopper selects a bank account and confirms the transaction.onGetShoppermay run if configured when the SDK builds the transaction request (before Unity submission).onPostAuthorisationruns after successful transaction submission.
The returning-shopper flow doesn't call onUserVerificationSuccess.
Configure onGetShopper on CheckoutConfig. For a new shopper, the SDK calls it when the Aeropay button is tapped and uses firstName, lastName, email, and phoneNumber to prefill consumer data.
The SDK may also call onGetShopper when building the pay-by-bank transaction request after onPreAuthorisation returns true. Shopper fields on the Unity request come from that call. Return current shopper data on every invocation, or keep the callback side-effect-free if the transaction doesn't require shopper fields. If you only supply data on the first call and return nil later, the submitted transaction can omit shopper details.
For a returning shopper with userId, the SDK doesn't call onGetShopper to open the popup. If onGetShopper is configured, it may still run when the transaction is submitted.
Use the callback to return the latest shopper data from your application:
onGetShopper: {
let shopper = await getCurrentShopper()
return TransactionShopper(
id: shopper.id,
firstName: shopper.firstName,
lastName: shopper.lastName,
email: shopper.email,
phoneNumber: shopper.phoneNumber
)
}The Aeropay flow uses these shopper properties:
| Property | Description |
|---|---|
idString? | Your shopper identifier. Include a stable value so you can associate the transaction with your customer record. |
firstNameString? | The shopper's given name. Used to prefill consumer data and included in the transaction request. |
lastNameString? | The shopper's family name. Used to prefill consumer data and included in the transaction request. |
emailString? | The shopper's email address. Used to prefill consumer data and included in the transaction request. |
phoneNumberString? | The shopper's US phone number, including the +1 country prefix. Used to prefill consumer data, OTP delivery, and the transaction request. |
The new-shopper flow validates any values returned for firstName, lastName, email, and phoneNumber. Invalid data calls onError and prevents the popup from opening.
Configure the following callbacks on AeropayButtonComponentConfig.
The SDK calls onClick when the shopper taps the Aeropay button. Custom validation and popup opening happen after this callback.
Use this callback to clear previous errors, update your checkout interface, or track the interaction:
config.onClick = {
clearPaymentErrors()
setCheckoutActive(true)
trackEvent("aeropay-button-clicked")
}This callback receives no parameters.
The SDK calls onCustomValidation after onClick and before the Aeropay flow starts. Because the callback is asynchronous, you can call network APIs directly.
Return true to continue or false to stop:
config.onCustomValidation = {
let checkoutReady = await validateCheckoutReady()
if !checkoutReady {
showPaymentError("Checkout isn't ready for Aeropay.")
}
return checkoutReady
}If the callback is omitted, the SDK treats the result as true.
| Return value | Behaviour |
|---|---|
true | The SDK continues with returning-user lookup or new-shopper shopper-data checks. |
false | The SDK stops and doesn't open the popup. |
The SDK calls onUserVerificationSuccess after a new shopper enters the correct OTP. The callback isn't called for returning shoppers who enter the flow with userId.
Store the returned Aeropay user ID securely so you can use the returning-shopper flow:
config.onUserVerificationSuccess = { user in
saveAeropayUserId(
shopperId: getCurrentShopperId(),
aeropayUserId: user.id
)
}The callback receives an AeropayUser object:
| Property | Description |
|---|---|
idString required | The verified Aeropay user ID. |
firstNameString? | The user's given name. |
lastNameString? | The user's family name. |
typeString? | The Aeropay user type. |
emailString? | The user's email address. |
phoneNumberString? | The user's phone number. |
createdDateString? | The date and time when the Aeropay user was created. |
The SDK calls onCancel when the shopper dismisses the Aeropay popup, including the close control and swipe dismiss.
Programmatic dismissal after a successful payment doesn't call onCancel.
Use this callback to restore your checkout interface without treating cancellation as an error:
config.onCancel = {
setCheckoutActive(false)
setLoading(false)
showAlternativePaymentMethods()
}This callback receives no parameters and has no return value.
The SDK calls onPreAuthorisation after the shopper selects a bank account and confirms the payment or payout. Use it to validate your order or payout before the SDK submits the transaction.
Return true to submit. Return false to abort submission without calling onCancel, onError, or onSubmitError — the bank-selection screen stays open:
config.onPreAuthorisation = {
let validation = await validateOrderOnBackend()
if !validation.approved {
showPaymentError(validation.message)
}
return validation.approved
}The callback controls transaction submission as follows:
| Return value | Behaviour |
|---|---|
true | The SDK builds and submits the transaction. |
false or omitted callback | The SDK aborts transaction submission without calling onCancel, onError, or onSubmitError, and leaves the bank-selection screen open. |
Implement onPreAuthorisation and return true when the transaction can proceed. If the callback is omitted or doesn't return true, the SDK doesn't submit the transaction.
The SDK calls onPostAuthorisation after PXP accepts the transaction submission. The successful payload is a MerchantSubmitResult containing the transaction identifiers.
Send the identifiers to your backend and verify the final transaction state:
config.onPostAuthorisation = { submitResult in
verifyPaymentOnBackend(
merchantTransactionId: submitResult.merchantTransactionId,
systemTransactionId: submitResult.systemTransactionId
)
}The successful payload contains these properties:
| Property | Description |
|---|---|
merchantTransactionIdString required | Your unique transaction identifier. |
systemTransactionIdString required | PXP's unique transaction identifier. |
The SDK calls onSubmitError when transaction submission fails. It isn't used for consumer data, user verification, bank account, or Aerosync failures. Those errors call onError.
Handle submission failures without exposing technical details to the shopper:
config.onSubmitError = { submitError in
if let failed = submitError as? FailedSubmitResult {
logPaymentFailure(
errorCode: failed.errorCode,
correlationId: failed.correlationId
)
}
setLoading(false)
showPaymentError("We could not complete the transaction. Try again or use another payment method.")
}A failed PXP response typically passes a FailedSubmitResult:
| Property | Description |
|---|---|
errorCodeString? | The transaction error code. |
errorReasonString? | A description of the failure. |
correlationIdString? | The correlation identifier to include in logs and support requests. |
httpStatusCodeInt? | The HTTP status code returned by PXP. |
details[String]? | Additional error details. |
When a failed Unity transaction response is mapped to FailedSubmitResult, the SDK also emits ComponentError analytics with SDK1326. Network or transport failures still call onSubmitError, but their ComponentError analytics can use a different code. Neither path delivers SDK1326 through onError. Handle the response details from onSubmitError.
The SDK calls onError for errors outside transaction submission, including:
- Invalid shopper data.
- Aeropay user creation or verification failure.
- Invalid or inactive returning users.
- Bank account retrieval or linking failure.
- Aerosync failure.
- Aerosync / bank-selection failures such as missing or invalid Aerosync payload (
SDK1303). Don't treatSDK1311as the primary "missing verified user ID" signal from the current bank UI.
Log recognised SDK errors and show a message that helps the shopper recover:
config.onError = { error in
logErrorToMonitoring(
errorCode: error.errorCode,
message: error.errorMessage
)
setLoading(false)
showPaymentError("Unable to continue with Aeropay. Try again or use another payment method.")
}Recognised SDK failures use BaseSdkException:
| Property | Description |
|---|---|
errorCodeString required | The PXP iOS SDK error code. |
errorMessageString required | A description of the error. |
onUserVerificationSuccess receives an AeropayUser with id and optional firstName, lastName, type, email, phoneNumber, and createdDate.
Successful transaction submission produces a MerchantSubmitResult with merchantTransactionId and systemTransactionId.
A failed PXP transaction response produces a FailedSubmitResult with errorCode, errorReason, correlationId, httpStatusCode, and details.
Recognised onError failures use BaseSdkException with errorCode and errorMessage.
Keep error logging separate from the message shown to the shopper. The following pattern records diagnostic information while displaying a neutral recovery message:
let config = AeropayButtonComponentConfig()
config.onPreAuthorisation = { true }
config.onPostAuthorisation = { result in
do {
try verifyPaymentOnBackend(result)
showPaymentSuccess()
} catch {
showPaymentError("We could not confirm the transaction status. Contact support before trying again.")
}
}
config.onSubmitError = { submitResult in
if let failed = submitResult as? FailedSubmitResult {
logPaymentFailure(
errorCode: failed.errorCode,
errorReason: failed.errorReason,
correlationId: failed.correlationId
)
}
showPaymentError("We could not complete the transaction. Try another payment method.")
}
config.onError = { error in
reportErrorToMonitoring(
errorCode: error.errorCode,
message: error.errorMessage
)
showPaymentError("Unable to continue with Aeropay. Try again or use another payment method.")
}