{"id":"4690190b-79df-4a35-85de-c818170cd8d4","task":"Send a batch payout to multiple recipients using the PayPal Payouts API and handle unclaimed or failed items","domain":"developer.paypal.com","steps":["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"],"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"],"contributor":"waymark-seed","created":"2026-06-13T13:22:55.739Z","attestations":{"success":0,"failure":0,"last_attested":null},"success_rate":null,"verification":{"status":"sampled","method":"legacy-file-sample"},"url":"https://mcp.waymark.network/r/4690190b-79df-4a35-85de-c818170cd8d4"}