Skip to content

Aeropay

Accept Aeropay pay-by-bank payments with automatic consumer verification, bank linking via Aerosync, and the same Drop-in callbacks as other payment methods.

Overview

Aeropay is included in Checkout Drop-in when it's enabled in your session and the transaction meets Aeropay eligibility rules. When the shopper selects Pay by bank via Aeropay and taps the pay button, Drop-in runs consumer data collection (when required), OTP verification, bank selection or linking, and Unity transaction authorisation.

There's no separate Aeropay factory call in Drop-in. Configure Aeropay through CheckoutDropInConfig and DropInMethodConfig.aeropay.

Key benefits

Aeropay in Drop-in gives you these benefits:

  • Aeropay appears automatically in the payment method list when the session includes Aeropay funding, the currency is USD, and the entry type is Ecom.
  • Drop-in handles consumer verification, Aerosync bank linking, and payment authorisation. You don't need Aeropay-specific UI code.
  • Aeropay uses the same onSuccess and onError callbacks as other payment methods for a unified integration.
  • Site branding from the Unity Portal is applied automatically to the Aeropay launcher button, popup, and form fields.
  • Currency and entry-type gating is enforced automatically.

How it works

When a shopper selects Aeropay in Checkout Drop-in and taps the pay button:

  1. The shopper selects the Aeropay panel. The SDK shows the Aeropay launcher in the panel.
  2. The shopper taps Pay by bank.
  3. Your onBeforeSubmit callback runs (if configured). Return false to stop the flow before the popup opens.
  4. Consumer data collection runs when required (skipped when userId is set, or when skipConsumerDataCollection is true and onGetShopper supplies all four consumer fields with editableConsumerDataFields empty).
  5. OTP verification runs when required (skipped when userId is set).
  6. Aerosync bank selection or bank linking runs.
  7. Your onSubmit callback fires, then the SDK submits the Unity transaction. Drop-in always proceeds after onSubmit (there's no merchant onPreAuthorisation gate).
  8. Your onSuccess callback fires with paymentMethod == PaymentMethod.AEROPAY.

If the shopper closes the Aeropay popup without completing, methodConfig.global.onCancel fires with PaymentMethod.AEROPAY. Errors during setup or the flow are delivered to onError.

Consumer data decision tree

How the SDK decides whether to collect consumer data:

  1. When methodConfig.aeropay.userId is set to a non-empty value, skip consumer data collection and OTP. Open Aerosync (bank selection) directly after validating that the user is active.
  2. When skipConsumerDataCollection is true, onGetShopper returns all four fields (firstName, lastName, email, and phoneNumber), and editableConsumerDataFields is null or empty, auto-create the Aeropay user, skip the data screen, and go to OTP.
  3. Otherwise, show the consumer data collection screen (prefilled from onGetShopper). Prefill fields with values are read-only unless listed in editableConsumerDataFields. Missing fields stay available for the shopper to complete.

Configuration

Configure Aeropay-specific behaviour at methodConfig.aeropay. All properties are optional.

Configuration properties

The following properties are available for Aeropay configuration:

Property Description
userId
String?
Pre-configured Aeropay user ID. When provided, consumer data collection and OTP are skipped and the flow opens directly at bank selection (Aerosync). The SDK validates that the user is active before opening the popup. When userId is set, Drop-in also skips shopper-data validation at load.
editableConsumerDataFields
List<ConsumerDataField>?
Fields returned from onGetShopper that remain editable on the consumer data collection screen. Possible values: ConsumerDataField.FIRST_NAME, LAST_NAME, EMAIL, PHONE_NUMBER. When null or empty, prefilled fields are read-only. Must be empty or null when using skipConsumerDataCollection.
excludedBankAccountIds
List<Number>?
Numeric bank account IDs to hide from the bank selection screen (e.g., listOf(1895986, 1895988)).
skipConsumerDataCollection
Boolean
When true, onGetShopper provides all four consumer fields, and editableConsumerDataFields is empty or null, the consumer data screen is skipped and the flow goes directly to OTP verification (the user is created automatically). Defaults to false.

Settings used from global configuration

Aeropay inherits the following setting from methodConfig.global:

Property Description
onCancel
(PaymentMethod, Any?) -> Unit
Called when the shopper closes the Aeropay popup. For Aeropay, the payload is null. Cancellation doesn't call onError.

onGetConsent doesn't apply to Aeropay in Drop-in (Card, PayPal, and Google Pay only).

What Drop-in doesn't expose via methodConfig.aeropay

The following are handled by Unity site branding and Drop-in wiring, not by methodConfig.aeropay:

  • Popup, OTP, bank selection, and launcher button styling.
  • Lifecycle steps outside the unified Drop-in callbacks (onBeforeSubmit, onSubmit, onSuccess, onError, and methodConfig.global.onCancel).
  • A merchant veto after bank selection (Drop-in always proceeds after onSubmit).
  • Payout intent.

For the Drop-in merchant surface and when each callback fires, see What Drop-in exposes vs what it manages.

Complete example

This example shows Aeropay intent, shopper identity, cancellation handling, and optional methodConfig.aeropay settings:

import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.ui.Modifier
import com.pxp.checkout.checkoutdropin.CheckoutDropIn
import com.pxp.checkout.checkoutdropin.types.CheckoutDropInConfig
import com.pxp.checkout.checkoutdropin.types.DropInMethodConfig
import com.pxp.checkout.checkoutdropin.types.PaymentMethod
import com.pxp.checkout.checkoutdropin.types.methodconfigs.DropInAeropayConfig
import com.pxp.checkout.checkoutdropin.types.methodconfigs.DropInGlobalConfig
import com.pxp.checkout.components.aeropaybutton.types.ConsumerDataField
import com.pxp.checkout.models.DropInAeropayIntentType
import com.pxp.checkout.models.DropInTransactionData
import com.pxp.checkout.models.DropInTransactionIntentData
import com.pxp.checkout.models.EntryType
import com.pxp.checkout.models.Environment
import com.pxp.checkout.models.SessionConfig
import com.pxp.checkout.services.models.transaction.Shopper

// sessionConfig from your Sessions API response (see Quickstart)
val sessionConfig: SessionConfig = fetchSessionFromBackend()

val dropInConfig = CheckoutDropInConfig(
    environment = Environment.TEST,
    session = sessionConfig,
    transactionData = DropInTransactionData(
        amount = 25.00,
        currency = "USD",
        entryType = EntryType.Ecom,
        intent = DropInTransactionIntentData(
            aeropayDropInIntent = DropInAeropayIntentType.Authorisation,
        ),
        merchant = "your-merchant-id",
        merchantTransactionId = java.util.UUID.randomUUID().toString(),
        merchantTransactionDate = { java.time.Instant.now().toString() },
    ),
    ownerType = "MerchantGroup",
    ownerId = "MERCHANT_GROUP_1",
    methodConfig = DropInMethodConfig(
        global = DropInGlobalConfig(
            onCancel = { paymentMethod, _ ->
                if (paymentMethod == PaymentMethod.AEROPAY) {
                    // Shopper closed Pay by Bank. Not an error.
                }
            },
        ),
        aeropay = DropInAeropayConfig(
            // userId = "existing-aeropay-user-id",
            // skipConsumerDataCollection = true,
            // editableConsumerDataFields = listOf(ConsumerDataField.EMAIL),
        ),
    ),
    onGetShopper = {
        Shopper(
            id = "shopper-001",
            firstName = "John",
            lastName = "Doe",
            email = "shopper@example.com",
            phoneNumber = "+16465180948", // US format: +1 + 10 digits
        )
    },
    onBeforeSubmit = { paymentMethod ->
        paymentMethod != PaymentMethod.AEROPAY || validateCheckoutForm()
    },
    onSubmit = { paymentMethod ->
        // Unity transaction is about to submit for Aeropay
    },
    onSuccess = { result ->
        if (result.paymentMethod == PaymentMethod.AEROPAY) {
            verifyPaymentOnBackend(result)
        }
    },
    onError = { paymentMethod, error ->
        if (paymentMethod == PaymentMethod.AEROPAY) {
            showError(error.errorCode, error.message)
        }
    },
)

val checkoutDropIn = CheckoutDropIn.initialize(context, dropInConfig)

// Load site config and wire payment methods (eligibility errors fire here)
// Then compose Content() so the Aeropay panel can render.
LaunchedEffect(checkoutDropIn) {
    checkoutDropIn.create()
}

checkoutDropIn.Content(modifier = Modifier.fillMaxWidth())

Eligibility errors such as SDK0114, SDK0116, SDK1300, and SDK1125 surface during create(), not initialize().

Aeropay requirements

Aeropay requires the following to function correctly:

  • Transaction currency must be USD. If another currency is set, the Aeropay panel isn't shown and Drop-in fires onError with SDK0116.
  • Entry type must be EntryType.Ecom. If it isn't, the Aeropay panel isn't shown and Drop-in fires onError with SDK0114.
  • Aeropay must be enabled for your merchant site in the Unity Portal. The session response must contain allowedFundingTypes.payByBanks.aeropay with externalMerchantId and configurationId. If Aeropay funding is absent, the panel isn't shown and no onError fires.
  • transactionData.intent.aeropayDropInIntent must be set to Authorisation, Purchase, or EstimatedAuthorisation. If it's missing (or Aeropay credentials are blank), create() calls onError with SDK1125. The underlying failure may be SDK0115 (missing intent) or SDK0113 (blank credentials); inspect error.cause if you need the root code.
  • Implement onGetShopper with valid consumer data when values are provided, or set methodConfig.aeropay.userId. Non-empty invalid shopper fields at Drop-in load fire SDK1300 and hide the Aeropay panel. Empty or omitted fields are allowed and collected in the popup when needed.
  • Checkout Drop-in site configuration must be available from Unity for branding and styling.
  • Aeropay appears in the Drop-in payment method list with the label Pay by bank via Aeropay (localisable). Panel order follows site paymentMethodOrdering.

Implementation

Aeropay works through the standard Drop-in implementation. Set the Aeropay intent, provide shopper data or a userId, and use the shared success and error callbacks.

Session configuration (backend)

Enable Aeropay in the Unity Portal for your merchant and site. Create a session with the standard Sessions API and include the Aeropay intent.

{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "sessionTimeout": 120,
  "merchantTransactionId": "0ce72cfd-014d-4256-a006-a56601b2ffc4",
  "transactionMethod": {
    "intent": {
      "card": "Authorisation",
      "paypal": "Purchase",
      "aeropay": "Authorisation"
    }
  },
  "amounts": {
    "currencyCode": "USD",
    "transactionValue": 25.00
  },
  "allowTransaction": true,
  "serviceType": "CheckoutDropIn"
}

When Aeropay is enabled, the session response includes:

{
  "sessionId": "...",
  "hmacKey": "...",
  "encryptionKey": "...",
  "allowedFundingTypes": {
    "payByBanks": {
      "aeropay": {
        "externalMerchantId": "...",
        "configurationId": "..."
      }
    }
  }
}

Pass the session credentials and funding types into SessionConfig when you initialise Drop-in. If allowedFundingTypes.payByBanks.aeropay is absent, the Aeropay panel isn't shown. If externalMerchantId or configurationId is blank, create() fails for Aeropay and onError fires with SDK1125.

Aeropay credentials (externalMerchantId, configurationId) come from the Unity Portal on the session response. Don't hardcode production values in the app.

Intent requirements

Set the Aeropay intent in transactionData.intent.aeropayDropInIntent:

intent = DropInTransactionIntentData(
    aeropayDropInIntent = DropInAeropayIntentType.Authorisation,
    // or DropInAeropayIntentType.Purchase
    // or DropInAeropayIntentType.EstimatedAuthorisation
)

Supported Aeropay intents in Drop-in:

Intent valueSupportedNotes
AuthorisationYesRecommended for checkout. There is no SDK default; you must set aeropayDropInIntent.
PurchaseYesNone
EstimatedAuthorisationYesNone
PayoutNoNot available on DropInAeropayIntentType.

Consumer data validation rules

When userId isn't provided, Drop-in validates non-empty onGetShopper fields before showing the Aeropay panel. Invalid formats raise SDK1300 through onError and hide Aeropay. Empty or omitted fields don't fail this load check.

FieldRules
firstNameIf provided: letters and spaces only (Unicode), max 100 characters
lastNameIf provided: letters and spaces only (Unicode), max 100 characters
emailIf provided: valid email format, max 128 characters
phoneNumberIf provided: US format +1 + 10 digits (e.g., +16465180948)

skipConsumerDataCollection additionally requires all four values to be non-empty.

Updating the amount at runtime

Use updateAmount() when the order total changes. This updates all enabled payment methods, including Aeropay.

checkoutDropIn.create()
checkoutDropIn.updateAmount(150.0)

Handling responses

Aeropay callback data

When an Aeropay payment succeeds, your onSuccess callback receives a DropInSubmitResult:

onSuccess = { result ->
    if (result.paymentMethod == PaymentMethod.AEROPAY) {
        // result.systemTransactionId
        // result.merchantTransactionId
        // result.paymentData is null for Aeropay
        verifyPaymentOnBackend(result)
    }
}

Cancellation

Handle shopper cancellation with methodConfig.global.onCancel. Don't treat this as an error.

methodConfig = DropInMethodConfig(
    global = DropInGlobalConfig(
        onCancel = { paymentMethod, _ ->
            if (paymentMethod == PaymentMethod.AEROPAY) {
                // Shopper closed the Aeropay popup
            }
        },
    ),
)

Error handling

Handle Aeropay-specific Drop-in errors:

onError = { paymentMethod, error ->
    if (paymentMethod == PaymentMethod.AEROPAY) {
        when (error.errorCode) {
            "SDK0114" -> showError("Pay by Bank is only available for e-commerce checkout.")
            "SDK0116" -> showError("Pay by Bank only supports USD.")
            "SDK1300" -> showError(
                "Please check your name, email, and US phone number (+1 followed by 10 digits).",
            )
            "SDK1125" -> showError(
                "Aeropay is temporarily unavailable. Please try another payment method.",
            )
            "SDK1126" -> showError(
                "Aeropay payment failed. Please try again or use a different payment method.",
            )
            else -> showError(error.message)
        }
    }
}

Common error scenarios

The following table describes common Aeropay error scenarios:

ScenarioHow to detectRecommended action
Shopper cancelledmethodConfig.global.onCancel with PaymentMethod.AEROPAYNo alert needed. The shopper action was intentional.
Currency not USDAeropay panel not shown, and onError with SDK0116Use currency = "USD" when Aeropay is in the session.
Entry type not EcomAeropay panel not shown, and onError with SDK0114Use entryType = EntryType.Ecom.
Aeropay not in sessionPanel not shown (no onError)Enable Aeropay in the Unity Portal. Ensure the session includes payByBanks.aeropay.
Missing credentials or intentSDK1125 via onErrorCheck externalMerchantId, configurationId, and aeropayDropInIntent.
Invalid shopper data at loadSDK1300 via onError; Aeropay panel not shownCheck onGetShopper field formats (especially phone +1XXXXXXXXXX), or provide userId.
User not activeSDK1307 via onErrorThe user must complete Aeropay verification before paying.
Transaction declinedAPI errorCode on onError, or SDK1126 as fallbackSuggest another payment method.

Backend verification

Always verify Aeropay payments on your backend before fulfilling orders:

onSuccess = { result ->
    if (result.paymentMethod == PaymentMethod.AEROPAY) {
        val verified = verifyPaymentOnBackend(
            systemTransactionId = result.systemTransactionId,
            merchantTransactionId = result.merchantTransactionId,
        )
        if (verified) {
            navigateToConfirmation(result.systemTransactionId)
        } else {
            showError("Payment verification failed")
        }
    }
}

Confirm the transaction state, merchant transaction ID, amount, and funding type (PayByBank) against your order records using the Transactions API.

Error codes

Drop-in–specific errors

Error codeWhen it occurs
SDK1125Aeropay failed to load in Drop-in. Merchants receive SDK1125 on error.errorCode. Underlying cause may be SDK0113 (blank credentials) or SDK0115 (missing aeropayDropInIntent); inspect error.cause for the root code.
SDK1126Generic Aeropay payment failure fallback when a submit error has no usable API error code.

Other Aeropay failures surface on onError with paymentMethod == PaymentMethod.AEROPAY. Branch on error.errorCode. Create-time consumer validation uses SDK1300 (invalid non-empty shopper fields). Popup and authorisation flows use codes such as SDK1307, SDK1302, and SDK1304.

SDK configuration errors

Error codeMessageWhen it occurs in Drop-in
SDK0114Aeropay only supports Ecom entry typeentryType isn't Ecom (panel hidden)
SDK0116Aeropay only supports USD currencycurrency isn't USD (panel hidden)
SDK0113Aeropay is missing in allow funding typesBlank Aeropay credentials in the session; often surfaces with Drop-in SDK1125
SDK0115Intent type for Aeropay is required but not providedaeropayDropInIntent missing when panel is enabled; often surfaces with Drop-in SDK1125

Aeropay flow errors

During the popup flow, Aeropay-related errors may also surface through onError. Representative codes:

Error codeScenario
SDK1300Invalid onGetShopper data (at Drop-in load when malformed, or during the popup flow)
SDK1301User creation API failure
SDK1302OTP verification failure (including provider code AP112)
SDK1303Invalid Aerosync widget response
SDK1304Aerosync widget error
SDK1305Bank account linking failure
SDK1306Bank account list retrieval failure
SDK1307Pre-configured userId isn't active
SDK1308Get user API failure
SDK1311No host Activity available to launch Aerosync (error.message is currently "Aeropay Aerosync token and deeplink are required.", the SDK constant for AEROPAY_AEROSYNC_CONFIG_MISSING).
SDK1319Aeropay aggregator credentials lookup failure

For Drop-in analytics events, use CheckoutDropInConfig.analyticsEvent. See Analytics.

What Drop-in exposes vs what it manages

Aeropay in Drop-in uses a fixed merchant surface. Use this table as the Drop-in contract:

ConcernDrop-in behaviour
UI placementPanel inside CheckoutDropIn.Content()
BrandingUnity Portal Drop-in site configuration (launcher, popup, fields)
Merchant callbacksUnified Drop-in sequence: onBeforeSubmit, onSubmit, onSuccess, onError, and methodConfig.global.onCancel
Pre-authorisation gateAlways proceeds after onSubmit (no merchant veto after bank confirmation)
Payout intentNot available (DropInAeropayIntentType has no payout)
Eligibility failuresPanel hidden; some failures also call onError (see Error codes)

How Drop-in's unified callbacks relate to the Aeropay flow:

Drop-in callbackWhen it fires for Aeropay
onBeforeSubmitShopper taps Pay by bank, before the popup opens. Return false to stop.
onSubmitBank selected and Unity transaction is about to submit. Drop-in always continues afterward.
onSuccessUnity authorises the transaction.
methodConfig.global.onCancelShopper closes the popup. Payload is null. Doesn't call onError.
onErrorSetup, flow, or transaction error (including mapped submit failures such as SDK1126).

Drop-in doesn't expose separate merchant channels for launcher click, user-verification success, or a second submit-error callback. Handle those concerns through the unified callbacks and analytics events above.

Troubleshooting

Use these checks when Aeropay doesn't appear or the pay-by-bank flow fails.

Aeropay panel not shown

Verify these conditions:

  • allowedFundingTypes.payByBanks.aeropay is present in the session response with non-blank externalMerchantId and configurationId.
  • transactionData.currency is "USD".
  • transactionData.entryType is EntryType.Ecom.
  • transactionData.intent.aeropayDropInIntent is set to a supported intent.
  • onError may fire with SDK0116 (currency), SDK0114 (entry type), SDK1300 (invalid shopper data at load), or SDK1125 (create failure).

Invalid shopper data (SDK1300)

Look for these symptoms:

  • Non-empty invalid onGetShopper fields at Drop-in load hide the Aeropay panel and call onError.
  • Name, email, or US phone format (+1 + 10 digits) is wrong, and methodConfig.aeropay.userId isn't set.

onError with SDK1125 during create

Check the following:

  • The session is missing Aeropay credentials, or aeropayDropInIntent isn't set.
  • Log error.message for the underlying failure detail.

Consumer data screen shown when userId is provided

Check the following:

  • methodConfig.aeropay.userId is empty or missing after trim.
  • The user doesn't exist or isn't active in Aeropay (SDK1307 or SDK1308).

onBeforeSubmit not preventing the popup

Check the following:

  • onBeforeSubmit returns false for PaymentMethod.AEROPAY.
  • The callback is set on CheckoutDropInConfig, not only inside methodConfig.

OTP screen not skipped with skipConsumerDataCollection

Check the following:

  • One or more of firstName, lastName, email, and phoneNumber is missing from onGetShopper.
  • editableConsumerDataFields is set to a non-empty list.

Quick integration checklist

Before you go live with Aeropay, confirm the following:

  1. Enable Aeropay in the Unity Portal for your merchant site.
  2. Confirm the session includes allowedFundingTypes.payByBanks.aeropay with externalMerchantId and configurationId.
  3. Include "aeropay": "Authorisation" (or another supported intent) in the session intent.
  4. Set transactionData.currency to "USD" and entryType to EntryType.Ecom.
  5. Set transactionData.intent.aeropayDropInIntent to a supported Drop-in intent.
  6. Implement onGetShopper with valid formats when you supply values, or provide methodConfig.aeropay.userId.
  7. Implement onSuccess and onError.
  8. Optionally configure methodConfig.aeropay for user ID, skip data collection, editable fields, or excluded bank accounts.
  9. Optionally handle cancellation via methodConfig.global.onCancel.
  10. Verify payments on your backend before fulfilling orders.