Learn about how to configure PayPal payout components for iOS.
The PayPal iOS SDK provides configurable components for integrating PayPal payouts into your iOS application. Each component is built with SwiftUI and offers comprehensive configuration options for styling, behaviour, and event handling.
All PayPal payout components follow a consistent configuration pattern:
// Payout submission component
let submissionConfig = PayoutSubmissionComponentConfig(
submitText: "Withdraw to PayPal",
submitAccessibilityLabel: "Withdraw funds to PayPal"
)
// Styling
submissionConfig.styles = ButtonStateStyles(
base: FieldStyle(
color: .white,
backgroundColor: Color(red: 0, green: 0.44, blue: 0.73)
)
)
// Event handlers
submissionConfig.onPostPayout = { result in
// Handle payout completion
}Environment and PayPal credentials are configured at SDK initialisation via CheckoutConfig and PayPalConfig. The payout execution mode (proceedPayoutWithSdk) is configured via PayPalConfig.
Each component can be customised with configuration properties:
// Payout submission component
let submissionConfig = PayoutSubmissionComponentConfig(
submitText: "Withdraw to PayPal",
submitAccessibilityLabel: "Withdraw funds to PayPal"
)
// Payout amount component (display only)
let amountConfig = PayoutAmountComponentConfig(
label: "Payout Amount",
accessibilityLabel: "Payout amount"
)
// PayPal payout receiver component (display only)
let receiverConfig = PayPalPayoutReceiverComponentConfig(
label: "PayPal Account",
accessibilityLabel: "PayPal account email"
)Each component supports the configuration properties described in the following sections.
The following table lists the properties you can set on the payout submission component.
| Property | Description |
|---|---|
recipientTypePayoutRecipientType | The recipient type. It must be .email, otherwise create throws SDK0807. Default: .email. |
walletPayPalPayoutWalletType | The wallet type. Default: .paypal. |
submitTextString? | The custom text for the submit button. Defaults to "Withdraw with". The PayPal logo is always shown after this text. |
submitAccessibilityLabelString? | The accessibility label for the button. Defaults to "Withdraw with PayPal". |
stylesButtonStateStyles? | The custom button styles for different states. |
onClick(() -> Void)? | Called when the button is clicked, before payout execution. This is the only callback that runs when proceedPayoutWithSdk is false. |
onPrePayoutSubmit(() async -> PrePayoutSubmitResult?)? | Called for merchant approval before the payout executes (SDK-managed mode only). |
onPostPayout((MerchantSubmitResult) -> Void)? | Called after the payout completes (SDK-managed mode only). |
onCancel(() -> Void)? | Not currently invoked by the SDK. To cancel a payout, return nil or isApproved: false from onPrePayoutSubmit. |
onError((Error) -> Void)? | Called when an error occurs during payout execution. Cast the error to BaseSdkException to read errorCode and errorMessage. |
The following table lists the properties you can set on the payout amount component.
| Property | Description |
|---|---|
labelString? | The label text displayed above the amount field. |
placeholderString? | The placeholder text. The configuration accepts it, but the amount display component doesn't render it. |
guideTextString? | The helper text displayed below the amount field. |
accessibilityLabelString? | The accessibility label for screen readers. |
stylesFieldStyle? | The custom styling for the container. |
inputStylesFieldInputStateStyles? | The input styling. The configuration accepts it, but the amount display component doesn't currently apply its text colour, font size, or font weight. Use styles to style the container. |
labelStylesFieldLabelStateStyles? | The custom styling for the label text. |
The following table lists the properties you can set on the PayPal payout receiver component.
| Property | Description |
|---|---|
labelString? | The label text displayed above the email field. |
placeholderString? | The placeholder text. The configuration accepts it, but the receiver display component doesn't render it. |
guideTextString? | The helper text displayed below the email field. |
accessibilityLabelString? | The accessibility label for screen readers. |
applyMaskBool | Whether to mask the email address. Defaults to true. |
showMaskToggleBool | 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. |
receiverTypePayoutRecipientType | The recipient type. Default: .email. |
stylesFieldStyle? | The custom styling for the container. |
inputStylesFieldInputStateStyles? | The input styling. The configuration accepts it, but the receiver display component doesn't currently apply its text colour, font size, or font weight. Use styles to style the container. |
labelStylesFieldLabelStateStyles? | The custom styling for the label text. |
validationsPayPalPayoutReceiverValidationResource? | The custom validation error messages. |
Error callback type handling: The onError parameter of the PayoutSubmissionComponentConfig initialiser accepts Error. Cast the error to BaseSdkException to read errorCode and errorMessage. Alternatively, assign onError after initialisation: the stored property accepts a BaseSdkException directly.
Validation errors for the payout configuration (e.g., a missing email or payer ID) are thrown by pxpCheckout.create, not delivered to onError. The onError callback is for failures during payout execution.
For more complex implementations, you can configure styling, callbacks, and additional features:
let submissionConfig = PayoutSubmissionComponentConfig(
submitText: "Withdraw to PayPal",
submitAccessibilityLabel: "Withdraw funds to PayPal",
// Custom button styling
styles: ButtonStateStyles(
base: FieldStyle(
color: .white,
fontWeight: .semibold,
fontSize: 16,
backgroundColor: Color(red: 0, green: 0.44, blue: 0.73),
cornerRadius: 8,
padding: EdgeInsets(top: 14, leading: 24, bottom: 14, trailing: 24)
),
disabled: FieldStyle(
backgroundColor: Color(.systemGray5),
opacity: 0.6
),
loading: FieldStyle(
backgroundColor: Color(red: 0, green: 0.37, blue: 0.65),
opacity: 0.9
)
),
// Event handlers
onClick: {
print("Submit button clicked")
},
onPrePayoutSubmit: {
let approved = await showApprovalDialog()
guard approved else { return nil }
return PrePayoutSubmitResult(isApproved: true)
},
onPostPayout: { result in
showSuccessMessage(result.merchantTransactionId)
},
onError: { error in
guard let error = error as? BaseSdkException else { return }
handlePayoutError(error)
}
)All components come with PayPal-branded default styling:
- Submission button: PayPal gold, at full width.
- Amount display: Read-only field with label.
- Receiver display: Read-only field with email masking.
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 radius and border styles.
The following example customises the submission button for each of its three states.
// Custom button styling with states
let buttonStyles = ButtonStateStyles(
base: FieldStyle(
color: .white,
fontWeight: .bold,
fontSize: 18,
backgroundColor: Color(red: 0.2, green: 0.7, blue: 0.3),
borderColor: Color(red: 0.2, green: 0.7, blue: 0.3),
borderWidth: 0,
cornerRadius: 12,
padding: EdgeInsets(top: 16, leading: 32, bottom: 16, trailing: 32),
opacity: 1.0
),
disabled: FieldStyle(
color: Color(.systemGray2),
backgroundColor: Color(.systemGray5),
opacity: 0.5
),
loading: FieldStyle(
color: .white,
backgroundColor: Color(red: 0.15, green: 0.55, blue: 0.25),
opacity: 0.9
)
)
let submissionConfig = PayoutSubmissionComponentConfig(
submitText: "Withdraw to PayPal",
styles: buttonStyles
)The display components (PayoutAmountComponent, PayPalPayoutReceiverComponent) support field-specific styling:
let amountConfig = PayoutAmountComponentConfig(
label: "Payout Amount",
placeholder: "$0.00",
guideText: "Amount to be sent to your PayPal account",
accessibilityLabel: "Payout amount",
styles: FieldStyle(
backgroundColor: Color(.systemGray6),
cornerRadius: 12,
padding: EdgeInsets(top: 20, leading: 20, bottom: 20, trailing: 20),
textAlignment: .center
),
inputStyles: FieldInputStateStyles(
base: FieldInputStyle(
color: Color(red: 0.2, green: 0.7, blue: 0.3),
fontWeight: .bold,
fontSize: 32
)
),
labelStyles: FieldLabelStateStyles(
base: FieldLabelStyle(
color: .secondary,
font: .system(size: 14, weight: .medium)
)
)
)The container FieldStyle (background, border, padding, margin, opacity, shadow, and textAlignment) is applied to the display components. The text colour, font size, and font weight in inputStyles are accepted by the configuration but aren't currently applied to the displayed amount or email text. FieldInputStyle doesn't have a textAlignment property.
All components provide event handlers for user interactions and lifecycle events.
Common event patterns:
- Click handlers: Called when the button is tapped.
- Success handlers: Called when operations complete successfully.
- Error handlers: Called when a payout fails during execution.
- Approval handlers: Called for merchant approval before payout execution. Return
nilorisApproved: falseto cancel the payout.
The following example sets each of these handlers on the submission component.
let submissionConfig = PayoutSubmissionComponentConfig(
submitText: "Withdraw to PayPal",
// Click handling
onClick: {
print("Button clicked")
showLoadingIndicator()
},
// Merchant approval (SDK-managed mode)
onPrePayoutSubmit: {
let approved = await showApprovalDialog(
amount: 100.00,
currency: "USD"
)
guard approved else { return nil }
return PrePayoutSubmitResult(isApproved: true)
},
// Success handling
onPostPayout: { result in
print("Payout completed: \(result.merchantTransactionId)")
navigateToSuccessScreen()
},
// Error handling
onError: { error in
guard let error = error as? BaseSdkException else { return }
print("Payout error: \(error.errorMessage)")
showErrorDialog(error.errorMessage)
}
)The payout SDK provides components for displaying payout information and executing transactions.
Use PayoutAmountComponent and PayPalPayoutReceiverComponent to show payout details to users:
// Create amount display
let amountConfig = PayoutAmountComponentConfig(
label: "Amount"
)
let amountComponent = try pxpCheckout.create(
.payoutAmount,
componentConfig: amountConfig
)
// Create receiver display
let receiverConfig = PayPalPayoutReceiverComponentConfig(
label: "PayPal Account",
applyMask: true,
showMaskToggle: true
)
let receiverComponent = try pxpCheckout.create(
.paypalPayoutReceiver,
componentConfig: receiverConfig
)Use PayoutSubmissionComponent to provide a button for users to execute the payout. The component reads the amount and currency from transactionData and the wallet from paypalConfig. It doesn't read values from the amount or receiver components. Both email and payerId are required in PayPalWallet:
// Configure SDK with stored credentials
let paypalConfig = PayPalConfig(
payout: PayPalPayoutConfig(
paypalWallet: PayPalWallet(
email: "user@example.com",
payerId: "PAYERID123ABC",
proceedPayoutWithSdk: true
)
)
)
let submissionConfig = PayoutSubmissionComponentConfig(
submitText: "Withdraw to PayPal",
onPrePayoutSubmit: {
// Return nil or isApproved: false to cancel the payout
return PrePayoutSubmitResult(isApproved: true)
},
onPostPayout: { result in
print("Payout completed: \(result.merchantTransactionId)")
}
)
let submitComponent = try pxpCheckout.create(
.payoutSubmission,
componentConfig: submissionConfig
)Configure how payouts are executed via PayPalConfig. The proceedPayoutWithSdk parameter controls whether the SDK or your backend manages payout execution.
The SDK executes the payout only after your onPrePayoutSubmit callback returns PrePayoutSubmitResult(isApproved: true):
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 SDK-managed payouts, implement the onPrePayoutSubmit and onPostPayout callbacks.
Your backend handles payout execution:
let paypalConfig = PayPalConfig(
payout: PayPalPayoutConfig(
paypalWallet: PayPalWallet(
email: "user@example.com", // From your backend
payerId: "PAYERID123ABC", // From your backend
proceedPayoutWithSdk: false // Backend manages payout (default)
)
)
)With backend-managed payouts, only the onClick callback runs. Use onClick to notify your backend that the user requested a payout, then your backend executes the payout via the Unity API.
Default behaviour: proceedPayoutWithSdk defaults to false. When false:
- The SDK doesn't execute the payout.
onPrePayoutSubmitandonPostPayoutcallbacks aren't triggered. OnlyonClickruns.- Your backend must handle payout execution.
- Your app must notify the backend from
onClickwhen the user initiates a payout.
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 success = Color(red: 0.2, green: 0.7, blue: 0.3)
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 submissionConfig = PayoutSubmissionComponentConfig(
submitText: "Withdraw to PayPal",
styles: ButtonStateStyles(
base: FieldStyle(
color: .white,
backgroundColor: BrandColors.primary,
cornerRadius: 8
)
)
)Implement comprehensive event handling:
let submissionConfig = PayoutSubmissionComponentConfig(
submitText: "Withdraw to PayPal",
onClick: { handleClick() },
onPrePayoutSubmit: { await handleApproval() },
onPostPayout: { handleSuccess($0) },
onError: { error in
guard let error = error as? BaseSdkException else { return }
handleError(error)
}
)For more information about events, see Events.
Test your components in various scenarios, including the following:
- Light and dark mode.
- Different screen sizes (iPhone, iPad).
- Various payout amounts.
- Error conditions.
- Network failures.
Here's a comprehensive example showing all configuration options for a complete payout flow:
import SwiftUI
import PXPCheckoutSDK
// Initialise SDK
let sessionData = SessionData(
sessionId: "your-session-id",
hmacKey: "your-hmac-key",
encryptionKey: "your-encryption-key",
allowedFundingTypes: nil
)
let transactionData = TransactionData(
amount: Decimal(100.00),
currency: "USD",
entryType: .ecom,
intent: TransactionIntentData(card: nil, paypal: .payout),
merchantTransactionId: "payout-\(UUID().uuidString)",
merchantTransactionDate: { Date() }
)
let paypalConfig = PayPalConfig(
payout: PayPalPayoutConfig(
paypalWallet: PayPalWallet(
email: "user@example.com", // From your backend
payerId: "PAYERID123ABC", // From your backend
proceedPayoutWithSdk: true
)
)
)
let checkoutConfig = CheckoutConfig(
environment: .test,
session: sessionData,
transactionData: transactionData,
merchantShopperId: "user-123",
ownerId: "merchant-456",
paypalConfig: paypalConfig,
analyticsEvent: { event in
print("Analytics: \(event.eventName)")
}
)
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 with full configuration
let submissionConfig = PayoutSubmissionComponentConfig(
recipientType: .email,
wallet: .paypal,
submitText: "Withdraw to PayPal",
submitAccessibilityLabel: "Withdraw funds to PayPal",
// Custom styling
styles: ButtonStateStyles(
base: FieldStyle(
color: .white,
fontWeight: .semibold,
fontSize: 16,
backgroundColor: Color(red: 0, green: 0.44, blue: 0.73),
borderColor: Color(red: 0, green: 0.44, blue: 0.73),
borderWidth: 0,
cornerRadius: 8,
padding: EdgeInsets(top: 14, leading: 24, bottom: 14, trailing: 24),
opacity: 1.0
),
disabled: FieldStyle(
color: Color(.systemGray),
backgroundColor: Color(.systemGray5),
borderColor: Color(.systemGray5),
opacity: 0.6
),
loading: FieldStyle(
color: .white,
backgroundColor: Color(red: 0, green: 0.37, blue: 0.65),
opacity: 0.9
)
),
// Event handlers
onClick: {
print("Withdraw button clicked")
Analytics.track("payout_initiated")
},
onPrePayoutSubmit: {
print("Approval requested")
// Show confirmation dialog
let approved = await showPayoutApprovalDialog(
amount: 100.00,
currency: "USD"
)
guard approved else {
Analytics.track("payout_approval_rejected")
return nil
}
Analytics.track("payout_approval_granted")
return PrePayoutSubmitResult(isApproved: true)
},
onPostPayout: { result in
print("Payout successful!")
print("Merchant TX ID: \(result.merchantTransactionId)")
print("System TX ID: \(result.systemTransactionId)")
Analytics.track("payout_completed", properties: [
"transactionId": result.merchantTransactionId
])
navigateToSuccessScreen(result.merchantTransactionId)
},
onError: { error in
guard let error = error as? BaseSdkException else { return }
print("Payout error: \(error.errorCode) - \(error.errorMessage)")
Analytics.track("payout_error", properties: [
"errorCode": error.errorCode,
"errorMessage": error.errorMessage
])
showErrorDialog(error.errorMessage)
}
)
// Create submission component
let submitComponent = try pxpCheckout.create(
.payoutSubmission,
componentConfig: submissionConfig
)
// Render in SwiftUI
VStack(spacing: 16) {
amountComponent.buildContent()
receiverComponent.buildContent()
submitComponent.buildContent()
}Now that you understand component configuration fundamentals, dive into the detailed documentation for each component:
- Payout amount component: Amount display configuration.
- Payout receiver component: Receiver display configuration.
- Payout submission component: Submit button configuration.