About configuration

Learn about how to configure PayPal components for Android.

Overview

The PayPal Android SDK provides a suite of configurable components for integrating PayPal payments into your Android application. Each component is built with Jetpack Compose and offers comprehensive configuration options for styling, behaviour, and event handling.

Configuration structure

All PayPal components follow a consistent configuration pattern:

val componentConfig = ComponentConfig(
    // Required properties
    requiredProperty = value,
    
    // Optional properties
    optionalProperty = value,
    
    // Styling
    style = StyleConfig(
        // Style properties
    ),
    
    // Event handlers
    onEvent = { data ->
        // Handle event
    }
)

Basic configuration

At minimum, each component requires a few essential properties:

// PayPal component
val paypalConfig = PayPalComponentConfig(
    renderType = "standalone",
    fundingSources = "paypal",
    shippingPreference = "NoShipping",
    userAction = "PayNow"
)

// Consent component
val consentConfig = PayPalConsentConfig(
    label = "Save my PayPal account"
)

// Toggle component
val toggleConfig = ToggleComponentConfig(
    label = "Use different PayPal account"
)

// Pre-built component
val prebuiltConfig = PreBuiltPayPalComponentConfig(
    paypalConfig = paypalConfig
)

Advanced configuration

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

val paypalConfig = PayPalComponentConfig(
    // Required configuration
    renderType = "standalone",
    fundingSources = "paypal",
    shippingPreference = "NoShipping",
    userAction = "PayNow",
    
    // Styling
    style = PayPalButtonStyle(
        layout = "horizontal",
        color = "blue",
        shape = "pill",
        height = 48,
        label = "checkout"
    ),
    
    // One-click payment
    enableOneClickPayment = true,
    scriptParams = PayPalScriptParams(
        userIdToken = getUserIdToken()
    ),
    
    // Event handlers
    onSuccess = { data ->
        handlePaymentSuccess(data)
    },
    onError = { error ->
        handlePaymentError(error)
    }
)

Styling components

Default styling

All components come with PayPal-branded default styling:

PayPal button: Gold button with vertical layout.
Consent checkbox: PayPal blue with standard dimensions.
Toggle switch: Material Design with PayPal blue active state.
Pre-built container: Clean white background with rounded corners.

Custom styling

Each component offers comprehensive styling options:

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

val customToggleConfig = ToggleComponentConfig(
    label = "Custom styled toggle",
    labelStyle = ToggleLabelStyle(
        color = Color(0xFF2C2E2F),
        fontSizeSp = 16f,
        fontWeight = FontWeight.SemiBold,
        position = LabelPosition.START,
        spacing = 16.dp
    ),
    toggleStyle = ToggleVisualStyle(
        width = 56.dp,
        height = 32.dp,
        borderRadius = 16.dp,
        activeTrackColor = Color(0xFF0070BA),
        inactiveTrackColor = Color(0xFFE0E0E0)
    )
)

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.
Lifecycle handlers: Called during component mounting and unmounting.

val paypalConfig = PayPalComponentConfig(
    // Success handling
    onSuccess = { data ->
        val jsonObject = JSONObject(data)
        val orderID = jsonObject.getString("orderID")
        navigateToSuccessScreen(orderID)
    },
    
    // Error handling
    onError = { error ->
        Log.e("PayPal", "Payment failed: $error")
        showErrorDialog(error)
    },
    
    // Cancellation handling
    onCancel = {
        Log.d("PayPal", "Payment cancelled")
        returnToCart()
    }
)

Component linking

Components can be linked together for coordinated behaviour.

Linking toggle with PayPal

// Create toggle first
val toggleComponent = pxpCheckout.createComponent(
    type = ComponentType.TOGGLE,
    config = toggleConfig
)

// Link to PayPal component
val paypalConfig = PayPalComponentConfig(
    toggleComponent = toggleComponent,
    enableOneClickPayment = true
)

// Create consent first
val consentComponent = pxpCheckout.createComponent(
    type = ComponentType.PAYPAL_CONSENT,
    config = consentConfig
)

// Link to PayPal component
val paypalConfig = PayPalComponentConfig(
    consentComponent = consentComponent,
    onGetConsent = {
        consentComponent.getValue() as? Boolean ?: false
    }
)

Best practices

Use appropriate components

Choose the right component for your use case:

Simple payments:: Use PayPal component alone.
One-click with consent: Add the consent component.
Account switching: Add the toggle component.
Quick implementation: Use the pre-built component.

Configure for your brand

Customise the styling to match your app's design:

// Define brand colors
object BrandColors {
    val primary = Color(0xFF0070BA)
    val surface = Color(0xFFF8F9FA)
    val onSurface = Color(0xFF212529)
}

// Apply to components
val paypalConfig = PayPalComponentConfig(
    style = PayPalButtonStyle(
        color = "blue",
        shape = "rect"
    )
)

Handle all events

Implement comprehensive event handling:

val paypalConfig = PayPalComponentConfig(
    onSuccess = { handleSuccess(it) },
    onError = { handleError(it) },
    onCancel = { handleCancel() },
    onOrderCreated = { trackOrder(it) },
    onScriptLoaded = { hideLoading() }
)

For more information about events, see Events.

Validate user input

Use validation for the consent and toggle components:

val consentConfig = PayPalConsentConfig(
    isRequired = true,
    onTriggerFieldValidation = { result ->
        if (!result.isValid) {
            showError("Please agree to save your PayPal account")
        }
    }
)

Test different configurations

Test your components in various scenarios:

Light and dark themes.
Different screen sizes.
Various payment amounts.
Error conditions.
Network failures.

Next steps

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

PayPal component: Comprehensive button configuration.
Consent component: Checkbox styling and behaviour.
Toggle component: Switch configuration options.
Pre-built component: Composite component setup.