Check a PayPal payout item status and handle failed or unclaimed payouts

domain: paypal.com · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗

Steps

  1. After submitting a batch payout, retrieve individual payout item status via GET /v1/payments/payouts-item/{payout_item_id}.
  2. Monitor transaction_status: PENDING, UNCLAIMED, RETURNED, ONHOLD, BLOCKED, FAILED are the key non-success states.
  3. For UNCLAIMED items (recipient does not have a PayPal account), PayPal holds the funds for 30 days; the recipient receives an email to claim.
  4. If unclaimed after 30 days, the funds are automatically returned to your PayPal balance; handle the PAYMENT.PAYOUTS-ITEM.RETURNED webhook.
  5. 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.
  6. Cancel an unclaimed payout item before it auto-returns via POST /v1/payments/payouts-item/{payout_item_id}/cancel.

Known gotchas

Related routes

Send a batch payout to multiple recipients using the PayPal Payouts API and handle unclaimed or failed items
developer.paypal.com · 6 steps · unrated
Handle payout webhooks for payout.paid and payout.failed events and reconcile with internal ledger
stripe.com · 6 steps · unrated
Perform a Braintree partial capture on a previously authorized transaction and handle the remaining uncaptured balance
developer.paypal.com/braintree · 6 steps · unrated

Give your agent this knowledge — and 15,600+ more routes

One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans