Skip to content
Components/
/
/
Confirm payment flow

Confirm payment flow

Authorise a payment, then capture it before it expires on Android.

Overview

The confirm payment flow is designed for scenarios where you need to authorise payment first, then capture it after additional confirmation steps, making it ideal for complex orders, inventory checks, or when manual review is required.

If the funds aren't captured within the appropriate time limit (29 days), then the authorisation expires.

Payment flow

The PayPal confirm payment flow consists of six key steps with authorisation and capture separation.

Step 1: Submission

The customer taps the PayPal button, which triggers the payment flow. The SDK validates the PayPal configuration and transaction data before proceeding to order creation. If validation fails, onError is triggered.

Step 2: Order creation

The SDK creates a PayPal order using the provided transaction details. This involves sending the payment amount, currency, merchant information, and any additional order details to PayPal's API for authorisation. If order creation fails, onError is triggered.

Step 3: PayPal approval

The customer is redirected to PayPal (via WebView) where they log in and approve the payment authorisation. PayPal handles all authentication and payment method selection within their secure environment.

This step has three associated callbacks:

  • onSuccess: Proceeds with payment authorisation if the customer successfully approves it.
  • onCancel: Cancels the transaction if the customer cancels the payment.
  • onError: Receives error data if any error occurs during the approval process.

Step 4: Return to merchant

After PayPal approval, the customer returns to your app with the authorised payment. The funds are authorised but not yet captured, giving you the opportunity to show order confirmation. This happens within your onSuccess callback handler where you typically navigate to a confirmation screen.

Step 5: Order confirmation

The customer reviews their final order details on your confirmation screen. This is where you can perform final inventory checks, calculate shipping, or apply additional discounts.

Step 6: Payment capture

Once the customer confirms their order, you capture the authorised payment. This is when the funds are actually transferred from the customer's account.

Your capture API call will return a success or failure response, which you handle in your backend code.

Implementation

Before you start

To use the PayPal confirm payment flow in your Android application:

  1. Ensure you have a valid PayPal Business account with API credentials.
  2. Configure your PayPal merchant account to accept the currencies you need.
  3. Set up your merchant configuration in the Unity Portal (API credentials, payment methods, risk settings).
  4. Prepare order confirmation screens for the authorisation-to-capture flow.
  5. Install and configure the PXP Checkout SDK for Android.

Step 1: Configure your SDK for authorisation

Set up your SDK configuration with transaction information for a PayPal authorisation. The SDK uses IntentType.Authorisation for authorisation requests, which PayPal maps to its authorize intent. For capturing funds, use IntentType.Purchase, which maps to PayPal's capture intent.

Intent Mapping: The SDK uses IntentType.Authorisation for authorisation requests, which PayPal maps to its "authorize" intent. For capturing funds, use IntentType.Purchase, which maps to PayPal's "capture" intent.

import com.pxp.checkout.PxpCheckout
import com.pxp.checkout.models.Environment
import com.pxp.checkout.models.OwnerType
import com.pxp.checkout.models.TransactionData
import com.pxp.checkout.models.EntryType
import com.pxp.checkout.models.IntentType
import com.pxp.checkout.models.CurrencyType
import com.pxp.checkout.models.Shopper
import com.pxp.checkout.models.ShippingAddress

// FIRST INTENT: Authorisation
val authPxpCheckout = PxpCheckout.builder()
    .withConfig(
        PxpCheckoutConfig(
            environment = Environment.TEST,
            session = sessionData,
            ownerId = "Unity",
            ownerType = OwnerType.MERCHANT_GROUP,
            transactionData = TransactionData(
                amount = 2500.0, // Amount in cents ($25.00)
                currency = "USD",
                entryType = EntryType.Ecom,
                intent = IntentType.Authorisation, // FIRST INTENT - for authorisation
                merchantTransactionId = "auth-${System.currentTimeMillis()}",
                merchantTransactionDate = { System.currentTimeMillis() }
            ),
            onGetShopper = {
                Shopper(
                    id = "Shopper_01",
                    email = "customer@example.com",
                    firstName = "John",
                    lastName = "Doe"
                )
            },
            onGetShippingAddress = {
                ShippingAddress(
                    addressLine1 = "123 Main Street",
                    city = "New York",
                    state = "NY",
                    postalCode = "10001",
                    countryCode = "US"
                )
            }
        )
    )
    .withContext(context)
    .build()

Step 2: Implement authorisation callbacks

Implement the required callbacks for the PayPal confirm payment flow.

import com.pxp.checkout.components.paypal.PayPalComponentConfig
import com.pxp.checkout.components.paypal.types.ShippingPreference
import com.pxp.checkout.components.paypal.types.UserAction
import org.json.JSONObject
import android.util.Log
import kotlinx.coroutines.launch

val paypalConfig = PayPalComponentConfig(
    // Required PayPal configuration
    payeeEmailAddress = "merchant@example.com",
    paymentDescription = "Product Purchase",
    shippingPreference = ShippingPreference.NoShipping.toString(),
    userAction = UserAction.Continue.toString(), // For authorisation + confirmation flow
    renderType = "standalone",
    fundingSources = "paypal",

    // REQUIRED: Handle successful payment authorisation
    onSuccess = { data ->
        Log.d("PayPal", "Payment authorised: $data")
        
        viewModelScope.launch {
            try {
                // Parse authorisation data
                val jsonObject = JSONObject(data)
                val orderID = jsonObject.getString("orderID")
                val payerID = jsonObject.getString("payerID")
                
                // Store authorisation details
                val authResult = repository.storePayPalAuthorization(
                    orderID = orderID,
                    payerID = payerID,
                    merchantTransactionId = transactionId,
                    status = "authorized"
                )
                
                if (authResult.isSuccess) {
                    Log.d("PayPal", "Authorisation stored successfully")
                    
                    // Save to preferences for confirmation screen
                    saveAuthorizationData(
                        orderID = orderID,
                        payerID = payerID,
                        authorizedAmount = transactionData.amount,
                        currency = transactionData.currency.toString()
                    )
                    
                    // Navigate to confirmation screen instead of completing payment
                    navController.navigate("order_confirmation/$orderID")
                } else {
                    throw Exception(authResult.error ?: "Authorisation storage failed")
                }
            } catch (e: Exception) {
                Log.e("PayPal", "Authorisation processing error", e)
                showError("Authorisation failed. Please try again.")
            }
        }
    },

    // REQUIRED: Handle payment errors
    onError = { error ->
        Log.e("PayPal", "Payment error: $error")
        showError("Authorisation failed. Please try again.")
    },

    // OPTIONAL: Handle payment cancellation
    onCancel = {
        Log.d("PayPal", "Payment cancelled by user")
        showMessage("Payment was cancelled. Your cart is still saved.")
    }
)

Step 3: Render the authorisation component

Create and render the PayPal component for the authorisation step.

import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.foundation.layout.fillMaxWidth
import com.pxp.checkout.types.ComponentType

@Composable
fun PayPalAuthorizationScreen(
    authPxpCheckout: PxpCheckout,
    paypalConfig: PayPalComponentConfig
) {
    val paypalComponent = remember {
        authPxpCheckout.createComponent(
            type = ComponentType.PAYPAL,
            config = paypalConfig
        )
    }
    
    authPxpCheckout.buildComponentView(
        component = paypalComponent,
        modifier = Modifier.fillMaxWidth()
    )
}

Step 4: Handle order confirmation screen

Create a separate flow for handling the order confirmation and proceeding with the final capture.

import androidx.compose.foundation.layout.*
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.unit.dp

@Composable
fun OrderConfirmationScreen(
    orderID: String,
    viewModel: PaymentViewModel
) {
    var showLoadingSpinner by remember { mutableStateOf(false) }
    var showSuccessDialog by remember { mutableStateOf(false) }
    var showErrorDialog by remember { mutableStateOf(false) }
    var errorMessage by remember { mutableStateOf<String?>(null) }
    
    // Retrieve authorisation data
    val authData = remember { viewModel.getAuthorizationData(orderID) }
    
    Column(
        modifier = Modifier
            .fillMaxSize()
            .padding(16.dp),
        verticalArrangement = Arrangement.spacedBy(16.dp)
    ) {
        Text(
            text = "Confirm Your Order",
            style = MaterialTheme.typography.headlineMedium
        )
        
        // Display order details
        Card(
            modifier = Modifier.fillMaxWidth()
        ) {
            Column(modifier = Modifier.padding(16.dp)) {
                Text("Order ID: $orderID")
                Text("Amount: $${authData.authorizedAmount / 100.0}")
                Text("Currency: ${authData.currency}")
            }
        }
        
        // Confirm button
        Button(
            onClick = {
                showLoadingSpinner = true
                viewModel.captureAuthorizedPayment(
                    orderID = orderID,
                    onSuccess = {
                        showLoadingSpinner = false
                        showSuccessDialog = true
                    },
                    onError = { error ->
                        showLoadingSpinner = false
                        errorMessage = error
                        showErrorDialog = true
                    }
                )
            },
            modifier = Modifier.fillMaxWidth(),
            enabled = !showLoadingSpinner
        ) {
            if (showLoadingSpinner) {
                CircularProgressIndicator(
                    modifier = Modifier.size(24.dp),
                    color = MaterialTheme.colorScheme.onPrimary
                )
            } else {
                Text("Confirm and Pay")
            }
        }
    }
    
    // Success dialog
    if (showSuccessDialog) {
        AlertDialog(
            onDismissRequest = { },
            title = { Text("Payment Successful") },
            text = { Text("Your payment has been captured successfully!") },
            confirmButton = {
                Button(onClick = {
                    showSuccessDialog = false
                    // Navigate to success screen
                }) {
                    Text("OK")
                }
            }
        )
    }
    
    // Error dialog
    if (showErrorDialog) {
        AlertDialog(
            onDismissRequest = { },
            title = { Text("Payment Error") },
            text = { Text(errorMessage ?: "An error occurred") },
            confirmButton = {
                Button(onClick = { showErrorDialog = false }) {
                    Text("OK")
                }
            }
        )
    }
}

Step 5: Implement payment capture

Implement the capture logic in your ViewModel or repository.

class PaymentViewModel : ViewModel() {
    
    suspend fun captureAuthorizedPayment(
        orderID: String,
        onSuccess: (CaptureResult) -> Unit,
        onError: (String) -> Unit
    ) {
        viewModelScope.launch {
            try {
                // Retrieve authorisation data
                val authData = getAuthorizationData(orderID)
                
                // Perform final checks (inventory, pricing, etc.)
                val orderValid = validateOrder(orderID)
                if (!orderValid) {
                    throw Exception("Order validation failed")
                }
                
                // Calculate the final amount (may include shipping, taxes, discounts)
                val finalAmount = calculateFinalAmount(orderID)
                
                // Create new SDK configuration for capture
                val capturePxpCheckout = PxpCheckout.builder()
                    .withConfig(
                        PxpCheckoutConfig(
                            environment = Environment.TEST,
                            session = sessionData,
                            ownerId = "Unity",
                            ownerType = OwnerType.MERCHANT_GROUP,
                            transactionData = TransactionData(
                                amount = finalAmount.toDouble(), // Final amount
                                currency = authData.currency,
                                entryType = EntryType.Ecom,
                                intent = IntentType.Purchase, // SECOND INTENT - for capture
                                merchantTransactionId = "capture-${System.currentTimeMillis()}",
                                merchantTransactionDate = { System.currentTimeMillis() },
                                parentTransactionId = authData.merchantTransactionId // Link to authorisation
                            ),
                            onGetShopper = {
                                Shopper(
                                    id = "Shopper_01",
                                    email = "customer@example.com",
                                    firstName = "John",
                                    lastName = "Doe"
                                )
                            },
                            onGetShippingAddress = {
                                ShippingAddress(
                                    addressLine1 = "123 Main Street",
                                    city = "New York",
                                    state = "NY",
                                    postalCode = "10001",
                                    countryCode = "US"
                                )
                            }
                        )
                    )
                    .withContext(getApplication())
                    .build()
                
                // Execute the capture
                val captureResult = repository.capturePayPalPayment(
                    orderID = authData.orderID,
                    payerID = authData.payerID,
                    captureAmount = finalAmount
                )
                
                if (captureResult.status == "COMPLETED") {
                    Log.d("PayPal", "Payment captured successfully")
                    
                    // Store capture confirmation
                    saveCaptureData(
                        captureID = captureResult.captureID,
                        transactionId = captureResult.transactionId,
                        amount = captureResult.amount,
                        status = "completed"
                    )
                    
                    onSuccess(captureResult)
                } else {
                    throw Exception("Payment capture failed: ${captureResult.status}")
                }
                
            } catch (e: Exception) {
                Log.e("PayPal", "Capture process failed", e)
                handleCaptureError(e, onError)
            }
        }
    }
    
    private fun handleCaptureError(error: Exception, onError: (String) -> Unit) {
        val errorMessage = when {
            error.message?.contains("AUTHORIZATION_EXPIRED") == true -> {
                "Payment authorisation has expired. Please start the payment process again."
            }
            error.message?.contains("INSUFFICIENT_FUNDS") == true -> {
                "Insufficient funds for final payment amount. Please try a different payment method."
            }
            error.message?.contains("CAPTURE_DECLINED") == true -> {
                "Payment capture was declined. Please contact your bank or try a different payment method."
            }
            error.message?.contains("INVALID_AUTHORIZATION") == true -> {
                "Authorisation is no longer valid. Please restart the payment process."
            }
            else -> {
                "Payment capture failed. Please contact support or try again."
            }
        }
        onError(errorMessage)
    }
}

Step 6: Handle common scenarios

Inventory validation

Validate inventory between authorisation and capture.

suspend fun validateInventoryForCapture(orderID: String): Boolean {
    return try {
        val inventoryCheck = repository.reserveInventory(
            orderID = orderID,
            items = getOrderItems(orderID),
            reservationDuration = 3600 // 1 hour reservation
        )
        
        if (inventoryCheck.success) {
            Log.d("PayPal", "Inventory reserved for capture")
            true
        } else {
            Log.w("PayPal", "Inventory not available: ${inventoryCheck.message}")
            showError("Some items are no longer available. Please review your order.")
            false
        }
    } catch (e: Exception) {
        Log.e("PayPal", "Inventory check failed", e)
        false
    }
}

Shipping calculation

Calculate final shipping costs during confirmation.

suspend fun calculateShippingAndTax(
    orderID: String,
    shippingAddress: ShippingAddress
): FinalCalculation {
    return try {
        val shippingResult = repository.calculateFinalShipping(
            orderID = orderID,
            shippingAddress = shippingAddress,
            items = getOrderItems(orderID)
        )
        
        if (shippingResult.success) {
            // Show final total including shipping
            FinalCalculation(
                subtotal = shippingResult.subtotal,
                shippingCost = shippingResult.shippingCost,
                tax = shippingResult.tax,
                total = shippingResult.total
            )
        } else {
            throw Exception("Shipping calculation failed")
        }
    } catch (e: Exception) {
        Log.e("PayPal", "Shipping calculation error", e)
        throw e
    }
}

Example

The following example shows a complete PayPal confirm payment implementation with two separate intents.

Phase 1: Authorisation (checkout screen)

import androidx.compose.foundation.layout.*
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.compose.ui.platform.LocalContext
import androidx.navigation.NavController
import com.pxp.checkout.PxpCheckout
import com.pxp.checkout.models.PxpCheckoutConfig
import com.pxp.checkout.models.TransactionData
import com.pxp.checkout.models.EntryType
import com.pxp.checkout.models.IntentType
import com.pxp.checkout.components.paypal.PayPalComponentConfig
import com.pxp.checkout.components.paypal.types.ShippingPreference
import com.pxp.checkout.components.paypal.types.UserAction
import com.pxp.checkout.components.paypal.types.PayPalButtonStyle
import com.pxp.checkout.types.ComponentType
import org.json.JSONObject
import android.util.Log
import kotlinx.coroutines.launch

@Composable
fun PayPalAuthorizationScreen(
    viewModel: PaymentViewModel,
    navController: NavController
) {
    var showLoadingSpinner by remember { mutableStateOf(false) }
    
    // FIRST INTENT: Authorisation
    val authPxpCheckout = remember {
        PxpCheckout.builder()
            .withConfig(
                PxpCheckoutConfig(
                    transactionData = TransactionData(
                        amount = 2500.0,
                        currency = "USD",
                        entryType = EntryType.Ecom,
                        intent = IntentType.Authorisation, // FIRST INTENT - for authorisation
                        merchantTransactionId = "auth-${System.currentTimeMillis()}",
                        merchantTransactionDate = { System.currentTimeMillis() }
                    )
                )
            )
            .withContext(LocalContext.current)
            .build()
    }
    
    val paypalConfig = remember {
        PayPalComponentConfig(
            // PayPal configuration for authorisation flow
            payeeEmailAddress = "merchant@example.com",
            paymentDescription = "Product Purchase - Review Order",
            shippingPreference = ShippingPreference.NoShipping.toString(),
            userAction = UserAction.Continue.toString(), // Authorisation + confirmation flow
            renderType = "standalone",
            fundingSources = "paypal",
            
            // Styling
            style = PayPalButtonStyle(
                layout = "vertical",
                color = "gold",
                shape = "rect",
                label = "paypal"
            ),

            // Step 1: Handle payment authorisation
            onSuccess = { data ->
                Log.d("PayPal", "Processing PayPal authorisation")
                showLoadingSpinner = true
                
                viewModelScope.launch {
                    try {
                        val jsonObject = JSONObject(data)
                        val orderID = jsonObject.getString("orderID")
                        val payerID = jsonObject.getString("payerID")
                        
                        Log.d("PayPal", "Order ID: $orderID")
                        Log.d("PayPal", "Authorised Amount: $${2500 / 100.0}")
                        
                        // Store authorisation data for capture step
                        viewModel.saveAuthorizationData(
                            orderID = orderID,
                            payerID = payerID,
                            merchantTransactionId = "auth-${System.currentTimeMillis()}",
                            authorizedAmount = 2500,
                            currency = "USD"
                        )
                        
                        showLoadingSpinner = false
                        
                        // Navigate to confirmation screen
                        navController.navigate("order_confirmation/$orderID")
                        
                    } catch (e: Exception) {
                        Log.e("PayPal", "Authorisation failed", e)
                        showLoadingSpinner = false
                        showError("Authorisation failed: ${e.message}")
                    }
                }
            },

            onCancel = {
                Log.d("PayPal", "PayPal authorisation cancelled by user")
                showMessage("Payment was cancelled. Your cart is still saved.")
            },

            onError = { error ->
                Log.e("PayPal", "PayPal authorisation error: $error")
                showLoadingSpinner = false
                showError("Authorisation failed. Please try again.")
            }
        )
    }
    
    val paypalComponent = remember(paypalConfig) {
        authPxpCheckout.createComponent(
            type = ComponentType.PAYPAL,
            config = paypalConfig
        )
    }

    Column(
        modifier = Modifier
            .fillMaxSize()
            .padding(16.dp),
        verticalArrangement = Arrangement.spacedBy(16.dp)
    ) {
        Text(
            text = "Authorize Payment",
            style = MaterialTheme.typography.headlineMedium
        )
        
        Text(
            text = "Amount: $25.00",
            style = MaterialTheme.typography.titleMedium
        )
        
        // Mount the authorisation component
        authPxpCheckout.buildComponentView(
            component = paypalComponent,
            modifier = Modifier.fillMaxWidth()
        )
        
        if (showLoadingSpinner) {
            CircularProgressIndicator()
        }
    }
}

Phase 2: Capture (confirmation screen)

import androidx.compose.foundation.layout.*
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.compose.ui.platform.LocalContext
import androidx.navigation.NavController
import com.pxp.checkout.PxpCheckout
import com.pxp.checkout.models.PxpCheckoutConfig
import com.pxp.checkout.models.TransactionData
import com.pxp.checkout.models.EntryType
import com.pxp.checkout.models.IntentType
import android.util.Log
import kotlinx.coroutines.launch

@Composable
fun PayPalCaptureScreen(
    orderID: String,
    viewModel: PaymentViewModel,
    navController: NavController
) {
    var showLoadingSpinner by remember { mutableStateOf(false) }
    var showSuccessDialog by remember { mutableStateOf(false) }
    var showErrorDialog by remember { mutableStateOf(false) }
    var errorMessage by remember { mutableStateOf<String?>(null) }
    
    val authData = remember { viewModel.getAuthorizationData(orderID) }
    
    // SECOND INTENT: Capture
    suspend fun captureAuthorizedPayment() {
        try {
            showLoadingSpinner = true
            
            // Calculate final amount (may be different due to shipping, taxes, etc.)
            val finalAmount = viewModel.calculateFinalAmount(orderID) // e.g., 2750 ($27.50 with shipping)
            
            // Create NEW SDK configuration for capture
            val capturePxpCheckout = PxpCheckout.builder()
                .withConfig(
                    PxpCheckoutConfig(
                        transactionData = TransactionData(
                            amount = finalAmount.toDouble(), // Final amount
                            currency = authData.currency,
                            entryType = EntryType.Ecom,
                            intent = IntentType.Purchase, // SECOND INTENT - for capture
                            merchantTransactionId = "capture-${System.currentTimeMillis()}",
                            merchantTransactionDate = { System.currentTimeMillis() },
                            parentTransactionId = authData.merchantTransactionId // Link to authorisation
                        )
                    )
                )
                .withContext(LocalContext.current)
                .build()
            
            // Execute the capture
            val captureResult = viewModel.repository.capturePayPalAuthorization(
                authorizationOrderID = authData.orderID,
                payerID = authData.payerID,
                captureAmount = finalAmount
            )
            
            showLoadingSpinner = false
            
            if (captureResult.status == "COMPLETED") {
                Log.d("PayPal", "Payment captured successfully")
                Log.d("PayPal", "Captured Amount: $${captureResult.amount / 100.0}")
                
                // Store capture confirmation
                viewModel.saveCaptureData(
                    captureID = captureResult.captureID,
                    transactionId = captureResult.transactionId,
                    amount = captureResult.amount,
                    status = "completed"
                )
                
                showSuccessDialog = true
            } else {
                throw Exception("Capture failed: ${captureResult.status}")
            }
            
        } catch (e: Exception) {
            Log.e("PayPal", "Capture process failed", e)
            showLoadingSpinner = false
            
            errorMessage = when {
                e.message?.contains("AUTHORIZATION_EXPIRED") == true -> {
                    "Authorisation expired. Please restart payment."
                }
                else -> {
                    "Payment capture failed. Please contact support."
                }
            }
            showErrorDialog = true
        }
    }
    
    Column(
        modifier = Modifier
            .fillMaxSize()
            .padding(16.dp),
        verticalArrangement = Arrangement.spacedBy(16.dp)
    ) {
        Text(
            text = "Confirm Your Order",
            style = MaterialTheme.typography.headlineMedium
        )
        
        Card(modifier = Modifier.fillMaxWidth()) {
            Column(modifier = Modifier.padding(16.dp)) {
                Text("Order ID: $orderID")
                Text("Authorised: $${authData.authorizedAmount / 100.0}")
            }
        }
        
        Button(
            onClick = { 
                viewModelScope.launch { 
                    captureAuthorizedPayment() 
                } 
            },
            modifier = Modifier.fillMaxWidth(),
            enabled = !showLoadingSpinner
        ) {
            if (showLoadingSpinner) {
                CircularProgressIndicator(modifier = Modifier.size(24.dp))
            } else {
                Text("Confirm and Pay")
            }
        }
    }
    
    // Success/Error dialogs...
}

Callback data

This section describes the data received by the different callbacks as part of the PayPal confirm payment flow.

onSuccess

The onSuccess callback receives payment approval data when the customer successfully approves the payment in PayPal. The approval data includes the PayPal order ID and payer information needed to capture the payment.

{
  "orderID": "7YH53119ML8957234",
  "payerID": "ABCDEFGHIJKLM",
  "paymentID": "PAYID-ABCDEFG",
  "billingToken": null,
  "facilitatorAccessToken": "A21AAFExi..."
}
ParameterDescription
orderID
String
required		The unique PayPal order ID that identifies this payment.
payerID
String
required		The unique PayPal payer ID that identifies the customer who approved the payment.
paymentID
String		The PayPal payment ID for this transaction.
billingToken
String?		The billing agreement token if applicable, otherwise null.
facilitatorAccessToken
String		The PayPal facilitator access token for processing the payment.

Here's an example of what to do with this data:

onSuccess = { data ->
    Log.d("PayPal", "Payment approved: $data")
    
    try {
        // Parse the payment data
        val jsonObject = JSONObject(data)
        val orderID = jsonObject.getString("orderID")
        val payerID = jsonObject.getString("payerID")
        
        // Capture the payment immediately for pay now flow
        viewModelScope.launch {
            val captureResponse = repository.capturePayPalPayment(
                orderID = orderID,
                payerID = payerID,
                merchantTransactionId = generateTransactionId(),
                timestamp = System.currentTimeMillis()
            )
            
            if (captureResponse.status == "COMPLETED") {
                // Payment captured successfully
                Log.d("PayPal", "Payment captured: ${captureResponse.id}")
                
                // Store transaction record
                database.insertTransaction(
                    Transaction(
                        paypalOrderId = orderID,
                        paypalPayerId = payerID,
                        transactionId = captureResponse.id,
                        amount = captureResponse.amount,
                        currency = captureResponse.currency,
                        status = "completed",
                        timestamp = System.currentTimeMillis()
                    )
                )
                
                // Navigate to success
                navController.navigate("success/$orderID")
            } else {
                throw Exception("Payment capture failed: ${captureResponse.status}")
            }
        }
    } catch (e: Exception) {
        Log.e("PayPal", "Payment capture error", e)
        showError("Payment processing failed. Please contact support.")
    }
}

onError

The onError callback receives error information when PayPal payments fail. PayPal errors include specific error names and details to help with troubleshooting.

{
  "name": "VALIDATION_ERROR",
  "message": "Invalid payment method",
  "details": [{
    "issue": "INSTRUMENT_DECLINED",
    "description": "The instrument presented was either declined by the processor or bank, or it can't be used for this payment."
  }]
}
ParameterDescription
name
String		The error name.

Possible values:
  • VALIDATION_ERROR
  • INSTRUMENT_DECLINED
  • PAYER_ACTION_REQUIRED
  • UNPROCESSABLE_ENTITY
message
String		A human-readable error message.

Here's an example of how to handle PayPal errors:

onError = { error ->
    Log.e("PayPal", "Payment error: $error")
    
    // Handle specific error types
    when {
        error.contains("VALIDATION_ERROR") -> {
            showErrorDialog(
                title = "Validation Error",
                message = "Payment information is invalid. Please try again."
            )
        }
        error.contains("INSTRUMENT_DECLINED") -> {
            showErrorDialog(
                title = "Payment Declined",
                message = "Your PayPal payment method was declined. Please try a different payment method."
            )
        }
        error.contains("PAYER_ACTION_REQUIRED") -> {
            showErrorDialog(
                title = "Action Required",
                message = "Additional verification required. Please complete the process in PayPal."
            )
        }
        error.contains("UNPROCESSABLE_ENTITY") -> {
            showErrorDialog(
                title = "Processing Error",
                message = "This payment cannot be processed. Please contact support."
            )
        }
        error.contains("INTERNAL_SERVICE_ERROR") -> {
            showErrorDialog(
                title = "Service Error",
                message = "PayPal service temporarily unavailable. Please try again later."
            )
        }
        else -> {
            showErrorDialog(
                title = "Payment Error",
                message = "Payment failed. Please try again or contact support."
            )
        }
    }
    
    // Log error details for monitoring
    analytics.track("paypal_payment_error", mapOf(
        "errorMessage" to error,
        "timestamp" to System.currentTimeMillis(),
        "paymentMethod" to "paypal"
    ))
}

onCancel

The onCancel callback receives no data when the customer cancels the PayPal payment process.

Here's an example of how to handle cancellations:

onCancel = {
    Log.d("PayPal", "Payment cancelled by user")
    
    // Log cancellation for analytics
    analytics.track("paypal_payment_cancelled", mapOf(
        "timestamp" to System.currentTimeMillis(),
        "paymentMethod" to "paypal"
    ))
    
    // Show user-friendly message
    showSnackbar("Payment was cancelled. Your cart items are still saved.")
    
    // Optional: Offer alternative payment methods
    showAlternativePaymentOptions()
}
©2025 PXP Financial. PXP Financial Registered Office: The Corn Mill - 1 Roydon Road - Stanstead Abbotts - Hertfordshire - SG12 8XL - United Kingdom Phone +44 2038850598. PXP Financial is Authorised By The Financial Conduct Authority And Our Financial Services Register Number is 504318.