I'm trying to send funds to a PayPal account via the PayPal REST Payouts API. The API call itself doesn't throw any errors, but the webhook notification I receive shows the payout failed and the recipient never gets the money. I initially thought the issue was with the recipient's account, but when I sent a payout directly through PayPal's official platform (not the REST API), the recipient received it successfully.

I can successfully send payouts to other PayPal accounts via the REST API, so the problem isn't with my sender account. Here's the webhook response from the failed payout:

{
    "batch_header": {
        "payout_batch_id": "5CUYYX9GRXXXX",
        "batch_status": "DENIED",
        "time_created": "2021-07-30T09:03:36Z",
        "time_completed": "2021-07-30T09:03:39Z",
        "time_closed": "2021-07-30T09:03:39Z",
        "sender_batch_header": {
            "sender_batch_id": "6318914d-8506-4182-be21-xxxxxxx",
            "email_subject": "You have money!",
            "email_message": "You received a payment. Thanks for using our service!"
        },
        "funding_source": "BALANCE",
        "amount": {
            "currency": "USD",
            "value": "1.00"
        },
        "fees": {
            "currency": "USD",
            "value": "0.00"
        }
    },
    "items": [
        {
            "payout_item_id": "APW3A3DKHDXXX",
            "transaction_status": "FAILED",
            "payout_item_fee": {
                "currency": "USD",
                "value": "0.00"
            },
            "payout_batch_id": "5CUYYX9GXXXXX",
            "payout_item": {
                "recipient_type": "EMAIL",
                "amount": {
                    "currency": "USD",
                    "value": "1.00"
                },
                "receiver": "rmxxxxx@gmail.com",
                "sender_item_id": "2014031400XXX",
                "recipient_wallet": "PAYPAL"
            },
            "time_processed": "2021-07-30T09:03:39Z",
            "errors": {
                "name": "UNDEFINED",
                "message": "Sorry, an error has occurred. For help, please contact your account manager or our Customer Service team. You can also try sending the Payout after sometime.",
                "information_link": "https://developer.paypal.com/docs/api/payments.payouts-batch/#errors",
                "details": [],
                "links": []
            },
            "links": [
                {
                    "href": "https://api.paypal.com/v1/payments/payouts-item/APW3A3DKHXXXX",
                    "rel": "item",
                    "method": "GET",
                    "encType": "application/json"
                }
            ]
        }
    ],
    "links": [
        {
            "href": "https://api.paypal.com/v1/payments/payouts/5CUYYX9GRGX2L?page_size=1000&page=1",
            "rel": "self",
            "method": "GET",
            "encType": "application/json"
        }
    ]
}

The response doesn't provide specific error details. Has any other developer encountered this kind of UNDEFINED error in webhooks without concrete details, and why can't I send payouts to certain recipients via the REST API when manual payouts work?

Answer #

This is a frustrating issue that many PayPal Payouts API developers have run into, and the UNDEFINED error typically points to internal PayPal logic or system checks that aren't exposed in public API responses. Here's what's likely happening, along with actionable steps to resolve it:

1. Separate Risk Rules for API vs Manual Payouts #

PayPal uses distinct risk assessment pipelines for API-initiated transactions versus manual platform payouts. Your API request might be triggering an automated rule that doesn't apply to manual payments:

• The recipient's account could have a history of unusual activity that flags automated API payouts, but manual payments get a different review tier.
• Your API's transaction pattern (like frequent small amounts, consistent sender-recipient pairs, or batch frequency) might trigger fraud prevention checks that manual payouts bypass.

2. Recipient Account Restrictions for API Payments #

Some PayPal accounts have default settings that block payments initiated via APIs, even if they accept manual payments. The recipient should:

• Check their account settings to ensure they allow payments from third-party APIs.
• Verify their account fully (if it's new or limited) to unlock API payment capabilities.

3. Subtle Request Parameter Issues #

Even if your request looks valid, minor inconsistencies could be causing the failure:

• Ensure sender_batch_id is unique for every payout batch—reusing IDs can confuse PayPal's systems.
• Double-check the receiver email for hidden characters (like trailing spaces) that aren't obvious but break API validation (even if manual entry works).
• Try removing non-essential parameters like recipient_wallet—PayPal often infers this automatically, and extra parameters can sometimes trigger unexpected checks.

4. Temporary PayPal System Glitch #

The error message explicitly suggests trying again later, which hints this could be a transient issue. PayPal might have had a temporary restriction on the recipient's account or a system hiccup that prevented the API payout from processing, even while manual payments worked.

Steps to Fix This #

• Contact PayPal Merchant Support: Provide your payout_batch_id and payout_item_id—only PayPal's internal team can look up the specific reason behind the UNDEFINED error, as public API responses don't expose this detail.
• Ask the recipient to review their account: Have them check for notifications or restrictions related to receiving automated payments in their PayPal settings.
• Retry after a delay: Follow the error message's advice and try the payout again in a few hours or the next day.
• Test with minimal parameters: Strip down your API request to only required fields (recipient email, amount, unique sender batch ID) to rule out parameter-related issues.

内容的提问来源于stack exchange，提问作者Pragadeesh Raj