After submitting a batch payout, retrieve individual payout item status via GET /v1/payments/payouts-item/{payout_item_id}.
Monitor transaction_status: PENDING, UNCLAIMED, RETURNED, ONHOLD, BLOCKED, FAILED are the key non-success states.
For UNCLAIMED items (recipient does not have a PayPal account), PayPal holds the funds for 30 days; the recipient receives an email to claim.
If unclaimed after 30 days, the funds are automatically returned to your PayPal balance; handle the PAYMENT.PAYOUTS-ITEM.RETURNED webhook.
For FAILED items, inspect the errors array for the error code and message, correct the receiver information, and re-submit as a new payout item.
Cancel an unclaimed payout item before it auto-returns via POST /v1/payments/payouts-item/{payout_item_id}/cancel.
Known gotchas
UNCLAIMED payouts tie up your PayPal balance for up to 30 days; validate email addresses against known PayPal accounts before sending, or use phone numbers as receiver identifiers where supported.
There is no bulk cancel endpoint — each unclaimed item must be canceled individually.
PayPal sandbox behavior for unclaimed payouts may differ from production; test failure scenarios using PayPal's sandbox test accounts.
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