Skip to content

Events

Implement callbacks to customise your PayPal and Venmo payout flow for Web.

Overview

Components emit events based on user interaction or validation. You can use these to implement callback functions, which allow you to inject your own business logic and user experience customisations into the payout flow at critical moments. They ensure that while the SDK handles the complex technical aspects of payout processing, you retain full control over the customer experience and can seamlessly integrate payouts into your broader business workflows and systems.

Callbacks enable you to:

  • Validate business rules before payouts proceed.
  • Display custom error, failure, or success messages.
  • Tailor user interfaces to match your brand's look and feel.
  • Integrate with your own systems for fraud detection or compliance checks.
  • Control exactly how your customers experience both successful and failed payouts.
  • Store customer wallet details for future payouts.
  • Signal your backend to run merchant-initiated payouts (proceedPayoutWithSdk: false) from onClick.

Available callbacks

These callbacks are available on the payout-submission component, used for returning customers with stored wallet details.

Only the submission components (payout-submission) supports event callbacks. The display components (payout-amount, paypal-payout-receiver, and venmo-payout-receiver) are configuration-only and don't emit events.

onClick

This callback is triggered when the customer clicks the withdrawal button. Wallet and amount validation already ran when you created the components.

You can use it to:

  • Track button click analytics.
  • Show loading indicators.
  • For merchant-initiated payouts (proceedPayoutWithSdk: false), signal your backend to call the payout API.

Example implementation

const submissionComponent = pxpCheckoutSdk.create("payout-submission", {
  recipientWallet: "Paypal",
  onClick: (event) => {
    console.log('Withdrawal button clicked');
    
    // Track button click
    trackEvent('payout-button-clicked', {
      walletType: 'paypal',
      timestamp: new Date().toISOString()
    });
    
    // Show loading indicator
    showLoadingState();
  }
});

onPrePayoutSubmit

This callback is triggered after the customer clicks the withdrawal button, when proceedPayoutWithSdk is true. Provide it for SDK-initiated payouts — without it, the SDK doesn't execute the payout. Show your own approval modal/UI and return the approval status.

You can use it to:

  • Display a confirmation dialog before proceeding.
  • Perform final validation before payout execution.
  • Check compliance requirements.
  • Verify sufficient balance.
  • Add a note to Venmo payouts (optional).

Return value

PropertyDescription
isApproved
boolean
required
Whether to proceed with the payout.
note
string
Included with Venmo payouts only (max 4000 characters; longer notes are truncated with a console warning).

Example implementation

const submissionComponent = pxpCheckoutSdk.create("payout-submission", {
  recipientWallet: "Paypal",
  onPrePayoutSubmit: async () => {
    console.log('Pre-payout submission triggered');
    
    try {
      // Show confirmation modal
      const confirmation = await showConfirmationModal({
        title: 'Confirm Withdrawal',
        message: `Are you sure you want to withdraw ${amount} ${currency}?`
      });
      
      if (!confirmation.confirmed) {
        return { isApproved: false };
      }
      
      // Check withdrawal limits
      const limitsCheck = await checkWithdrawalLimits({
        customerId: getCurrentCustomerId(),
        amount: amount,
        currency: currency
      });
      
      if (!limitsCheck.allowed) {
        showMessage(`Withdrawal limit exceeded. Maximum: ${limitsCheck.maxAmount} ${currency}`, 'error');
        return { isApproved: false };
      }
      
      // Verify sufficient balance
      const balanceCheck = await verifyBalance({ amount, currency });
      
      if (!balanceCheck.sufficient) {
        showMessage('Insufficient funds for this withdrawal.', 'error');
        return { isApproved: false };
      }
      
      // Approve (note is included with Venmo payouts only)
      return { 
        isApproved: true,
        note: recipientWallet === 'Venmo' ? 'Customer withdrawal request' : undefined
      };
      
    } catch (error) {
      console.error('Pre-payout check failed:', error);
      showMessage('Unable to process withdrawal. Please try again.', 'error');
      return { isApproved: false };
    }
  }
});

onPostPayout

This callback is triggered when the payout is successfully processed.

You can use it to:

  • Display success confirmation to the customer.
  • Update your internal records.
  • Send confirmation notifications.
  • Redirect to a success page.

Event data

ParameterDescription
result
object
The payout transaction result from PXP.

Example implementation

const submissionComponent = pxpCheckoutSdk.create("payout-submission", {
  recipientWallet: "Paypal",
  onPostPayout: async (result) => {
    console.log('Payout successful:', result);
    
    // Update customer balance in your system
    await updateCustomerBalance({
      customerId: getCurrentCustomerId(),
      amount: -result.amount,
      currency: result.currency,
      transactionId: result.transactionId,
      type: 'withdrawal'
    });
    
    // Store transaction record
    await storeTransaction({
      pxpTransactionId: result.transactionId,
      amount: result.amount,
      currency: result.currency,
      status: result.status,
      customerId: getCurrentCustomerId()
    });
    
    // Send confirmation email
    await sendPayoutConfirmationEmail({
      email: getCustomerEmail(),
      amount: result.amount,
      currency: result.currency,
      transactionId: result.transactionId
    });
    
    // Track successful payout
    trackEvent('payout-completed', {
      transactionId: result.transactionId,
      amount: result.amount,
      currency: result.currency,
      timestamp: new Date().toISOString()
    });
    
    // Show success message
    showMessage(`Withdrawal of ${result.amount} ${result.currency} processed successfully!`, 'success');
    
    // Redirect to success page
    setTimeout(() => {
      window.location.href = `/payout-success?txn=${result.transactionId}`;
    }, 2000);
  }
});

onError

This callback is triggered when an error occurs during payout processing.

You can use it to:

  • Display user-friendly error messages.
  • Log errors for debugging.
  • Offer retry options.
  • Show alternative payout methods.

Event data

ParameterDescription
error
object
The error object containing details about what went wrong.

Example implementation

const submissionComponent = pxpCheckoutSdk.create("payout-submission", {
  recipientWallet: "Paypal",
  onError: (error) => {
    console.error('Payout error:', error);
    
    // Log error for debugging
    logError('payout-error', {
      message: error.message,
      ErrorCode: error.ErrorCode,
      timestamp: new Date().toISOString(),
      userAgent: navigator.userAgent
    });
    
    // Display user-friendly message based on error
    showMessage('Withdrawal failed. Please try again or contact support.', 'error');
    
    // Track error
    trackEvent('payout-failed', {
      errorCode: error.ErrorCode,
      errorMessage: error.message,
      timestamp: new Date().toISOString()
    });
  }
});