{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-heading","admonition","br","details","required"]},"type":"markdown"},"seo":{"title":"Implementation","description":"Transform your commerce with PXP's unified platform—seamless payments, real-time insights, and global growth in one powerful integration.","lang":"en-UK","siteUrl":"https://developer.pxp.io"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"implementation","__idx":0},"children":["Implementation"]},{"$$mdtype":"Tag","name":"SubHeading","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Complete guide to integrating the Aeropay component into your iOS application."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Aeropay component lets shoppers make payments or receive payouts through a linked US bank account. The integration follows a three-stage lifecycle:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Initialise:"]}," Configure the SDK with an Aeropay-enabled session and transaction data."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create and render:"]}," Create the Aeropay button and show it in your SwiftUI view."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Handle the flow:"]}," Respond to custom validation, user verification, transaction results, cancellation, and errors."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK handles consumer data collection, OTP verification, bank selection, Aerosync bank linking, and pay-by-bank transaction submission."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Backend verification is mandatory. Always verify transactions on your backend before fulfilling orders or confirming payouts. Client callbacks can be manipulated by malicious users."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-start","__idx":2},"children":["Before you start"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Complete ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/components/ios/aeropay/onboarding"},"children":["Aeropay onboarding"]}," in the Unity Portal before integrating the component. You'll need:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Aeropay enabled at merchant group and site level."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your Aeropay merchant ID, API key, API secret, and configuration ID added to the Aeropay service."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["PXP API credentials for creating sessions on your backend."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An iOS app that meets the SDK requirements (iOS 14 or later, and SwiftUI)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Aeropay transactions must also meet these requirements:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Setting"},"children":["Setting"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required value"},"children":["Required value"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Currency"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USD"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Entry type"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".ecom"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Intent"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".authorisation"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".purchase"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".estimatedAuthorisation"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".payout"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-install-the-ios-sdk","__idx":3},"children":["Step 1: Install the iOS SDK"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add the PXP Checkout SDK through Swift Package Manager. The public product is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PXPCheckoutSDK"]},", and the package requires iOS 14 or later."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In Xcode, add the package dependency for your PXP Checkout distribution, then link the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PXPCheckoutSDK"]}," product to your app target."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Import the SDK in your Swift files:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"import PXPCheckoutSDK\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Register the SDK callback URL scheme so your app can complete Aerosync bank linking. The SDK builds the callback as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{callbackScheme}://aerosync/callback"]},", where ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["callbackScheme"]}," comes from the SDK configuration (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PXP_CALLBACK_SCHEME"]},") and defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pxpcheckout"]},". Make sure your app can handle that URL, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pxpcheckout://aerosync/callback"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Register the scheme in your app's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Info.plist"]},". The value must match ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PXP_CALLBACK_SCHEME"]}," for your SDK distribution (default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pxpcheckout"]},"):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"xml","header":{"controls":{"copy":{}}},"source":"<key>CFBundleURLTypes</key>\n<array>\n    <dict>\n        <key>CFBundleURLSchemes</key>\n        <array>\n            <string>pxpcheckout</string>\n        </array>\n    </dict>\n</array>\n","lang":"xml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Without ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CFBundleURLTypes"]},", Aerosync bank linking can't return to the app. For package setup details, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/components/ios/install"},"children":["Install"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-create-a-session-on-your-backend","__idx":4},"children":["Step 2: Create a session on your backend"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create sessions on your backend using PXP-UST1 HMAC authentication. Never expose your PXP token value or other API credentials in the iOS app."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," request to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v1/sessions"]}," with the Aeropay intent under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionMethod.intent.aeropay"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"merchant\": \"MERCHANT-1\",\n  \"site\": \"SITE-1\",\n  \"sessionTimeout\": 120,\n  \"merchantTransactionId\": \"0f3501f0-2577-4dee-8be2-bbb6908588e3\",\n  \"amounts\": {\n    \"currencyCode\": \"USD\",\n    \"transactionValue\": 25.00\n  },\n  \"transactionMethod\": {\n    \"intent\": {\n      \"aeropay\": \"Authorisation\"\n    }\n  },\n  \"allowTransaction\": true\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure the request with these Aeropay-specific values:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Property"},"children":["Property"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantTransactionId"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your unique identifier for the session transaction. We recommend reusing the value when initialising the SDK to simplify reconciliation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amounts.currencyCode"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction currency. Set this to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USD"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amounts.transactionValue"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The payment or payout amount."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionMethod.intent.aeropay"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Aeropay transaction intent. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorisation"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Purchase"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EstimatedAuthorisation"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Payout"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowTransaction"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["boolean"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Whether the session can be used to submit a transaction."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"session-response","__idx":5},"children":["Session response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If Aeropay is configured for the site, the session response includes its funding configuration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"sessionId\": \"c5f0799b-0839-43ce-abc5-5b462a98f250\",\n  \"hmacKey\": \"904bc42395d4af634e2fd48ee8c2c7f52955a1da97a3aa3d82957ff12980a7bb\",\n  \"encryptionKey\": \"20d175a669ad3f8c195c9c283fc86155\",\n  \"sessionExpiry\": \"2026-07-21T12:00:00.000Z\",\n  \"allowedFundingTypes\": {\n    \"payByBanks\": {\n      \"aeropay\": {\n        \"externalMerchantId\": \"aeropay-merchant-id\",\n        \"configurationId\": \"aerosync-configuration-id\"\n      }\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK requires both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedFundingTypes.payByBanks.aeropay.externalMerchantId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedFundingTypes.payByBanks.aeropay.configurationId"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["PXP adds the Aeropay funding configuration to the session automatically from your Unity Portal setup. Don't add Aeropay credentials to the response yourself."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Return the session and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantTransactionId"]}," to your iOS app."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-initialise-the-sdk","__idx":6},"children":["Step 3: Initialise the SDK"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Request the session from your backend, then initialise ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PxpCheckout"]},":"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Decode the backend session response into ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SessionData"]},", then pass that session into ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutConfig"]},". Aeropay funding is already on the decoded session at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedFundingTypes.payByBanks.aeropay"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"import PXPCheckoutSDK\n\nlet session = try JSONDecoder().decode(SessionData.self, from: responseData)\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use a merchant-defined wrapper if you also pass your own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantTransactionId"]}," (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SessionResult"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session: SessionData"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantTransactionId: String"]},"):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"func createPxpCheckout(sessionResult: SessionResult) throws -> PxpCheckout {\n    let transactionData = TransactionData(\n        amount: Decimal(25.00),\n        currency: \"USD\",\n        entryType: .ecom,\n        intent: TransactionIntentData(aeropay: .authorisation),\n        merchantTransactionId: sessionResult.merchantTransactionId,\n        merchantTransactionDate: { Date() }\n    )\n\n    let checkoutConfig = CheckoutConfig(\n        environment: .test,\n        session: sessionResult.session,\n        transactionData: transactionData,\n        merchantShopperId: \"shopper-123\",\n        ownerId: \"MERCHANT_GROUP_1\",\n        onGetShopper: { TransactionShopper(\n                id: \"shopper-123\",\n                firstName: \"John\",\n                lastName: \"Doe\",\n                email: \"john.doe@example.com\",\n                phoneNumber: \"+14155550123\"\n            )\n        }\n    )\n\n    return try PxpCheckout.initialize(config: checkoutConfig)\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["environment"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".test"]}," for UAT or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".live"]}," for production. The SDK maps those values to Aerosync as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sandbox"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["production"]}," respectively."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep the session request and SDK transaction data consistent so that you can trace and reconcile transactions. The iOS SDK doesn't compare the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantTransactionId"]},", amount, currency, or intent with the values used to create the session. Verify the completed transaction against records stored on your backend."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"shopper-data","__idx":7},"children":["Shopper data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For new shoppers, the SDK uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]}," to prefill the consumer data screen. It supports these fields:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["firstName"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastName"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["phoneNumber"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you provide a field, it must be valid. First and last names accept a maximum of 100 Unicode letters and spaces. Email addresses accept a maximum of 128 characters and must match the SDK's email format. Phone numbers must contain ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["+1"]}," followed by ten digits, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["+14155550123"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If a supplied name, email address, or phone number is non-empty but invalid, the SDK invokes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1300"]}," before opening the popup."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Return only the data required for the flow. Don't include personal data in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantTransactionId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shopper.id"]},", or free-text order descriptions."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-create-the-aeropay-button","__idx":8},"children":["Step 4: Create the Aeropay button"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create the component with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pxpCheckout.create(.aeropayButton, componentConfig:)"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"let config = AeropayButtonComponentConfig(label: \"Pay by bank\")\nconfig.onClick = {\n    clearPaymentErrors()\n}\nconfig.onCustomValidation = {\n    await validateCheckoutReady()\n}\nconfig.onUserVerificationSuccess = { user in\n    saveAeropayUserId(user.id)\n}\nconfig.onCancel = {\n    resetCheckoutState()\n}\nconfig.onPreAuthorisation = {\n    await validateOrderOnBackend()\n}\nconfig.onPostAuthorisation = { result in\n    verifyPaymentOnBackend(result)\n}\nconfig.onSubmitError = { error in\n    if let failed = error as? FailedSubmitResult {\n        showPaymentError(\"Unable to complete the transaction.\")\n    }\n}\nconfig.onError = { error in\n    showPaymentError(\"Unable to continue with Aeropay.\")\n}\n\nlet aeropayButton = try pxpCheckout.create(.aeropayButton, componentConfig: config)\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Implement ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPreAuthorisation"]}," and return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," when the transaction can proceed. If this callback is omitted or doesn't return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},", the SDK doesn't submit the transaction. Return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," (or omit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPreAuthorisation"]},") to abort submission without calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCancel"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," — the bank-selection screen stays open and no transaction is sent."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCustomValidation"]}," runs after the optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onClick"]}," handler on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AeropayButtonComponentConfig"]}," (inherited from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ButtonComponentConfig"]},") and before the Aeropay popup opens. Return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCustomValidation"]}," to block the flow. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onClick"]}," is for synchronous side effects only and can't cancel the flow."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCancel"]}," runs when the shopper dismisses the popup, including the close control and swipe dismiss. Successful payment dismissal is programmatic and doesn't invoke ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCancel"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For all component properties, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/components/ios/aeropay/configuration"},"children":["Configuration"]},". For callback payloads and examples, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/components/ios/aeropay/events"},"children":["Events"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5-render-the-button","__idx":9},"children":["Step 5: Render the button"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buildContent()"]}," in your SwiftUI view:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"import SwiftUI\nimport PXPCheckoutSDK\n\nstruct AeropayCheckoutButton: View {\n    let aeropayButton: BaseComponent?\n\n    var body: some View {\n        aeropayButton?.buildContent()\n            .frame(maxWidth: .infinity)\n    }\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create the component in a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Task"]}," from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".onAppear"]}," or an equivalent lifecycle hook, then store it in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@State"]}," so the view can render it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-6-verify-the-transaction-on-your-backend","__idx":10},"children":["Step 6: Verify the transaction on your backend"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After transaction submission, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPostAuthorisation"]}," receives the merchant and PXP transaction identifiers. Send the result to your backend and retrieve the transaction from PXP before updating the order or payout:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"config.onPostAuthorisation = { submitResult in\n    verifyPaymentOnBackend(\n        merchantTransactionId: submitResult.merchantTransactionId,\n        systemTransactionId: submitResult.systemTransactionId\n    )\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your backend verification must:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Authenticate directly with PXP."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Retrieve the transaction using its transaction identifier."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm that the merchant, amount, currency, intent, and final state match your records."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update the order or payout only after every check passes."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Don't trust values sent only from the app. Use them to identify the transaction, then compare the authoritative PXP response with values stored on your backend."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"manage-post-transaction-operations","__idx":11},"children":["Manage post-transaction operations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After a successful Aeropay transaction, you can find it by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantTransactionId"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["systemTransactionId"]}," in ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Reporting"]}," in the Unity Portal and select an available action:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Capture:"]}," Capture funds for an authorised transaction."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Increment:"]}," Increase the authorised amount."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Void:"]}," Cancel an authorisation before it's captured."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Refund:"]}," Return funds for a captured or purchased transaction."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Available actions depend on the transaction intent and current state. A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Purchase"]}," captures funds at submission, so it doesn't need a separate capture."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"new-shopper-flow","__idx":12},"children":["New-shopper flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the new-shopper flow when you don't have a verified Aeropay user ID. Don't set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userId"]}," on the component."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The shopper completes these stages:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reviews or enters their first name, last name, email address, and phone number."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enters the OTP sent to their phone."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Selects a linked bank account or links a new account through Aerosync."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirms the transaction."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the verified Aeropay user ID in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onUserVerificationSuccess"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"config.onUserVerificationSuccess = { user in\n    saveAeropayUserId(\n        shopperId: \"shopper-123\",\n        aeropayUserId: user.id\n    )\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"skip-consumer-data-collection","__idx":13},"children":["Skip consumer data collection"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your application already has all four consumer fields, set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["skipConsumerDataCollection"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," to begin with OTP verification:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"let config = AeropayButtonComponentConfig()\nconfig.skipConsumerDataCollection = true\nconfig.onUserVerificationSuccess = { user in\n    saveAeropayUserId(user.id)\n}\nconfig.onPreAuthorisation = { true }\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK skips the screen only when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]}," returns valid, non-empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["firstName"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastName"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["phoneNumber"]}," values, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["consumerDataCollectionConfig.editableFields"]}," is omitted, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nil"]},", or empty."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"returning-shopper-flow","__idx":14},"children":["Returning-shopper flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a returning shopper, get their stored Aeropay user ID from your backend and pass it to the component:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"let config = AeropayButtonComponentConfig()\nconfig.userId = aeropayProfile.userId\nconfig.onPreAuthorisation = { true }\nconfig.onPostAuthorisation = { result in\n    verifyPaymentOnBackend(result)\n}\nconfig.onError = { error in\n    switch error.errorCode {\n    case \"SDK1307\", \"SDK1308\":\n        offerNewShopperFlow()\n    default:\n        showPaymentError(\"Unable to continue with Aeropay.\")\n    }\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK validates that the Aeropay user exists and is active. It then skips consumer data collection and OTP verification, and opens the Aerosync bank-selection screen."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the user isn't active, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," receives ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1307"]},". If retrieving the user fails, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," receives ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1308"]},". Remove the invalid stored ID and let the shopper restart the new-shopper flow."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Associate each Aeropay user ID with the authenticated customer on your backend. Retrieve it from your backend rather than device storage alone, and don't accept a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userId"]}," supplied or changed by untrusted client input."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK and provider handle bank linking. Don't collect routing numbers or full account numbers in your checkout. If you store bank metadata for a business need, restrict access and retain only the required values."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payout-flow","__idx":15},"children":["Payout flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".payout"]}," in the SDK and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Payout"]}," in the session request:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"let transactionData = TransactionData(\n    amount: Decimal(25.00),\n    currency: \"USD\",\n    entryType: .ecom,\n    intent: TransactionIntentData(aeropay: .payout),\n    merchantTransactionId: sessionResult.merchantTransactionId,\n    merchantTransactionDate: { Date() }\n)\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, shoppers can only select an existing linked bank account during a payout. To allow bank linking, set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowLinkBankOnPayout"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"let config = AeropayButtonComponentConfig()\nconfig.userId = aeropayProfile.userId\nconfig.bankSelectionConfig = BankSelectionConfig(\n    allowLinkBankOnPayout: true\n)\nconfig.onPreAuthorisation = { true }\nconfig.onPostAuthorisation = { result in\n    verifyPayoutOnBackend(result)\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["config.label"]}," doesn't override the payout button text. For ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".payout"]},", the SDK uses the localised payout label (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["en-US"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Withdraw by Bank"]},")."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before enabling payouts, confirm that your PXP and Aeropay accounts support them. Validate customer eligibility, amount limits, account status, and duplicate requests on your backend."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"control-the-component","__idx":16},"children":["Control the component"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["disabled"]}," on the config before you create the component if the button should start disabled. After creation, cast to the button component and call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["setDisabled(_:)"]}," so the button state updates:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"let config = AeropayButtonComponentConfig()\nconfig.disabled = true\n\nlet component = try pxpCheckout.create(.aeropayButton, componentConfig: config)\n\nif let aeropayButton = component as? AeropayButtonComponent {\n    aeropayButton.setDisabled(false)\n    aeropayButton.setDisabled(true)\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Changing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["config.disabled"]}," after creation doesn't update the rendered button on its own. The button is also non-interactive while loading."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hide()"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["show()"]}," are available on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AeropayButtonComponent"]},", not on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BaseComponent"]}," protocol returned by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create"]},". Cast before you use them when Aeropay availability depends on your application state:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"if let aeropayButton = component as? AeropayButtonComponent {\n    aeropayButton.hide()\n    aeropayButton.show()\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"complete-swiftui-example","__idx":17},"children":["Complete SwiftUI example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example creates a new-shopper ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".authorisation"]}," flow:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"import SwiftUI\nimport PXPCheckoutSDK\n\nstruct AeropayPaymentView: View {\n    @State private var aeropayComponent: BaseComponent?\n    @State private var isLoading = true\n\n    var body: some View {\n        Group {\n            if isLoading {\n                ProgressView()\n            } else {\n                aeropayComponent?.buildContent()\n                    .frame(maxWidth: .infinity)\n            }\n        }\n        .padding()\n        .onAppear {\n            createAeropayComponent()\n        }\n    }\n\n    private func createAeropayComponent() {\n        Task {\n            do {\n                let pxpCheckout = try createPxpCheckout(sessionResult: await fetchSessionFromBackend())\n                let config = AeropayButtonComponentConfig(label: \"Pay by bank\")\n                config.onCustomValidation = { true }\n                config.onUserVerificationSuccess = { user in\n                    saveAeropayUserId(user.id)\n                }\n                config.onCancel = {\n                    resetCheckoutState()\n                }\n                config.onPreAuthorisation = {\n                    await validateOrderOnBackend()\n                }\n                config.onPostAuthorisation = { result in\n                    verifyPaymentOnBackend(result)\n                }\n                config.onSubmitError = { error in\n                    if error is FailedSubmitResult {\n                        showPaymentError(\"Unable to complete the transaction.\")\n                    }\n                }\n                config.onError = { _ in\n                    showPaymentError(\"Unable to continue with Aeropay.\")\n                }\n\n                let component = try pxpCheckout.create(.aeropayButton, componentConfig: config)\n                await MainActor.run {\n                    aeropayComponent = component\n                    isLoading = false\n                }\n            } catch {\n                await MainActor.run {\n                    isLoading = false\n                    showPaymentError(\"Pay by Bank is not available for this checkout.\")\n                }\n            }\n        }\n    }\n}\n","lang":"swift"},"children":[]}]},"headings":[{"value":"Implementation","id":"implementation","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Before you start","id":"before-you-start","depth":2},{"value":"Step 1: Install the iOS SDK","id":"step-1-install-the-ios-sdk","depth":2},{"value":"Step 2: Create a session on your backend","id":"step-2-create-a-session-on-your-backend","depth":2},{"value":"Session response","id":"session-response","depth":3},{"value":"Step 3: Initialise the SDK","id":"step-3-initialise-the-sdk","depth":2},{"value":"Shopper data","id":"shopper-data","depth":3},{"value":"Step 4: Create the Aeropay button","id":"step-4-create-the-aeropay-button","depth":2},{"value":"Step 5: Render the button","id":"step-5-render-the-button","depth":2},{"value":"Step 6: Verify the transaction on your backend","id":"step-6-verify-the-transaction-on-your-backend","depth":2},{"value":"Manage post-transaction operations","id":"manage-post-transaction-operations","depth":2},{"value":"New-shopper flow","id":"new-shopper-flow","depth":2},{"value":"Skip consumer data collection","id":"skip-consumer-data-collection","depth":3},{"value":"Returning-shopper flow","id":"returning-shopper-flow","depth":2},{"value":"Payout flow","id":"payout-flow","depth":2},{"value":"Control the component","id":"control-the-component","depth":2},{"value":"Complete SwiftUI example","id":"complete-swiftui-example","depth":2}],"frontmatter":{"seo":{"title":"Implementation"}},"lastModified":"2026-08-11T10:42:42.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/checkout/components/ios/aeropay/implementation","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}