Install the Android SDK library and start using components in your project.
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
- Target SDK: API level 35 (Android 15)
- Kotlin: Version 1.9.0 or higher
- Jetpack Compose: Version 1.5.8 or higher
- Google Play Services: Version 21.0.0 or higher (for Google Pay)
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.
- Download the AAR files:
pxpcheckout-debug.aar (Debug version)
pxpcheckout-release.aar (Release version)- Copy the AAR file to your project's
libsfolder:
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')
}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>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.
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", "googlepay": "Authorisation" } }, "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",
"googlepay": "Authorisation"
}
},
"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:
1DE2DFC390D7CD746A972140F26846AFA81CF85F5A0BAABA95DBC95301795EA6You 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",
"googlepay": "Authorisation"
}
},
"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"
}
}'| Parameter | Description |
|---|---|
merchantstring (≤ 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. |
sitestring (≤ 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. |
merchantTransactionIdstring (≤ 50 characters) required | A unique identifier of your choice that represents this transaction. |
sessionTimeoutnumber required | The duration of the session, in minutes. |
transactionMethodobject required | Details about the transaction method, including the intent for each payment type. |
transactionMethod.intentobject required | The transaction intent for each payment method. |
transactionMethod.intent.cardstring | The intent for card transactions. Possible values:
|
transactionMethod.intent.paypalstring | The intent for PayPal transactions. Possible values:
|
transactionMethod.intent.googlepaystring | The intent for Google Pay transactions. Possible values:
|
amountsobject required | Details about the transaction amount. |
amounts.currencyCodestring (3 characters) required | The currency code associated with the transaction, in ISO 4217 format. See Supported payment currencies. |
amounts.transactionValuenumber 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). |
authorisationboolean | Whether or not to proceed with authorisation. |
addressVerificationobject | 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.countryCodestring (≤ 2 characters) | The country associated with the cardholder's address, in ISO 3166-1 alpha-2 format. |
addressVerification.houseNumberOrNamestring (≤ 100 characters) | The house number or name associated with the cardholder's address. |
addressVerification.postalCodestring (≤ 10 characters) | The postal code of the cardholder's address. |
identityVerificationobject | Details about the cardholder's identity. These help in ensuring that the information provided matches the cardholder's details on file. |
identityVerification.nameVerificationboolean | Whether the cardholder's name matches the name associated with the registered address on file. |
threeDSecureDataobject | Details about the 3D Secure authentication data from an external authentication process. |
threeDSecureData.threeDSecureVersionstring (≤ 10 characters) | The 3DS protocol version. |
threeDSecureData.electronicCommerceIndicatorstring (≤ 2 characters) | The ECI value indicating the authentication result. |
threeDSecureData.cardHolderAuthenticationVerificationValuestring (≤ 50 characters) | The CAVV value from 3DS authentication. |
threeDSecureData.directoryServerTransactionIdstring (≤ 50 characters) | The Directory Server transaction identifier. |
threeDSecureData.threeDSecureTransactionStatusstring (≤ 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"
],
"merchantId": "paypal-merchant-123"
},
"googlePay": {
"merchantId": "googlepay-merchant-id",
"gatewayMerchantId": "gateway-merchant-id",
"merchantName": "Your Store Name"
},
"applepay": {}
}
},
"restrictions": {
"card": {
"ownerTypes": ["Consumer"],
"fundingSources": ["Credit", "Debit"]
}
}
}| Parameter | Description |
|---|---|
sessionIdstring (UUID) | The unique identifier for the newly-created session. |
hmacKeystring | The HMAC key generated for securing session communications. |
encryptionKeystring | A key used for encrypting sensitive session data during communication. |
sessionExpirystring | The timestamp indicating when the session will expire, in ISO 8601 format. |
allowedFundingTypesobject | Details about the funding types allowed for this session. Possible values:
|
allowedFundingTypes.cardsarray of strings or null | The list of supported card schemes. |
allowedFundingTypes.walletsarray of strings or null | The list of supported wallets. |
restrictionsobject or null | Optional card restrictions for frontend validation returned from the session. The restrictions object contains:
|
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
# PayPal Configuration (if using PayPal component)
PXP_PAYPAL_CLIENT_ID_TEST=your-test-paypal-client-id
PXP_PAYPAL_CLIENT_ID_LIVE=your-live-paypal-client-id
PXP_PAYPAL_LOGIN_RETURN_URL_TEST=https://your-test-domain.com/oauth/callback
PXP_PAYPAL_LOGIN_RETURN_URL_LIVE=https://your-production-domain.com/oauth/callbackPXP_BASE_URL_TEST and PXP_BASE_URL_LIVE are required. The build will fail if these are not provided. PayPal variables are only required if you're using the PayPal component.
The SDK includes consumer ProGuard rules that are automatically applied to your project. However, for release builds, ensure ProGuard/R8 is enabled in your app/build.gradle:
android {
buildTypes {
release {
minifyEnabled true
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
}
}
}The SDK automatically preserves all necessary classes. If you encounter issues, you can add these rules to your app/proguard-rules.pro:
# Keep PXP SDK classes
-keep class com.pxp.checkout.** { *; }
# Keep Google Pay SDK classes
-keep class com.google.android.gms.wallet.** { *; }
# Keep Kount SDK classes (fraud detection)
-keep class com.kount.** { *; }
-dontwarn com.kount.**If you're using the Google Pay component, add this meta-data to your AndroidManifest.xml:
<application>
<!-- Your application configuration -->
<!-- Google Pay API Configuration -->
<meta-data
android:name="com.google.android.gms.wallet.api.enabled"
android:value="true" />
</application>Then initialise the SDK in your Android application:
import com.pxp.PxpCheckout
import com.pxp.checkout.components.cardnumber.CardNumberComponent
import com.pxp.checkout.components.cardnumber.CardNumberComponentConfig
import com.pxp.checkout.models.*
import com.pxp.checkout.services.models.transaction.Shopper
import com.pxp.checkout.types.ComponentType
import androidx.compose.foundation.layout.*
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import java.util.*
@Composable
fun PaymentScreen() {
var pxpCheckout by remember { mutableStateOf<PxpCheckout?>(null) }
var cardNumberComponent by remember { mutableStateOf<CardNumberComponent?>(null) }
LaunchedEffect(Unit) {
// Initialise the SDK
pxpCheckout = initializeSDK()
}
LaunchedEffect(pxpCheckout) {
pxpCheckout?.let { checkout ->
// Create components after SDK is initialised
cardNumberComponent = checkout.createComponent(
type = ComponentType.CARD_NUMBER,
config = CardNumberComponentConfig(isRequired = true)
)
}
}
Column(
modifier = Modifier
.fillMaxWidth()
.padding(16.dp)
) {
// Render the card number component
cardNumberComponent?.Content()
}
}
suspend fun initializeSDK(): PxpCheckout {
// 1. Get the session data from your backend
val sessionData: SessionConfig = fetchSessionFromBackend()
// 2. Initialise the SDK using the builder pattern
return PxpCheckout.builder()
.withConfig(
PxpSdkConfig(
environment = Environment.TEST,
session = sessionData,
ownerId = "your-owner-id",
ownerType = "MerchantGroup",
transactionData = TransactionData(
amount = 25.00,
currency = "USD",
entryType = EntryType.Ecom,
intent = TransactionIntentData(
card = IntentType.Authorisation,
paypal = IntentType.Purchase
),
merchant = "your-merchant-id",
merchantTransactionId = UUID.randomUUID().toString(),
merchantTransactionDate = {
// Return ISO 8601 formatted date string
java.text.SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'", java.util.Locale.US)
.apply { timeZone = java.util.TimeZone.getTimeZone("UTC") }
.format(Date())
}
),
kountDisabled = false, // OPTIONAL: Set to true to disable Kount fraud detection
// OPTIONAL: Provide shopper data dynamically
onGetShopper = {
Shopper(
id = "shopper-123",
email = "customer@example.com",
firstName = "John",
lastName = "Doe",
phoneNumber = "+1-555-0123"
)
},
// OPTIONAL: Provide shipping address dynamically
onGetShippingAddress = {
ShippingAddress(
addressLine1 = "123 Main Street",
addressLine2 = "Apt 4B",
city = "New York",
state = "NY",
postalCode = "10001",
countryCode = "US"
)
},
// OPTIONAL: Restrict accepted card types for frontend validation
restrictions = Restrictions(
card = RestrictionsCard(
ownerTypes = listOf(RestrictionOwnerType.CONSUMER),
fundingSources = listOf(RestrictionFundingSource.CREDIT, RestrictionFundingSource.DEBIT)
)
),
// OPTIONAL: PayPal payout configuration (if using PayPal payouts)
paypalConfig = PaypalConfig(
payout = PayoutConfig(
paypalWallet = PayPalPayOutWalletConfig(
email = "recipient@example.com",
payerId = "PAYER123"
),
venmoWallet = VenmoPayOutWalletConfig(
recipientType = VenmoRecipientType.EMAIL,
receiver = "recipient@example.com"
),
proceedPayoutWithSdk = true
)
)
)
)
.withContext(getApplicationContext())
.build()
}
// Fetch session from your backend
suspend fun fetchSessionFromBackend(): SessionConfig {
// Make API call to your backend to get session data
// Your backend should call the PXP Sessions API
// See Step 4 for details on the Sessions API
return SessionConfig(
sessionId = "session-id-from-backend",
hmacKey = "hmac-key-from-backend",
data = "session-data-from-backend",
encryptionKey = "encryption-key-from-backend",
locale = "en-US",
allowedFundingTypes = AllowedFundingTypes(
cards = listOf("Visa", "Mastercard", "AmericanExpress"),
wallets = WalletsConfig(
paypal = PayPalWalletConfig(
allowedFundingOptions = listOf("paypal", "paylater", "venmo")
),
googlePay = GooglePayWalletConfig()
)
),
restrictions = Restrictions(
card = RestrictionsCard(
ownerTypes = listOf(RestrictionOwnerType.CONSUMER),
fundingSources = listOf(RestrictionFundingSource.CREDIT, RestrictionFundingSource.DEBIT)
)
)
)
}| Parameter | Description |
|---|---|
environmentEnvironment required | The environment type enum. Possible values:
|
sessionSessionConfig required | Details about the checkout session. This is a SessionConfig object containing sessionId, hmacKey, encryptionKey, sessionExpiry, and optional allowedFundingTypes. Get this from your backend by calling the Sessions API (see Step 4). |
ownerIdstring required | The identifier of the owner related to the ownerType. Get this from the Unity Portal. |
ownerTypestring required | The type of owner. Always set this to "MerchantGroup". |
transactionDataTransactionData required | Details about the transaction. |
transactionData.amountDouble required | The transaction amount as a Double (e.g., 25.00). |
transactionData.currencyString (3 characters) required | The currency code associated with the transaction, in ISO 4217 format (e.g., "USD", "GBP", "EUR"). |
transactionData.merchantString required | Your unique merchant identifier, as assigned by PXP. Get this from the Unity Portal. |
transactionData.merchantTransactionIdString required | A unique identifier for this transaction. Use UUID.randomUUID().toString(). |
transactionData.merchantTransactionDate() -> String required | A callback function that returns the transaction date as an ISO 8601 formatted string. |
transactionData.entryTypeEntryType | The entry type for the transaction. Possible values:
|
transactionData.intentTransactionIntentData | The transaction intents for each payment method. |
transactionData.intent.cardIntentType | The intent for card transactions. Possible values:
|
transactionData.intent.paypalIntentType | The intent for PayPal transactions. Possible values:
|
kountDisabledBoolean | Whether to disable the Kount fraud detection service. Defaults to false (fraud detection enabled). |
onGetShopper() -> Shopper? | Optional callback function to provide shopper data dynamically. Returns a Shopper object with shopper information including ID, email, name, and contact details. |
onGetShippingAddress() -> ShippingAddress? | Optional callback function to provide shipping address data dynamically. Returns a ShippingAddress object with current shipping address information. |
restrictionsRestrictions | Optional card restrictions for frontend validation. Restricts what card types are accepted in the new card component. The Restrictions object contains:
RestrictionsCard object contains:
If restrictions are specified in both the session (via Sessions API) and the SDK config, they are merged using a union approach: session restrictions come first, followed by SDK-only values. If a restriction axis is empty after merging, it becomes null. |
paypalConfigPaypalConfig | Optional PayPal configuration for payout operations. Contains wallet configurations for PayPal and Venmo payouts. See PayPal payouts documentation for details. |
Cause: Required environment variables are missing from gradle.properties.
Solution: Ensure your gradle.properties file contains all required variables:
PXP_BASE_URL_TEST=https://api-services.test.pxp.io
PXP_BASE_URL_LIVE=https://api-services.pxp.ioCause: ProGuard rules are not properly configured.
Solution: The SDK includes consumer ProGuard rules that should be automatically applied. If issues persist, add the rules manually to your app/proguard-rules.pro (see ProGuard configuration section above).
Cause: The AAR file is not properly included, or the module dependency is not configured correctly.
Solution:
- For AAR installation: Verify the file is in
app/libs/and the dependency is added tobuild.gradle - For source code integration: Ensure the module is properly imported and added as a dependency
- Sync your Gradle project: File > Sync Project with Gradle Files
Cause: Kotlin version doesn't match Compose compiler version.
Solution: Ensure your build.gradle has:
composeOptions {
kotlinCompilerExtensionVersion '1.5.8'
}Cause: Missing Google Pay meta-data or Google Play Services.
Solution:
- Add the Google Pay meta-data to your
AndroidManifest.xml(see configuration section above) - Ensure Google Play Services is installed on the device
- For testing, use a device with a Google account and at least one payment method configured
Now that you've installed and initialised the SDK, you're ready to start integrating payment components:
That's it! You've successfully installed the PXP Checkout SDK and created your first component. The SDK is now ready to use in your Android application.