How it works

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 the user confirms. This is the fastest time-to-market option.
• Merchant-initiated payout: The SDK collects and validates information, but your backend triggers the payout via API. This gives you maximum control for additional validation or business logic.

In SDK-initiated mode, the SDK calls the PXP backend after your onPrePayoutSubmit callback approves the payout, and then invokes onPostPayout with the result. In merchant-initiated mode, the SDK validates inputs and returns control to your backend, which 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:

SDK components

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

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.

Pre-requisites

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
      // Optionally add paypalWallet / venmoWallet for withdrawal flow
    }
  }
});

What's next?

Now that you understand how payouts work, you're ready to start integrating:

• Installation: Set up the Web SDK in your project.

• Withdrawal flow: Implement payouts for returning customers.
• Configuration: Configure the appearance and behaviour of components.
• Events: Handle payout events and callbacks.