How it works

PayPal payouts enable you to easily send money to your users' PayPal accounts.

With the PayPal payout components, you can benefit from:

• Flexible payout execution: Choose between SDK-managed payouts for simplicity or backend-managed payouts for custom workflows.
• Secure credential management: PayPal account credentials are securely stored on your backend and provided to the SDK at initialization.
• Customizable approval flows: Implement custom merchant approval logic before payout execution.
• Native iOS integration: Built with SwiftUI for modern iOS app development with proper lifecycle management.
• Real-time status updates: Receive immediate confirmation when payouts complete successfully.
• Read-only display components: Show users their payout amount and destination email with optional masking for privacy.

The PayPal payout components enable various business scenarios where you need to send money to users:

• Gig economy and marketplaces: Pay freelancers, drivers, delivery personnel, or sellers for completed work or sales.
• Rewards and loyalty programmes: Distribute cashback, loyalty points converted to cash, or promotional rewards.
• Refunds: Return money to customers for returned items, cancelled services, or dispute resolutions.
• Affiliate commissions: Pay partners, influencers, or affiliates for referrals and sales.
• Contests and sweepstakes: Distribute prize money to winners of contests, tournaments, or raffles.
• Revenue sharing: Split payments among multiple parties in revenue-sharing arrangements.
• Expense reimbursements: Reimburse employees or contractors for business expenses.

PayPal payout credentials (email and payer ID) must be collected and stored by your backend system. The iOS SDK receives these credentials at initialization time and uses them to display payout information and execute transactions.

Your backend is responsible for:

• Collecting PayPal account information from users through your own UI or processes
• Securely storing the email address and payer ID
• Providing these credentials to the iOS app when initializing the SDK

The PayPal payout components support two execution modes, allowing you to choose the approach that fits your business requirements:

• SDK-managed payouts: A streamlined flow where the SDK handles payout execution after merchant approval. Best for simple implementations with minimal backend logic.
• Backend-managed payouts: A flexible flow where your backend controls payout execution. Use this when you need custom business logic, compliance checks, or complex workflows.

let paypalConfig = PayPalConfig(
    payout: PayPalPayoutConfig(
        paypalWallet: PayPalWallet(
            email: "user@example.com",     // From your backend
            payerId: "PAYERID123ABC",      // From your backend
            proceedPayoutWithSdk: true     // SDK manages payout
        )
    )
)

When you initiate a payout transaction, you must provide key information in the transactionData object:

• The amount and currency of the payout.
• The entry type (EntryType), which describes the origin of the transaction. For payouts, use .ecom for e-commerce transactions.
• The intent (PayPalIntentType), which must be .payout for payout transactions. This indicates that money flows from you to the user.
• A merchant transaction identifier of your choosing, which uniquely identifies this specific payout.
• The merchant transaction date.

let transactionData = TransactionData(
    amount: Decimal(100.00),
    currency: "USD",
    entryType: .ecom,
    intent: TransactionIntentData(
        card: nil,
        paypal: .payout  // Critical: Must use .payout intent
    ),
    merchantTransactionId: "payout-\(UUID().uuidString)",
    merchantTransactionDate: { Date() }
)

PayPal payouts support only one intent: PayPalIntentType.payout. It transfers funds from your PayPal Business account to the recipient's PayPal account.

PayPal payouts for iOS provides display and submission components for users with stored PayPal credentials:

Here's a complete example showing how to implement PayPal payouts with stored credentials:

// Configure with stored credentials from your backend
let paypalConfig = PayPalConfig(
    payout: PayPalPayoutConfig(
        paypalWallet: PayPalWallet(
            email: "user@example.com",      // From your backend
            payerId: "PAYERID123ABC",       // From your backend
            proceedPayoutWithSdk: true
        )
    )
)

let pxpCheckout = try PxpCheckout.initialize(config: checkoutConfig)

// Create amount display component
let amountConfig = PayoutAmountComponentConfig(
    label: "Payout Amount"
)
let amountComponent = try pxpCheckout.create(.payoutAmount, componentConfig: amountConfig)

// Create receiver display component
let receiverConfig = PayPalPayoutReceiverComponentConfig(
    label: "PayPal Account",
    applyMask: true,
    showMaskToggle: true
)
let receiverComponent = try pxpCheckout.create(.paypalPayoutReceiver, componentConfig: receiverConfig)

// Create submission component
let submissionConfig = PayoutSubmissionComponentConfig(
    submitText: "Withdraw to PayPal",
    
    onClick: {
        print("Withdraw button clicked")
    },
    
    onPrePayoutSubmit: {
        let approved = await showApprovalDialog()
        guard approved else { return nil }
        return PrePayoutSubmitResult(isApproved: true)
    },
    
    onPostPayout: { result in
        print("Payout completed: \(result.merchantTransactionId)")
    },
    
    onError: { error in
        print("Error: \(error.errorMessage)")
    }
)
let submissionComponent = try pxpCheckout.create(.payoutSubmission, componentConfig: submissionConfig)

// Render in SwiftUI
VStack(spacing: 16) {
    amountComponent.buildContent()
    receiverComponent.buildContent()
    submissionComponent.buildContent()
}

PayPal has the following limits on payout transactions:

• Standard payouts: Typically within minutes.
• International payouts: May take 1-3 business days.
• New recipients: First payout may take longer due to fraud checks.

PayPal charges fees for payouts. Check your PayPal Business account for current rates:

• Domestic payouts: ~2% (varies by country).
• International payouts: Higher fees apply.
• Volume discounts may be available.

• Backend storage only: PayPal email addresses and payer IDs must be securely stored on your backend.
• Use HTTPS: All backend API calls must use HTTPS with valid SSL certificates.
• Secure transmission: When providing credentials to the iOS app, use secure API calls over HTTPS.
• Validate credentials: Verify email and payer ID formats before storing and transmitting.

• Validate payer ID: Always validate the payer ID format (max 13 characters, alphanumeric).
• Verify amounts: Ensure payout amounts are positive, valid numbers before processing.
• Implement rate limiting: Protect against abuse by limiting payout frequency per user.
• Audit logging: Log all payout attempts, successes, and failures for compliance and debugging.

The SDK performs extensive validation and provides specific error codes to help you handle different failure scenarios. All validation exceptions extend BaseSdkException and can be caught in onError callbacks.

let config = PayoutSubmissionComponentConfig(
    submitText: "Withdraw to PayPal",
    
    onError: { error in
        // Handle specific error types
        switch error {
        case is PayoutAmountNotPositiveException:
            showError("Payout amount must be greater than zero")
        case is PayoutEmailMaxLengthException:
            showError("Email address is too long (max 127 characters)")
        case is PayoutPayerIdMaxLengthException:
            showError("Payer ID is too long (max 13 characters)")
        case is PaypalPayoutEmailInvalidException:
            showError("Please enter a valid email address")
        default:
            showError("An error occurred: \(error.localizedDescription)")
        }
    }
)

Ready to implement PayPal Payouts? Follow these guides in order:

1. PayPal onboarding: Configure your PayPal Developer account.
2. Withdrawal flow: Implement payout components with stored credentials.
3. Testing: Test your payout integration in sandbox mode.