Accept Aeropay pay-by-bank payments with automatic consumer verification, bank linking via Aerosync, and the same Drop-in callbacks as other payment methods.
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.
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 isEcom. - Drop-in handles consumer verification, Aerosync bank linking, and payment authorisation. You don't need Aeropay-specific UI code.
- Aeropay uses the same
onSuccessandonErrorcallbacks 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.
When a shopper selects Aeropay in Checkout Drop-in and taps the pay button:
- The shopper selects the Aeropay panel. The SDK shows the Aeropay launcher in the panel.
- The shopper taps Pay by bank.
- Your
onBeforeSubmitcallback runs (if configured). Returnfalseto stop the flow before the popup opens. - Consumer data collection runs when required (skipped when
userIdis set, or whenskipConsumerDataCollectionistrueandonGetShoppersupplies all four consumer fields witheditableConsumerDataFieldsempty). - OTP verification runs when required (skipped when
userIdis set). - Aerosync bank selection or bank linking runs.
- Your
onSubmitcallback fires, then the SDK submits the Unity transaction. Drop-in always proceeds afteronSubmit(there's no merchantonPreAuthorisationgate). - Your
onSuccesscallback fires withpaymentMethod == 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.
How the SDK decides whether to collect consumer data:
- When
methodConfig.aeropay.userIdis set to a non-empty value, skip consumer data collection and OTP. Open Aerosync (bank selection) directly after validating that the user is active. - When
skipConsumerDataCollectionistrue,onGetShopperreturns all four fields (firstName,lastName,email, andphoneNumber), andeditableConsumerDataFieldsisnullor empty, auto-create the Aeropay user, skip the data screen, and go to OTP. - Otherwise, show the consumer data collection screen (prefilled from
onGetShopper). Prefill fields with values are read-only unless listed ineditableConsumerDataFields. Missing fields stay available for the shopper to complete.
Configure Aeropay-specific behaviour at methodConfig.aeropay. All properties are optional.
The following properties are available for Aeropay configuration:
| Property | Description |
|---|---|
userIdString? | 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. |
editableConsumerDataFieldsList<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. |
excludedBankAccountIdsList<Number>? | Numeric bank account IDs to hide from the bank selection screen (e.g., listOf(1895986, 1895988)). |
skipConsumerDataCollectionBoolean | 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. |
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).
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, andmethodConfig.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.
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 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 firesonErrorwithSDK0116. - Entry type must be
EntryType.Ecom. If it isn't, the Aeropay panel isn't shown and Drop-in firesonErrorwithSDK0114. - Aeropay must be enabled for your merchant site in the Unity Portal. The session response must contain
allowedFundingTypes.payByBanks.aeropaywithexternalMerchantIdandconfigurationId. If Aeropay funding is absent, the panel isn't shown and noonErrorfires. transactionData.intent.aeropayDropInIntentmust be set toAuthorisation,Purchase, orEstimatedAuthorisation. If it's missing (or Aeropay credentials are blank),create()callsonErrorwithSDK1125. The underlying failure may beSDK0115(missing intent) orSDK0113(blank credentials); inspecterror.causeif you need the root code.- Implement
onGetShopperwith valid consumer data when values are provided, or setmethodConfig.aeropay.userId. Non-empty invalid shopper fields at Drop-in load fireSDK1300and 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.
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.
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.
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 value | Supported | Notes |
|---|---|---|
Authorisation | Yes | Recommended for checkout. There is no SDK default; you must set aeropayDropInIntent. |
Purchase | Yes | None |
EstimatedAuthorisation | Yes | None |
Payout | No | Not available on DropInAeropayIntentType. |
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.
| Field | Rules |
|---|---|
firstName | If provided: letters and spaces only (Unicode), max 100 characters |
lastName | If provided: letters and spaces only (Unicode), max 100 characters |
email | If provided: valid email format, max 128 characters |
phoneNumber | If provided: US format +1 + 10 digits (e.g., +16465180948) |
skipConsumerDataCollection additionally requires all four values to be non-empty.
Use updateAmount() when the order total changes. This updates all enabled payment methods, including Aeropay.
checkoutDropIn.create()
checkoutDropIn.updateAmount(150.0)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)
}
}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
}
},
),
)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)
}
}
}The following table describes common Aeropay error scenarios:
| Scenario | How to detect | Recommended action |
|---|---|---|
| Shopper cancelled | methodConfig.global.onCancel with PaymentMethod.AEROPAY | No alert needed. The shopper action was intentional. |
| Currency not USD | Aeropay panel not shown, and onError with SDK0116 | Use currency = "USD" when Aeropay is in the session. |
Entry type not Ecom | Aeropay panel not shown, and onError with SDK0114 | Use entryType = EntryType.Ecom. |
| Aeropay not in session | Panel not shown (no onError) | Enable Aeropay in the Unity Portal. Ensure the session includes payByBanks.aeropay. |
| Missing credentials or intent | SDK1125 via onError | Check externalMerchantId, configurationId, and aeropayDropInIntent. |
| Invalid shopper data at load | SDK1300 via onError; Aeropay panel not shown | Check onGetShopper field formats (especially phone +1XXXXXXXXXX), or provide userId. |
| User not active | SDK1307 via onError | The user must complete Aeropay verification before paying. |
| Transaction declined | API errorCode on onError, or SDK1126 as fallback | Suggest another payment method. |
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 code | When it occurs |
|---|---|
SDK1125 | Aeropay 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. |
SDK1126 | Generic 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.
| Error code | Message | When it occurs in Drop-in |
|---|---|---|
SDK0114 | Aeropay only supports Ecom entry type | entryType isn't Ecom (panel hidden) |
SDK0116 | Aeropay only supports USD currency | currency isn't USD (panel hidden) |
SDK0113 | Aeropay is missing in allow funding types | Blank Aeropay credentials in the session; often surfaces with Drop-in SDK1125 |
SDK0115 | Intent type for Aeropay is required but not provided | aeropayDropInIntent missing when panel is enabled; often surfaces with Drop-in SDK1125 |
During the popup flow, Aeropay-related errors may also surface through onError. Representative codes:
| Error code | Scenario |
|---|---|
SDK1300 | Invalid onGetShopper data (at Drop-in load when malformed, or during the popup flow) |
SDK1301 | User creation API failure |
SDK1302 | OTP verification failure (including provider code AP112) |
SDK1303 | Invalid Aerosync widget response |
SDK1304 | Aerosync widget error |
SDK1305 | Bank account linking failure |
SDK1306 | Bank account list retrieval failure |
SDK1307 | Pre-configured userId isn't active |
SDK1308 | Get user API failure |
SDK1311 | No 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). |
SDK1319 | Aeropay aggregator credentials lookup failure |
For Drop-in analytics events, use CheckoutDropInConfig.analyticsEvent. See Analytics.
Aeropay in Drop-in uses a fixed merchant surface. Use this table as the Drop-in contract:
| Concern | Drop-in behaviour |
|---|---|
| UI placement | Panel inside CheckoutDropIn.Content() |
| Branding | Unity Portal Drop-in site configuration (launcher, popup, fields) |
| Merchant callbacks | Unified Drop-in sequence: onBeforeSubmit, onSubmit, onSuccess, onError, and methodConfig.global.onCancel |
| Pre-authorisation gate | Always proceeds after onSubmit (no merchant veto after bank confirmation) |
| Payout intent | Not available (DropInAeropayIntentType has no payout) |
| Eligibility failures | Panel hidden; some failures also call onError (see Error codes) |
How Drop-in's unified callbacks relate to the Aeropay flow:
| Drop-in callback | When it fires for Aeropay |
|---|---|
onBeforeSubmit | Shopper taps Pay by bank, before the popup opens. Return false to stop. |
onSubmit | Bank selected and Unity transaction is about to submit. Drop-in always continues afterward. |
onSuccess | Unity authorises the transaction. |
methodConfig.global.onCancel | Shopper closes the popup. Payload is null. Doesn't call onError. |
onError | Setup, 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.
Use these checks when Aeropay doesn't appear or the pay-by-bank flow fails.
Verify these conditions:
allowedFundingTypes.payByBanks.aeropayis present in the session response with non-blankexternalMerchantIdandconfigurationId.transactionData.currencyis"USD".transactionData.entryTypeisEntryType.Ecom.transactionData.intent.aeropayDropInIntentis set to a supported intent.onErrormay fire withSDK0116(currency),SDK0114(entry type),SDK1300(invalid shopper data at load), orSDK1125(create failure).
Look for these symptoms:
- Non-empty invalid
onGetShopperfields at Drop-in load hide the Aeropay panel and callonError. - Name, email, or US phone format (
+1+ 10 digits) is wrong, andmethodConfig.aeropay.userIdisn't set.
Check the following:
- The session is missing Aeropay credentials, or
aeropayDropInIntentisn't set. - Log
error.messagefor the underlying failure detail.
Check the following:
methodConfig.aeropay.userIdis empty or missing after trim.- The user doesn't exist or isn't active in Aeropay (
SDK1307orSDK1308).
Check the following:
onBeforeSubmitreturnsfalseforPaymentMethod.AEROPAY.- The callback is set on
CheckoutDropInConfig, not only insidemethodConfig.
Check the following:
- One or more of
firstName,lastName,email, andphoneNumberis missing fromonGetShopper. editableConsumerDataFieldsis set to a non-empty list.
Before you go live with Aeropay, confirm the following:
- Enable Aeropay in the Unity Portal for your merchant site.
- Confirm the session includes
allowedFundingTypes.payByBanks.aeropaywithexternalMerchantIdandconfigurationId. - Include
"aeropay": "Authorisation"(or another supported intent) in the session intent. - Set
transactionData.currencyto"USD"andentryTypetoEntryType.Ecom. - Set
transactionData.intent.aeropayDropInIntentto a supported Drop-in intent. - Implement
onGetShopperwith valid formats when you supply values, or providemethodConfig.aeropay.userId. - Implement
onSuccessandonError. - Optionally configure
methodConfig.aeropayfor user ID, skip data collection, editable fields, or excluded bank accounts. - Optionally handle cancellation via
methodConfig.global.onCancel. - Verify payments on your backend before fulfilling orders.