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

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

Read back only the first 10 items:

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

Check one payout item’s status:

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

Cancel an item the recipient never claimed:

{
  "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.