Skip to content

PayPal

Withdraw funds to a linked PayPal account using a stored wallet association.

Overview

PayPal in Payout Drop-in is a stored-account flow. When the payout session allows PayPal and the authenticated shopper has an active PayPal wallet association, Drop-in shows the linked email and submits the payout to the linked payer ID. The panel uses that linked association; it doesn't run a PayPal login or OAuth popup.

Key benefits

This method gives you:

  • Stored relationship: Uses a PayPal account already linked for the shopper.
  • Simple panel UX: Shows the linked email (with optional mask toggle) and a submit control.
  • Unified outcomes: Uses Drop-in onSuccess and onError.
  • SDK-driven submit: The stored panel approves and submits without an extra merchant confirmation step in the UI.
  • Branding: Panel styling comes from your payout site configuration.

How it works

The flow works like this:

  1. Your payout session allows PayPal under allowedFundingTypes.wallets.paypal.
  2. You return a shopper ID from onGetShopper.
  3. Drop-in looks up the PayPal wallet association for that shopper.
  4. The association must be active and for the PayPal recipient wallet.
  5. If eligible, PayPal appears in the accordion with the linked email and a submit control.
  6. The shopper submits; payout initiation completes with onSuccess or onError.

This panel doesn't call Drop-in onBeforeSubmit or onSubmit. There is no Drop-in onCancel for the PayPal stored panel. Drive loading and outcome UI from onSuccess and onError. If every method is filtered out, Drop-in reports SDK1701.

Session requirements

PayPal must be allowed on the payout session through allowedFundingTypes.wallets.paypal. The SDK treats PayPal as eligible for lookup when the paypal object is present. Values such as merchantId may appear on that object when PayPal is enabled for the site; this panel uses the linked wallet association only.

Example session fragment:

{
  "allowedFundingTypes": {
    "wallets": {
      "paypal": {}
    }
  }
}

Match transactionData.amount and transactionData.currency to the payout session amounts. Create the session with serviceType: "PayoutDropIn" and PayPal intent Payout on your backend (see Implementation).

Shopper and account requirements

PayPal appears only when these shopper and account checks pass:

RequirementDescription
onGetShopperThe authenticated shopper ID used for wallet association lookup. Without it, PayPal can't resolve a linked account.
Active associationThe lookup must return activeStatus of Active.
Recipient walletThe association recipientWallet must be Paypal.
BlacklistPayPal is hidden when methodConfig.paypal.blacklistedPayerId matches the linked payerId.

Association lookup uses:

GET
/v1/paypal/wallet-associations/{shopperId}?walletType=Paypal

The response body is a compact JWT string. The SDK decodes the payload client-side. PayPal appears only when the association is active for the PayPal recipient wallet and the linked payerId isn't blacklisted.

The SDK uses a successful association response to show the linked email and submit to the stored payer ID. Lookup failures or inactive associations hide PayPal without necessarily calling onError.

Showing PayPal in Drop-in doesn't authorise the payout. Confirm amount, destination, and eligibility on your backend before treating the withdrawal as complete.

Configuration

Blacklist a linked payer

Use blacklistedPayerId to hide PayPal when the linked payer matches:

import type { PayoutDropInMethodConfig } from '@pxpio/web-components-sdk';

const methodConfig: PayoutDropInMethodConfig = {
  paypal: {
    blacklistedPayerId: '<PAYPAL_PAYER_ID>',
  },
};

When the linked account's payerId matches, PayPal is treated as unavailable. Blacklisting hides the method in the accordion. When closed-loop enforcement is active, the same blacklist value is also sent on the closed-loop allocation request. Confirm payout eligibility on your backend.

Localisation

Override the accordion label:

localisation: {
  payoutDropIn: {
    paypalLabel: 'PayPal',
  },
},

paypalConfig

Drop-in merges linked account data into paypalConfig.payoutConfig:

  • paypalWallet.email: Shown on the receiver field and sent as the payout receiver email.
  • paypalWallet.payerId: Submitted as the payout receiver.
  • proceedPayoutWithSdk: true: SDK-driven submit for the stored panel.

You can pass additional paypalConfig where the shared Web SDK config supports it. The stored panel overlays wallet details from the association response.

Stored panel receiver data

For the stored-account panel, Drop-in overlays association data into the payout path:

ValueUse
Linked emailThe linked email shown on the receiver field and sent as the payout receiver email.
Linked payer IDThe linked payer ID submitted as the payout receiver.

Implementation

The following example initialises Drop-in for a PayPal payout. Drive loading UI from onSuccess and onError, because onBeforeSubmit and onSubmit aren't called for this panel:

import {
  PayoutDropIn,
  type PayoutDropInSubmitResult,
} from '@pxpio/web-components-sdk';
import type { BaseSdkException } from '@pxpio/web-components-sdk';

const payoutDropIn = PayoutDropIn.initialize({
  environment: 'test',
  session: sessionData,
  ownerId: 'YOUR-MERCHANT-GROUP-ID',
  transactionData: {
    currency: 'USD',
    amount: 75,
    entryType: 'Ecom',
    merchantTransactionId: crypto.randomUUID(),
    merchantTransactionDate: () => new Date().toISOString(),
  },
  onGetShopper: async () => ({ id: 'shopper-with-linked-paypal' }),
  onSuccess: async (result: PayoutDropInSubmitResult) => {
    showLoading(false);
    console.log('PayPal payout submitted', result.systemTransactionId);
    console.log('Payout method', result.payoutMethod);
    await verifyPayoutOnBackend(result);
  },
  onError: (error: BaseSdkException) => {
    showLoading(false);
    console.error(error.ErrorCode, error.message);
  },
});

await payoutDropIn.create('payout-drop-in-container');

Success and verification

On success, onSuccess receives a PayoutDropInSubmitResult with at least:

PropertyDescription
systemTransactionIdThe PXP system transaction ID.
merchantTransactionIdYour merchant transaction ID.
payoutMethodThe payment method used. Paypal in this instance.

Treat onSuccess as submission acknowledgement. Verify the transaction with your webhook handler or a server-side lookup before updating the shopper's withdrawal status.

A successful PayPal payout merchant webhook looks like this:

{ "eventDate": "2025-12-16T07:37:11.1613200Z", "eventCategory": "transaction", "eventData": { "state": "Authorised", "amount": { "transaction": 100, "currencyCode": "USD" }, "transactionMethod": "Payout", "merchant": "merchant-1", "site": "site-1", "merchantTransactionDate": "2025-12-16T07:37:11.1613200Z", "merchantTransactionId": "PAYOUT_001", "systemTransactionId": "787ebfee-c0ce-497a-82c3-265d1bf19b0c", "providerTransactionId": "PAYPAL_PAYOUT_ITEM_ID", "fundingData": { "paypal": { … } } } }

See Quickstart for the end-to-end session and reconciliation pattern, and Manage webhooks for subscription and signature validation.

Error handling

These codes are the ones you're most likely to see on the PayPal path:

CodeTypical PayPal context
SDK1701No payout methods remain. For example, PayPal was the only candidate and the association was missing, inactive, or blacklisted.
SDK1703PayPal payout initiation failed (PayoutInitiationFailedException). Inspect message and details; correlate with backend transaction state.

Example onError handling for PayPal submission failures:

onError: (error: BaseSdkException) => {
  if (error.ErrorCode === 'SDK1703') {
    showMessage(
      'PayPal could not complete this withdrawal. Please try again or choose another method.'
    );
    return;
  }

  showMessage(
    'We could not complete your withdrawal. Please try again or contact support.'
  );
},

See Error handling.

Testing

Validate the path with these steps:

  1. Use environment: 'test' with sandbox credentials.
  2. Prepare a test shopper that already has an active PayPal wallet association (recipientWallet: Paypal) using your programme's linking and sandbox procedures.
  3. Create a payout session with allowedFundingTypes.wallets.paypal enabled and PayPal intent Payout.
  4. Confirm the PayPal accordion appears, the linked email renders, and submit reaches onSuccess or a clear SDK1703.
  5. Verify the transaction on your backend before treating the withdrawal as complete.

See Testing.