Webhook event names
PayPal supports these webhook events:
- Payments
- Batch payouts
- Billing plans and agreements
- Log in with PayPal
- Checkout buyer approval
- Disputes
- Invoicing
- Marketplaces and Platforms
- Merchant onboarding
- Orders
- Payment orders
- Referenced payouts
- Sales
- Subscriptions
- Payment Method Tokens
Payments
The webhooks for authorizing and capturing payments correspond to both supported versions of the Payments API:
Note: PayPal supports only PayPal authorizations.
Payments V2
| Event | Trigger | Related method |
|---|---|---|
PAYMENT.AUTHORIZATION.CREATED | A payment authorization is created, approved, executed, or a future payment authorization is created. | Capture authorized payment |
PAYMENT.AUTHORIZATION.VOIDED | A payment authorization is voided either due to authorization reaching it’s 30 day validity period or authorization was manually voided using the Void Authorized Payment API. | Show details for authorized payment with response status of voided. |
PAYMENT.CAPTURE.DECLINED | A payment capture is declined. | Capture authorized payment with status of declined. |
PAYMENT.CAPTURE.COMPLETED | A payment capture completes. | Capture authorized payment with response status of completed. |
PAYMENT.CAPTURE.PENDING | The state of a payment capture changes to pending. | Show details for authorized payment with response status of pending. |
PAYMENT.CAPTURE.REFUNDED | A merchant refunds a payment capture. | Capture authorized payment with response status of refunded. |
PAYMENT.CAPTURE.REVERSED | PayPal reverses a payment capture. | Refund captured payment |
Payments V1
| Event | Trigger | Related method |
|---|---|---|
PAYMENT.AUTHORIZATION.CREATED | A payment authorization is created, approved, executed, or a future payment authorization is created. | Create payment with intent set to authorize |
PAYMENT.AUTHORIZATION.VOIDED | A payment authorization is voided. | Void authorization |
PAYMENT.CAPTURE.COMPLETED | A payment capture completes. | Show captured payment details |
PAYMENT.CAPTURE.DENIED | A payment capture is denied. | Show captured payment details |
PAYMENT.CAPTURE.PENDING | The state of a payment capture changes to pending. | Show captured payment details |
PAYMENT.CAPTURE.REFUNDED | A merchant refunds a payment capture. | Refund captured payment |
PAYMENT.CAPTURE.REVERSED | PayPal reverses a payment capture. | Refund captured payment |
Batch payouts
Note: ThePAYOUTSBATCHwebhooks do not contain item-related information.To get item-related information, use the HATEOAS links from the webhooks response.
| Event | Trigger | Related method |
|---|---|---|
PAYMENT.PAYOUTSBATCH.DENIED | A batch payout payment is denied. | Show payout details |
PAYMENT.PAYOUTSBATCH.PROCESSING | The state of a batch payout payment changes to processing. | Show payout details |
PAYMENT.PAYOUTSBATCH.SUCCESS | A batch payout payment completes successfully. | Show payout details |
PAYMENT.PAYOUTS-ITEM.BLOCKED | A payouts item is blocked. | Show payout item details |
PAYMENT.PAYOUTS-ITEM.CANCELED | A payouts item is canceled. | Cancel unclaimed payout item |
PAYMENT.PAYOUTS-ITEM.DENIED | A payouts item is denied. | Show payout item details |
PAYMENT.PAYOUTS-ITEM.FAILED | A payouts item fails. | Show payout item details |
PAYMENT.PAYOUTS-ITEM.HELD | A payouts item is held. | Show payout item details |
PAYMENT.PAYOUTS-ITEM.REFUNDED | A payouts item is refunded. | Show payout item details |
PAYMENT.PAYOUTS-ITEM.RETURNED | A payouts item is returned. | Show payout item details |
PAYMENT.PAYOUTS-ITEM.SUCCEEDED | A payouts item succeeds. | Show payout item details |
PAYMENT.PAYOUTS-ITEM.UNCLAIMED | A payouts item is unclaimed. | Show payout item details |
Billing plans and agreements
Deprecation notice: The billing plans and agreements webhooks are deprecated along with the Billing Agreements REST API.
| Event | Trigger | Related method |
|---|---|---|
BILLING.PLAN.CREATED | A billing plan is created. | Create billing plan |
BILLING.PLAN.UPDATED | A billing plan is updated. | Update billing plan |
BILLING.SUBSCRIPTION.CANCELLED | A billing agreement is canceled. | Cancel agreement |
BILLING.SUBSCRIPTION.CREATED | A billing agreement is created. | Create agreement |
BILLING.SUBSCRIPTION.RE-ACTIVATED | A billing agreement is re-activated. | Re-activate agreement |
BILLING.SUBSCRIPTION.SUSPENDED | A billing agreement is suspended. | Suspend agreement |
BILLING.SUBSCRIPTION.UPDATED | A billing agreement is updated. | Update agreement |
Log in with PayPal
| Event | Trigger | Related method |
|---|---|---|
IDENTITY.AUTHORIZATION-CONSENT.REVOKED | A user's consent token is revoked. | Not applicable |
Checkout buyer approval
| Event | Triggered when | Related method | |
|---|---|---|---|
PAYMENTS.PAYMENT.CREATED | Checkout payment is created and approved by buyer. | Payment details | |
CHECKOUT.ORDER.APPROVED | A buyer approved a checkout order | Orders | |
CHECKOUT.CHECKOUT.BUYER-APPROVED | Express checkout payment is created and approved by buyer. | Express Checkout | |
Disputes
| Event | Trigger | Related method |
|---|---|---|
CUSTOMER.DISPUTE.CREATED | A dispute is created. | N/A |
CUSTOMER.DISPUTE.RESOLVED | A dispute is resolved. | Settle dispute |
CUSTOMER.DISPUTE.UPDATED | A dispute is updated. | Partially update dispute |
RISK.DISPUTE.CREATED | A risk dispute is created. | The CUSTOMER.DISPUTE.CREATED event type supersedes and deprecates this event type. |
Invoicing
| Event | Trigger | Related method |
|---|---|---|
INVOICING.INVOICE.CANCELLED | A merchant or customer cancels an invoice. | Cancel invoice |
INVOICING.INVOICE.CREATED | An invoice is created. | Create draft invoice |
INVOICING.INVOICE.PAID | An invoice is paid, partially paid, or payment is made and is pending. | Mark invoice as paid |
INVOICING.INVOICE.REFUNDED | An invoice is refunded or partially refunded. | Mark invoice as refunded |
INVOICING.INVOICE.SCHEDULED | An invoice is scheduled. | Schedule invoice |
INVOICING.INVOICE.UPDATED | An invoice is updated. | Update invoice |
Marketplaces and Platforms
| Event | Triggered When | Related method |
|---|---|---|
CHECKOUT.ORDER.COMPLETED | See CHECKOUT.ORDER.COMPLETED. | |
CHECKOUT.ORDER.APPROVED | See CHECKOUT.ORDER.APPROVED. | |
CHECKOUT.ORDER.PROCESSED | See CHECKOUT.ORDER.PROCESSED. | |
CUSTOMER.ACCOUNT-LIMITATION.ADDED | A limitation is added for a partner's managed account. | Update managed account |
CUSTOMER.ACCOUNT-LIMITATION.ESCALATED | A limitation is escalated for a partner's managed account. | Update managed account |
CUSTOMER.ACCOUNT-LIMITATION.LIFTED | A limitation is lifted for a partner's managed account. | Update managed account |
CUSTOMER.ACCOUNT-LIMITATION.UPDATED | A limitation is updated for a partner's managed account. | Update managed account |
CUSTOMER.MERCHANT-INTEGRATION.CAPABILITY-UPDATED | PayPal must enable the merchant's account as PPCP for this webhook to work. | Create partner referral |
CUSTOMER.MERCHANT-INTEGRATION.PRODUCT-SUBSCRIPTION-UPDATED | The products available to the merchant have changed. | Create partner referral |
CUSTOMER.MERCHANT-INTEGRATION.SELLER-ALREADY-INTEGRATED | Merchant onboards again to a partner. | Create partner referral |
CUSTOMER.MERCHANT-INTEGRATION.SELLER-ONBOARDING-INITIATED | PayPal creates a merchant account from the partner's onboarding link. | Create partner referral |
CUSTOMER.MERCHANT-INTEGRATION.SELLER-CONSENT-GRANTED | Merchant grants consents to a partner. | Create partner referral |
CUSTOMER.MERCHANT-INTEGRATION.SELLER-EMAIL-CONFIRMED | Merchant confirms the email and consents are granted. | Create partner referral |
MERCHANT.ONBOARDING.COMPLETED | Merchant completes setup. | See MERCHANT.ONBOARDING.COMPLETED in Merchant onboarding |
MERCHANT.PARTNER-CONSENT.REVOKED | The consents for a merchant account setup are revoked or an account is closed. | See MERCHANT.PARTNER-CONSENT.REVOKED in Merchant onboarding |
PAYMENT.CAPTURE.COMPLETED | A payment capture completes. | See PAYMENT.CAPTURE.COMPLETED in Payments |
PAYMENT.CAPTURE.DENIED | A payment capture is denied. | See PAYMENT.CAPTURE.DENIED in Payments |
PAYMENT.CAPTURE.REFUNDED | A merchant refunds a payment capture. | See PAYMENT.CAPTURE.REFUNDED in Payments |
PAYMENT.REFERENCED-PAYOUT-ITEM.COMPLETED | Funds are disbursed to the seller and partner. | See PAYMENT.REFERENCED-PAYOUT-ITEM.COMPLETE in Payments |
PAYMENT.REFERENCED-PAYOUT-ITEM.FAILED | Attempt to disburse funds fails. | See PAYMENT.REFERENCED-PAYOUT-ITEM.FAILED in Payments |
Merchant onboarding
| Event | Trigger | Related method |
|---|---|---|
MERCHANT.ONBOARDING.COMPLETED | A merchant completes setup. | Seller Onboarding |
MERCHANT.PARTNER-CONSENT.REVOKED | The consents for a merchant account setup are revoked or an account is closed. | Seller Onboarding |
CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-CREATED | Managed account has been created. | Managed Path Onboarding |
CUSTOMER.MANAGED-ACCOUNT.CREATION-FAILED | Managed account creation failed. | Managed Path Onboarding |
CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-UPDATED | Managed account has been updated. | Managed Path Onboarding |
CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-STATUS-CHANGED | Capabilities and/or process status has been changed on a managed account. | Managed Path Onboarding |
CUSTOMER.MANAGED-ACCOUNT.RISK-ASSESSED | Managed account has been risk assessed or the risk assessment has been changed. | Managed Path Onboarding |
CUSTOMER.MANAGED-ACCOUNT.NEGATIVE-BALANCE-NOTIFIED | Negative balance debit has been notified on a managed account. | Update managed account |
CUSTOMER.MANAGED-ACCOUNT.NEGATIVE-BALANCE-DEBIT-INITIATED | Negative balance debit has been initiated on a managed account. | Update managed account |
CUSTOMER.ACCOUNT-LIMITATION.ADDED | A limitation was added for given merchant account. | Update managed account |
CUSTOMER.ACCOUNT-LIMITATION.LIFTED | A limitation was lifted for given merchant account. | Update managed account |
CUSTOMER.ACCOUNT-LIMITATION.UPDATED | A limitation was updated for given merchant account. | Update managed account |
CUSTOMER.ACCOUNT-LIMITATION.ESCALATED | A limitation was escalated for given merchant account. | Update managed account |
Orders
The webhooks for orders correspond to both supported versions of the Orders API:
Orders V2
| Event | Trigger | Related method |
|---|---|---|
CHECKOUT.ORDER.COMPLETED | A checkout order is processed. Note: For use by marketplaces and platforms only. | Orders API |
CHECKOUT.ORDER.APPROVED | A buyer approved a checkout order | Orders API |
CHECKOUT.PAYMENT-APPROVAL.REVERSED | A problem occurred after the buyer approved the order but before you captured the payment. Refer to Handle uncaptured payments for what to do when this event occurs. | Orders API |
Orders V1
| Event | Trigger | Related method |
|---|---|---|
CHECKOUT.ORDER.PROCESSED | A checkout order is processed. | Orders API |
Payment orders
| Event | Trigger | Related method |
|---|---|---|
PAYMENT.ORDER.CANCELLED | A payment order is canceled. | Void order |
PAYMENT.ORDER.CREATED | A payment order is created. | Create payment |
Referenced payouts
| Event | Trigger | Related method |
|---|---|---|
PAYMENT.REFERENCED-PAYOUT-ITEM.COMPLETED | Funds are disbursed to the seller and partner. | Create referenced payout item |
PAYMENT.REFERENCED-PAYOUT-ITEM.FAILED | Attempt to disburse funds fails. | Create referenced payout item |
Sales
| Event | Trigger | Related method |
|---|---|---|
PAYMENT.SALE.COMPLETED | A sale completes. | Show sale details |
PAYMENT.SALE.DENIED | The state of a sale changes from pending to denied. | Show sale details |
PAYMENT.SALE.PENDING | The state of a sale changes to pending. | Show sale details |
PAYMENT.SALE.REFUNDED | A merchant refunds a sale. | Refund sale |
PAYMENT.SALE.REVERSED | PayPal reverses a sale. | Refund sale |
Subscriptions
| Webhook | Trigger | Related method |
|---|---|---|
CATALOG.PRODUCT.CREATED | A product is created. | Create product |
CATALOG.PRODUCT.UPDATED | A product is updated. | Update product |
PAYMENT.SALE.COMPLETED | A payment is made on a subscription. | |
PAYMENT.SALE.REFUNDED | A merchant refunds a sale. | |
PAYMENT.SALE.REVERSED | A payment is reversed on a subscription. | |
BILLING.PLAN.CREATED | A billing plan is created. | Create plan |
BILLING.PLAN.UPDATED | A billing plan is updated. | Update plan |
BILLING.PLAN.ACTIVATED | A billing plan is activated. | Activate plan |
BILLING.PLAN.PRICING-CHANGE.ACTIVATED | A price change for the plan is activated. | Update pricing |
BILLING.PLAN.DEACTIVATED | A billing plan is deactivated. | Deactivate plan |
BILLING.SUBSCRIPTION.CREATED | A subscription is created. | Create subscription |
BILLING.SUBSCRIPTION.ACTIVATED | A subscription is activated. | Activate subscription |
BILLING.SUBSCRIPTION.UPDATED | A subscription is updated. | Update subscription |
BILLING.SUBSCRIPTION.EXPIRED | A subscription expires. | Show subscription details |
BILLING.SUBSCRIPTION.CANCELLED | A subscription is cancelled. | Cancel subscription |
BILLING.SUBSCRIPTION.SUSPENDED | A subscription is suspended. | Suspend subscription |
BILLING.SUBSCRIPTION.PAYMENT.FAILED | Payment failed on subscription. | Subscription failed payment details |
Payment Method Tokens
The Payment Method Tokens API saves payment methods to a digital vault so payers don't have to enter details for future transactions. Payers can check out faster or pay without being present after they agree to save a payment method.
| Event | Trigger | Payment methods |
|---|---|---|
VAULT.PAYMENT-TOKEN.CREATED | A payment token is created to save a payment method. | Cards and PayPal |
VAULT.PAYMENT-TOKEN.DELETED | A payment token is deleted. The payer's payment method is no longer saved to the PayPal vault. | Cards and PayPal |
VAULT.PAYMENT-TOKEN.DELETION-INITIATED | A request to delete a payment token has been submitted to the Payment Method Tokens API. | PayPal |