Learn about validation requirements for PayPal payout data in your Android app.
The PayPal Android SDK validates payout data at multiple stages to ensure successful transactions. Understanding these validation rules helps you prevent errors and provide better user experiences.
Validation occurs at three key stages:
- SDK initialisation: Validates transaction data and configuration.
- Component creation: Validates component-specific configuration.
- Payout submission: Validates wallet details and payout parameters before sending to the backend.
The amount must meet these rules before you initialise the SDK:
| Rule | Description | Error |
|---|---|---|
| Amount required | The amount must be provided. | Validation error. |
| Positive value | The amount must be greater than zero. | PO02: "Transaction amount should be greater than 0." |
| Numeric value | The amount must be a valid number. | Validation error. |
Use a positive numeric amount in transactionData:
// Valid amounts
transactionData = TransactionData(
amount = 100.0, // Valid
amount = 0.01, // Valid: minimum positive value
amount = 999999.99 // Valid
)
// Invalid amounts
transactionData = TransactionData(
amount = 0.0, // Invalid: must be > 0
amount = -50.0 // Invalid: cannot be negative
)The currency must meet these rules:
| Rule | Description | Error |
|---|---|---|
| Currency required | The currency must be provided. | Validation error. |
| Format | The currency must be a valid 3-letter ISO currency code. | PO03: "Invalid currency code". |
| Supported | The currency must be supported by PayPal. | Validation error. |
Pass a supported 3-letter ISO currency code:
// Valid currencies
transactionData = TransactionData(
currency = "USD", // Valid
currency = "EUR", // Valid
currency = "GBP" // Valid
)
// Invalid currencies
transactionData = TransactionData(
currency = "", // Invalid: empty
currency = "US", // Invalid: not 3 letters
currency = "DOLLAR" // Invalid: not ISO code
)Set entryType to EntryType.Ecom for payouts. The payout request the SDK builds uses an e-commerce entry type.
| Rule | Description | Guidance |
|---|---|---|
| Recommended value | Use EntryType.Ecom for payouts. | Match the e-commerce payout request the SDK builds. |
Configure the entry type like this:
// Recommended entry type for payouts
transactionData = TransactionData(
entryType = EntryType.Ecom
)The intent must identify the transaction as a payout:
| Rule | Description | Error |
|---|---|---|
| Intent required | The intent must be provided. | Error during initialisation. |
| Value | Must be TransactionIntentData(paypal = PayPalIntentType.Payout) for payouts. | Error during initialisation. |
Set the PayPal intent to Payout:
// Valid intent for payouts
transactionData = TransactionData(
intent = TransactionIntentData(paypal = PayPalIntentType.Payout) // Required for payouts
)
// Invalid intents
transactionData = TransactionData(
intent = TransactionIntentData(paypal = PayPalIntentType.Purchase) // Not for payouts
intent = TransactionIntentData(paypal = PayPalIntentType.Authorisation) // Not for payouts
)For the withdrawal flow, the PayPal wallet must include a valid email and payer ID:
| Rule | Description | Error |
|---|---|---|
| Email required | The PayPal email must be provided for the withdrawal flow. | PO04: "Receiver cannot be empty". |
| PayerId required | The PayPal payer ID must be provided for the withdrawal flow. | PO04: "Payer ID is required for PayPal wallet payout". |
| Email format | The email must use a valid format (maximum 127 characters). | PO04: "Invalid email format". |
Provide both wallet fields when configuring the withdrawal flow:
// Valid PayPal wallet (withdrawal flow)
paypalConfig = PaypalConfig(
payout = PayoutConfig(
proceedPayoutWithSdk = true,
paypalWallet = PayPalPayOutWalletConfig(
email = "customer@example.com", // Required
payerId = "PAYER_ID_XXX" // Required
)
)
)
// Invalid PayPal wallet
paypalConfig = PaypalConfig(
payout = PayoutConfig(
proceedPayoutWithSdk = true,
paypalWallet = PayPalPayOutWalletConfig(
email = "customer@example.com",
payerId = "" // Invalid: empty payer ID
)
)
)The submission component validates recipientWallet as follows:
| Rule | Description | Error |
|---|---|---|
| Supported values | Only "Paypal" is currently supported (case-sensitive). | PO04: "Invalid recipient wallet. Only 'Paypal' is supported." |
| Default value | Empty or blank values default to "Paypal". | N/A |
Use "Paypal" (or leave the value empty so it defaults):
// Valid recipient wallet
PayoutSubmissionComponentConfig(
recipientWallet = "Paypal" // Valid (case-sensitive)
)
PayoutSubmissionComponentConfig(
recipientWallet = "" // Valid: empty or blank defaults to "Paypal"
)
// Invalid recipient wallet
PayoutSubmissionComponentConfig(
recipientWallet = "Venmo" // Not a supported value
)
PayoutSubmissionComponentConfig(
recipientWallet = "paypal" // Invalid: case-sensitive (must be "Paypal")
)Use these codes when diagnosing validation failures:
| Error code | Description | Solution |
|---|---|---|
PO02 | The transaction amount should be greater than 0. | Provide a positive amount value. |
PO03 | The currency code is invalid. | Use a valid 3-letter ISO currency code. |
PO04 | The recipient is invalid. | Ensure paypalWallet.email and paypalWallet.payerId are provided correctly. |
PO07 | The merchant transaction date is invalid. | Use ISO 8601 format (e.g., 2025-10-28T10:00:00Z). |
Validate data before SDK initialisation:
fun validatePayoutData(amount: Double, currency: String): ValidationResult {
return when {
amount <= 0 -> ValidationResult(
isValid = false,
message = "Amount must be greater than zero"
)
currency.length != 3 -> ValidationResult(
isValid = false,
message = "Currency must be 3-letter ISO code"
)
else -> ValidationResult(isValid = true)
}
}
// Use validation before initialisation
val validation = validatePayoutData(amount, currency)
if (!validation.isValid) {
showError(validation.message)
return
}
// Proceed with SDK initialisation
val pxpCheckout = PxpCheckout.builder()
.withConfig(config)
.build()Show user-friendly error messages:
onError = { error ->
val userMessage = when (error.errorCode) {
"PO02" -> "The payout amount must be greater than zero."
"PO03" -> "Please specify a valid currency."
"PO04" -> "Please verify your PayPal account information."
"PO07" -> "Invalid transaction date."
else -> "An error occurred: ${error.errorReason}"
}
showError(userMessage)
}Implement comprehensive error logging:
onError = { error ->
// Log for debugging
Log.e("Payout", """
Validation error occurred:
Code: ${error.errorCode}
Reason: ${error.errorReason}
HTTP Status: ${error.httpStatusCode}
Correlation ID: ${error.correlationId}
""".trimIndent())
// Track in analytics
trackEvent("payout_validation_error", mapOf(
"errorCode" to error.errorCode,
"errorReason" to error.errorReason
))
// Show user-friendly message
showError(getUserFriendlyMessage(error))
}Perform custom validation before payout:
onPrePayoutSubmit = {
// Validate balance
val balance = getUserBalance()
if (balance < payoutAmount) {
showError("Insufficient balance. Available: $$balance")
return@PayoutSubmissionComponentConfig PrePayoutSubmitResult(isApproved = false)
}
// Validate daily limit
val dailyTotal = getTodayPayoutTotal()
if (dailyTotal + payoutAmount > DAILY_LIMIT) {
showError("Daily payout limit exceeded")
return@PayoutSubmissionComponentConfig PrePayoutSubmitResult(isApproved = false)
}
// Validate minimum payout
if (payoutAmount < MINIMUM_PAYOUT) {
showError("Minimum payout amount is $$MINIMUM_PAYOUT")
return@PayoutSubmissionComponentConfig PrePayoutSubmitResult(isApproved = false)
}
// All validations passed
PrePayoutSubmitResult(isApproved = true)
}Implement your own business rules:
data class PayoutValidationRules(
val minimumAmount: Double = 10.0,
val maximumAmount: Double = 10000.0,
val dailyLimit: Double = 5000.0,
val requiredVerificationLevel: Int = 2
)
fun validatePayout(
amount: Double,
customerVerificationLevel: Int,
todayTotal: Double
): ValidationResult {
val rules = PayoutValidationRules()
return when {
amount < rules.minimumAmount -> ValidationResult(
isValid = false,
message = "Minimum payout is $${rules.minimumAmount}"
)
amount > rules.maximumAmount -> ValidationResult(
isValid = false,
message = "Maximum payout is $${rules.maximumAmount}"
)
todayTotal + amount > rules.dailyLimit -> ValidationResult(
isValid = false,
message = "Daily limit of $${rules.dailyLimit} would be exceeded"
)
customerVerificationLevel < rules.requiredVerificationLevel -> ValidationResult(
isValid = false,
message = "Account verification required for payouts"
)
else -> ValidationResult(isValid = true)
}
}