Paying payees with PayPal
Enabling PayPal Payouts for your business account, choosing the REST app, webhook events, unclaimed and returned payouts, sandbox testing and common errors.
PayPal Payouts sends money from your PayPal Business account to payees' PayPal addresses, many at once. Each payout batch here becomes one PayPal payout batch.
1. Get Payouts enabled#
Payouts is not on by default for live accounts. In your PayPal Business account, request access to Payouts (PayPal reviews it; have your business details ready). Sandbox business accounts can use Payouts at once.
2. Use your REST app#
Payouts uses the same REST app as your PayPal credential set (developer.paypal.com → Apps & Credentials). Choose that set under Payouts → Settings → PayPal REST app. A Live set pays Live batches; a Sandbox set pays Test batches. A set connected through the platform's partner application cannot be used.
3. Add the payout events to the webhook#
On developer.paypal.com → your app → your webhook, add the events listed on the settings page: PAYMENT.PAYOUTS-ITEM.SUCCEEDED, …FAILED, …RETURNED, …UNCLAIMED, …BLOCKED, …CANCELED, …DENIED, …REFUNDED, PAYMENT.PAYOUTSBATCH.SUCCESS, PAYMENT.PAYOUTSBATCH.DENIED. Without them the system still asks PayPal every 15 minutes.
What payees see#
PayPal e-mails the payee when money arrives. A payee without a PayPal account at that address gets a sign-up invitation; the payout is Unclaimed until they accept it. PayPal returns unclaimed money to you after 30 days: the payout becomes Returned and its amount is back on the payee's balance. Correct the address on the payee's page and the next batch sends it again. You need not wait the 30 days: Cancel unclaimed on the batch page asks PayPal to cancel the item (POST /v1/payments/payouts-item/{id}/cancel); the money returns to your PayPal balance and to the payee's balance here at once. PayPal only cancels items that are still unclaimed.
PayPal may charge a fee per payout item, taken from your PayPal balance; payees receive the full amount.
Sandbox test#
- Sandbox PayPal set chosen in Settings; a test product with a revenue share; a payee (PayPal) with a sandbox personal account address.
- Pay the product with a sandbox buyer.
- Payouts → Test mode → Build a test batch → Send. The payout is Sent, then Paid when the sandbox reports SUCCESS.
Common errors#
| Message | Fix |
|---|---|
| Payouts is not enabled for this account | Step 1. |
| Insufficient funds | Your PayPal balance cannot cover the batch; add funds and build the next batch. |
| Receiver is unregistered / blocked | The address cannot receive; change it on the payee's page. |
| ITEM_CANNOT_BE_CANCELLED | The item is no longer unclaimed (claimed, paid or already returned); nothing changed. |