Learn about PXP's PayPal payout components for Android.
The PayPal payouts components enable you to send payouts directly to your customers' PayPal wallets from your Android application. Whether you're paying vendors, freelancers, partners, or disbursing refunds, rebates, and rewards — the payouts components provide a streamlined experience built on top of PayPal's payout rails.
With the payouts components, you can benefit from:
- Simplified disbursements: Send payouts directly to PayPal wallets without managing the underlying PayPal API complexity.
- SDK or merchant-initiated payouts: Choose whether the SDK handles the payout execution, or you trigger it from your own backend after your own validation checks.
- Customisable UI components: Use pre-built components with configurable styling, or build your own UI with custom Compose layouts.
- Native Android integration: Seamlessly integrated with Jetpack Compose for modern Android UI development.
- Operational safeguards: Benefit from built-in logging, retries, and reconciliation handled by the gateway.
When initiating a payout, you can choose who triggers the actual payout request:
- SDK-initiated payout: The SDK handles the payout execution after the user confirms. This is the fastest time-to-market option.
- Merchant-initiated payout: The SDK renders the UI and calls
onClickwhen the customer taps submit, then returns without executing the payout. Your backend triggers the payout via API. This gives you maximum control for additional validation or business logic.
Compare the two modes side by side:
| Aspect | SDK-initiated | Merchant-initiated |
|---|---|---|
proceedPayoutWithSdk | true | false |
| Payout trigger | The SDK calls the PXP backend automatically. | Your backend calls the payout API. |
| Control level | Simplified flow. | Full control over timing and validation. |
| Use cases | Standard payouts, quick integration. | Custom validation, compliance checks, multi-step approval. |
In SDK-initiated mode, the SDK calls the PXP backend after your onPrePayoutSubmit callback approves the payout, and then invokes onPostPayout with the result. In merchant-initiated mode (proceedPayoutWithSdk = false), the SDK calls onClick (if configured) and doesn't run onPrePayoutSubmit, execute the payout, or call onPostPayout. Your backend calls the payout API directly and can implement additional approval workflows.
When you initiate a payout transaction, you need to provide key information about the transaction method, amount, and currency.
The transaction method includes:
- The entry type, which describes the origin of the transaction. For payouts, this is always
EntryType.Ecom. - The intent, which describes the purpose of a transaction and indicates the intended money flow direction.
Payouts support the following intent:
| Intent | Description |
|---|---|
PayPalIntentType.Payout | Disburse funds to a recipient's PayPal wallet. Use this for all payout transactions. Must be wrapped in TransactionIntentData(paypal = PayPalIntentType.Payout). |
The payouts SDK provides several components you can use based on your integration needs:
| Component | Type | Description | When to use |
|---|---|---|---|
| Payout amount | ComponentType.PAYOUT_AMOUNT | Display-only payout amount. | Show the payout amount to the customer before confirming. |
| PayPal receiver | ComponentType.PAYPAL_PAYOUT_RECEIVER | Display-only PayPal email from config with optional masking. | Returning customers when you have their PayPal email and payer ID. |
| Payout submission | ComponentType.PAYOUT_SUBMISSION | "Withdraw with PayPal" button that executes the payout. | Returning customers when you already have stored wallet details. |
All components follow the same basic lifecycle:
- Create the component with configuration and callbacks using
pxpCheckout.createComponent(). - Render the component using Jetpack Compose with
component.Content()to make it visible and interactive. - Dispose the component when the user leaves the screen. This is handled automatically by Compose.
Before integrating the payouts components, ensure you have:
- A merchant account with PXP (credentials or API key).
- Your PayPal merchant account onboarded with PXP.
- Verified identity and account (if required by compliance).
- Sufficient funds in your gateway balance to cover payout amounts and fees.
- The recipients' PayPal identifiers (if using the withdrawal flow).
- An HTTPS endpoint with a valid SSL certificate (if you plan to receive webhooks).
At minimum, your SDK initialisation must provide the following configuration:
import com.pxp.PxpCheckout
import com.pxp.checkout.models.PxpSdkConfig
import com.pxp.checkout.models.Environment
import com.pxp.checkout.models.SessionConfig
import com.pxp.checkout.models.TransactionData
import com.pxp.checkout.models.TransactionIntentData
import com.pxp.checkout.models.EntryType
import com.pxp.checkout.models.PayPalIntentType
import com.pxp.checkout.models.PaypalConfig
import com.pxp.checkout.models.PayoutConfig
import java.util.UUID
val pxpCheckout = PxpCheckout.builder()
.withConfig(
PxpSdkConfig(
environment = Environment.TEST, // or Environment.LIVE
session = sessionData,
ownerId = "your-owner-id",
ownerType = "MerchantGroup",
clientId = "your-client-id",
transactionData = TransactionData(
amount = 100.0, // > 0
currency = "USD", // 3-letter ISO code
merchant = "your-merchant-id",
entryType = EntryType.Ecom,
intent = TransactionIntentData(paypal = PayPalIntentType.Payout), // required for payouts
merchantTransactionId = UUID.randomUUID().toString(),
merchantTransactionDate = { java.time.Instant.now().toString() }
),
paypalConfig = PaypalConfig(
payout = PayoutConfig(
proceedPayoutWithSdk = true
// Optionally add paypalWallet for withdrawal flow
)
)
)
)
.withContext(context)
.build()When you offer PayPal payouts, you must meet PayPal branding and behaviour requirements, and you remain responsible for financial, privacy, and security obligations in your markets.
| Description | Requirement | |
|---|---|---|
| Logos | PayPal logos and acceptance marks are displayed in parity with other payout options anywhere the payout method is presented. | required |
| Logos | PayPal logos are taken from official sources and aren't modified. | required |
| Branding | The correct capitalisation and spelling of PayPal is always used in both text and images (instead of Paypal, Pay Pal, and similar variants). | required |
| Buttons | PayPal payout buttons are presented with equal prominence and close proximity to other withdrawal methods. | required |
| Buttons | PayPal payout buttons are placed above other payout options. | required |
| Buttons | The PayPal button is sized in parity with other payout buttons or otherwise in keeping with other elements on the screen. See the PayPal style guide. | required |
| Description | Requirement | |
|---|---|---|
| Fees | You don't add any additional surcharge or fee for PayPal payout transactions beyond what PayPal charges. | required |
| Customer journey | Selecting the PayPal payout method takes the customer through the PayPal experience (where applicable) and back to your app without unnecessary intermediate steps. | required |
| Payout methods | If payout methods can be stored or set as a preference, PayPal can also be stored or set as the preferred payout method. | required |
| Payout methods | For the customer's first payout, no payout method should be preselected by default. For subsequent payouts, the customer's previously used payout method may be preselected. | optional |
| Payout methods | When a payout method is selected, any fields specific to other payout methods are hidden. | optional |
| Account | The customer isn't required to create or log into a store or application account to receive a payout. | optional |
| Confirmation | After payout initiation, the customer sees a confirmation step indicating the payout status; PayPal details or logos are presented in parity with other payout methods. | required |
| Receiver validation | PayPal receiver details are validated before submission where possible; PayPal error responses are surfaced with guidance to correct details. | required |
You own KYC, AML, transaction limits, data protection, consent, and record-keeping for your integration. Before you go live, confirm at least the following:
- Customer identity verification where your market requires it.
- AML monitoring and payout limits appropriate to your risk policy.
- Secure handling of personal and financial data, including encryption in transit (TLS 1.2 or higher) and at rest for any stored wallet identifiers.
- Inbound API credentials (token ID and token value) kept on your backend only — never embed them in the Android app.
- Clear customer consent for payout terms and privacy where required.
- Audit logging for payout initiation, approval, success, and failure.
- Country-specific regulatory requirements for the markets you serve.
- Legal and security review of your payout flows.
Store only the wallet identifiers you need for returning customers,such as the PayPal payer ID. Don't keep unnecessary sensitive personal data on the device.
Now that you understand how payouts work, explore these related topics:
- Installation: Set up the Android SDK in your project.
- Onboarding: Connect your PayPal Business account for payouts.
- Withdrawal flow: Implement payouts for returning customers.
- Configuration: Configure the appearance and behaviour of components.
- Events: Handle payout events and callbacks.