Learn about PXP's PayPal and Venmo payout components.
The PayPal payouts components enable you to send payouts directly to your customers' PayPal or Venmo wallets. Whether you're paying vendors, freelancers, partners, or disbursing refunds, rebates, and rewards — the payouts components provide a streamlined experience built on top of PayPal's payout rails.
With the payouts components, you can benefit from:
- Simplified disbursements: Send payouts directly to PayPal or Venmo wallets without managing the underlying PayPal API complexity.
- SDK or merchant-initiated payouts: Choose whether the SDK handles the payout execution or trigger it from your own backend after your own validation checks.
- Customisable UI components: Use pre-built components with configurable styling, or build your own UI and call the APIs directly.
- Operational safeguards: Benefit from built-in logging, retries, and reconciliation handled by the gateway.
The payouts components support the following wallet types:
- PayPal: Send payouts to recipients using their PayPal email address or Payer ID.
- Venmo: Send payouts to recipients using their Venmo email, phone number, or handle.
When initiating a payout, you can choose who triggers the actual payout request:
- SDK-initiated payout: The SDK handles the payout execution after your
onPrePayoutSubmitcallback approves it. This is the fastest time-to-market option. - Merchant-initiated payout: The SDK calls
onClick(if configured) and returns without executing the payout. Your backend triggers the payout via API. This gives you maximum control for additional validation or business logic.
| Aspect | SDK-initiated | Merchant-initiated |
|---|---|---|
proceedPayoutWithSdk | true | false |
| Payout trigger | The SDK calls PXP backend automatically. | Your backend calls the payout API. |
| Control level | Simplified flow. | Full control over timing and validation. |
| Use cases | Standard payouts, quick integration. | Custom validation, compliance checks, multi-step approval. |
In SDK-initiated mode (proceedPayoutWithSdk: true), the SDK calls the PXP backend after your onPrePayoutSubmit callback approves the payout, and then invokes onPostPayout with the result. Provide onPrePayoutSubmit when you use this mode — without it, the SDK does not execute the payout. In merchant-initiated mode (proceedPayoutWithSdk: false, the default), the SDK calls onClick (if configured) and doesn't run onPrePayoutSubmit, execute the payout, or call onPostPayout. Your backend calls the payout API directly and can implement additional approval workflows.
When you initiate a payout transaction, you need to provide key information about the transaction method, amount, and currency.
The transaction method includes:
- The entry type, which describes the origin of the transaction. For payouts, this is always
Ecom. - The intent, which describes the purpose of a transaction and indicates the intended money flow direction.
Payouts support the following intent:
| Intent | Description |
|---|---|
Payout | Disburse funds to a recipient's PayPal or Venmo wallet. Use this for all payout transactions. |
The payouts SDK provides several components you can use based on your integration needs:
| Component | Type | Description |
|---|---|---|
| Amount | payout-amount | Display-only payout amount. Use this to show the payout amount to the customer before confirming. |
| PayPal receiver | paypal-payout-receiver | Display-only PayPal email from config with optional masking. Use this for returning customers when you have their PayPal email/Payer ID. |
| Venmo receiver | venmo-payout-receiver | Display-only Venmo receiver from config with optional masking. Use this for returning customers when you have their Venmo details. |
| Submission | payout-submission | "Withdraw with PayPal/Venmo" button that executes the payout. Use this for returning customers when you already have stored wallet details. |
All components follow the same basic lifecycle:
- Create the component with any configuration and callbacks you need.
- Mount the component into a container in your DOM to make it visible and interactive.
- Unmount the component when the user leaves the page or when the component is no longer needed.
Before integrating the payouts components, ensure you have:
- A merchant account with PXP (credentials/API key).
- Your PayPal merchant account onboarded with PXP.
- Verified identity/account (if required by compliance).
- Sufficient funds in your gateway balance to cover payout amounts and fees.
- The recipients' PayPal or Venmo identifiers (if using the withdrawal flow).
- An HTTPS endpoint with a valid SSL certificate (if you plan to receive webhooks).
At minimum, your SDK initialisation must provide:
import { PxpCheckout, IntentType, CurrencyType } from "@pxpio/web-components-sdk";
const pxpCheckoutSdk = PxpCheckout.initialize({
environment: "test", // or "production"
session: sessionData,
ownerId: "your-owner-id",
ownerType: "MerchantGroup",
transactionData: {
amount: 100, // > 0
currency: "USD" as CurrencyType, // 3-letter ISO code
entryType: "Ecom",
intent: {
paypal: IntentType.Payout // required for payouts
},
merchantTransactionId: crypto.randomUUID(),
merchantTransactionDate: () => new Date().toISOString()
},
paypalConfig: {
payoutConfig: {
proceedPayoutWithSdk: true // Defaults to false (merchant-initiated)
// Add paypalWallet / venmoWallet for the withdrawal flow
}
}
});When you offer PayPal or Venmo payouts, you must meet PayPal branding and behaviour requirements, and you remain responsible for financial, privacy, and security obligations in your markets.
| Description | Requirement | |
|---|---|---|
| Logos | PayPal logos and acceptance marks are displayed in parity with other payout options anywhere the payout method is presented. | required |
| Logos | PayPal logos are taken from official sources and aren't modified. | required |
| Branding | The correct capitalisation and spelling of PayPal is always used in both text and images (instead of Paypal, Pay Pal, and similar variants). | required |
| Accessibility | The Google Mobile-Friendly Test Tool recognises the main web pages of your site as mobile-friendly. | optional |
| Accessibility | The viewport meta tag ensures optimal rendering on mobile devices: <meta name="viewport" content="width=device-width, initial-scale=1"> | optional |
| Buttons | PayPal or Venmo payout buttons are presented with equal prominence and close proximity to other withdrawal methods. | required |
| Buttons | PayPal payout buttons are placed above other payout options. | required |
| Buttons | The PayPal button is sized in parity with other payout buttons or otherwise in keeping with other elements on the page. See the PayPal style guide. | required |
| Description | Requirement | |
|---|---|---|
| Fees | You don't add any additional surcharge or fee for PayPal or Venmo payout transactions beyond what PayPal charges. | required |
| Customer journey | Selecting the PayPal payout method takes the user directly to the PayPal login/consent step (where applicable) and then back to your site without deviations or intermediate steps. | required |
| Payout methods | If payout methods can be stored and/or set as a preference, PayPal/Venmo can also be stored or set as the preferred payout method. | required |
| Payout methods | For the customer's first payout, no payout method should be preselected by default. For subsequent payouts, the customer's previously used payout method may be preselected. | optional |
| Payout methods | When a payout method is selected, any fields specific to other payout methods are hidden. For example, bank details hidden when PayPal is selected. | optional |
| Account | The customer isn't required to create or log into a store/application account to receive a payout. | optional |
| Confirmation page | After the payout initiation, the user sees a confirmation page/step indicating the payout status; PayPal details or logos are presented in parity with other payout methods. | required |
| Mobile experience | Confirm iFrame isn't used. | required |
| Receiver validation | PayPal email/phone or Venmo handle is validated before submission where possible; PayPal error responses are surfaced to the user with guidance to correct details. | required |
You own KYC, AML, transaction limits, data protection, consent, and record-keeping for your integration. Before you go live, confirm at least the following:
- Customer identity verification where your market requires it.
- AML monitoring and payout limits appropriate to your risk policy.
- Secure handling of personal and financial data, including encryption in transit (TLS 1.2 or higher) and at rest for any stored wallet identifiers.
- Inbound API credentials (token ID and token value) kept on your backend only — never embed them in client-side JavaScript.
- Clear customer consent for payout terms and privacy where required.
- Audit logging for payout initiation, approval, success, and failure.
- Country-specific regulatory requirements for the markets you serve.
- Legal and security review of your payout flows.
Store only the wallet identifiers you need for returning customers, such as the PayPal payer ID and email. Don't keep unnecessary sensitive personal data in the browser.
Now that you understand how payouts work, you're ready to start integrating:
- Quickstart: Set up the Web SDK in your project.
- Onboarding: Connect your PayPal Business account for payouts.
- Withdrawal flow: Implement payouts for returning customers.
- Configuration: Configure the appearance and behaviour of components.
- Events: Handle payout events and callbacks.