Skip to main content

Webhook reference

This guide explains the webhook events for batch payouts and individual payout items. These webhooks notify your application about the status and changes in payout processes, enabling real-time updates and automation.

Batch payouts​

These webhooks notify you when the overall status of a batch payout changes:

EventTriggerRelated method
PAYMENT.PAYOUTSBATCH.DENIEDThe entire batch payout is denied; no funds were released.Use Show payout details to review error codes and batch-level issues. Investigate funding source or account permissions, then consider retrying the payout.
PAYMENT.PAYOUTSBATCH.PROCESSINGThe batch payout request is received and is being processed.Use Show payout details or await item-level webhooks to monitor per-recipient progress. Update internal status accordingly.
PAYMENT.PAYOUTSBATCH.SUCCESSA batch payout payment completes successfully.Verify via Show payout details. Check for any held or unclaimed items and finalize your internal records or triggers for business logic.

Note: The PAYOUTSBATCH webhooks do not contain item-related information. To get item-related information, use the HATEOAS links from the webhooks response.

Individual payout items​

These webhooks provide updates on the status of individual payout items within a batch:

EventTriggerRelated method
PAYMENT.PAYOUTS-ITEM.SUCCEEDEDThe payout item was processed successfully—funds were credited to the recipient’s account.Use Show payout item details to confirm transaction_status == SUCCESS. Update your system to reflect the delivery and notify the recipient.
PAYMENT.PAYOUTS-ITEM.REFUNDEDA refund was initiated by the recipient’s business account—funds were returned to the sender.Call Show payout item details to get refund info. Mark the payout as refunded, reconcile balances, and notify the sender about the refund.
PAYMENT.PAYOUTS-ITEM.RETURNEDThe payout item was returned—typically due to being unclaimed or canceled—and funds have been credited back to the sender.Retrieve error details via Show payout item details. Log the return, refund the sender, and optionally retry the payout after resolving the issue.
PAYMENT.PAYOUTS-ITEM.UNCLAIMEDThe payout item remains unclaimed—PayPal sent a signup link to the recipient, and if not claimed within 30 days, funds will return.Use Show payout item details to check the 30‑day claim window. Notify the recipient or proactively retry if they’ve created an account. Consider automatic refund workflow after expiration. To cancel unclaimed items, use Cancel unclaimed payout item.
PAYMENT.PAYOUTS-ITEM.FAILEDThe payout item failed during processing due to a recipient account error or system issue—no funds were removed.Inspect the error message via Show payout item details. Classify failure, alert support, and attempt retry after fixing the underlying issue or switch payment method.
PAYMENT.PAYOUTS-ITEM.DENIEDThe payout item got rejected—typically due to insufficient funds, account limitations, or compliance issues.Fetch details via Show payout item details. Address denial reason (e.g., funding or account issues). Decide whether to retry or cancel. Notify sender of the denial.
PAYMENT.PAYOUTS-ITEM.CANCELEDThe sender canceled the payout item before processing began.Confirm cancellation via Show payout item details. Update your system, stop any further retries, and notify the recipient if necessary.
PAYMENT.PAYOUTS-ITEM.BLOCKEDPayPal's risk or compliance systems blocked the payout item—processing has been halted.Call Show payout item details for risk context. Engage PayPal support or compliance team. Hold for resolution or cancel based on risk outcome.
PAYMENT.PAYOUTS-ITEM.HELDThe payout item is temporarily on hold pending further verification or security review.Pull details via Show payout item details. Depending on hold reason (e.g., KYC or limits), take appropriate action: submit documents, wait, or cancel. Notify stakeholders.

Webhook resources don't contain error objects. If you receive a webhook for a failed payout and would like to understand why the payout failed, do a GET request on the object. For more details, see Webhook event names.

Handling Webhook Events​

  1. Configure your webhook endpoint in the PayPal Developer Dashboard.
  2. Parse incoming webhook payloads to identify the event type and resource.
  3. Update your application state based on the event. For example:
    • Mark a payout as completed when receiving PAYMENT.PAYOUTS-ITEM.SUCCEEDED.
    • Notify recipients or trigger business logic on failure or denial events.
  4. Use HATEOAS links in the webhook payload to fetch additional details about the payout batch or item.

Sample webhook payload​

A typical webhook notification includes the event type, resource, and HATEOAS links:

{
  "event_type": "PAYMENT.PAYOUTS-ITEM.SUCCEEDED",
  "resource": {
    "payout_item_id": "XXXXXXXXXX",
    "transaction_status": "SUCCESS",
    "links": [
      {
        "href": "https://api.paypal.com/v1/payments/payouts-item/XXXXXXXXXX",
        "rel": "self",
        "method": "GET"
      }
    ]
  }
}

See also​