Skip to content

Withdrawal flow

Send payouts to customers using PayPal account credentials provided by your backend.

Overview

The withdrawal flow is designed for customers whose PayPal account credentials your backend provides. This provides a streamlined experience: the customer simply reviews the payout details and confirms.

This flow uses the receiver and submission components together, displaying the PayPal account information and providing a "Withdraw" button.

Payout flow

The withdrawal flow consists of five key steps for customer payouts.

Step 1: Display payout details

The customer sees their PayPal email displayed alongside the payout amount. The receiver component shows the wallet destination, optionally masked for privacy.

Step 2: Submission

The customer taps the "Withdraw with PayPal" button. The SDK validates the payout configuration and PayPal account details when you create the components, and pxpCheckout.create throws an error if validation fails. The onError callback is for failures during payout execution.

Step 3: Payout approval (SDK-managed mode)

The onPrePayoutSubmit callback is triggered, giving you the opportunity to show a confirmation dialog or perform additional validation before the payout executes.

Return a PrePayoutSubmitResult with isApproved: true to proceed with the payout, or return nil to cancel.

Step 4: Payout execution

For SDK-managed mode, the SDK automatically sends the payout request to the PXP gateway. For backend-managed mode, your backend triggers the payout via API.

Step 5: Payout result

The onPostPayout callback receives the transaction result. You can display a success message and navigate the customer to a confirmation screen.

Implementation

Before you start

To use the withdrawal flow for payouts:

  1. Ensure your PayPal merchant account is onboarded with PXP.
  2. Have sufficient funds in your gateway balance to cover payout amounts and fees.
  3. Have PayPal account credentials provided by your backend.

Step 1: Configure your SDK

Set up your SDK configuration with PayPal account credentials from your backend to trigger the withdrawal flow.

import PXPCheckoutSDK

// Get session data from your backend
let sessionData = try await fetchSessionData()

// Get customer wallet credentials from your backend
let customerWallet = try await getCustomerWalletFromBackend(userId: currentUserId)

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

// Configure PayPal with wallet credentials from backend (withdrawal flow)
let paypalConfig = PayPalConfig(
    payout: PayPalPayoutConfig(
        paypalWallet: PayPalWallet(
            email: customerWallet.email,       // PayPal email from backend
            payerId: customerWallet.payerId,   // Required: payer ID from backend
            proceedPayoutWithSdk: true
        )
    )
)

// Initialise the SDK
let checkoutConfig = CheckoutConfig(
    environment: .test,  // Use .live for production
    session: sessionData,
    transactionData: transactionData,
    merchantShopperId: "customer-123",
    ownerId: "your-owner-id",
    paypalConfig: paypalConfig
)

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

The withdrawal flow requires PayPal account credentials provided by your backend in PayPalWallet:

  • email is required. It's displayed in the receiver component and validated when you create the submission component.
  • payerId is required and is used for payout execution.

If either value is nil, pxpCheckout.create(.payoutSubmission, ...) throws PaypalPayoutReceiverRequiredException (SDK0803). If payerId is an empty string, it throws PayoutPayerIdRequiredException (SDK0809).

// Configure with credentials from your backend
PayPalWallet(
    email: "user@example.com",  // Required
    payerId: "PAYERID123",       // Required
    proceedPayoutWithSdk: true
)

Step 2: Create the components

Use the amount, receiver, and submission components to build the withdrawal experience.

When the user taps "Withdraw", the submission component reads its data from your SDK configuration. It doesn't pull values from the amount or receiver components:

  • The amount and currency come from transactionData.
  • The wallet (email and payer ID) comes from paypalConfig.

The amount and receiver components only display these values. You don't need to wire the components together.

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

// Create the PayPal receiver display component
let receiverComponent = try pxpCheckout.create(
    .paypalPayoutReceiver,
    componentConfig: PayPalPayoutReceiverComponentConfig(
        label: "PayPal Account",
        applyMask: true,        // Start with email masked
        showMaskToggle: true    // Display a toggle (eye icon) to show or hide the email
    )
)

// Create the payout submission component
let submissionComponent = try pxpCheckout.create(
    .payoutSubmission,
    componentConfig: PayoutSubmissionComponentConfig(
        submitText: "Withdraw with PayPal",
        
        // OPTIONAL: Called when the button is clicked (before payout execution)
        onClick: {
            print("Withdrawal button clicked")
            // Track analytics, show loading state, etc.
        },
        
        // Required for the SDK to execute the payout (SDK-managed mode only).
        // Return nil or isApproved: false to cancel.
        onPrePayoutSubmit: {
            let confirmed = await showConfirmationDialog()
            return confirmed ? PrePayoutSubmitResult(isApproved: true) : nil
        },
        
        // OPTIONAL: Called when payout completes (SDK-managed mode only)
        onPostPayout: { result in
            print("Payout successful:", result.merchantTransactionId)
            showSuccessMessage("Your withdrawal has been processed!")
            navigateToSuccessScreen(transactionId: result.merchantTransactionId)
        },
        
        // OPTIONAL: Called when the payout fails during execution
        onError: { error in
            guard let error = error as? BaseSdkException else { return }
            print("Error occurred:", error.errorMessage)
            showErrorMessage("Something went wrong. Please try again.")
        }
    )
)

Step 3: Render the components

Render the components in your SwiftUI view.

struct WithdrawalFlowView: View {
    @State private var amountComponent: BaseComponent?
    @State private var receiverComponent: BaseComponent?
    @State private var submissionComponent: BaseComponent?
    
    var body: some View {
        VStack(spacing: 20) {
            Text("Withdraw Funds")
                .font(.title)
            
            // Amount display
            if let amountComponent = amountComponent {
                amountComponent.buildContent()
                    .frame(height: 60)
            }
            
            // Receiver display
            if let receiverComponent = receiverComponent {
                receiverComponent.buildContent()
                    .frame(height: 60)
            }
            
            Spacer()
            
            // Submit button
            if let submissionComponent = submissionComponent {
                submissionComponent.buildContent()
                    .frame(height: 50)
            }
        }
        .padding()
        .onAppear {
            initialiseComponents()
        }
    }
    
    private func initialiseComponents() {
        Task {
            do {
                let components = try await createPayoutComponents()
                await MainActor.run {
                    self.amountComponent = components.amount
                    self.receiverComponent = components.receiver
                    self.submissionComponent = components.submission
                }
            } catch {
                print("Failed to initialise: \(error)")
            }
        }
    }
}

Step 4: Handle payout modes

The proceedPayoutWithSdk parameter controls whether the SDK or your backend executes the payout. The default value is false (backend-managed).

When proceedPayoutWithSdk: true, the SDK handles the complete flow:

  1. The customer taps "Withdraw with PayPal".
  2. onPrePayoutSubmit is called for approval. You must provide this callback, and it must return PrePayoutSubmitResult(isApproved: true) for the payout to execute.
  3. The SDK executes the payout automatically.
  4. onPostPayout is called with the result.

The following example configures the SDK to manage payout execution.

let paypalConfig = PayPalConfig(
    payout: PayPalPayoutConfig(
        paypalWallet: PayPalWallet(
            email: customerWallet.email,
            payerId: customerWallet.payerId,
            proceedPayoutWithSdk: true  // SDK handles payout execution
        )
    )
)

With proceedPayoutWithSdk: true, both onPrePayoutSubmit and onPostPayout callbacks are triggered. The SDK manages the payout execution after approval.

Step 5: Handle errors

Handle errors in two places. Validation errors are thrown when you create the components. Failures during payout execution are delivered to onError.

The following example catches validation errors thrown by pxpCheckout.create:

do {
    let amountComponent = try pxpCheckout.create(
        .payoutAmount,
        componentConfig: PayoutAmountComponentConfig(label: "Withdrawal Amount")
    )
    
    let submissionComponent = try pxpCheckout.create(
        .payoutSubmission,
        componentConfig: PayoutSubmissionComponentConfig(
            submitText: "Withdraw with PayPal",
            onPrePayoutSubmit: {
                let confirmed = await showConfirmationDialog()
                return confirmed ? PrePayoutSubmitResult(isApproved: true) : nil
            }
        )
    )
} catch let error as BaseSdkException {
    let userMessage: String
    
    switch error.errorCode {
    case "SDK0803":
        userMessage = "PayPal receiver information is missing."
    case "SDK0808":
        userMessage = "Invalid PayPal email format."
    case "SDK0809":
        userMessage = "PayPal account information is missing."
    case "SDK0810", "SDK0811":
        userMessage = "Invalid payout amount. Please contact support."
    case "SDK0817":
        userMessage = "PayPal account identifier is too long."
    case "SDK0818":
        userMessage = "Invalid PayPal account."
    default:
        userMessage = "An error occurred. Please try again or contact support."
    }
    
    showErrorAlert(userMessage)
}

The following example handles a payout that fails during execution. The error is a PayoutFailedException, and its errorCode and errorMessage contain the code and reason returned by the API:

let submissionConfig = PayoutSubmissionComponentConfig(
    submitText: "Withdraw with PayPal",
    onPrePayoutSubmit: {
        let confirmed = await showConfirmationDialog()
        return confirmed ? PrePayoutSubmitResult(isApproved: true) : nil
    },
    onError: { error in
        guard let error = error as? BaseSdkException else { return }
        
        if error is PayoutFailedException {
            print("Payout failed:", error.errorCode, error.errorMessage)
            showErrorAlert("Payout transaction failed. Please try again.")
        } else {
            showErrorAlert("An error occurred. Please try again or contact support.")
        }
    }
)

For a complete list of error codes, including SDK0810 to SDK0815 (amount and currency validation), see Data validation.

Example

The following example shows a complete withdrawal flow implementation.

import SwiftUI
import PXPCheckoutSDK

struct PayoutWithdrawalFlowView: View {
    @State private var pxpCheckout: PxpCheckout?
    @State private var amountComponent: BaseComponent?
    @State private var receiverComponent: BaseComponent?
    @State private var submissionComponent: BaseComponent?
    @State private var isLoading = true
    @State private var errorMessage: String?
    @State private var showApprovalAlert = false
    @State private var pendingApprovalContinuation: CheckedContinuation<PrePayoutSubmitResult?, Never>?
    
    let currentUserId: String = "user123"
    @State private var payoutAmount: Double = 0
    @State private var customerEmail: String = ""
    
    var body: some View {
        VStack(spacing: 20) {
            Text("Withdraw Funds")
                .font(.title)
                .fontWeight(.bold)
            
            if isLoading {
                ProgressView("Initialising...")
            } else if let error = errorMessage {
                Text(error)
                    .foregroundColor(.red)
                    .multilineTextAlignment(.center)
            } else {
                // Amount component
                if let amountComponent = amountComponent {
                    amountComponent.buildContent()
                        .frame(height: 60)
                }
                
                // Receiver component
                if let receiverComponent = receiverComponent {
                    receiverComponent.buildContent()
                        .frame(height: 60)
                }
                
                Spacer()
                
                // Submission button
                if let submissionComponent = submissionComponent {
                    submissionComponent.buildContent()
                        .frame(height: 50)
                }
            }
        }
        .padding()
        .alert("Confirm Payout", isPresented: $showApprovalAlert) {
            Button("Cancel", role: .cancel) {
                pendingApprovalContinuation?.resume(returning: nil)
                pendingApprovalContinuation = nil
            }
            Button("Confirm") {
                pendingApprovalContinuation?.resume(returning: 
                    PrePayoutSubmitResult(isApproved: true)
                )
                pendingApprovalContinuation = nil
            }
        } message: {
            Text("Send $\(String(format: "%.2f", payoutAmount)) to \(customerEmail)?")
        }
        .onAppear {
            initialisePayoutFlow()
        }
    }
    
    private func initialisePayoutFlow() {
        Task {
            do {
                isLoading = true
                
                // Get session data from backend
                let sessionResponse = try await getSessionDataFromBackend()
                
                payoutAmount = sessionResponse.payoutAmount
                customerEmail = sessionResponse.customerWallet.email
                
                // Configure transaction data
                let transactionData = TransactionData(
                    amount: Decimal(sessionResponse.payoutAmount),
                    currency: sessionResponse.currency,
                    entryType: .ecom,
                    intent: TransactionIntentData(
                        card: nil,
                        paypal: .payout
                    ),
                    merchantTransactionId: "payout-\(UUID().uuidString)",
                    merchantTransactionDate: { Date() }
                )
                
                // Configure PayPal with wallet credentials from backend
                let paypalConfig = PayPalConfig(
                    payout: PayPalPayoutConfig(
                        paypalWallet: PayPalWallet(
                            email: sessionResponse.customerWallet.email,
                            payerId: sessionResponse.customerWallet.payerId,
                            proceedPayoutWithSdk: true
                        )
                    )
                )
                
                // Initialise SDK
                let checkoutConfig = CheckoutConfig(
                    environment: .test,
                    session: sessionResponse.session,
                    transactionData: transactionData,
                    merchantShopperId: currentUserId,
                    ownerId: "Unity",
                    paypalConfig: paypalConfig
                )
                
                let pxpCheckout = try PxpCheckout.initialize(config: checkoutConfig)
                
                // Create components
                let amountComponent = try pxpCheckout.create(
                    .payoutAmount,
                    componentConfig: PayoutAmountComponentConfig(
                        label: "Withdrawal Amount"
                    )
                )
                
                let receiverComponent = try pxpCheckout.create(
                    .paypalPayoutReceiver,
                    componentConfig: PayPalPayoutReceiverComponentConfig(
                        label: "PayPal Account",
                        applyMask: true,
                        showMaskToggle: true
                    )
                )
                
                let submissionComponent = try pxpCheckout.create(
                    .payoutSubmission,
                    componentConfig: PayoutSubmissionComponentConfig(
                        submitText: "Withdraw with PayPal",
                        
                        onPrePayoutSubmit: { [self] in
                            return await showPayoutApproval()
                        },
                        
                        onPostPayout: { result in
                            handlePayoutSuccess(result)
                        },
                        
                        onError: { error in
                            guard let error = error as? BaseSdkException else { return }
                            handleError(error)
                        }
                    )
                )
                
                await MainActor.run {
                    self.pxpCheckout = pxpCheckout
                    self.amountComponent = amountComponent
                    self.receiverComponent = receiverComponent
                    self.submissionComponent = submissionComponent
                    self.isLoading = false
                }
                
            } catch {
                await MainActor.run {
                    self.errorMessage = "Failed to initialise: \(error.localizedDescription)"
                    self.isLoading = false
                }
            }
        }
    }
    
    private func showPayoutApproval() async -> PrePayoutSubmitResult? {
        return await withCheckedContinuation { continuation in
            Task { @MainActor in
                self.pendingApprovalContinuation = continuation
                self.showApprovalAlert = true
            }
        }
    }
    
    private func handlePayoutSuccess(_ result: MerchantSubmitResult) {
        print("🎉 Payout successful!")
        print("Merchant TX ID: \(result.merchantTransactionId)")
        print("System TX ID: \(result.systemTransactionId)")
        
        // Show success message and navigate
        // showSuccessMessage("Withdrawal completed successfully!")
        // navigateToSuccessScreen()
    }
    
    private func handleError(_ error: BaseSdkException) {
        print("❌ Error: \(error.errorCode) - \(error.errorMessage)")
        errorMessage = "Payout failed: \(error.errorMessage)"
    }
    
    // Backend API call
    
    struct SessionResponse {
        let session: SessionData
        let payoutAmount: Double
        let currency: String
        let customerWallet: (email: String, payerId: String)
    }
    
    private func getSessionDataFromBackend() async throws -> SessionResponse {
        // Call your backend endpoint: POST /api/sessions/payout
        // Returns session data and customer wallet details
        fatalError("Implement your backend call")
    }
}

Callback data

This section describes the data received by the different callbacks as part of the withdrawal flow.

onClick

The onClick callback is triggered when the user taps the withdrawal button, before the payout executes. It's the only callback that runs when proceedPayoutWithSdk is false.

onClick: {
    print("Withdrawal button clicked")
    // Track analytics, show loading state, etc.
}

This callback receives no parameters and is useful for analytics tracking and UI state management.

onPrePayoutSubmit

The onPrePayoutSubmit callback is called before payout execution. Return an object indicating whether to proceed.

This callback is only triggered when proceedPayoutWithSdk: true. If set to false, this callback won't be called and your backend must handle payout execution independently.

The following example approves the payout only when the customer confirms.

onPrePayoutSubmit: {
    let approved = await showConfirmationDialog()
    return approved ? PrePayoutSubmitResult(isApproved: true) : nil
}

The following table describes the value that the callback returns.

Return propertyDescription
isApproved
Bool
required
Whether to proceed with the payout. Return nil to cancel.

onPostPayout

The onPostPayout callback receives the payout result when the transaction completes successfully.

The following example prints the system transaction ID from the result.

onPostPayout: { result in
    print("Transaction ID:", result.systemTransactionId)
}

The following table describes the data that the callback receives.

ParameterDescription
result
MerchantSubmitResult
An object containing transaction identifiers.
result.merchantTransactionId
String
Your unique identifier for the transaction.
result.systemTransactionId
String
The system's unique identifier for the transaction.

PayoutSubmissionComponentConfig also has an onCancel property, but the SDK doesn't currently invoke it. To cancel a payout, return nil or isApproved: false from onPrePayoutSubmit.

onError

The onError callback receives error information when the payout fails during execution. Validation errors are thrown by pxpCheckout.create and aren't delivered here.

The following example casts the error and prints its code and message.

onError: { error in
    guard let error = error as? BaseSdkException else { return }
    print("Error:", error.errorCode, error.errorMessage)
}

The following table describes the data that the callback receives.

ParameterDescription
error
BaseSdkException
The error object containing details about what went wrong. Cast the Error passed to the initialiser closure to BaseSdkException.
error.errorCode
String
The error code identifier. For a failed payout, this is the code returned by the API.
error.errorMessage
String
A human-readable error message describing what went wrong.
error.localizedDescription
String
The localised error description (same as errorMessage).

What's next?

Once you've implemented the withdrawal flow, explore these additional resources: