Create a batch payout via POST /v1/payments/payouts; provide a sender_batch_id for idempotency, an email_subject and email_message for recipient notification, and an items array with each recipient's receiver (email or PayPal merchant id), amount, and note
Poll the batch status via GET /v1/payments/payouts/{payout_batch_id} until batch_header.batch_status transitions to SUCCESS or DENIED; individual items may have a different status than the batch
Retrieve individual item statuses via GET /v1/payments/payouts-item/{payout_item_id}; items can be PENDING, UNCLAIMED, SUCCESS, RETURNED, FAILED, or BLOCKED
Handle UNCLAIMED items (recipient has no PayPal account) by deciding whether to wait for the recipient to claim within PayPal's unclaimed expiry window or cancel the item via POST /v1/payments/payouts-item/{payout_item_id}/cancel
For FAILED items, inspect payout_item_fee, errors, and transaction_status to determine the root cause (e.g., receiver account restrictions, currency mismatch) and retry with corrected parameters
Use the sender_batch_id for deduplication — resubmitting a batch with the same sender_batch_id within a validity window returns the original batch rather than creating a duplicate
Known gotchas
Batch payouts are processed asynchronously — do not poll too aggressively; use exponential backoff and respect PayPal's rate limits on the batch status endpoint to avoid throttling
PayPal Payouts API access requires separate enablement and may not be available on all account types — verify your PayPal app has Payouts scope and that your account is approved for live payouts before testing in production
Unclaimed payouts are held for a period defined by PayPal (consult current docs for the exact duration) before being returned; if your use case requires immediate fund availability confirmation, consider whether PayPal Payouts is the right rail or if a different method is more appropriate
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp