Skip to content

Data validation

Learn about validation requirements for PayPal payout data in your Android app.

Overview

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 stages

Validation occurs at three key stages:

  1. SDK initialisation: Validates transaction data and configuration.
  2. Component creation: Validates component-specific configuration.
  3. Payout submission: Validates wallet details and payout parameters before sending to the backend.

Transaction data validation

Amount validation

The amount must meet these rules before you initialise the SDK:

RuleDescriptionError
Amount requiredThe amount must be provided.Validation error.
Positive valueThe amount must be greater than zero.PO02: "Transaction amount should be greater than 0."
Numeric valueThe 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
)

Currency validation

The currency must meet these rules:

RuleDescriptionError
Currency requiredThe currency must be provided.Validation error.
FormatThe currency must be a valid 3-letter ISO currency code.PO03: "Invalid currency code".
SupportedThe 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
)

Entry type validation

Set entryType to EntryType.Ecom for payouts. The payout request the SDK builds uses an e-commerce entry type.

RuleDescriptionGuidance
Recommended valueUse 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
)

Intent validation

The intent must identify the transaction as a payout:

RuleDescriptionError
Intent requiredThe intent must be provided.Error during initialisation.
ValueMust 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
)

Wallet data validation

PayPal wallet validation

For the withdrawal flow, the PayPal wallet must include a valid email and payer ID:

RuleDescriptionError
Email requiredThe PayPal email must be provided for the withdrawal flow.PO04: "Receiver cannot be empty".
PayerId requiredThe PayPal payer ID must be provided for the withdrawal flow.PO04: "Payer ID is required for PayPal wallet payout".
Email formatThe 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
        )
    )
)

Component validation

Recipient wallet validation

The submission component validates recipientWallet as follows:

RuleDescriptionError
Supported valuesOnly "Paypal" is currently supported (case-sensitive).PO04: "Invalid recipient wallet. Only 'Paypal' is supported."
Default valueEmpty 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")
)

Validation error codes

Payout error codes

Use these codes when diagnosing validation failures:

Error codeDescriptionSolution
PO02The transaction amount should be greater than 0.Provide a positive amount value.
PO03The currency code is invalid.Use a valid 3-letter ISO currency code.
PO04The recipient is invalid.Ensure paypalWallet.email and paypalWallet.payerId are provided correctly.
PO07The merchant transaction date is invalid.Use ISO 8601 format (e.g., 2025-10-28T10:00:00Z).

Validation best practices

Validate early

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()

Provide clear error messages

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)
}

Log validation errors

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))
}

Handle validation in onPrePayoutSubmit

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)
}

Custom validation rules

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)
    }
}