Skip to content

Events

Implement callbacks to customise your Aeropay payment flow for iOS.

Overview

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.

Basic event handling

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.

Callback order

New-shopper flow

For a successful new-shopper transaction, callbacks run in this order:

  1. onClick runs when the shopper taps the button.
  2. onCustomValidation runs. Return false to stop before the flow starts.
  3. The SDK requests available consumer details from onGetShopper.
  4. The component shows the consumer-data screen and then OTP, unless skipConsumerDataCollection is true with complete valid shopper data (and empty/nil editableFields), in which case it skips consumer data and opens OTP after background user creation.
  5. onUserVerificationSuccess runs after successful OTP verification.
  6. onPreAuthorisation runs after the shopper selects a bank account and confirms the transaction.
  7. onGetShopper may run again when the SDK builds the transaction request (after onPreAuthorisation returns true and before Unity submission).
  8. onPostAuthorisation runs after successful transaction submission.

If the shopper dismisses the popup, onCancel runs. Flow errors call onError, while transaction submission failures call onSubmitError.

Returning-shopper flow

When you provide userId, the SDK skips consumer data collection and OTP verification. A successful returning-shopper transaction follows this order:

  1. onClick runs when the shopper taps the button.
  2. onCustomValidation runs. Return false to stop before user lookup.
  3. The SDK validates userId and opens the Aerosync bank-selection screen.
  4. onPreAuthorisation runs after the shopper selects a bank account and confirms the transaction.
  5. onGetShopper may run if configured when the SDK builds the transaction request (before Unity submission).
  6. onPostAuthorisation runs after successful transaction submission.

The returning-shopper flow doesn't call onUserVerificationSuccess.

SDK data callbacks

onGetShopper

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
id
String?
Your shopper identifier. Include a stable value so you can associate the transaction with your customer record.
firstName
String?
The shopper's given name. Used to prefill consumer data and included in the transaction request.
lastName
String?
The shopper's family name. Used to prefill consumer data and included in the transaction request.
email
String?
The shopper's email address. Used to prefill consumer data and included in the transaction request.
phoneNumber
String?
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.

Aeropay component callbacks

Configure the following callbacks on AeropayButtonComponentConfig.

onClick

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.

onCustomValidation

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 valueBehaviour
trueThe SDK continues with returning-user lookup or new-shopper shopper-data checks.
falseThe SDK stops and doesn't open the popup.

onUserVerificationSuccess

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
id
String
required
The verified Aeropay user ID.
firstName
String?
The user's given name.
lastName
String?
The user's family name.
type
String?
The Aeropay user type.
email
String?
The user's email address.
phoneNumber
String?
The user's phone number.
createdDate
String?
The date and time when the Aeropay user was created.

onCancel

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.

onPreAuthorisation

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 valueBehaviour
trueThe SDK builds and submits the transaction.
false or omitted callbackThe 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.

onPostAuthorisation

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
merchantTransactionId
String
required
Your unique transaction identifier.
systemTransactionId
String
required
PXP's unique transaction identifier.

onSubmitError

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
errorCode
String?
The transaction error code.
errorReason
String?
A description of the failure.
correlationId
String?
The correlation identifier to include in logs and support requests.
httpStatusCode
Int?
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.

onError

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 treat SDK1311 as 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
errorCode
String
required
The PXP iOS SDK error code.
errorMessage
String
required
A description of the error.

Event data structures

AeropayUser

onUserVerificationSuccess receives an AeropayUser with id and optional firstName, lastName, type, email, phoneNumber, and createdDate.

MerchantSubmitResult

Successful transaction submission produces a MerchantSubmitResult with merchantTransactionId and systemTransactionId.

FailedSubmitResult

A failed PXP transaction response produces a FailedSubmitResult with errorCode, errorReason, correlationId, httpStatusCode, and details.

BaseSdkException

Recognised onError failures use BaseSdkException with errorCode and errorMessage.

Error-handling pattern

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.")
}