Obtain an access token via POST /v1/oauth2/token with your client credentials using Basic Auth.
Construct a batch payout body with sender_batch_header (sender_batch_id for idempotency, email_subject, recipient_type) and a list of items each containing receiver, amount, and note.
Submit the batch via POST /v1/payments/payouts; save the returned payout_batch_id.
Poll the batch status via GET /v1/payments/payouts/{payout_batch_id} until batch_status is 'SUCCESS' or 'DENIED'.
For individual item failures, inspect each payout item's transaction_status and errors array; re-queue failed items with corrected data.
Subscribe to PAYMENT.PAYOUTSBATCH.DENIED and PAYMENT.PAYOUTS-ITEM.FAILED webhook events for asynchronous failure notification.
Known gotchas
sender_batch_id must be unique per batch submission; reusing it within a 30-day window returns the existing batch rather than creating a new one — use this for safe retries only.
PayPal Payouts API requires your account to have payout permissions enabled; request this from PayPal before testing in sandbox.
Individual payout items within a batch can fail independently — always check per-item status, not just the batch-level status.
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