How it works

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 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 collects and validates information, but your backend triggers the payout via API. This gives you maximum control for additional validation or business logic.

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, the SDK validates inputs and returns control to your backend, which 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:

SDK components

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

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 pxpCheckout.buildComponentView() to make it visible and interactive.
3. Dispose the component when the user leaves the screen. This is handled automatically by Compose.

Pre-requisites

Before integrating the payouts components, ensure you have:

• A merchant account with PXP (credentials/API key).
• Your PayPal merchant account onboarded with PXP.
• Verified identity/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:

import com.pxp.checkout.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.IntentType
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 = IntentType.Payout), // required for payouts
                merchantTransactionId = UUID.randomUUID().toString(),
                merchantTransactionDate = { System.currentTimeMillis() }
            ),
            paypalConfig = PaypalConfig(
                payout = PayoutConfig(
                    proceedPayoutWithSdk = true
                    // Optionally add paypalWallet for withdrawal flow
                )
            )
        )
    )
    .withContext(context)
    .build()

What's next?

Now that you understand how payouts work, you're ready to start integrating:

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