Troubleshooting

Learn how to fix common issues with the payout components.

Common issues

Issue	Description	Next steps
Payout button not rendering.	The submission button doesn't appear in the container.	Verify that the container ID exists in the DOM. Check that `recipientWallet` is specified (`Paypal` or `Venmo`). Ensure that `paypalConfig` is provided in SDK initialisation. Confirm that the component is properly mounted.
"PayPal configuration is required" error.	SDK throws `SDK1000` error on component creation.	Add `paypalConfig` with `payoutConfig` to your SDK initialisation. Ensure `transactionData.intent.paypal` is set to `IntentType.Payout`.
"Payer ID required" error.	SDK throws `SDK0809` error during payout submission.	For returning customers: Ensure `paypalWallet.payerId` or `paypalWallet.email` is provided. Verify that `onAccountVerified` callback stores the account details correctly.
Venmo payout fails with currency error.	SDK throws `SDK0905` error.	Venmo only supports USD currency. Change `transactionData.currency` to `"USD"`. For non-USD payouts, use PayPal instead of Venmo.
Invalid email format error.	SDK throws `SDK0808` error.	Verify the PayPal email is correctly formatted. Check for leading/trailing whitespace in the email. Ensure the email doesn't contain special characters that aren't valid.
Invalid phone format error.	SDK throws `SDK0904` for Venmo phone payouts.	Phone numbers must contain only numeric characters. Remove dashes, spaces, and parentheses from the phone number. Include the country code if required.
Amount validation errors.	SDK throws `SDK0810`, `SDK0811`, or `SDK0812`.	Ensure `transactionData.amount` is a positive number greater than zero. Verify the amount is a valid numeric type (not a string). Check that the amount is provided in the SDK configuration.
Receiver masking not working.	Email/phone always shows masked or unmasked.	Check `showMaskToggle` configuration. When `showMaskToggle` is `false`, verify `applyMask` (PayPal) or `applyEmailMask`/`applyPhoneMask` (Venmo) settings. Note: Venmo handles (UserHandle) cannot be masked.
Payout note too long warning.	SDK logs a console warning about note length.	Notes longer than 4000 characters will be automatically truncated. The note is provided via `onPrePayoutSubmit` callback.
onPostPayout not being called.	Payout completes but callback doesn't fire.	Ensure `proceedPayoutWithSdk` is set to `true`. When `proceedPayoutWithSdk` is `false`, the SDK doesn't execute the payout — your backend must handle it. Check that `onPrePayoutSubmit` returns `{ isApproved: true }`.
Component styles not applying.	Custom styles are ignored.	Verify the `styles` object structure matches the expected format. Check that CSS property names use camelCase (e.g., `backgroundColor` not `background-color`). Ensure style values are strings (e.g., `"16px"` not `16`).

SDK initialisation issues

Missing or invalid configuration

Ensure your SDK initialisation includes all required payout configuration:

const pxpCheckoutSdk = PxpCheckout.initialize({
  environment: "test",  // or "production"
  session: sessionData,
  ownerId: "Unity",
  ownerType: "MerchantGroup",
  transactionData: {
    amount: 100,           // Required: must be > 0
    currency: "USD",       // Required: 3-letter ISO code
    entryType: "Ecom",
    intent: {
      paypal: IntentType.Payout  // Required for payouts
    },
    merchantTransactionId: crypto.randomUUID(),
    merchantTransactionDate: () => new Date().toISOString()
  },
  paypalConfig: {          // Required for payout components
    payoutConfig: {
      proceedPayoutWithSdk: true,  // or false for merchant-initiated
      // For returning customers:
      paypalWallet: {
        email: "customer@example.com",
        payerId: "PAYER_ID_XXX"    // Optional but recommended
      }
      // OR for Venmo:
      // venmoWallet: {
      //   receiver: "+14155551234",
      //   recipientType: "Phone"
      // }
    }
  }
});

Environment mismatch

Ensure your environment setting matches your credentials:

test: Development and testing with sandbox credentials.
production: Live transactions with production credentials.

// For development
environment: "test"

// For production
environment: "production"

Payout execution issues

SDK-initiated vs merchant-initiated

Understand the difference between payout modes:

Mode	`proceedPayoutWithSdk`	Behaviour
SDK-initiated	`true`	SDK executes payout after user approval. `onPostPayout` is called.
Merchant-initiated	`false`	SDK collects data only. Your backend must call the payout API.

// SDK-initiated: SDK handles everything
payoutConfig: {
  proceedPayoutWithSdk: true,
  paypalWallet: { email: "customer@example.com" }
}

// Merchant-initiated: You control payout execution
payoutConfig: {
  proceedPayoutWithSdk: false,
  paypalWallet: { email: "customer@example.com" }
}

Approval callback not working

If onPrePayoutSubmit isn't being called or payout proceeds without approval:

onPrePayoutSubmit: async () => {
  console.log("onPrePayoutSubmit called");  // Debug log
  
  // Show confirmation dialog
  const approved = await showConfirmationDialog();
  
  console.log("User approved:", approved);  // Debug log
  
  // Must return an object with isApproved
  return { 
    isApproved: approved,
    note: "Optional note"
  };
}

Always return an object with isApproved from onPrePayoutSubmit. Returning undefined or not returning anything may cause unexpected behaviour.

Receiver component issues

PayPal email not displaying

If the PayPal receiver component shows no email:

Verify paypalConfig.payoutConfig.paypalWallet.email is provided.
Check that the email value is a non-empty string.
Ensure the component is mounted after SDK initialisation completes.

Venmo receiver type mismatch

Ensure the recipientType matches the receiver format:

Receiver format	Required `recipientType`
`user@example.com`	`"Email"`
`+14155551234`	`"Phone"`
`@username`	`"UserHandle"`

// Email example
venmoWallet: {
  receiver: "user@example.com",
  recipientType: "Email"
}

// Phone example
venmoWallet: {
  receiver: "14155551234",  // Numbers only
  recipientType: "Phone"
}

// Handle example
venmoWallet: {
  receiver: "@john-doe",
  recipientType: "UserHandle"
}

Debugging tips

Enable console logging

Add logging to track the payout flow:

const payoutConfig = {
  onClick: (event) => {
    console.log("[Payout] Button clicked");
  },
  
  onPrePayoutSubmit: async () => {
    console.log("[Payout] Pre-submit validation");
    return { isApproved: true };
  },
  
  onPostPayout: (result) => {
    console.log("[Payout] Success:", result);
  },
  
  onError: (error) => {
    console.error("[Payout] Error:", error.ErrorCode, error.message);
  }
};

Verify session data

Ensure session data is valid and not expired:

async function initializePayoutSdk() {
  const sessionData = await getSessionDataFromBackend();
  
  // Debug: Log session data
  console.log("Session data:", {
    sessionId: sessionData.sessionId,
    expiry: sessionData.sessionExpiry,
    hasHmacKey: !!sessionData.hmacKey,
    hasEncryptionKey: !!sessionData.encryptionKey
  });
  
  // Check if session is expired
  if (new Date(sessionData.sessionExpiry) < new Date()) {
    console.error("Session has expired!");
    // Request a new session
    return;
  }
  
  // Proceed with SDK initialisation
  const sdk = PxpCheckout.initialize({
    session: sessionData,
    // ... rest of config
  });
}