How to Integrate Retool with PayPal 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.

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

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

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.

1// JavaScript transformer for PayPal batch detail response
2const batch = data;
3const items = batch.items || [];
4
5const summary = {
6  batchId: batch.batch_header?.payout_batch_id,
7  status: batch.batch_header?.batch_status,
8  totalAmount: batch.batch_header?.amount?.value,
9  currency: batch.batch_header?.amount?.currency,
10  fundingSource: batch.batch_header?.funding_source,
11  timeCompleted: batch.batch_header?.time_completed
12    ? new Date(batch.batch_header.time_completed).toLocaleString()
13    : 'Processing...',
14  successCount: items.filter(i => i.transaction_status === 'SUCCESS').length,
15  failedCount: items.filter(i => i.transaction_status === 'FAILED').length,
16  unclaimedCount: items.filter(i => i.transaction_status === 'UNCLAIMED').length
17};
18
19const lineItems = items.map(item => ({
20  payoutItemId: item.payout_item_id,
21  recipient: item.payout_item?.receiver,
22  amount: `${item.payout_item?.amount?.currency} ${item.payout_item?.amount?.value}`,
23  status: item.transaction_status,
24  error: item.errors?.name || '',
25  errorMessage: item.errors?.message || '',
26  transactionId: item.transaction_id || 'N/A'
27}));
28
29return { summary, lineItems };

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.

1// POST /v1/payments/payouts
2// Create a payout batch from selected rows in the pending payouts table
3{
4  "sender_batch_header": {
5    "sender_batch_id": "{{ 'BATCH-' + new Date().getTime() }}",
6    "email_subject": "You have received a payment",
7    "email_message": "Thank you for your work. Please claim your payment.",
8    "recipient_type": "EMAIL"
9  },
10  "items": {{ pendingPayoutsTable.selectedRows.map((row, index) => ({
11    "payout_item_id": row.id || String(index + 1),
12    "recipient_type": "EMAIL",
13    "amount": {
14      "value": row.amount.toFixed(2),
15      "currency": "USD"
16    },
17    "receiver": row.paypalEmail,
18    "note": row.note || "Payment from platform",
19    "sender_item_id": row.internalId || String(row.id)
20  })) }}  
21}

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.

1// JavaScript transformer to calculate payout batch summary
2const selectedRows = pendingPayoutsTable.selectedRows || [];
3
4const summary = {
5  recipientCount: selectedRows.length,
6  totalAmount: selectedRows.reduce((sum, row) => sum + (parseFloat(row.amount) || 0), 0).toFixed(2),
7  currency: 'USD',
8  estimatedFee: (selectedRows.reduce((sum, row) => sum + (parseFloat(row.amount) || 0), 0) * 0.02).toFixed(2), // ~2% PayPal Payouts fee
9  currencies: [...new Set(selectedRows.map(r => r.currency || 'USD'))].join(', ')
10};
11
12return summary;