Skip to content

Installation

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

Before you start

Make sure you meet the system requirements:

RequirementMinimum or notes
minSdk24
compileSdk37 or higher
Kotlin2.x
Jetpack ComposeRequired (SDK UI is Compose-based)
Java desugaringRecommended for Java 8+ APIs
Android StudioLatest stable version (Hedgehog or later recommended)
Java Development Kit (JDK)17 (matches the SDK sourceCompatibility and jvmTarget)
Custom Tabs browserChrome 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.

Step 1: Install the Android SDK library

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.

Configure repositories

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
}

Apply the Kotlin Compose plugin

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'
}

Add the SDK dependency

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.

Check the latest published version

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

Use the <release> value (or the version shown on Sonatype) in your implementation line.

Verify dependency resolution

Confirm the SDK resolves on your compile classpath:

./gradlew :app:dependencies --configuration debugCompileClasspath | grep io.pxp

Expected output includes io.pxp:android-components-sdk:<version>.

Step 2: Add the required permissions

The SDK automatically merges the required permissions from its manifest, including:

  • INTERNET: required for API communication
  • ACCESS_NETWORK_STATE: required for network state checking
  • SYSTEM_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.

Step 3: Get your API credentials

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

To get your credentials:

  1. In the Unity Portal, go to Merchant setup > Merchant groups.
  2. Select a merchant group.
  3. Click the Inbound calls tab.
  4. Copy the Client ID in the top-right corner.
  5. Click New token.
  6. Choose a number of days before token expiry. For example, 30.
  7. Click Save to confirm. Your token is now created.
  8. 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": {
           "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:

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.

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
}'

Body parameters

Use these fields in the Sessions API request body. Required fields are merchant, site, merchantTransactionId, amounts, and transactionMethod.

ParameterDescription
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 for this transaction.
sessionTimeout
integer (≥ 1)
The duration of the session, in minutes.
transactionMethod
object
required
Details about the transaction method.
transactionMethod.intent
object
required
Details about the intent for different payment methods.
transactionMethod.intent.paypal
string
The intent for PayPal. For PayPal payouts, set this to Payout. Possible values: Authorisation, Purchase, Payout.
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 currencies.
amounts.transactionValue
number (≥ 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).
allowTransaction
boolean 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"
      }
    }
  }
}

Response parameters

Map these response fields into your SDK session configuration. The Sessions API response always includes sessionId, hmacKey, encryptionKey, and sessionExpiry.

ParameterDescription
sessionId
string (UUID)
The unique identifier for the created session. Required for SDK initialisation.
hmacKey
string
The HMAC key generated for securing session communications. Required for SDK initialisation.
encryptionKey
string
A key used for encrypting sensitive session data during communication. Required for SDK initialisation.
sessionExpiry
string (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.
data
string 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 ("").
allowedFundingTypes
object
Details about the funding types allowed for this session.
allowedFundingTypes.wallets
object
Details about the wallets allowed for this session. Map this to SessionConfig.allowedFundingTypes.wallets.
allowedFundingTypes.wallets.paypal
object
The PayPal configuration settings. Maps to WalletsConfig.paypal.
allowedFundingTypes.wallets.paypal.allowedFundingOptions
array of strings
The list of allowed funding options for PayPal.
allowedFundingTypes.wallets.paypal.merchantId
string or null
The PayPal merchant identifier.

Step 5: Initialise the SDK

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.

Configure ProGuard or R8

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'
        }
    }
}

Initialise the SDK in your application

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.

Configuration parameters

Pass these values when you build PxpSdkConfig:

ParameterDescription
environment
Environment
required
The environment type enum.

Possible values:
  • Environment.TEST
  • Environment.LIVE
session
SessionConfig
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.
clientId
String
required
Your client ID from the Unity Portal. Get this from Merchant setup > Merchant groups > Inbound calls in the Unity Portal.
ownerId
string
required
The identifier of the owner related to the ownerType. Get this from the Unity Portal.
ownerType
string
required
The type of owner. Always set this to "MerchantGroup".
transactionData
TransactionData
required
Details about the payout.
transactionData.amount
Double
required
The payout amount as a Double (e.g., 100.00).
transactionData.currency
String (3 characters)
required
The currency code associated with the payout, in ISO 4217 format (e.g., "USD", "GBP", "EUR").
transactionData.merchant
String
required
Your unique merchant identifier, as assigned by PXP. Get this from the Unity Portal.
transactionData.merchantTransactionId
String
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.entryType
EntryType
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.intent
TransactionIntentData
The transaction intents. For PayPal payouts, set paypal to PayPalIntentType.Payout.
transactionData.intent.paypal
PayPalIntentType
The intent for PayPal.

For payouts, use PayPalIntentType.Payout.

Other possible values:
  • PayPalIntentType.Authorisation
  • PayPalIntentType.Purchase
paypalConfig
PaypalConfig
The PayPal configuration for payout operations. Set payout with proceedPayoutWithSdk and, for returning customers, paypalWallet. See How it works.
paypalConfig.payout
PayoutConfig
The payout-specific settings.
paypalConfig.payout.proceedPayoutWithSdk
Boolean
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.paypalWallet
PayPalPayOutWalletConfig
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.
kountDisabled
Boolean
Whether to disable the Kount fraud detection service. Defaults to false (fraud detection enabled).
locale
String
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.
localisation
LocalisationConfig?
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.
merchantId
String
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.

Troubleshooting installation

Use this table when Gradle sync, minify, or Compose setup fails:

IssueCauseFix
Could not find io.pxp:android-components-sdk:<version>Version not on Maven Central yetConfirm the version string; wait for Central sync or contact PXP support
Transitive dependency resolution fails (artifact hosted on JitPack)Missing JitPack repositoryAdd maven { url = 'https://jitpack.io' } to your repositories block
Unresolved SDK symbols at compile timeSDK version mismatch or stale cacheConfirm the Maven Central version matches this guide; run Gradle sync or a clean build
Duplicate classes or version conflictsCompose or OkHttp version clashAlign with SDK POM versions or use a current Compose BOM ({composeBomVersion})
minSdk errorApp minSdk < 24Set minSdk = 24 or higher
R8 or missing class at runtimeApp release minify misconfiguration, or SDK older than 1.1.2Use 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 obfuscationProGuard rules aren't properly configuredUse 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 classesThe SDK dependency isn't properly synced or includedVerify the Maven Central dependency is in your app module; sync Gradle; clean and rebuild
Compose compiler version mismatchKotlin version doesn't match Compose compiler requirementsUse 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.