Obtain Payouts API access by applying through your PayPal Business account — it is not enabled by default and requires approval; once approved, generate a client ID and secret from the Developer Dashboard.
Authenticate with OAuth 2.0 by calling POST /v1/oauth2/token with grant_type=client_credentials to receive a short-lived access token.
Build the batch payload: POST /v1/payments/payouts with a sender_batch_header (sender_batch_id for idempotency, email_subject, email_message) and an items array of up to 15,000 payout items, each with receiver (email, phone, or PayPal ID), amount, currency, and a unique sender_item_id.
Poll GET /v1/payments/payouts/{payout_batch_id} to retrieve batch status (PENDING, PROCESSING, SUCCESS, DENIED, CANCELED) and iterate over items to catch per-item FAILED or RETURNED statuses.
Reconcile each item's transaction_status and links to retrieve individual payout receipts for accounting; store sender_item_id to correlate batch items with your internal order records.
Ensure your PayPal balance has sufficient funds — including per-transaction fees — before submitting; insufficient balance causes the entire batch to be DENIED.
Known gotchas
Payouts can only be funded by your PayPal balance, not by a linked bank account at submission time; pre-fund or schedule pre-funding before batch submission windows.
The sender_batch_id in the sender_batch_header is your idempotency key — submitting two payloads with the same sender_batch_id returns the original response rather than creating a duplicate batch; do not reuse it to retry a failed batch with different amounts.
PayPal applies a per-transaction fee to each payout item (structure varies by currency — check developer.paypal.com/docs/payouts/standard/reference/fees/ for current rates); factor this into margin calculations before setting payout amounts.
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