Skip to content

Aeropay onboarding

Configure Aeropay in the Unity Portal and connect your merchant account.

Before you start

If you haven't already, make sure that you have activated the Components service in the Unity Portal. For more information, see Activate Components.

You'll also need the following account details, provided by Aeropay:

  • Merchant ID
  • API key
  • API secret
  • Configuration ID

Step 1: Ensure Aeropay is enabled at the merchant group level

Aeropay must be enabled for your merchant group before it can be configured on individual sites.

  1. In the Unity Portal, go to Merchant setup > Merchant groups.
  2. Select your merchant group.
  3. In the Services tab, find Aeropay service.
  4. If Aeropay is not listed, click Add service and select Aeropay.

Step 2: Get your PXP API credentials

Your backend needs API credentials to create checkout sessions with HMAC authentication.

  1. In the Unity Portal, go to Merchant setup > Merchant groups.
  2. Select your merchant group.
  3. Click the Inbound calls tab.
  4. Copy the Client ID shown in the top-right corner.
  5. Click + New token to create an authentication token.
  6. Choose an expiry period and click Save.
  7. Copy both the token ID and token value. Store these securely on your backend.

Never expose your token value or HMAC credentials in your iOS app. Session creation must happen on your backend.

Step 3: Configure Aeropay on your site

Add your Aeropay account details to each site where you'll accept Aeropay payments or payouts.

  1. In the Unity Portal, go to Merchant setup > Sites.
  2. Select the site you want to enable Aeropay for.
  3. Click the Services tab.
  4. Select Aeropay service and click Edit.
  5. Enter the Merchant ID, API key, API secret, and Configuration ID provided by Aeropay.
  6. Click Save in the top right.

Step 4: Verify session configuration

After saving your Aeropay account settings, create a test session from your backend and confirm that Aeropay is included in the response.

The session request must enable Aeropay. Use the following checklist:

  1. Use the correct merchant and site IDs for the Aeropay-enabled site.
  2. Set amounts.currencyCode to USD.
  3. Include a supported Aeropay intent under transactionMethod.intent.aeropay, for example:
"transactionMethod": {
  "intent": {
    "aeropay": "Authorisation"
  }
}

Supported intent values are Authorisation, Purchase, EstimatedAuthorisation, and Payout. For the full HMAC and session walkthrough, see the iOS install guide.

Portal field names for the site Aeropay service map to these session properties:

Unity Portal (site Aeropay service)Session response (allowedFundingTypes.payByBanks.aeropay)
Merchant IDexternalMerchantId
Configuration IDconfigurationId

The API key and API secret are stored in the portal for backend and provider use. The iOS SDK only needs non-empty externalMerchantId and configurationId at component creation. It doesn't read apiKey or apiSecret from the session on the client.

A correctly configured session includes Aeropay pay-by-bank settings:

{
  "sessionId": "c5f0799b-0839-43ce-abc5-5b462a98f250",
  "hmacKey": "904bc42395d4af634e2fd48ee8c2c7f52955a1da97a3aa3d82957ff12980a7bb",
  "encryptionKey": "20d175a669ad3f8c195c9c283fc86155",
  "allowedFundingTypes": {
    "payByBanks": {
      "aeropay": {
        "externalMerchantId": "your-aeropay-merchant-id",
        "configurationId": "your-aerosync-configuration-id"
      }
    }
  }
}

If allowedFundingTypes.payByBanks.aeropay is missing, or externalMerchantId or configurationId is empty, the SDK throws SDK0113 when you create the component. The SDK message is generic: Aeropay is missing in allow funding types. It doesn't name the missing field, so inspect allowedFundingTypes.payByBanks.aeropay in the session response. See Portal and session setup.

What's next?

  • Implementation: Integrate the Aeropay button into your iOS app.
  • Testing: Test your integration in the sandbox environment.
  • How it works: Understand the Aeropay payment and payout flows.

If you run into setup issues, see Portal and session setup in Troubleshooting.