# 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 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.


| 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, 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:

| Intent | Description |
|  --- | --- |
| `Payout` | Disburse 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  |
|  --- | --- | --- |
| **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:

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:


```typescript
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:

* [Quickstart](/guides/checkout/components/web/quickstart): Set up the Web SDK in your project.


* [Withdrawal flow](/guides/checkout/components/web/paypal/payouts/withdrawal-flow): Implement payouts for returning customers.
* [Configuration](/guides/checkout/components/web/paypal/payouts/about-configuration): Configure the appearance and behaviour of components.
* [Events](/guides/checkout/components/web/paypal/payouts/events): Handle payout events and callbacks.