Install the Android SDK library and start using PayPal payout components in your project.
Make sure you meet the system requirements:
| Requirement | Minimum or notes |
|---|---|
minSdk | 24 |
compileSdk | 37 or higher |
| Kotlin | 2.x |
| Jetpack Compose | Required (SDK UI is Compose-based) |
| Java desugaring | Recommended for Java 8+ APIs |
| Android Studio | Latest stable version (Hedgehog or later recommended) |
| Java Development Kit (JDK) | 17 (matches the SDK sourceCompatibility and jvmTarget) |
| Custom Tabs browser | Chrome or another Custom Tabs-compatible browser (used for PayPal browser flows) |
Use minSdk 24, Kotlin 2.x, Jetpack Compose, JDK 17, and core library desugaring. Set your app compileSdk to 37 or higher.
The SDK pulls transitive dependencies (Compose, Retrofit, OkHttp, Gson, Koin, and others) via its POM. Some transitive dependencies are hosted on JitPack rather than Maven Central — your project must declare the JitPack repository so Gradle can download them when resolving the SDK.
Add the latest PXP Android Components SDK from Maven Central in your Android app. Browse published versions, dependencies, and the POM on the artifact page.
Add mavenCentral() and the JitPack repository in your project-level build.gradle, settings.gradle, or dependencyResolutionManagement block:
repositories {
google()
mavenCentral()
maven { url = 'https://jitpack.io' } // Required for some SDK transitive dependencies hosted on JitPack
}The SDK UI is Compose-based. Apply the Kotlin Compose plugin in your root and app module build files.
Root build.gradle:
buildscript {
ext.kotlin_version = "<kotlin-version>"
dependencies {
classpath "com.android.tools.build:gradle:<agp-version>"
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
classpath "org.jetbrains.kotlin:compose-compiler-gradle-plugin:$kotlin_version"
}
}
plugins {
id 'org.jetbrains.kotlin.plugin.compose' version '<kotlin-version>' apply false
}App module plugins:
plugins {
id 'com.android.application'
id 'org.jetbrains.kotlin.plugin.compose'
}Configure your app module and add the Maven Central dependency:
plugins {
id 'com.android.application'
id 'org.jetbrains.kotlin.plugin.compose'
}
android {
compileSdk = 37
defaultConfig {
minSdk = 24
}
compileOptions {
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
coreLibraryDesugaringEnabled = true
}
buildFeatures {
compose = true
}
}
dependencies {
coreLibraryDesugaring "com.android.tools:desugar_jdk_libs:2.1.5"
implementation "io.pxp:android-components-sdk:{versionNumber}"
// Your app Compose dependencies (example)
implementation platform("androidx.compose:compose-bom:{composeBomVersion}")
implementation "androidx.compose.ui:ui"
implementation "androidx.compose.material3:material3"
implementation "androidx.activity:activity-compose:1.8.2"
}Sync Gradle. Android Studio downloads the AAR from Maven Central.
Open the Maven Central artifact page and select the Versions tab, or query metadata directly:
curl -s https://repo.maven.apache.org/maven2/io/pxp/android-components-sdk/maven-metadata.xmlUse the <release> value (or the version shown on Sonatype) in your implementation line.
Confirm the SDK resolves on your compile classpath:
./gradlew :app:dependencies --configuration debugCompileClasspath | grep io.pxpExpected output includes io.pxp:android-components-sdk:<version>.
The SDK automatically merges the required permissions from its manifest, including:
INTERNET: required for API communicationACCESS_NETWORK_STATE: required for network state checkingSYSTEM_ALERT_WINDOW: merged by the SDK for challenge overlays
The SDK also merges a Custom Tabs <queries> entry so the SDK can detect a Custom Tabs-compatible browser.
No manual manifest configuration is required. These entries are merged automatically when you add the SDK dependency.
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": { "paypal": "Payout" } }, "amounts": { "currencyCode": "USD", "transactionValue": 100 }, "allowTransaction": true }
Put these four parts together as one concatenated string with no separators: {timestamp}{requestId}{requestPath}{requestBody}. {requestBody} must be the exact JSON bytes you send in the POST body (typically minified, no extra whitespace). For example:
1754701373ce244054-b372-42c2-9102-f0d976db69f6api/v1/sessions{"merchant":"MERCHANT-1","site":"SITE-1","sessionTimeout":120,"merchantTransactionId":"0ce72cfd-014d-4256-a006-a56601b2ffc4","transactionMethod":{"intent":{"paypal":"Payout"}},"amounts":{"currencyCode":"USD","transactionValue":100},"allowTransaction":true}Use your token value (secret) to HMAC-SHA256 this string. You can find your token ID in the Unity Portal. Here's an example of an hmacSignature after you've signed 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:1DE2DFC390D7CD746A972140F26846AFA81CF85F5A0BAABA95DBC95301795EA6Lastly, send your request to the Sessions API.
Here's a full example of what your request might look like:
Use the production host https://api-services.pxp.io/api/v1 or the sandbox host https://api-services.test.pxp.io/api/v1.
curl -i -X POST \
'https://api-services.test.pxp.io/api/v1/sessions' \
-H 'Authorization: PXP-UST1 9aac6071-38d0-4545-9d2f-15b936af6d7f:1754701373:1DE2DFC390D7CD746A972140F26846AFA81CF85F5A0BAABA95DBC95301795EA6' \
-H 'Content-Type: application/json' \
-d '{
"merchant": "MERCHANT-1",
"site": "SITE-1",
"sessionTimeout": 120,
"merchantTransactionId": "0ce72cfd-014d-4256-a006-a56601b2ffc4",
"transactionMethod": {
"intent": {
"paypal": "Payout"
}
},
"amounts": {
"currencyCode": "USD",
"transactionValue": 100
},
"allowTransaction": true
}'Use these fields in the Sessions API request body. Required fields are merchant, site, merchantTransactionId, amounts, and transactionMethod.
| 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 for this transaction. |
sessionTimeoutinteger (≥ 1) | The duration of the session, in minutes. |
transactionMethodobject required | Details about the transaction method. |
transactionMethod.intentobject required | Details about the intent for different payment methods. |
transactionMethod.intent.paypalstring | The intent for PayPal. For PayPal payouts, set this to Payout. Possible values: Authorisation, Purchase, Payout. |
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 currencies. |
amounts.transactionValuenumber (≥ 0) 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). |
allowTransactionboolean or null | Whether the transaction is allowed to proceed. If not provided, defaults to null (no decision made yet). |
If your request is successful, you'll receive a 200 response containing the session data.
{
"sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"hmacKey": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"encryptionKey": "k8l9m0n1o2p3q4r5s6t7u8v9w0x1y2z",
"sessionExpiry": "2025-05-19T13:39:20.3843454Z",
"allowedFundingTypes": {
"wallets": {
"paypal": {
"allowedFundingOptions": [
"paypal"
],
"merchantId": "PayPalMerchant123"
}
}
}
}Map these response fields into your SDK session configuration. The Sessions API response always includes sessionId, hmacKey, encryptionKey, and sessionExpiry.
| Parameter | Description |
|---|---|
sessionIdstring (UUID) | The unique identifier for the created session. Required for SDK initialisation. |
hmacKeystring | The HMAC key generated for securing session communications. Required for SDK initialisation. |
encryptionKeystring | A key used for encrypting sensitive session data during communication. Required for SDK initialisation. |
sessionExpirystring (date-time) | The timestamp indicating when the session will expire, in ISO 8601 format. The Android SDK's SessionConfig model does not include this field. |
datastring or null | Optional session data payload from the Sessions API. The Android SessionConfig model still requires a data string when you build the config. If the API omits data, pass an empty string (""). |
allowedFundingTypesobject | Details about the funding types allowed for this session. |
allowedFundingTypes.walletsobject | Details about the wallets allowed for this session. Map this to SessionConfig.allowedFundingTypes.wallets. |
allowedFundingTypes.wallets.paypalobject | The PayPal configuration settings. Maps to WalletsConfig.paypal. |
allowedFundingTypes.wallets.paypal.allowedFundingOptionsarray of strings | The list of allowed funding options for PayPal. |
allowedFundingTypes.wallets.paypal.merchantIdstring or null | The PayPal merchant identifier. |
To initialise the SDK, you need to pass the session data from Step 4 back to your Android application.
You'll also need to provide your client ID, details about the environment, your owner ID and type, the transaction data with a PayPal payout intent, and a paypalConfig for payout behaviour.
The SDK release AAR is minified at publish time and ships consumer ProGuard rules as proguard.txt inside the AAR. Gradle merges them automatically.
Enable minify in your app release build:
android {
buildTypes {
release {
minifyEnabled true
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
}
}
}Here's a complete example showing how to initialise the SDK and create PayPal payout components for a returning customer:
import android.content.Context
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import com.pxp.PxpCheckout
import com.pxp.checkout.components.payoutamount.PayoutAmountComponent
import com.pxp.checkout.components.payoutamount.PayoutAmountComponentConfig
import com.pxp.checkout.components.paypalpayoutreceiver.PaypalPayoutReceiverComponent
import com.pxp.checkout.components.paypalpayoutreceiver.PaypalPayoutReceiverComponentConfig
import com.pxp.checkout.components.payoutsubmission.PayoutSubmissionComponent
import com.pxp.checkout.components.payoutsubmission.PayoutSubmissionComponentConfig
import com.pxp.checkout.models.*
import com.pxp.checkout.models.payout.PrePayoutSubmitResult
import com.pxp.checkout.types.ComponentType
import java.time.Instant
import java.util.UUID
fun initialisePayoutSdk(context: Context, session: SessionConfig): PxpCheckout {
return PxpCheckout.builder()
.withConfig(
PxpSdkConfig(
environment = Environment.TEST,
locale = "en-US",
session = session,
clientId = "your-client-id-from-unity-portal",
ownerId = "your-merchant-group-id",
ownerType = "MerchantGroup",
transactionData = TransactionData(
amount = 100.00,
currency = "USD",
entryType = EntryType.Ecom,
intent = TransactionIntentData(
paypal = PayPalIntentType.Payout
),
merchant = "your-merchant-id",
merchantTransactionId = UUID.randomUUID().toString(),
merchantTransactionDate = { Instant.now().toString() }
),
paypalConfig = PaypalConfig(
payout = PayoutConfig(
proceedPayoutWithSdk = true,
paypalWallet = PayPalPayOutWalletConfig(
email = "customer@example.com",
payerId = "PAYER_ID_XXX"
)
)
)
)
)
.withContext(context.applicationContext)
.build()
}
fun createPayoutComponents(pxpCheckout: PxpCheckout): Triple<
PayoutAmountComponent,
PaypalPayoutReceiverComponent,
PayoutSubmissionComponent
> {
val amountComponent = pxpCheckout.createComponent<PayoutAmountComponent>(
type = ComponentType.PAYOUT_AMOUNT,
config = PayoutAmountComponentConfig(
label = "Withdrawal Amount"
)
)
val receiverComponent = pxpCheckout.createComponent<PaypalPayoutReceiverComponent>(
type = ComponentType.PAYPAL_PAYOUT_RECEIVER,
config = PaypalPayoutReceiverComponentConfig(
label = "PayPal Account",
showMaskToggle = true,
applyMask = true
)
)
val submitComponent = pxpCheckout.createComponent<PayoutSubmissionComponent>(
type = ComponentType.PAYOUT_SUBMISSION,
config = PayoutSubmissionComponentConfig(
recipientWallet = "Paypal",
onPrePayoutSubmit = {
PrePayoutSubmitResult(isApproved = true)
},
onPostPayout = { result ->
// Handle successful payout
},
onError = { error ->
// PayOutError: error.errorCode and error.errorReason
showErrorDialog(error.errorReason ?: error.errorCode)
}
)
)
return Triple(amountComponent, receiverComponent, submitComponent)
}
@Composable
fun PayoutScreen(
amountComponent: PayoutAmountComponent,
receiverComponent: PaypalPayoutReceiverComponent,
submitComponent: PayoutSubmissionComponent
) {
Column(
modifier = Modifier
.fillMaxWidth()
.padding(16.dp),
verticalArrangement = Arrangement.spacedBy(16.dp)
) {
amountComponent.Content(Modifier.fillMaxWidth())
receiverComponent.Content(Modifier.fillMaxWidth())
submitComponent.Content(Modifier.fillMaxWidth())
}
}
// Fetch session from your backend
suspend fun fetchSessionFromBackend(): SessionConfig {
// Make an API call to your backend to get session data.
// Your backend should call the PXP Sessions API with intent.paypal set to "Payout".
// 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", // Required on SessionConfig; use "" if the API omits data
encryptionKey = "encryption-key-from-backend",
locale = "en-US",
allowedFundingTypes = AllowedFundingTypes(
wallets = WalletsConfig(
paypal = PayPalWalletConfig(
allowedFundingOptions = listOf("paypal"),
merchantId = "paypal-merchant-123"
)
)
)
)
}Providing paypalWallet supplies the stored PayPal email and payer ID for the withdrawal components. See How it works and Withdrawal flow.
Pass these values when you build PxpSdkConfig:
| Parameter | Description |
|---|---|
environmentEnvironment required | The environment type enum. Possible values:
|
sessionSessionConfig required | Details about the payout session. Map sessionId, hmacKey, encryptionKey, and optional allowedFundingTypes from the Sessions API response (see Step 4). The Android SessionConfig model also requires data and locale. If the Sessions API omits data, pass "".sessionExpiry is returned by the API but is not a field on the Android SessionConfig model. |
clientIdString required | Your client ID from the Unity Portal. Get this from Merchant setup > Merchant groups > Inbound calls in the Unity Portal. |
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 payout. |
transactionData.amountDouble required | The payout amount as a Double (e.g., 100.00). |
transactionData.currencyString (3 characters) required | The currency code associated with the payout, 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 payout. 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 payout. For PayPal payouts, use EntryType.Ecom. The payout request the SDK builds uses an e-commerce entry type. |
transactionData.intentTransactionIntentData | The transaction intents. For PayPal payouts, set paypal to PayPalIntentType.Payout. |
transactionData.intent.paypalPayPalIntentType | The intent for PayPal. For payouts, use PayPalIntentType.Payout.Other possible values:
|
paypalConfigPaypalConfig | The PayPal configuration for payout operations. Set payout with proceedPayoutWithSdk and, for returning customers, paypalWallet. See How it works. |
paypalConfig.payoutPayoutConfig | The payout-specific settings. |
paypalConfig.payout.proceedPayoutWithSdkBoolean | When true, the SDK executes the payout after onPrePayoutSubmit approves it. When false, the SDK calls onClick (if configured) and does not run onPrePayoutSubmit or execute the payout — your backend must call the payout API. Defaults to false. |
paypalConfig.payout.paypalWalletPayPalPayOutWalletConfig | The stored PayPal wallet details for the withdrawal flow (email and payerId). On Android, email and payer ID each have a maximum length of 127 characters. |
kountDisabledBoolean | Whether to disable the Kount fraud detection service. Defaults to false (fraud detection enabled). |
localeString | Optional locale for UI localisation on PxpSdkConfig (e.g., "en-US", "es-ES"). Defaults to "en-US" if omitted. Set this on PxpSdkConfig, not only on SessionConfig. SessionConfig.locale must still be supplied when you build SessionConfig manually, but component UI text follows PxpSdkConfig.locale. |
localisationLocalisationConfig? | Optional LocalisationConfig object of string overrides for component text. For example LocalisationConfig(paypalPayoutReceiverLabel = "PayPal account"). |
analyticsEvent(BaseAnalyticsEvent) -> Unit | Optional callback function to receive analytics events from the SDK. Use this to forward events to your analytics platform. |
merchantIdString | Optional merchant identifier override. Typically not needed as the SDK uses transactionData.merchant. |
onGetShopper() -> Shopper? | Optional callback function to provide shopper data dynamically. Returns a Shopper object with shopper information including ID, email, name, and contact details. |
Use this table when Gradle sync, minify, or Compose setup fails:
| Issue | Cause | Fix |
|---|---|---|
Could not find io.pxp:android-components-sdk:<version> | Version not on Maven Central yet | Confirm the version string; wait for Central sync or contact PXP support |
| Transitive dependency resolution fails (artifact hosted on JitPack) | Missing JitPack repository | Add maven { url = 'https://jitpack.io' } to your repositories block |
| Unresolved SDK symbols at compile time | SDK version mismatch or stale cache | Confirm the Maven Central version matches this guide; run Gradle sync or a clean build |
| Duplicate classes or version conflicts | Compose or OkHttp version clash | Align with SDK POM versions or use a current Compose BOM ({composeBomVersion}) |
minSdk error | App minSdk < 24 | Set minSdk = 24 or higher |
| R8 or missing class at runtime | App release minify misconfiguration, or SDK older than 1.1.2 | Use SDK 1.1.2 or newer so consumer rules include -keep class com.pxp.PxpCheckout$* { *; }. On 1.1.1 or earlier, upgrade or add that keep rule manually. Use the published release AAR; rules are bundled as proguard.txt. |
| App crashes after ProGuard obfuscation | ProGuard rules aren't properly configured | Use SDK 1.1.2+ so consumer rules merge automatically from the AAR, or add -keep class com.pxp.PxpCheckout$* { *; } for older versions. |
| "Class not found" errors for SDK classes | The SDK dependency isn't properly synced or included | Verify the Maven Central dependency is in your app module; sync Gradle; clean and rebuild |
| Compose compiler version mismatch | Kotlin version doesn't match Compose compiler requirements | Use Kotlin 2.x with the Kotlin Compose Compiler Gradle plugin (see Step 1) |
That's it for SDK installation. Next, follow the guide for PayPal payouts, and see Error handling for payout error codes and callbacks.