Skip to content

Receiver component

Learn how to configure the PayPal payout receiver component for iOS.

Overview

The PayPalPayoutReceiverComponent displays the recipient's PayPal email address with optional masking for privacy. This component shows users which PayPal account will receive their payout. Use this component alongside the PayoutAmountComponent and PayoutSubmissionComponent for returning users who have already linked their PayPal accounts.

This component is for users with stored PayPal credentials provided by your backend. Both email and payerId are required in PayPalWallet to create the PayoutSubmissionComponent. The submission component reads the wallet from paypalConfig, not from this component.

Requirements

Before using the payout receiver component, ensure you have:

  1. Initialised the SDK with stored PayPal credentials:
let paypalConfig = PayPalConfig(
    payout: PayPalPayoutConfig(
        paypalWallet: PayPalWallet(
            email: "user@example.com",        // This email will be displayed
            payerId: "PAYERID123ABC",         // Credentials from backend
            proceedPayoutWithSdk: true
        )
    )
)

let checkoutConfig = CheckoutConfig(
    environment: .test,
    session: sessionData,
    transactionData: transactionData,
    merchantShopperId: "user-123",
    ownerId: "merchant-456",
    paypalConfig: paypalConfig
)

let pxpCheckout = try PxpCheckout.initialize(config: checkoutConfig)
  1. Retrieved the user's PayPal credentials from your backend:
// Fetch stored PayPal credentials from your backend
let credentials = try await fetchPayPalCredentials(userId: currentUser.id)
// Use credentials.paypalAccountId and credentials.paypalEmail in SDK initialisation

Basic usage

Minimal configuration

At minimum, the payout receiver component requires no mandatory configuration:

let config = PayPalPayoutReceiverComponentConfig()
let component = try pxpCheckout.create(.paypalPayoutReceiver, componentConfig: config)

With masking

Enable email masking for privacy (e.g., j***@****.com):

let config = PayPalPayoutReceiverComponentConfig(
    label: "PayPal Account",
    accessibilityLabel: "PayPal account email",
    applyMask: true,
    showMaskToggle: true
)
let component = try pxpCheckout.create(.paypalPayoutReceiver, componentConfig: config)

The following table describes the properties used in this example.

PropertyDescription
label
String?
The label text displayed above the email field.
accessibilityLabel
String?
The accessibility label for screen readers.
applyMask
Bool
Whether to mask the email address. Defaults to true.
showMaskToggle
Bool
Whether to show a toggle button to reveal or hide the email address. Defaults to true. The toggle is visible only when both applyMask and showMaskToggle are true.

Advanced configuration

For more complex implementations, configure styling, validation messages, and receiver type:

let config = PayPalPayoutReceiverComponentConfig(
    label: "Receiving PayPal Account",
    placeholder: "PayPal email",
    guideText: "Funds will be sent to this account",
    accessibilityLabel: "PayPal account receiving the payout",
    applyMask: true,
    showMaskToggle: true,
    receiverType: .email,
    
    // Custom container styling
    styles: FieldStyle(
        backgroundColor: Color(.systemGray6),
        borderColor: Color(.systemGray4),
        borderWidth: 1,
        cornerRadius: 8,
        padding: EdgeInsets(top: 12, leading: 16, bottom: 12, trailing: 16)
    ),
    
    // Custom input text styling
    inputStyles: FieldInputStateStyles(
        base: FieldInputStyle(
            color: Color(.label),
            fontWeight: .regular,
            fontSize: 16
        )
    ),
    
    // Custom label styling
    labelStyles: FieldLabelStateStyles(
        base: FieldLabelStyle(
            color: Color(.secondaryLabel),
            font: .system(size: 14, weight: .medium)
        )
    ),
    
    // Custom validation messages
    validations: PayPalPayoutReceiverValidationResource(
        PPE01: "PayPal email is required",
        PPE02: "Please enter a valid email address"
    )
)

The following table describes the properties used in this example.

PropertyDescription
label
String?
The label text displayed above the email field.
placeholder
String?
The placeholder text. The configuration accepts it, but the receiver display component doesn't render it.
guideText
String?
The helper text displayed below the email field.
accessibilityLabel
String?
The accessibility label for screen readers.
applyMask
Bool
Whether to mask the email address. Defaults to true.
showMaskToggle
Bool
Whether to show a toggle to reveal or hide the email address. Defaults to true. The toggle is visible only when both applyMask and showMaskToggle are true.
receiverType
PayoutRecipientType
The recipient type. Defaults to .email.
styles
FieldStyle?
The custom styling for the container: background, border, padding, margin, opacity, shadow, and textAlignment.
inputStyles
FieldInputStateStyles?
The input text styling (colour, font size, and font weight). The configuration accepts these values, but the receiver display component doesn't currently apply them to the displayed email.
labelStyles
FieldLabelStateStyles?
The custom styling for the label text.
validations
PayPalPayoutReceiverValidationResource?
The custom validation error messages.

Email masking

The receiver component supports email masking for user privacy. When masking is enabled, emails are displayed in a protected format.

For john.doe@example.com:

  • If applyMask: false, then john.doe@example.com is displayed.
  • If applyMask: true, then j***@****.com is displayed.

Email masking displays:

  • The first character of the local part (before @)
  • Three asterisks replacing the remaining local part characters
  • The @ symbol
  • Four asterisks replacing the domain name
  • .com (or the actual TLD)

Mask toggle

When both applyMask and showMaskToggle are true, users can tap to reveal or hide their email. If applyMask is false, the email is always visible and no toggle is shown.

The following example starts with the email masked and lets users reveal or hide it.

let config = PayPalPayoutReceiverComponentConfig(
    applyMask: true,        // Start with masked email
    showMaskToggle: true    // Allow user to reveal/hide
)

Privacy-focused configuration

For maximum privacy, hide the toggle so users can't reveal the full email:

let config = PayPalPayoutReceiverComponentConfig(
    label: "PayPal Account",
    applyMask: true,
    showMaskToggle: false
)

Full display configuration

For contexts where privacy is less of a concern:

let config = PayPalPayoutReceiverComponentConfig(
    label: "PayPal Account",
    applyMask: false,       
    showMaskToggle: false   
)

Styling

Default styling

The payout receiver component renders with default styling suitable for most applications:

// Default container style
FieldStyle(
    color: Color(red: 0.035, green: 0.035, blue: 0.047),
    font: .system(size: 16, weight: .regular),
    backgroundColor: Color(red: 0.929, green: 0.933, blue: 0.937),
    borderColor: Color(red: 0.725, green: 0.741, blue: 0.753),
    borderWidth: 1,
    cornerRadius: 4,
    padding: EdgeInsets(top: 12, leading: 16, bottom: 12, trailing: 16)
)

// Default label style
FieldLabelStyle(
    color: Color(red: 0.035, green: 0.035, blue: 0.047),  // rgba(9, 9, 12, 1)
    font: .system(size: 14, weight: .bold)
)

Custom styling

Customise the appearance to match your app's design:

let config = PayPalPayoutReceiverComponentConfig(
    label: "PayPal Account",
    applyMask: true,
    showMaskToggle: true,
    
    // Container styling
    styles: FieldStyle(
        backgroundColor: Color(red: 0.0, green: 0.44, blue: 0.73).opacity(0.1),  // Light PayPal blue
        borderColor: Color(red: 0.0, green: 0.44, blue: 0.73),
        borderWidth: 1,
        cornerRadius: 8,
        padding: EdgeInsets(top: 14, leading: 16, bottom: 14, trailing: 16)
    ),
    
    // Email text styling
    inputStyles: FieldInputStateStyles(
        base: FieldInputStyle(
            color: Color(red: 0.0, green: 0.44, blue: 0.73),  // PayPal blue
            fontWeight: .medium,
            fontSize: 16
        )
    ),
    
    // Label styling
    labelStyles: FieldLabelStateStyles(
        base: FieldLabelStyle(
            color: Color(.secondaryLabel),
            font: .system(size: 12, weight: .semibold)
        )
    )
)

PayPal branded styling

Apply PayPal's brand colours:

struct PayPalBrand {
    static let blue = Color(red: 0.0, green: 0.44, blue: 0.73)
    static let darkBlue = Color(red: 0.0, green: 0.18, blue: 0.38)
    static let lightBlue = Color(red: 0.0, green: 0.44, blue: 0.73).opacity(0.1)
}

let config = PayPalPayoutReceiverComponentConfig(
    label: "PayPal Account",
    applyMask: true,
    showMaskToggle: true,
    
    styles: FieldStyle(
        backgroundColor: PayPalBrand.lightBlue,
        borderColor: PayPalBrand.blue,
        borderWidth: 2,
        cornerRadius: 8,
        padding: EdgeInsets(top: 16, leading: 20, bottom: 16, trailing: 20)
    ),
    
    inputStyles: FieldInputStateStyles(
        base: FieldInputStyle(
            color: PayPalBrand.darkBlue,
            fontWeight: .semibold,
            fontSize: 16
        )
    ),
    
    labelStyles: FieldLabelStateStyles(
        base: FieldLabelStyle(
            color: PayPalBrand.blue,
            font: .system(size: 13, weight: .bold)
        )
    )
)

FieldStyle properties

Each FieldStyle object supports the following SwiftUI-based properties:

PropertyTypeDescriptionExample
colorColor?The text or foreground colour..label
fontFont?The SwiftUI font for the text..body
fontWeightFont.Weight?The font weight..semibold, .bold
fontSizeCGFloat?The font size in points.16
labelFontFont?The SwiftUI font for labels..caption
labelColorColor?The colour for labels..secondary
valueFontFont?The SwiftUI font for values..body
valueColorColor?The colour for values..primary
backgroundColorColor?The background colour.Color(.systemGray6)
borderColorColor?The border colour..gray
borderWidthCGFloat?The border width in points.1
cornerRadiusCGFloat?The corner radius in points.8
paddingEdgeInsets?The padding around the content.EdgeInsets(top: 12, leading: 16, bottom: 12, trailing: 16)
marginEdgeInsets?The margin around the component.EdgeInsets(top: 8, leading: 0, bottom: 8, trailing: 0)
textAlignmentTextAlignment?The text alignment..leading
opacityDouble?The opacity (0.0 - 1.0).1.0
shadowShadowStyle?The shadow styling.ShadowStyle(color: .black.opacity(0.2), radius: 4, x: 0, y: 2)
iconIconStyle?The icon styling, including size and tint colour.IconStyle(size: CGSize(width: 24, height: 24), tintColor: .white)

Validation

Custom validation messages

Provide custom error messages for validation scenarios:

let config = PayPalPayoutReceiverComponentConfig(
    label: "PayPal Account",
    validations: PayPalPayoutReceiverValidationResource(
        PPE01: "Please provide a PayPal email address",
        PPE02: "The email address format is invalid"
    )
)

The receiver component is display-only, so these messages aren't shown in the UI. You can set them on the configuration, but an invalid value still makes pxpCheckout.create throw an error with the SDK's own message.

The following table describes the two validation message keys.

ValidationDescription
PPE01The message for a missing receiver email. It isn't shown in the UI.
PPE02The message for an invalid email format. It isn't shown in the UI.

receiverType

Currently, only .email is supported:

receiverType: .email  // Only supported value

Methods

buildContent()

Renders the receiver display as a SwiftUI view:

func buildContent() -> AnyView

Returns the component as a SwiftUI AnyView. The returned view is a read-only display showing the PayPal email from SDK configuration.

The following example creates the receiver component and renders it in a SwiftUI view.

struct PayoutView: View {
    @State private var receiverComponent: BaseComponent?
    
    var body: some View {
        VStack {
            if let component = receiverComponent {
                component.buildContent()
                    .frame(maxWidth: .infinity)
            }
        }
        .onAppear {
            createReceiverComponent()
        }
    }
    
    private func createReceiverComponent() {
        Task {
            let config = PayPalPayoutReceiverComponentConfig(
                label: "PayPal Account",
                applyMask: true,
                showMaskToggle: true
            )
            
            let component = try pxpCheckout.create(.paypalPayoutReceiver, componentConfig: config)
            
            await MainActor.run {
                self.receiverComponent = component
            }
        }
    }
}

The PayPalPayoutReceiverComponent is primarily a display component. The email address displayed is determined by the paypalConfig.payout.paypalWallet.email configured during the SDK initialisation.

Important: Display-only component

The PayPalPayoutReceiverComponent is a read-only display component, which means the following.

  • The email address is sourced from PayPalWallet.email in the SDK configuration.
  • Users can't edit the email through this component.
  • To change the displayed email, you must reinitialise SDK with a different PayPalWallet configuration.
  • The component has no getValue() method (display-only, no input collection).

The following example shows how to change the displayed email by updating the SDK configuration.

// To change the displayed email, update SDK configuration
let updatedPaypalWallet = PayPalWallet(
    email: "newemail@example.com",  // New email to display
    payerId: "PAYERID123ABC",
    proceedPayoutWithSdk: true
)

// Reinitialise SDK with new configuration
let checkoutConfig = CheckoutConfig(
    // ... other config
    paypalConfig: PayPalConfig(
        payout: PayPalPayoutConfig(
            paypalWallet: updatedPaypalWallet
        )
    )
)

Examples

Basic receiver display

A simple implementation showing the PayPal email:

import SwiftUI
import PXPCheckoutSDK

struct BasicReceiverView: View {
    @State private var receiverComponent: BaseComponent?
    
    var body: some View {
        VStack(spacing: 16) {
            Text("Payout Destination")
                .font(.title)
            
            if let component = receiverComponent {
                component.buildContent()
                    .frame(maxWidth: .infinity)
            }
        }
        .padding()
        .onAppear {
            createComponent()
        }
    }
    
    private func createComponent() {
        Task {
            let config = PayPalPayoutReceiverComponentConfig(
                label: "PayPal Account",
                accessibilityLabel: "PayPal account for receiving payout",
                applyMask: true,
                showMaskToggle: true
            )
            
            let component = try pxpCheckout.create(.paypalPayoutReceiver, componentConfig: config)
            
            await MainActor.run {
                self.receiverComponent = component
            }
        }
    }
}

Privacy-focused display

Implementation with masked email and no reveal option:

let config = PayPalPayoutReceiverComponentConfig(
    label: "Linked PayPal Account",
    guideText: "Your email is hidden for security",
    accessibilityLabel: "Linked PayPal account",
    applyMask: true,
    showMaskToggle: false,  // Cannot reveal email
    
    styles: FieldStyle(
        backgroundColor: Color(.systemGray6),
        borderColor: Color(.systemGray4),
        borderWidth: 1,
        cornerRadius: 8,
        padding: EdgeInsets(top: 14, leading: 16, bottom: 14, trailing: 16)
    ),
    
    inputStyles: FieldInputStateStyles(
        base: FieldInputStyle(
            color: Color(.label),
            fontWeight: .medium,
            fontSize: 16
        )
    )
)

Combined with other payout components

Use the receiver component alongside the amount and submission components:

struct DirectPayoutView: 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 to PayPal")
                .font(.title)
            
            // Amount display
            if let amount = amountComponent {
                amount.buildContent()
                    .frame(maxWidth: .infinity)
            }
            
            // Receiver display
            if let receiver = receiverComponent {
                receiver.buildContent()
                    .frame(maxWidth: .infinity)
            }
            
            Divider()
                .padding(.vertical, 8)
            
            // Submit button
            if let submit = submissionComponent {
                submit.buildContent()
                    .frame(maxWidth: .infinity)
            }
        }
        .padding()
        .onAppear {
            createComponents()
        }
    }
    
    private func createComponents() {
        Task {
            // Create amount component
            let amountConfig = PayoutAmountComponentConfig(
                label: "Payout Amount"
            )
            let amount = try pxpCheckout.create(.payoutAmount, componentConfig: amountConfig)
            
            // Create receiver component with PayPal branding
            let receiverConfig = PayPalPayoutReceiverComponentConfig(
                label: "PayPal Account",
                applyMask: true,
                showMaskToggle: true,
                
                styles: FieldStyle(
                    backgroundColor: Color(red: 0.0, green: 0.44, blue: 0.73).opacity(0.05),
                    borderColor: Color(red: 0.0, green: 0.44, blue: 0.73).opacity(0.3),
                    borderWidth: 1,
                    cornerRadius: 8
                )
            )
            let receiver = try pxpCheckout.create(.paypalPayoutReceiver, componentConfig: receiverConfig)
            
            // Create submission component
            let submissionConfig = PayoutSubmissionComponentConfig(
                submitText: "Withdraw Now",
                onPrePayoutSubmit: {
                    // Return nil or isApproved: false to cancel the payout
                    return PrePayoutSubmitResult(isApproved: true)
                },
                onPostPayout: { result in
                    print("Payout completed: \(result.merchantTransactionId)")
                }
            )
            let submission = try pxpCheckout.create(.payoutSubmission, componentConfig: submissionConfig)
            
            await MainActor.run {
                self.amountComponent = amount
                self.receiverComponent = receiver
                self.submissionComponent = submission
            }
        }
    }
}

Error handling

The SDK validates the receiver when you create the component. pxpCheckout.create(.paypalPayoutReceiver, ...) throws an error if validation fails, so catch these errors with try-catch. They aren't delivered to the onError callback of the PayoutSubmissionComponent, which is for failures during payout execution.

The following table lists the error codes the receiver component can throw.

Error codeExceptionDescription
SDK0803PaypalPayoutReceiverRequiredExceptionThe email in PayPalWallet is missing or empty.
SDK0805PaypalPayoutReceiverTypeEmailOnlyExceptionThe receiverType must be .email.
SDK0808PaypalPayoutEmailInvalidExceptionThe email address format is invalid.
SDK0816PayoutEmailMaxLengthExceptionThe email address exceeds 127 characters.

The following example shows how to catch these errors:

do {
    let component = try pxpCheckout.create(
        .paypalPayoutReceiver,
        componentConfig: PayPalPayoutReceiverComponentConfig(label: "PayPal Account")
    )
} catch let error as BaseSdkException {
    switch error.errorCode {
    case "SDK0803", "SDK0805", "SDK0808", "SDK0816":
        print("Receiver error: \(error.errorMessage)")
    default:
        print("Unexpected error: \(error.errorMessage)")
    }
}

For a complete list of error codes, see Data validation.