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 can 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.

curl -i -X POST \
  'https://api-services.pxp.io/api/v1/sessions' \
  -H 'Authorization: PXP-UST1 {tokenId}:{timestamp}:{hmac}' \
  -H 'X-Request-Id: {requestId}' \
  -H 'X-Client-Id: {clientId}' \
  -H 'Content-Type: application/json' \
  -d '{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "sessionTimeout": 120,
  "merchantTransactionId": "TRANSACTION-1",
  "amounts": {
    "currencyCode": "EUR",
    "transactionValue": 20
  }
}'

Header parameters

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 authenticate, you'll need to:

Create a unique request ID (UUID or GUID) for each API request.
Use your token value and request details to create an HMAC signature with cryptographic functions.

Header name	Description	Format
`Authorization Header`	The HMAC signature. This is made up of the authentication scheme, (e.g., PXP-UST1), your tokenId, the timestamp, and the HMAC value.	`"Authorization: PXP-UST1 {tokenId}:{timestamp}:{hmac}"` For example: `"Authorization:PXP-UST1tok_abc123def456:1703875200:a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"`
`X-Request-Id Header`	The unique request ID that you generated, in UUID or GUID format.	`"X-Request-Id: {requestId}"` For example: `"X-Request-Id: 550e8400-e29b-41d4-a716-446655440000"`
`X-Client-Id Header`	Your `clientId`, which identifies your specific client application.	`"X-Client-Id: {clientId}"` For example: `"X-Client-Id: f47ac10b-58cc-4372-a567-0e02b2c3d479"`

Body parameters

Parameter	Description
`merchant` string (≤ 20 characters) required	Your unique merchant identifier, as assigned by PXP. This is supplied to you during onboarding.
`site` string (≤ 20 characters) required	Your unique site identifier, as assigned by PXP. This is supplied to you during onboarding.
`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.
`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).

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": {},
      "applepay": {}
    }
  }
}

Parameter	Description
`sessionId` string (UUID) required	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. Note that currently, only `cards` is supported for Android. 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 the front-end.

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

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.models.CurrencyType
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

@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 = getSessionDataFromBE()

    // 2. Initialise the SDK
    val pxpCheckoutSdk = PxpCheckout.initialize(
        environment = "test",
        session = sessionData,
        ownerId = "Unity",
        ownerType = "MerchantGroup",
        merchantShopperId = "Shopper_01",
        transactionData = TransactionData(
            currency = CurrencyType.USD,
            amount = 25.0,
            entryType = "Ecom",
            intent = "Authorisation",
            merchantTransactionId = java.util.UUID.randomUUID().toString(),
            merchantTransactionDate = java.time.Instant.now().toString()
        )
    )

    onComplete(pxpCheckoutSdk)
}

Parameter	Description
`environment` string required	The environment type. Possible values: `test` `live`
`session` sessionData required	Details about the checkout session.
`ownerId` string required	The identifier of the owner related to the `ownerType`.
`ownerType` string required	The type of owner. Possible values: `MerchantGroup` `Merchant` Coming soon `Site` Coming soon
`merchantShopperId` string required	A unique identifier for this shopper.
`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` string required	The entry type. Possible values: `Ecom` `MOTO`
`transactionData.intent` string required	The transaction intent. Learn more about intents. Possible values: `Authorisation` `EstimatedAuthorisation` `Purchase` `Payout` `Verification`
`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.
`shippingAddress` object	Details about the shipping address.
`shippingAddress.address` string	The first line of the shipping address.
`shippingAddress.addressLine2` string	The second line of the shipping address.
`shippingAddress.city` string	The city of the shipping address.
`shippingAddress.postalCode` string	The postal or ZIP code of the shipping address.
`shippingAddress.countryCode` string (2 characters)	The country code of the shipping address, in ISO-3166-1 alpha-2 format.
`analyticsEvent: analyticsEventHandler`	Handler for analytics events.

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