About configuration

Learn about how to configure PayPal components for iOS.

Overview

The PayPal iOS SDK provides configurable components for integrating PayPal payments into your iOS application. Each component is built with SwiftUI and offers comprehensive configuration options for styling, behaviour, and event handling.

Configuration structure

All PayPal components follow a consistent configuration pattern:

// PayPal button component
let paypalConfig = PayPalButtonComponentConfig()

// Configure properties
paypalConfig.paymentDescription = "Payment"
paypalConfig.userAction = .payNow
paypalConfig.fundingSource = .paypal

// Styling
paypalConfig.style = PayPalButtonStyleConfig(
    color: .blue,
    label: .checkout,
    size: .expanded,
    edges: .rounded
)

// Event handlers
paypalConfig.onApprove = { approvalData in
    // Handle approval
}

Note: Authentication and environment are configured at SDK initialization via CheckoutConfig, not at component level.

Basic configuration

At minimum, each component requires a few essential properties:

// PayPal button component
let paypalConfig = PayPalButtonComponentConfig()
paypalConfig.fundingSource = .paypal

// Consent component
let consentConfig = PayPalConsentComponentConfig(
    label: "Save my PayPal account"
)

Advanced configuration

For more complex implementations, you can configure styling, callbacks, and additional features:

let paypalConfig = PayPalButtonComponentConfig()

// Payment details
paypalConfig.fundingSource = .paypal
paypalConfig.payeeEmailAddress = "merchant@example.com"
paypalConfig.paymentDescription = "Premium subscription"
paypalConfig.shippingPreference = .noShipping
paypalConfig.userAction = .payNow

// Styling
paypalConfig.style = PayPalButtonStyleConfig(
    color: .blue,
    label: .checkout,
    size: .collapsed,
    edges: .rounded,
    contentInsets: .uniform(12)
)

// Event handlers
paypalConfig.onApprove = { approvalData in
    handlePaymentSuccess(approvalData)
}

paypalConfig.onError = { error in
    handlePaymentError(error)
}

Styling components

Default styling

All components come with PayPal-branded default styling:

PayPal button: Gold button with collapsed size and soft edges.
Consent checkbox: PayPal blue with standard dimensions (20pt).

Custom styling

Each component offers comprehensive styling options:

Colours: Customise all colour properties including backgrounds, text, and states.
Typography: Control font sizes, weights, and text styles.
Layout: Configure spacing, padding, dimensions, and positioning.
Shapes: Adjust corner styles and dimensions.

let consentConfig = PayPalConsentComponentConfig(
    label: "Custom styled consent",
    labelStyles: CheckboxLabelStyles(
        checked: CheckboxLabelStyle(
            font: .system(size: 15),
            fontWeight: .semibold,
            color: Color(red: 0.13, green: 0.15, blue: 0.16)
        ),
        unchecked: CheckboxLabelStyle(
            font: .system(size: 15),
            fontWeight: .regular,
            color: Color(red: 0.42, green: 0.46, blue: 0.49)
        )
    ),
    checkedColor: Color(red: 0, green: 0.44, blue: 0.73),
    uncheckedColor: Color(red: 0.62, green: 0.65, blue: 0.67),
    size: 24
)

Event handling

All components provide event handlers for user interactions and lifecycle events.

Common event patterns:

Success handlers: Called when operations complete successfully.
Error handlers: Called when errors occur.
State change handlers: Called when a component state changes.
Pre-authorisation handlers: Called before payment processing.

let paypalConfig = PayPalButtonComponentConfig()

// Click handling
paypalConfig.onClick = {
    print("Button clicked")
}

// Success handling
paypalConfig.onApprove = { approvalData in
    print("Payment approved: \(approvalData.orderID)")
    navigateToSuccessScreen(approvalData.orderID)
}

// Error handling
paypalConfig.onError = { error in
    print("Payment failed: \(error.errorMessage)")
    showErrorDialog(error.errorMessage)
}

// Cancellation handling
paypalConfig.onCancel = { error in
    print("Payment cancelled")
    returnToCart()
}

Component linking

Components can be linked together for coordinated behaviour.

// Create consent component first
let consentConfig = PayPalConsentComponentConfig(
    label: "Save my PayPal account for faster checkout"
)
let consentComponent = try pxpCheckout.create(
    .paypalConsent,
    componentConfig: consentConfig
)

// Link to PayPal button component
let paypalConfig = PayPalButtonComponentConfig()
paypalConfig.fundingSource = .paypal
paypalConfig.paypalConsentComponent = consentComponent as? PayPalConsentComponent

// Alternative: Use onGetConsent callback
paypalConfig.onGetConsent = {
    let consentGiven = consentComponent.getValue() as? Bool ?? false
    return consentGiven
}

Best practices

Configure for your brand

Customise the styling to match your app's design:

// Define brand colours
struct BrandColors {
    static let primary = Color(red: 0, green: 0.44, blue: 0.73)
    static let surface = Color(red: 0.97, green: 0.98, blue: 0.98)
    static let onSurface = Color(red: 0.13, green: 0.15, blue: 0.16)
}

// Apply to components
let paypalConfig = PayPalButtonComponentConfig()
paypalConfig.style = PayPalButtonStyleConfig(
    color: .blue,
    label: .checkout,
    size: .expanded,
    edges: .rounded
)

Handle all events

Implement comprehensive event handling:

let paypalConfig = PayPalButtonComponentConfig()
paypalConfig.onClick = { handleClick() }
paypalConfig.onApprove = { handleSuccess($0) }
paypalConfig.onError = { handleError($0) }
paypalConfig.onCancel = { handleCancel($0) }
paypalConfig.onOrderCreated = { trackOrder($0) }

For more information about events, see Events.

Test different configurations

Test your components in various scenarios:

Light and dark mode.
Different screen sizes (iPhone, iPad).
Various payment amounts.
Error conditions.
Network failures.

Complete configuration example

Here's a comprehensive example showing all configuration options:

import SwiftUI
import PXPCheckoutSDK

// Initialise SDK
let sessionData = SessionData(
    sessionId: "your-session-id",
    hmacKey: "your-hmac-key",
    encryptionKey: "your-encryption-key"
)

let transactionData = TransactionData(
    amount: 25.00,
    currency: "USD",
    entryType: .ecom,
    intent: TransactionIntentData(card: nil, paypal: .authorisation),
    merchantTransactionId: "tx-\(UUID().uuidString)",
    merchantTransactionDate: { Date() }
)

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

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

// Create consent component
let consentConfig = PayPalConsentComponentConfig(
    label: "I agree to save my PayPal account for future transactions",
    labelStyles: CheckboxLabelStyles(
        checked: CheckboxLabelStyle(
            font: .system(size: 14),
            fontWeight: .semibold,
            color: .primary
        ),
        unchecked: CheckboxLabelStyle(
            font: .system(size: 14),
            fontWeight: .regular,
            color: .secondary
        )
    ),
    checkedColor: Color(red: 0, green: 0.44, blue: 0.73),
    uncheckedColor: .gray,
    size: 22
)

let consentComponent = try pxpCheckout.create(
    .paypalConsent,
    componentConfig: consentConfig
)

// Create PayPal button with full configuration
let paypalConfig = PayPalButtonComponentConfig()

// Payment details
paypalConfig.fundingSource = .paypal
paypalConfig.payeeEmailAddress = "merchant@example.com"
paypalConfig.paymentDescription = "Premium Product"
paypalConfig.shippingPreference = .noShipping
paypalConfig.userAction = .payNow
paypalConfig.locale = "en_US"

// Styling
paypalConfig.style = PayPalButtonStyleConfig(
    color: .blue,
    label: .checkout,
    size: .expanded,
    edges: .rounded,
    contentInsets: .uniform(12)
)

// Link consent component
paypalConfig.paypalConsentComponent = consentComponent as? PayPalConsentComponent

// Event handlers
paypalConfig.onClick = {
    print("Button clicked")
}

paypalConfig.onPreAuthorisation = {
    return PayPalTransactionInitData(
        riskScreeningData: RiskScreeningData(
            performRiskScreening: true,
            excludeDeviceData: false,
            deviceSessionId: "device-\(UUID().uuidString)"
        )
    )
}

paypalConfig.onOrderCreated = { submitResult in
    if let merchantResult = submitResult as? MerchantSubmitResult {
        print("Order created - Merchant TX ID: \(merchantResult.merchantTransactionId)")
        print("System TX ID: \(merchantResult.systemTransactionId)")
    }
}

paypalConfig.onApprove = { approvalData in
    print("Payment approved: \(approvalData.orderID)")
    // Check consent
    let consentGiven = consentComponent.getValue() as? Bool ?? false
    if consentGiven {
        print("User consented to save PayPal account")
    }
    navigateToSuccessScreen(approvalData.orderID)
}

paypalConfig.onError = { error in
    print("Payment error: \(error.errorMessage)")
    showErrorDialog(error.errorMessage)
}

paypalConfig.onCancel = { error in
    print("Payment cancelled")
    showCancelMessage()
}

paypalConfig.onSubmitError = { error in
    print("Submit error: \(error.errorMessage)")
    handleSubmitError(error)
}

// Create component
let paypalComponent = try pxpCheckout.create(
    .paypalButton,
    componentConfig: paypalConfig
)

Next steps

Now that you understand component configuration fundamentals, dive into the detailed documentation for each component:

Button component: Comprehensive PayPal button configuration.
Consent component: Checkbox styling and behaviour.