Skip to content

How it works

Learn about PXP's PayPal payout components for iOS.

Overview

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

PayPal payouts require a verified PayPal Business account. Recipients must have a PayPal account to receive funds, though PayPal will send an invitation if they don't have one.

Use cases

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.

How credentials are provided

PayPal payout credentials (email and payer ID) must be collected and stored by your backend system. The iOS SDK receives these credentials at initialisation 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 initialising the SDK.

Both the email and the payer ID are required to create the PayoutSubmissionComponent. If either is nil, the SDK throws PaypalPayoutReceiverRequiredException (SDK0803). If the payer ID is empty, it throws PayoutPayerIdRequiredException (SDK0809). The submission component reads the amount and currency from transactionData and the wallet from paypalConfig. It doesn't take values from the amount or receiver components.

The payer ID is a unique identifier for a PayPal account. You can get this through your backend integration with PayPal's APIs or by having users provide their PayPal account details through your own account management system.

Payout flows

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.

The SDK-managed flow works as follows.

  1. Your backend provides PayPal credentials (email and payer ID) to the iOS app.
  2. The user initiates a payout request in your app.
  3. SDK triggers onPrePayoutSubmit callback for merchant approval.
  4. Merchant shows approval dialog and returns PrePayoutSubmitResult(isApproved: true) to proceed, or nil to cancel.
  5. SDK executes payout transaction via Unity API.
  6. SDK triggers onPostPayout callback with transaction details.
  7. The funds are transferred to the user's PayPal account.

The following example configures the SDK to manage the payout.

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

With backend-managed payouts, only the onClick callback runs. The onPrePayoutSubmit and onPostPayout callbacks aren't triggered because the SDK doesn't execute the payout. Notify your backend from onClick. Your backend handles the entire payout execution flow.

Transaction data

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.

The following example sets each of these values for a payout.

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

PayPal payouts use the PayPalIntentType.payout intent. It transfers funds from your PayPal Business account to the recipient's PayPal account. For payout integrations, set paypal: .payout in the TransactionIntentData of your transactionData in CheckoutConfig. The other intents (.authorisation and .purchase) are for receiving payments, not sending payouts.

Available components

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

ComponentTypeDescription
PayoutAmountComponent.payoutAmountDisplays the payout amount (read-only).
PayPalPayoutReceiverComponent.paypalPayoutReceiverDisplays the recipient email with optional masking. Configure with PayPalPayoutReceiverComponentConfig: applyMask (default: true) to mask email as j***@****.com, showMaskToggle (default: true) to show or hide the toggle button, and receiverType (must be .email). The toggle is visible only when both applyMask and showMaskToggle are true.
PayoutSubmissionComponent.payoutSubmissionSubmit button to execute the payout.

For detailed configuration of payout components, see the Withdrawal flow guide.

Implementation example

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
        guard let error = error as? BaseSdkException else { return }
        print("Error: \(error.errorMessage)")
    }
)
let submissionComponent = try pxpCheckout.create(.payoutSubmission, componentConfig: submissionConfig)

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

Transaction limits and fees

Limits

PayPal has the following limits on payout transactions:

Limit typeValue
Minimum amount$1.00 USD (varies by currency).
Maximum single payout$60,000 USD (varies by account status).
Daily limitVaries based on account verification level.
Payer ID lengthMaximum 13 characters.
Receiver email lengthMaximum 127 characters.

Contact your PayPal account manager to increase limits for high-volume payout operations.

Processing time

Processing times depend on the type of payout and the recipient:

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

Fees

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.

Security considerations

Credential management

Follow these practices when you handle PayPal credentials:

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

Payout validation

Apply these checks before you process a payout:

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

Error codes

The SDK performs extensive validation and provides specific error codes to help you handle different failure scenarios. All validation exceptions extend BaseSdkException. They're thrown by pxpCheckout.create, so catch them with try-catch. They aren't delivered to the onError callback, which is for failures during payout execution.

Amount validation errors

The following table lists the errors thrown for an invalid payout amount.

ErrorDescription
PayoutAmountInvalidExceptionAmount is NaN (Not a Number) or infinite.
PayoutAmountNotPositiveExceptionAmount is zero or negative. Payouts must be positive values.

Currency validation errors

The following table lists the errors thrown for an invalid currency code.

ErrorDescription
PayoutCurrencyRequiredExceptionCurrency code is empty or missing.
PayoutCurrencyLengthInvalidExceptionCurrency code is not exactly 3 characters (ISO 4217 format).
PayoutCurrencyCodeInvalidExceptionCurrency code is not a valid ISO 4217 code.

Receiver validation errors

The following table lists the errors thrown for an invalid receiver.

ErrorDescription
PaypalPayoutReceiverRequiredExceptionReceiver email is empty or missing.
PaypalPayoutEmailInvalidExceptionEmail address format is invalid.
PayoutEmailMaxLengthExceptionEmail address exceeds 127 characters.
PaypalPayoutReceiverTypeEmailOnlyExceptionReceiver type is not .email (only email is currently supported).

Payer ID validation errors

The following table lists the errors thrown for an invalid payer ID.

ErrorDescription
PayoutPayerIdMaxLengthExceptionPayer ID exceeds 13 characters.
PayoutPayerIdInvalidExceptionPayer ID contains non-alphanumeric characters. Only letters and numbers are allowed.

Error handling example

The following example catches the validation errors that pxpCheckout.create throws and shows a message for each error type.

do {
    let amountComponent = try pxpCheckout.create(
        .payoutAmount,
        componentConfig: PayoutAmountComponentConfig(label: "Payout Amount")
    )
    let submissionComponent = try pxpCheckout.create(
        .payoutSubmission,
        componentConfig: PayoutSubmissionComponentConfig(submitText: "Withdraw to PayPal")
    )
} catch {
    // 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)")
    }
}

If a payout fails during execution, the onError callback receives a PayoutFailedException. Its errorCode and errorMessage contain the code and reason returned by the API.

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
AccessibilityThe app supports Dynamic Type for text scaling to accommodate users with visual impairments.optional
AccessibilityVoiceOver is fully supported with appropriate accessibility labels on all interactive elements.optional
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 in the app. 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 allows the user to provide their PayPal account details and proceed with the payout without deviations or 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. For example, bank details hidden when PayPal is selected.optional
PayPal account dataPayPal account information (email or phone) collected from users is transmitted securely to the backend and handled according to data protection regulations.required
AccountThe customer isn't required to create or log into a store or application account to receive a payout.optional
ConfirmationAfter the payout initiation, the user sees a confirmation screen indicating the payout status; PayPal details or logos are presented in parity with other payout methods.required
Credential managementAPI credentials are managed securely on the backend and never exposed to the iOS client.required
Receiver validationPayPal email is validated before submission where possible; PayPal error responses are surfaced to the user 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 iOS 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?

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

  1. Installation: Set up the iOS SDK in your project.
  2. PayPal onboarding: Configure your PayPal Developer account.
  3. Withdrawal flow: Implement payout components with stored credentials.
  4. Testing: Test your payout integration in sandbox mode.