Skip to content

How it works

Learn about PXP's PayPal and Venmo payout components.

Overview

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.

Payout options

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.

Payout initiation modes

When initiating a payout, you can choose who triggers the actual payout request:

  • SDK-initiated payout: The SDK handles the payout execution after your onPrePayoutSubmit callback 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.
AspectSDK-initiatedMerchant-initiated
proceedPayoutWithSdktruefalse
Payout triggerThe SDK calls PXP backend automatically.Your backend calls the payout API.
Control levelSimplified flow.Full control over timing and validation.
Use casesStandard 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.

Supported transaction intents

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:

IntentDescription
PayoutDisburse funds to a recipient's PayPal or Venmo wallet. Use this for all payout transactions.

SDK components

The payouts SDK provides several components you can use based on your integration needs:

Component Type Description
Amountpayout-amountDisplay-only payout amount. Use this to show the payout amount to the customer before confirming.
PayPal receiverpaypal-payout-receiverDisplay-only PayPal email from config with optional masking. Use this for returning customers when you have their PayPal email/Payer ID.
Venmo receivervenmo-payout-receiverDisplay-only Venmo receiver from config with optional masking. Use this for returning customers when you have their Venmo details.
Submissionpayout-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:

  1. Create the component with any configuration and callbacks you need.
  2. Mount the component into a container in your DOM to make it visible and interactive.
  3. Unmount the component when the user leaves the page or when the component is no longer needed.

Requirements

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
    }
  }
});

Compliance

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.

Branding and appearance

DescriptionRequirement
LogosPayPal logos and acceptance marks are displayed in parity with other payout options anywhere the payout method is presented.required
LogosPayPal logos are taken from official sources and aren't modified.required
BrandingThe correct capitalisation and spelling of PayPal is always used in both text and images (instead of Paypal, Pay Pal, and similar variants).required
AccessibilityThe Google Mobile-Friendly Test Tool recognises the main web pages of your site as mobile-friendly.optional
AccessibilityThe viewport meta tag ensures optimal rendering on mobile devices: <meta name="viewport" content="width=device-width, initial-scale=1">optional
ButtonsPayPal or Venmo payout buttons are presented with equal prominence and close proximity to other withdrawal methods.required
ButtonsPayPal payout buttons are placed above other payout options.required
ButtonsThe 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

Behaviour

DescriptionRequirement
FeesYou don't add any additional surcharge or fee for PayPal or Venmo payout transactions beyond what PayPal charges.required
Customer journeySelecting 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 methodsIf 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 methodsFor 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 methodsWhen a payout method is selected, any fields specific to other payout methods are hidden. For example, bank details hidden when PayPal is selected.optional
AccountThe customer isn't required to create or log into a store/application account to receive a payout.optional
Confirmation pageAfter 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 experienceConfirm iFrame isn't used.required
Receiver validationPayPal 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

Your regulatory responsibilities

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.

What's next?

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.