# How to Integrate Retool with PayPal Payouts

- Tool: Retool
- Difficulty: Intermediate
- Time required: 30 minutes
- Last updated: April 2026

## TL;DR

Connect Retool to PayPal Payouts using a REST API Resource with OAuth 2.0 client credentials. Configure PayPal's API credentials in Retool's Resources tab, obtain an access token, and build payout operations dashboards that create batch payouts, track disbursement status, and view recipient details for marketplace and gig economy payment workflows.

## Build a Payout Operations Dashboard with PayPal and Retool

Marketplaces, gig economy platforms, and affiliate programs regularly need to disburse payments to large numbers of recipients — sellers, contractors, influencers, or referral partners. PayPal Payouts supports batch disbursements to thousands of recipients at once, but PayPal's native dashboard provides limited operational visibility: it's difficult to track individual recipient payment status, troubleshoot failed payouts, or build custom approval workflows before disbursements go out. Retool connected to PayPal's Payouts API solves this.

PayPal's Payouts API organizes disbursements into 'payout batches' — a single API call submits a batch with multiple recipient objects, each specifying an email address, amount, currency, and optional note. PayPal processes the batch asynchronously and assigns success, pending, failed, or unclaimed status to each item. A Retool operations dashboard can show all recent batches, drill down into individual item statuses, identify failed or unclaimed payouts requiring follow-up, and trigger new batch creation for scheduled disbursement runs.

Beyond simple payout tracking, Retool's integration with PayPal enables building pre-disbursement approval workflows: finance managers review a pending payout list, approve or modify individual items, and then trigger the batch creation via a button — rather than relying on manual processes or expensive custom software. This pattern is particularly valuable for teams that handle payouts weekly or monthly and need clear audit trails of who approved each disbursement.

## Before you start

- A PayPal Business account with Payouts enabled (requires a one-time request to PayPal for Payouts API access)
- A PayPal developer application created at developer.paypal.com with Live credentials (Client ID and Secret)
- PayPal Payouts API access enabled for your Live application (separate approval from standard PayPal APIs)
- A Retool account with permission to create and configure Resources
- Recipient PayPal email addresses or phone numbers for the disbursement targets

## Step-by-step guide

### 1. Create a PayPal developer application and enable Payouts

Go to developer.paypal.com and sign in with your PayPal Business account. Navigate to 'Apps & Credentials'. Under the 'Live' tab (not Sandbox for production), click 'Create App'. Name your application (e.g., 'Retool Payout Operations') and select 'Merchant' as the app type.

After creation, PayPal shows your Live Client ID and allows you to reveal your Secret. Copy both values — you'll need them for Retool Resource configuration.

Critically, PayPal Payouts is not enabled by default on new applications. You must specifically enable it: in your app's settings page, scroll to 'Features' and locate 'Payouts'. Toggle it on and click Save. If you don't see the Payouts toggle, contact PayPal's technical support to have Payouts API access enabled for your account — this is a separate approval process that PayPal requires for mass disbursement capability.

For testing, use the Sandbox tab with Sandbox credentials pointing to developer.paypal.com/sandbox — create Sandbox business and personal accounts to test payout flows without real money. Switch to Live credentials only after testing is complete.

**Expected result:** You have Live Client ID and Secret for your PayPal developer application, and Payouts is enabled as a feature. You can proceed to configure Retool.

### 2. Configure PayPal OAuth resource and token query in Retool

PayPal uses OAuth 2.0 client credentials flow for server-to-server API access. You need two Retool resources: one for obtaining tokens and one for making payout API calls with the token.

In Retool's Resources tab, create a REST API resource named 'PayPal OAuth'. Set the base URL to https://api-m.paypal.com (Live) or https://api-m.sandbox.paypal.com (Sandbox). For authentication, select 'Basic Auth'. Enter your Client ID as the username and Secret as the password.

Create a query named 'getPayPalToken' using the PayPal OAuth resource. Set method to POST and path to /v1/oauth2/token. In the Body tab, select 'URL Encoded' (application/x-www-form-urlencoded) and add the field: grant_type with value client_credentials. Run this query — it returns an access_token string valid for approximately 32400 seconds (9 hours).

Create a second REST API resource named 'PayPal Payouts API'. Set the base URL to https://api-m.paypal.com. For authentication, select 'Bearer Token' and set the value to {{ getPayPalToken.data.access_token }}. Also add a Content-Type header: application/json.

Store your Client ID and Secret in Retool configuration variables (Settings → Configuration Variables, marked as secrets). Reference them in the Basic Auth fields as {{ retoolContext.configVars.PAYPAL_CLIENT_ID }} and {{ retoolContext.configVars.PAYPAL_SECRET }}.

```
// GET /v1/oauth2/token response structure
// The access_token is valid for ~9 hours (32400 seconds)
{
  "scope": "https://uri.paypal.com/services/payouts...",
  "access_token": "A21AAF...",
  "token_type": "Bearer",
  "app_id": "APP-80W284485P519543T",
  "expires_in": 32400,
  "nonce": "2020-04-03T15:35:36ZaYZlGvEkV7b0I3ztI/CNNF9FJk_PDneTVHTHF2"
}
```

**Expected result:** The getPayPalToken query returns a valid access_token. The PayPal Payouts API resource uses this token for authentication. You can now make payout API calls.

### 3. Build a query to list recent payout batches

Create a query to retrieve recent payout batches for your operations overview. In your Retool app, create a query named 'getPayoutBatches'. Use the PayPal Payouts API resource, set method to GET, and path to /v1/payments/payouts.

Note: PayPal's Payouts list endpoint requires specific query parameters to scope results. Add the following URL parameters: start_time (set to {{ new Date(Date.now() - 30*24*60*60*1000).toISOString() }} for last 30 days), end_time (set to {{ new Date().toISOString() }}), page_size (set to 20), and fields (set to all for complete batch details).

However, PayPal's Payouts API does not have a simple 'list all batches' endpoint — you must know the batch_payout_id to retrieve specific batch details via GET /v1/payments/payouts/{batch_payout_id}. The recommended approach is to store batch IDs in a Retool Database or PostgreSQL table when creating payouts, then query your own database for the batch ID list and use a Retool JavaScript query to fetch details for each batch from PayPal.

For the batch detail view, create a query named 'getBatchDetails'. Set method to GET and path to /v1/payments/payouts/{{ batchesTable.selectedRow?.batchId }}. This endpoint returns full batch details including all item statuses, recipients, amounts, and error messages for any failed items.

```
// JavaScript transformer for PayPal batch detail response
const batch = data;
const items = batch.items || [];

const summary = {
  batchId: batch.batch_header?.payout_batch_id,
  status: batch.batch_header?.batch_status,
  totalAmount: batch.batch_header?.amount?.value,
  currency: batch.batch_header?.amount?.currency,
  fundingSource: batch.batch_header?.funding_source,
  timeCompleted: batch.batch_header?.time_completed
    ? new Date(batch.batch_header.time_completed).toLocaleString()
    : 'Processing...',
  successCount: items.filter(i => i.transaction_status === 'SUCCESS').length,
  failedCount: items.filter(i => i.transaction_status === 'FAILED').length,
  unclaimedCount: items.filter(i => i.transaction_status === 'UNCLAIMED').length
};

const lineItems = items.map(item => ({
  payoutItemId: item.payout_item_id,
  recipient: item.payout_item?.receiver,
  amount: `${item.payout_item?.amount?.currency} ${item.payout_item?.amount?.value}`,
  status: item.transaction_status,
  error: item.errors?.name || '',
  errorMessage: item.errors?.message || '',
  transactionId: item.transaction_id || 'N/A'
}));

return { summary, lineItems };
```

**Expected result:** The batch detail query returns complete status information for a payout batch, including per-item status, recipient details, and any error information for failed payments.

### 4. Build a payout batch creation query

The most important capability in a payout operations panel is creating new payout batches from Retool. Create a query named 'createPayoutBatch' using the PayPal Payouts API resource. Set method to POST and path to /v1/payments/payouts.

The request body requires a sender_batch_header with your internal batch ID, email subject, and email message for recipients, plus an items array with each recipient's details. The items array is built dynamically from your Retool Table component — specifically from the rows that finance managers have approved for payment.

The payout recipient can be identified by email address, phone number, or PayPal username. For marketplaces, email is the most common identifier. Each item requires a recipient_type (EMAIL, PHONE, or PAYPAL_ID), an amount object with value and currency, and a receiver (the email address or identifier).

After creating the query, build the approval workflow UI: a Table component showing pending payouts pulled from your internal database, checkboxes for selecting rows to include in the batch, a summary showing total amount and recipient count for selected rows, and a 'Create Payout Batch' button that triggers the createPayoutBatch query with selected row data.

On success, the query returns a batch_header with a payout_batch_id and PENDING status. Store this batch ID in your database using a second query that fires in the On Success event handler. For complex multi-step payout workflows with approval gates, custom fee calculations, and reconciliation reporting, RapidDev's team can help build the complete operational system.

```
// POST /v1/payments/payouts
// Create a payout batch from selected rows in the pending payouts table
{
  "sender_batch_header": {
    "sender_batch_id": "{{ 'BATCH-' + new Date().getTime() }}",
    "email_subject": "You have received a payment",
    "email_message": "Thank you for your work. Please claim your payment.",
    "recipient_type": "EMAIL"
  },
  "items": {{ pendingPayoutsTable.selectedRows.map((row, index) => ({
    "payout_item_id": row.id || String(index + 1),
    "recipient_type": "EMAIL",
    "amount": {
      "value": row.amount.toFixed(2),
      "currency": "USD"
    },
    "receiver": row.paypalEmail,
    "note": row.note || "Payment from platform",
    "sender_item_id": row.internalId || String(row.id)
  })) }}  
}
```

**Expected result:** The payout batch creation query successfully submits disbursements to PayPal. The response includes a payout_batch_id that you store for tracking. The batch appears in PayPal's Payouts dashboard within minutes.

### 5. Build the payout operations dashboard UI

Assemble the complete payout operations dashboard. Use a Tab component with three tabs: 'Pending Payouts', 'Batch History', and 'Failed Items'.

On Pending Payouts: Display a Table showing recipients eligible for payment from your internal database. Add columns: recipient name, PayPal email, amount to pay, payment reason, and a checkbox for approval. Show a summary bar below showing total selected amount and recipient count. The 'Execute Payout Batch' button at the bottom creates the batch and shows a confirmation modal before proceeding.

On Batch History: Show a Table listing recent payout batches from your database (batch ID, creation date, total amount, recipient count, status). Clicking a batch row triggers the getBatchDetails query and shows a side panel with the batch summary statistics and a detailed item list below.

On Failed Items: Query your database for payout batch items that returned FAILED, UNCLAIMED, or RETURNED status. Display recipient email, error reason (e.g., 'RECEIVER_ACCOUNT_LOCKED', 'INVALID_ACCOUNT_NUMBER'), original amount, and a 'Retry' button. The Retry button opens a form to enter a corrected PayPal email and creates a new single-item batch.

Add role-based access control by using Retool's Groups feature — only users in the 'Finance' group can see the 'Execute Payout Batch' button and the actual PayPal email addresses; other groups see masked values.

```
// JavaScript transformer to calculate payout batch summary
const selectedRows = pendingPayoutsTable.selectedRows || [];

const summary = {
  recipientCount: selectedRows.length,
  totalAmount: selectedRows.reduce((sum, row) => sum + (parseFloat(row.amount) || 0), 0).toFixed(2),
  currency: 'USD',
  estimatedFee: (selectedRows.reduce((sum, row) => sum + (parseFloat(row.amount) || 0), 0) * 0.02).toFixed(2), // ~2% PayPal Payouts fee
  currencies: [...new Set(selectedRows.map(r => r.currency || 'USD'))].join(', ')
};

return summary;
```

**Expected result:** The three-tab payout dashboard is complete. Finance managers can review pending payouts, approve a subset, create the PayPal batch, and track status through to completion. Failed payouts surface clearly for follow-up.

## Best practices

- Store all PayPal payout batch IDs in your own database immediately after batch creation — PayPal doesn't provide a reliable batch history endpoint, so your records are the source of truth for reconciliation
- Implement a pre-flight validation check in Retool before creating batches: verify no duplicate emails, confirm all amounts are positive, check the total doesn't exceed your daily payout limit, and require explicit approval confirmation
- Use PayPal Sandbox for all development and testing — Sandbox provides isolated test accounts and doesn't touch real money, but the API behaviour is identical to Live
- Store PayPal Client ID and Secret in Retool configuration variables marked as secrets, never in query bodies or component values that could be exposed to end users
- Build a reconciliation report that compares your internal database of expected payouts with PayPal's actual batch item statuses — discrepancies indicate either missing payouts or unexpected extra disbursements
- Monitor UNCLAIMED payouts proactively — funds held in UNCLAIMED status for 30 days are automatically returned by PayPal; build a Retool Workflow that alerts your team when UNCLAIMED items approach the 30-day threshold
- For international payouts, always specify the currency explicitly in each payout item and verify that currency is supported in the recipient's country — PayPal's Payouts API supports multiple currencies but not all currencies work in all countries

## Use cases

### Weekly marketplace seller payment dashboard

Build a dashboard that shows all sellers eligible for weekly payment, calculates amounts based on completed order data from your database, lets a finance manager review and approve the payout list, then triggers a PayPal batch payout with one click. Track batch status and follow up on any failed or unclaimed items.

Prompt example:

```
Build a Retool app with a Table showing pending seller payouts imported from our orders database (seller email, earned amount, completed orders count). Add checkboxes to approve individual payouts and an 'Execute Payout Batch' button that sends all approved items to PayPal's Payouts API. Show a status panel tracking batch processing results.
```

### Failed payout triage panel

Build a triage dashboard that shows all payout items with FAILED, UNCLAIMED, or RETURNED status across recent batches. Display the failure reason, recipient details, and amount. Allow operations staff to update PayPal email addresses and retry failed payouts individually.

Prompt example:

```
Build a Retool dashboard that queries recent PayPal payout batches and filters for items with non-SUCCESS status. Show recipient email, failure reason, amount, batch date, and a 'Retry' button that creates a new single-item payout batch with corrected details. Group by failure reason with counts.
```

### Gig economy contractor payment operations panel

Build a contractor payment panel that processes weekly pay runs for gig workers. Pull earnings data from your platform's database, combine with contractor PayPal emails, calculate deductions, show a pre-payment summary, and trigger disbursements. Track payment confirmation and flag contractors who haven't linked a PayPal account.

Prompt example:

```
Build a Retool app combining data from our PostgreSQL database (contractor ID, earnings, hours, PayPal email) with PayPal payout status. Show a payment run summary with total amount, recipient count, and estimated processing time. Include an approval flow before executing, and a post-payment reconciliation view.
```

## Troubleshooting

### PayPal API returns 401 Unauthorized even with correct Client ID and Secret

Cause: The token query may be using Sandbox credentials against the Live endpoint (or vice versa), or the Client ID and Secret have been entered in the wrong order (Client ID must be the username, Secret must be the password for Basic Auth).

Solution: Confirm you're using the correct environment — Live credentials go to api-m.paypal.com, Sandbox credentials go to api-m.sandbox.paypal.com. In the Retool Resource's Basic Auth settings, ensure Client ID is the username field and Client Secret is the password field. Regenerate the token query and check the raw request headers to confirm the Authorization header contains the correct Base64-encoded string.

### Payout batch creation returns 403 with 'You are not authorized to use this service'

Cause: Payouts API access has not been enabled for your PayPal account or application. This is a separate approval from standard PayPal API access.

Solution: Log into developer.paypal.com, open your Live application settings, and verify the Payouts feature toggle is enabled. If it's not visible, contact PayPal technical support (developer.paypal.com/support) and request Payouts API access. This approval process can take 1-5 business days. During this wait, test with Sandbox credentials where Payouts is available without special approval.

### Individual payout items show UNCLAIMED status for several days after the batch was processed

Cause: UNCLAIMED means PayPal sent the payment but the recipient doesn't have a PayPal account linked to that email address. PayPal holds the funds for 30 days, then returns them if unclaimed.

Solution: Contact recipients with UNCLAIMED status to create a PayPal account with the email address you sent the payment to. In your Retool dashboard, highlight UNCLAIMED items and add a 'Send Reminder' button that logs the follow-up action. Monitor these items and build an alert in a Retool Workflow that flags items approaching the 30-day return deadline.

### PayPal batch creation fails with 'DUPLICATE_REQUEST' error

Cause: The sender_batch_id in the request body matches a batch created within the last 30 days. PayPal treats duplicate sender_batch_ids as idempotent replays of the original request.

Solution: Ensure each payout batch uses a unique sender_batch_id. Use a timestamp-based approach or UUID: 'BATCH-' + Date.now() for simple uniqueness. If you're retrying a failed batch creation (not a duplicate — an actual server-side failure), check whether the original batch was created despite the error by querying PayPal with the original batch ID before generating a new one.

```
// Generate a unique sender_batch_id
const batchId = 'BATCH-' + new Date().toISOString().replace(/[:.]/g, '-') + '-' + Math.random().toString(36).substr(2, 9);
return batchId;
```

## Frequently asked questions

### What is the difference between PayPal Payouts and regular PayPal payments?

PayPal Payouts (formerly Mass Pay) is specifically designed for businesses sending money to multiple recipients in a single API call — it supports batch sizes of up to 15,000 recipients per batch and typically charges lower per-transaction fees than regular PayPal payments. Regular PayPal payment APIs (Checkout, Payment Intents) are for accepting money from customers. Payouts is for disbursing money to sellers, contractors, or affiliates.

### How much does PayPal Payouts cost per transaction?

PayPal Payouts fees vary by recipient location and funding source. For domestic US payouts funded by PayPal balance, the fee is approximately 2% per transaction with a $1 maximum. International payouts have different fee structures. Check PayPal's current pricing at paypal.com/us/business/payouts — fees change periodically and vary by market. Your PayPal account agreement may include custom rates for high-volume senders.

### Can I cancel a payout after creating the batch?

Individual payout items with UNCLAIMED status can be cancelled via a DELETE /v1/payments/payouts-item/{payout_item_id} call before the recipient claims the funds. However, items with SUCCESS or PENDING status cannot be cancelled — you would need to request a refund from the recipient. Plan your payout approval workflow carefully with confirmation modals in Retool to prevent accidental disbursements.

### What happens to payout funds if a recipient's email is wrong or they don't have a PayPal account?

If the recipient doesn't have a PayPal account linked to the provided email, the payout shows as UNCLAIMED. PayPal sends the recipient an email inviting them to create an account or link their existing account. If the recipient doesn't claim the funds within 30 days, PayPal returns the funds to your account balance. Build a monitoring view in your Retool dashboard that tracks UNCLAIMED items and alerts your team as they approach the 30-day deadline.

### Is there a limit on how many recipients can be in one PayPal payout batch?

PayPal Payouts supports up to 15,000 items per batch. There's also a rate limit for batch creation — typically one batch per 30 seconds. For very large disbursements (15,000+ recipients), split recipients across multiple batches and create them sequentially using a Retool Workflow with a wait block between each batch creation call.

---

Source: https://www.rapidevelopers.com/retool-integrations/paypal-payouts
© RapidDev — https://www.rapidevelopers.com/retool-integrations/paypal-payouts