<!-- BusyBot node reference — https://busybot.net/tools/paypal/ -->

> Node: PayPal (`paypal`) · Action · v1
> Category: Finance · Credentials: PayPal (`payPalApi`)
> Updated: 2026-08-16

# PayPal

> Manage PayPal batch payouts and payout items.

## Overview

PayPal action node for the Payouts API. Supports creating batch payouts with multiple recipients, retrieving batch payout details with pagination, getting individual payout item details, and canceling unclaimed payout items. Uses OAuth2 client credentials grant for authentication. Supports both live and sandbox environments.

**Category:** Finance  
**Tool Name:** `paypal`  
**Version:** 1

**Appearance:** Icon: `si-paypal` | Color: `#003087`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **PayPal** credentials.
See the [Credentials Guide](https://busybot.net/credentials/pay-pal-api/) for setup instructions.

### Resources

| Resource | Value |
|----------|-------|
| Payout | `payout` |
| Payout Item | `payoutItem` |

### Operations

Each resource has its own Operation list, and both reuse the operation value `get`. Pick the resource first, then the operation.

| Resource | Operation | Value | Description |
|----------|-----------|-------|-------------|
| Payout | Create | `create` | Create a batch payout |
| Payout | Get | `get` | Show batch payout details |
| Payout Item | Cancel | `cancel` | Cancel an unclaimed payout item |
| Payout Item | Get | `get` | Show payout item details |

### Parameters

All fields accept expressions, so IDs, amounts and recipients can come from the incoming item — `{{ $json.email }}` in Receiver Value, for example.

#### Payout: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Sender Batch ID | `string` | Yes | — | A sender-specified ID number. Tracks the payout in an accounting system. |
| JSON Parameters | `boolean` | No | `false` | Whether to provide payout items as raw JSON instead of using the form fields. |
| Items | `fixedCollection` | No | `{}` | The payout items to include in the batch. Add one entry per recipient. _(shown when JSON Parameters is `false`)_ |
| — Recipient Type | `options` | No | `email` | The ID type that identifies the recipient of the payment. |
| | | | | Options: `email` (the unencrypted email), `phone` (the unencrypted phone number), `paypalId` (the encrypted PayPal account number) |
| — Receiver Value | `string` | Yes | — | The receiver of the payment. Corresponds to the recipient_type value. Max length: 127 characters. |
| — Currency | `options` | No | `USD` | The currency code for the payment amount. |
| | | | | Options: `AUD`, `BRL`, `CAD`, `CZK`, `DKK`, `EUR`, `USD` |
| — Amount | `string` | Yes | — | The payment amount value. |
| — Note | `string` | No | — | Sender-specified note for notifications. Supports up to 4000 ASCII characters or 1000 non-ASCII characters. |
| — Sender Item ID | `string` | No | — | Sender-specified ID number. Tracks the payout item in an accounting system. |
| — Recipient Wallet | `options` | No | `paypal` | The target wallet for the payment. |
| | | | | Options: `paypal` (PayPal Wallet), `venmo` (Venmo Wallet) |
| Items (JSON) | `json` | No | — | An array of individual payout items as JSON. Each item should have recipient_type, amount (with currency and value), receiver, etc. _(shown when JSON Parameters is `true`)_ |
| Additional Fields | `collection` | No | `{}` | Additional optional fields for the batch payout header. |
| — Email Subject | `string` | No | — | The subject line for the email that PayPal sends when payment completes. Max length: 255 characters. |
| — Email Message | `string` | No | — | The email message that PayPal sends when the payout item completes. The message is the same for all recipients. |
| — Note | `string` | No | — | Batch-level note sent on sender_batch_header.note. Appears in PayPal's notification email along with any per-item notes. Max length: 1000 characters. |

#### Payout: Get

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Payout Batch ID | `string` | Yes | — | The ID of the payout batch for which to show details. |
| Return All | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit | `number` | No | `100` | Max number of results to return. _(shown when Return All is `false`)_ |

#### Payout Item: Cancel

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Payout Item ID | `string` | Yes | — | The ID of the payout item to cancel. The item must have an UNCLAIMED status. |

#### Payout Item: Get

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Payout Item ID | `string` | Yes | — | The ID of the payout item for which to show details. |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

The PayPal response is **merged onto the input item's JSON** at the top level — the returned fields sit alongside the fields the item already carried, so downstream nodes address them directly (`{{ $json.payout_item_id }}`). A response field with the same name as an existing item field overwrites it, and an `_error` property left over from upstream is dropped. Binary data on the input item is forwarded.

| Operation | Output |
|-----------|--------|
| Payout: Create | One output item carrying the created batch's `batch_header` (with `payout_batch_id` and `batch_status`) and `links`. |
| Payout: Get | **One output item per payout item in the batch** — a batch of 40 recipients becomes 40 output items from one input item. With Return All on, every page is fetched; otherwise Limit sets the page size. The batch header is not carried on these items, only the individual payout items. A batch with no items produces no output items for that input. |
| Payout Item: Get | One output item carrying that payout item's details, including `transaction_status` and `payout_item`. |
| Payout Item: Cancel | One output item carrying the cancelled item's details with its updated status. |

A payout item from **Payout: Get** or **Payout Item: Get** looks like this:

```json
{
  "payout_item_id": "8AELMXH8UB2P8",
  "transaction_id": "0X0X0X0X0X0X0",
  "transaction_status": "SUCCESS",
  "payout_batch_id": "FYXMPQTX4JC9N",
  "payout_item_fee": { "currency": "USD", "value": "0.25" },
  "payout_item": {
    "recipient_type": "EMAIL",
    "amount": { "currency": "USD", "value": "25.00" },
    "receiver": "recipient1@example.com",
    "sender_item_id": "item_001"
  },
  "time_processed": "2026-01-15T10:35:12Z",
  "links": []
}
```

Creating a batch returns immediately with a pending status — PayPal processes the payout asynchronously. Poll with **Payout: Get** using the `payout_batch_id` from the create response to see the per-item outcome.

Because Create is idempotent on the Sender Batch ID, re-running the same node on the same execution returns the original batch instead of paying twice. Give each real batch a distinct Sender Batch ID.

## Usage Examples

- Create a batch payout to multiple email recipients via PayPal
- Get details and status of a PayPal batch payout
- Retrieve a specific payout item status from PayPal
- Cancel an unclaimed PayPal payout item
- Send payments to multiple vendors via PayPal payouts

## Example Configuration

Pay several recipients from the form fields:

```json
{
  "type": "paypal",
  "parameters": {
    "resource": "payout",
    "operation": "create",
    "senderBatchId": "batch_001",
    "jsonParameters": false,
    "itemsUi": {
      "itemsValues": [
        {
          "recipientType": "email",
          "receiverValue": "recipient1@example.com",
          "currency": "USD",
          "amount": "25.00",
          "note": "Payment for services",
          "senderItemId": "item_001",
          "recipientWallet": "paypal"
        },
        {
          "recipientType": "email",
          "receiverValue": "recipient2@example.com",
          "currency": "USD",
          "amount": "50.00",
          "note": "Bonus payment",
          "senderItemId": "item_002",
          "recipientWallet": "paypal"
        }
      ]
    },
    "additionalFields": {
      "emailSubject": "Your payment from Company XYZ",
      "emailMessage": "Thank you for your work!",
      "note": "Monthly contractor payments"
    }
  }
}
```

Supply the same batch as raw JSON in PayPal's own field names:

```json
{
  "type": "paypal",
  "parameters": {
    "resource": "payout",
    "operation": "create",
    "senderBatchId": "batch_002",
    "jsonParameters": true,
    "itemsJson": "[{\"recipient_type\":\"EMAIL\",\"amount\":{\"value\":\"25.00\",\"currency\":\"USD\"},\"receiver\":\"recipient1@example.com\",\"note\":\"Payment for services\",\"sender_item_id\":\"item_001\",\"recipient_wallet\":\"PAYPAL\"}]",
    "additionalFields": {
      "emailSubject": "Your payment from Company XYZ",
      "note": "Monthly contractor payments"
    }
  }
}
```

Pay a single contractor using values from an upstream item:

```json
{
  "type": "paypal",
  "parameters": {
    "resource": "payout",
    "operation": "create",
    "senderBatchId": "payroll-{{ $json.periodId }}",
    "jsonParameters": false,
    "itemsUi": {
      "itemsValues": [
        {
          "recipientType": "email",
          "receiverValue": "{{ $json.email }}",
          "currency": "USD",
          "amount": "{{ $json.amount }}",
          "note": "{{ $json.period }} payment",
          "senderItemId": "{{ $json.contractorId }}",
          "recipientWallet": "paypal"
        }
      ]
    },
    "additionalFields": {
      "emailSubject": "Your Monthly Payment"
    }
  }
}
```

Read back every item in a batch:

```json
{
  "type": "paypal",
  "parameters": {
    "resource": "payout",
    "operation": "get",
    "payoutBatchId": "{{ $json.batch_header.payout_batch_id }}",
    "returnAll": true
  }
}
```

Read back only the first 10 items:

```json
{
  "type": "paypal",
  "parameters": {
    "resource": "payout",
    "operation": "get",
    "payoutBatchId": "BATCH123456789",
    "returnAll": false,
    "limit": 10
  }
}
```

Check one payout item's status:

```json
{
  "type": "paypal",
  "parameters": {
    "resource": "payoutItem",
    "operation": "get",
    "payoutItemId": "ITEM123456789"
  }
}
```

Cancel an item the recipient never claimed:

```json
{
  "type": "paypal",
  "parameters": {
    "resource": "payoutItem",
    "operation": "cancel",
    "payoutItemId": "{{ $json.payout_item_id }}"
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Manages PayPal batch payouts -- create payouts to multiple recipients, retrieve batch/item details, and cancel unclaimed payout items. Uses PayPal Payouts API with OAuth2 client credentials authentication.