Install the Android SDK

Install the Android SDK library and start using components in your project.

Before you start

Make sure you meet the system requirements:

Android Studio: Latest stable version (recommended: Android Studio Hedgehog or later).
Java Development Kit (JDK): Version 17 or higher.
Android SDK: API level 24 (Android 7.0) or higher.
Kotlin: Version 1.9.0 or higher.
Jetpack Compose: Version 1.5.8 or higher.

Step 1: Install the Android SDK library

To get started, download the latest version of the Android SDK from Maven.

You can choose between two installation methods:

AAR (Android Archive) library installation.
Source code integration.

Method 1: AAR library installation (recommended)

Download the AAR files:

pxpcheckout-debug.aar    (Debug version)
pxpcheckout-release.aar  (Release version)

Copy the AAR file to your project's libs folder:

your-project/
├── app/
│   ├── libs/
│   │   └── pxpcheckout-release.aar
│   └── build.gradle

Add the AAR dependency to your app/build.gradle:

dependencies {
    implementation files('libs/pxpcheckout-release.aar')
}

Method 2: Source code integration

Clone the repository:

git clone <repository-url>
cd Pxp.Unity.Components.Android

In Android Studio, go to File > New > Import Module.
Select the pxpcheckout folder.

Add the module dependency in your app/build.gradle:

dependencies {
    implementation project(':pxpcheckout')
}

Step 2: Add the required permissions

Add the following permissions to your AndroidManifest.xml:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    
    <!-- Required permission for 3DS Challenge overlay -->
    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
    
    <!-- Required permission for internet access -->
    <uses-permission android:name="android.permission.INTERNET" />
    
    <!-- Required permission for network state checking -->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    
    <!-- Optional: For enhanced security features -->
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    
    <application>
        <!-- Your application configuration -->
    </application>
</manifest>

Step 3: Get your API credentials

In order to initialise the SDK, you'll need to send authenticated requests to the PXP API.

To get your credentials:

In the Unity Portal, go to Merchant setup > Merchant groups.
Select a merchant group.
Click the Inbound calls tab.
Copy the Client ID in the top-right corner.
Click New token.
Choose a number of days before token expiry. For example, 30.
Click Save to confirm. Your token is now created.
Copy the token ID and token value. Make sure to keep these confidential to protect the integrity of your authentication process.

As best practice, we recommend regularly generating and implementing new tokens.

Step 4: Get the session data

Now that you have your credentials, you're ready to send an API request to the sessions endpoint. This allows you to retrieve the transaction session data from the back-end, so you can supply it when you initialise the SDK.

Our platform uses HMAC (Hash-based Message Authentication Code) with SHA256 for authentication to ensure secure communication and data integrity. This method involves creating a signature by hashing your request data with a secret key, which must then be included in the HTTP headers of your API request.

To create the HMAC signature, you need to prepare a string that includes four parts:

A timestamp, in Unix format. For example, 1754701373.
A unique request ID, in GUID format. For example, ce244054-b372-42c2-9102-f0d976db69f6.
The request path, which is api/v1/sessions.

The request body. For example:

{
   "merchant": "MERCHANT-1",
   "site": "SITE-1",
   "sessionTimeout": 120,
   "merchantTransactionId": "0ce72cfd-014d-4256-a006-a56601b2ffc4",
   "transactionMethod": {
     "intent": {
       "card": "Authorisation",
       "paypal": "Purchase"
     }
   },
   "amounts": {
     "currencyCode": "EUR",
     "transactionValue": 20
   },
   "authorisation": true,
   "addressVerification": {
     "countryCode": "GB",
     "houseNumberOrName": "10 Downing Street",
     "postalCode": "SW1A 2AA"
   },
   "identityVerification": {
     "nameVerification": true
   },
   "threeDSecureData": {
     "threeDSecureVersion": "2.2",
     "electronicCommerceIndicator": "05",
     "cardHolderAuthenticationVerificationValue": "CAVV1234567890",
     "directoryServerTransactionId": "550e8400-e29b-41d4-a716-446655440000",
     "threeDSecureTransactionStatus": "Y"
   }
}

Put these four parts together following this format: "{timestamp}{requestId}{requestPath}{requestBody}". The result should look something like this:

1754701373ce244054-b372-42c2-9102-f0d976db69f6api/v1/sessions{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "sessionTimeout": 120,
  "merchantTransactionId": "0ce72cfd-014d-4256-a006-a56601b2ffc4",
  "transactionMethod": {
    "intent": {
      "card": "Authorisation",
      "paypal": "Purchase"
    }
  },
  "amounts": {
    "currencyCode": "EUR",
    "transactionValue": 20
  },
  "authorisation": true,
  "addressVerification": {
    "countryCode": "GB",
    "houseNumberOrName": "10 Downing Street",
    "postalCode": "SW1A 2AA"
  },
  "identityVerification": {
    "nameVerification": true
  },
  "threeDSecureData": {
    "threeDSecureVersion": "2.2",
    "electronicCommerceIndicator": "05",
    "cardHolderAuthenticationVerificationValue": "CAVV1234567890",
    "directoryServerTransactionId": "550e8400-e29b-41d4-a716-446655440000",
    "threeDSecureTransactionStatus": "Y"
  }
}

Use your token ID to encrypt this data structure by SHA256. You can find your token ID in the Unity Portal. Here's an example of an hmacSignature after you've encrypted the data:

1DE2DFC390D7CD746A972140F26846AFA81CF85F5A0BAABA95DBC95301795EA6

You can now put together your Authorization header. It follows this format: PXP-UST1 {tokenId}:{timestamp}:{hmacSignature}. For example:

"PXP-UST1 9aac6071-38d0-4545-9d2f-15b936af6d7f:1754701373:1DE2DFC390D7CD746A972140F26846AFA81CF85F5A0BAABA95DBC95301795EA6"

Lastly, send your request to the Sessions API. You'll need to add a request ID of your choice and include your client ID, which you can find in the Unity Portal.

Here's a full example of what your request might look like:

curl -i -X POST \
  'https://api-services.pxp.io/api/v1/sessions' \
  -H 'Authorization: "PXP-UST1 9aac6071-38d0-4545-9d2f-15b936af6d7f:1754701373:1DE2DFC390D7CD746A972140F26846AFA81CF85F5A0BAABA95DBC95301795EA6"' \
  -H 'X-Request-Id: "550e8400-e29b-41d4-a716-446655440000"' \
  -H 'X-Client-Id: "f47ac10b-58cc-4372-a567-0e02b2c3d479"' \
  -H 'Content-Type: application/json' \
  -d '{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "sessionTimeout": 120,
  "merchantTransactionId": "0ce72cfd-014d-4256-a006-a56601b2ffc4",
  "transactionMethod": {
    "intent": {
      "card": "Authorisation",
      "paypal": "Purchase"
    }
  },
  "amounts": {
    "currencyCode": "EUR",
    "transactionValue": 20
  },
  "authorisation": true,
  "addressVerification": {
    "countryCode": "GB",
    "houseNumberOrName": "10 Downing Street",
    "postalCode": "SW1A 2AA"
  },
  "identityVerification": {
    "nameVerification": true
  },
  "threeDSecureData": {
    "threeDSecureVersion": "2.2",
    "electronicCommerceIndicator": "05",
    "cardHolderAuthenticationVerificationValue": "CAVV1234567890",
    "directoryServerTransactionId": "550e8400-e29b-41d4-a716-446655440000",
    "threeDSecureTransactionStatus": "Y"
  }
}'

Body parameters

Parameter	Description
`merchant` string (≤ 20 characters) required	Your unique merchant identifier, as assigned by PXP. You can find it in the Unity Portal, by going to Merchant setup > Merchants and checking the Merchant ID column or by clicking on a merchant and checking the General information section.
`site` string (≤ 20 characters) required	Your unique site identifier, as assigned by PXP. You can find it in the Unity Portal, by going to Merchant setup > Sites and checking the Site ID column or by clicking on a site and checking the General information section.
`merchantTransactionId` string (≤ 50 characters) required	A unique identifier of your choice that represents this transaction.
`sessionTimeout` number required	The duration of the session, in minutes.
`transactionMethod` object required	Details about the transaction method, including the intent for each payment type.
`transactionMethod.intent` object required	The transaction intent for each payment method.
`transactionMethod.intent.card` string	The intent for card transactions. Possible values: `Authorisation` `Purchase` `Verification` `EstimatedAuthorisation` `Payout`
`transactionMethod.intent.paypal` string	The intent for PayPal transactions. Possible values: `Authorisation` `Purchase`
`amounts` object required	Details about the transaction amount.
`amounts.currencyCode` string (3 characters) required	The currency code associated with the transaction, in ISO 4217 format. See Supported payment currencies.
`amounts.transactionValue` number required	The transaction amount. The numbers after the decimal will be zero padded if they are less than the expected `currencyCode` exponent. For example, GBP 1.1 = GBP 1.10, EUR 1 = EUR 1.00, or BHD 1.3 = 1.300. The transaction will be rejected if numbers after the decimal are greater than the expected `currencyCode` exponent (e.g., GBP 1.234), or if a decimal is supplied when the `currencyCode` of the exponent does not require it (e.g., JPY 1.0).
`authorisation` boolean	Whether or not to proceed with authorisation.
`addressVerification` object	Details about the cardholder's address. These help in the validation and fraud prevention process by matching the provided address with the cardholder's address on file.
`addressVerification.countryCode` string (≤ 2 characters)	The country associated with the cardholder's address, in ISO 3166-1 alpha-2 format.
`addressVerification.houseNumberOrName` string (≤ 100 characters)	The house number or name associated with the cardholder's address.
`addressVerification.postalCode` string (≤ 10 characters)	The postal code of the cardholder's address.
`identityVerification` object	Details about the cardholder's identity. These help in ensuring that the information provided matches the cardholder's details on file.
`identityVerification.nameVerification` boolean	Whether the cardholder's name matches the name associated with the registered address on file.
`threeDSecureData` object	Details about the 3D Secure authentication data from an external authentication process.
`threeDSecureData.threeDSecureVersion` string (≤ 10 characters)	The 3DS protocol version.
`threeDSecureData.electronicCommerceIndicator` string (≤ 2 characters)	The ECI value indicating the authentication result.
`threeDSecureData.cardHolderAuthenticationVerificationValue` string (≤ 50 characters)	The CAVV value from 3DS authentication.
`threeDSecureData.directoryServerTransactionId` string (≤ 50 characters)	The Directory Server transaction identifier.
`threeDSecureData.threeDSecureTransactionStatus` string (≤ 1 character)	The 3DS transaction status.

If your request is successful, you'll receive a 200 response containing the session data.

{
  "sessionId": "c5f0799b-0839-43ce-abc5-5b462a98f250",
  "hmacKey": "904bc42395d4af634e2fd48ee8c2c7f52955a1da97a3aa3d82957ff12980a7bb",
  "encryptionKey": "20d175a669ad3f8c195c9c283fc86155",
  "sessionExpiry": "2025-05-19T13:39:20.3843454Z",
  "allowedFundingTypes": {
    "cards": [
      "Visa",
      "Diners",
      "Mastercard",
      "AmericanExpress"
    ],
    "wallets": {
      "paypal": {
        "allowedFundingOptions": [
          "venmo", 
          "paylater", 
          "paypal"
        ]
      },
      "applepay": {}
    }
  }
}

Parameter	Description
`sessionId` string (UUID)	The unique identifier for the newly-created session.
`hmacKey` string	The HMAC key generated for securing session communications.
`encryptionKey` string	A key used for encrypting sensitive session data during communication.
`sessionExpiry` string	The timestamp indicating when the session will expire, in ISO 8601 format.
`allowedFundingTypes` object	Details about the funding types allowed for this session. Possible values: `cards` `wallets`
`allowedFundingTypes.cards` array of strings or null	The list of supported card schemes.
`allowedFundingTypes.wallets` array of strings or null	The list of supported wallets.

Step 5: Initialise the SDK

To initialise the SDK, you then need to pass this session data back to your Android application.

You'll also need to provide details about the environment you're using, your owner ID and type, the transaction data, and optionally provide shopper and shipping address data dynamically.

First, set up your environment configuration in gradle.properties:

# PXP Checkout Environment Configuration
# Test Environment URLs
PXP_BASE_URL_TEST=https://api-services.test.pxp.io
PXP_BASE_URL_TEST_DEBUG=https://api-services.test.pxp.io

# Live Environment URLs
PXP_BASE_URL_LIVE=https://api-services.pxp.io
PXP_BASE_URL_LIVE_DEBUG=https://api-services.pxp.io

Then initialise the SDK in your Android application:

import com.pxp.checkout.PxpCheckout
import com.pxp.checkout.components.CardNumberComponent
import com.pxp.checkout.components.CardNumberComponentConfig
import com.pxp.checkout.models.PxpSdkConfig
import com.pxp.checkout.models.SessionConfig
import com.pxp.checkout.models.Environment
import com.pxp.checkout.models.TransactionData
import com.pxp.checkout.models.TransactionIntentData
import com.pxp.checkout.models.EntryType
import com.pxp.checkout.models.IntentType
import com.pxp.checkout.models.ShippingAddress
import com.pxp.checkout.services.models.transaction.Shopper
import com.pxp.checkout.types.ComponentType
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import java.util.UUID

@Composable
fun CreateComponent() {
    var pxpCheckout by remember { mutableStateOf<PxpCheckout?>(null) }
    var cardNumberComponent by remember { mutableStateOf<CardNumberComponent?>(null) }

    LaunchedEffect(Unit) {
        initializeTheSdk { checkout ->
            pxpCheckout = checkout
        }
    }

    LaunchedEffect(pxpCheckout) {
        pxpCheckout?.let { checkout ->
            // Create and customise components
            cardNumberComponent = checkout.createComponent(
                ComponentType.CARD_NUMBER,
                CardNumberComponentConfig(isRequired = true)
            )
        }
    }

    Column(
        modifier = Modifier
            .fillMaxWidth()
            .padding(16.dp)
    ) {
        // Render the card number component
        cardNumberComponent?.let { component ->
            component.BuildComponent()
        }
    }
}

suspend fun initializeTheSdk(onComplete: (PxpCheckout) -> Unit) {
    // 1. Get the session data from the back-end
    val sessionData: SessionConfig = getSessionDataFromBE()

    // 2. Initialise the SDK
    val pxpCheckoutSdk = PxpCheckout.builder()
        .withConfig(
            PxpSdkConfig(
                environment = Environment.TEST,
                session = sessionData,
                ownerId = "Unity",
                ownerType = "MerchantGroup",
                transactionData = TransactionData(
                    amount = 25.0,
                    currency = "USD",
                    merchant = "MERCHANT-1",
                    entryType = EntryType.Ecom,
                    intent = object : TransactionIntentData {
                        override val card: IntentType? = IntentType.Authorisation
                        override val paypal: IntentType? = IntentType.Purchase
                    },
                    merchantTransactionId = UUID.randomUUID().toString(),
                    merchantTransactionDate = { 
                        java.time.Instant.now().toString() 
                    }
                ),
                onGetShopper = {
                    // Return current shopper data dynamically
                    Shopper(
                        id = "shopper-123",
                        email = "customer@example.com",
                        firstName = "John",
                        lastName = "Doe",
                        phoneNumber = "+1-555-0123"
                    )
                },
                onGetShippingAddress = {
                    // Return current shipping address dynamically
                    ShippingAddress(
                        addressLine1 = "123 Main Street",
                        addressLine2 = "Apt 4B",
                        city = "New York",
                        state = "NY",
                        postalCode = "10001",
                        countryCode = "US"
                    )
                }
            )
        )
        .withContext(getApplicationContext())
        .build()

    onComplete(pxpCheckoutSdk)
}

Parameter	Description
`environment` Environment required	The environment type enum. Possible values: `Environment.TEST` `Environment.LIVE`
`session` SessionConfig required	Details about the checkout session. This is a `SessionConfig` object containing `sessionId`, `hmacKey`, `data`, `encryptionKey`, `locale`, and optional `allowedFundingTypes`.
`ownerId` string required	The identifier of the owner related to the `ownerType`.
`ownerType` string required	The type of owner. Set this to `"MerchantGroup"`. Possible values: `"MerchantGroup"` `"Merchant"` Coming soon `"Site"` Coming soon
`onGetShopper` function	Callback function to provide shopper data dynamically. Returns a `Shopper` object with shopper information including ID, email, name, and contact details.
`onGetShippingAddress` function	Callback function to provide shipping address data dynamically. Returns a `ShippingAddress` object with current shipping address information.
`transactionData` object required	Details about the transaction.
`transactionData.currency` string (1-3 characters) required	The currency code associated with the transaction, in ISO 4217 format.
`transactionData.amount` number	The transaction amount.
`transactionData.entryType` EntryType? required	The entry type sealed class. Possible values: `EntryType.Ecom` `EntryType.MOTO`
`transactionData.intent` TransactionIntentData required	The transaction intents for each payment method. This is an object implementing the `TransactionIntentData` interface with `card` and `paypal` properties. Learn more about intents for card or PayPal.
`transactionData.intent.card` IntentType?	The intent for card transactions. Possible values: `IntentType.Authorisation` `IntentType.EstimatedAuthorisation` `IntentType.Purchase` `IntentType.Payout` `IntentType.Verification`
`transactionData.intent.paypal` IntentType?	The intent for PayPal transactions. Possible values: `IntentType.Authorisation` `IntentType.Purchase`
`transactionData.merchant` string required	Your unique merchant identifier, as assigned by PXP.
`transactionData.merchantTransactionId` string required	A unique identifier for this transaction.
`transactionData.merchantTransactionDate` string required	The date and time of the transaction, in ISO 8601 format.
`analyticsEvent: analyticsEventHandler`	Handler for analytics events.

That's it! You've got your first card component up and running.