Skip to content

How it works

Learn about PXP's PayPal payout components for Android.

Overview

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.

Payout initiation modes

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 onClick when 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:

AspectSDK-initiatedMerchant-initiated
proceedPayoutWithSdktruefalse
Payout triggerThe SDK calls the PXP backend automatically.Your backend calls the payout API.
Control levelSimplified flow.Full control over timing and validation.
Use casesStandard 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.

Supported transaction intents

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:

IntentDescription
PayPalIntentType.PayoutDisburse funds to a recipient's PayPal wallet. Use this for all payout transactions. Must be wrapped in TransactionIntentData(paypal = PayPalIntentType.Payout).

SDK components

The payouts SDK provides several components you can use based on your integration needs:

ComponentTypeDescriptionWhen to use
Payout amountComponentType.PAYOUT_AMOUNTDisplay-only payout amount.Show the payout amount to the customer before confirming.
PayPal receiverComponentType.PAYPAL_PAYOUT_RECEIVERDisplay-only PayPal email from config with optional masking.Returning customers when you have their PayPal email and payer ID.
Payout submissionComponentType.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:

  1. Create the component with configuration and callbacks using pxpCheckout.createComponent().
  2. Render the component using Jetpack Compose with component.Content() to make it visible and interactive.
  3. Dispose the component when the user leaves the screen. This is handled automatically by Compose.

Requirements

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()

Compliance

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.

Branding and appearance

DescriptionRequirement
LogosPayPal logos and acceptance marks are displayed in parity with other payout options anywhere the payout method is presented.required
LogosPayPal logos are taken from official sources and aren't modified.required
BrandingThe correct capitalisation and spelling of PayPal is always used in both text and images (instead of Paypal, Pay Pal, and similar variants).required
ButtonsPayPal payout buttons are presented with equal prominence and close proximity to other withdrawal methods.required
ButtonsPayPal payout buttons are placed above other payout options.required
ButtonsThe 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

Behaviour

DescriptionRequirement
FeesYou don't add any additional surcharge or fee for PayPal payout transactions beyond what PayPal charges.required
Customer journeySelecting the PayPal payout method takes the customer through the PayPal experience (where applicable) and back to your app without unnecessary intermediate steps.required
Payout methodsIf payout methods can be stored or set as a preference, PayPal can also be stored or set as the preferred payout method.required
Payout methodsFor 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 methodsWhen a payout method is selected, any fields specific to other payout methods are hidden.optional
AccountThe customer isn't required to create or log into a store or application account to receive a payout.optional
ConfirmationAfter 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 validationPayPal receiver details are validated before submission where possible; PayPal error responses are surfaced with guidance to correct details.required

Your regulatory responsibilities

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.

What's next?

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.