Withdraw funds to a linked PayPal account using a stored wallet association.
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.
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
onSuccessandonError. - 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.
The flow works like this:
- Your payout session allows PayPal under
allowedFundingTypes.wallets.paypal. - You return a shopper ID from
onGetShopper. - Drop-in looks up the PayPal wallet association for that shopper.
- The association must be active and for the PayPal recipient wallet.
- If eligible, PayPal appears in the accordion with the linked email and a submit control.
- The shopper submits; payout initiation completes with
onSuccessoronError.
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.
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).
PayPal appears only when these shopper and account checks pass:
| Requirement | Description |
|---|---|
onGetShopper | The authenticated shopper ID used for wallet association lookup. Without it, PayPal can't resolve a linked account. |
| Active association | The lookup must return activeStatus of Active. |
| Recipient wallet | The association recipientWallet must be Paypal. |
| Blacklist | PayPal is hidden when methodConfig.paypal.blacklistedPayerId matches the linked payerId. |
Association lookup uses:
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.
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.
Override the accordion label:
localisation: {
payoutDropIn: {
paypalLabel: 'PayPal',
},
},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.
For the stored-account panel, Drop-in overlays association data into the payout path:
| Value | Use |
|---|---|
| Linked email | The linked email shown on the receiver field and sent as the payout receiver email. |
| Linked payer ID | The linked payer ID submitted as the payout receiver. |
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');On success, onSuccess receives a PayoutDropInSubmitResult with at least:
| Property | Description |
|---|---|
systemTransactionId | The PXP system transaction ID. |
merchantTransactionId | Your merchant transaction ID. |
payoutMethod | The 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.
These codes are the ones you're most likely to see on the PayPal path:
| Code | Typical PayPal context |
|---|---|
SDK1701 | No payout methods remain. For example, PayPal was the only candidate and the association was missing, inactive, or blacklisted. |
SDK1703 | PayPal 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.
Validate the path with these steps:
- Use
environment: 'test'with sandbox credentials. - Prepare a test shopper that already has an active PayPal wallet association (
recipientWallet: Paypal) using your programme's linking and sandbox procedures. - Create a payout session with
allowedFundingTypes.wallets.paypalenabled and PayPal intentPayout. - Confirm the PayPal accordion appears, the linked email renders, and submit reaches
onSuccessor a clearSDK1703. - Verify the transaction on your backend before treating the withdrawal as complete.
See Testing.