Get started

PayPal new dispute notifications on your phone.

Get a push notification the moment a buyer opens a PayPal dispute, claim or chargeback, with the reason and the date you must respond by.

Install in Studio See the setup
CUSTOMER.DISPUTE.CREATEDPayments & billingFailed payments & disputes
How it works

Three steps to your first push

STEP 01

Install the recipe

One click in Studio gives you a personal webhook URL.

STEP 02

Paste your URL into PayPal

Add it as a webhook for CUSTOMER.DISPUTE.CREATED.

STEP 03

Get a push on your phone

With the text, sound and buttons from the recipe.

Setup

How to set up the PayPal customer.dispute.created webhook

  1. Click Install in Studio and sign in. The recipe is added to your account and you get a personal webhook URL.
  2. In the PayPal Developer Dashboard, open Apps & Credentials, switch to Sandbox or Live, and open the REST app that takes your payments.
  3. Under Webhooks, click Add Webhook and paste your webhook URL as the Webhook URL.https://••••••••/•••••••• your personal URL, shown after install
  4. Tick the CUSTOMER.DISPUTE.CREATED event and save.
  5. Tick **CUSTOMER.DISPUTE.CREATED** (it may be listed as *Customer dispute created*). You don't need the older **RISK.DISPUTE.CREATED**: PayPal has replaced it with this event, and this recipe ignores it.
  6. The push is titled by stage:
  7. **New dispute**: an inquiry between you and the buyer. High priority.
  8. **New claim**: the buyer escalated it, or it opened directly as a claim. Highest priority.
  9. **New chargeback**: the buyer's card issuer filed it. Highest priority.
  10. The **Respond** button opens the Resolution Center. To test in the sandbox, log in as a sandbox buyer and open a case on a sandbox payment. It can take a few minutes for PayPal to send the webhook.
  11. Sandbox events are recognised from their API links and marked **(sandbox)**; add `?sandbox=1` to the URL to force that.
  12. PayPal signs every delivery (`PAYPAL-TRANSMISSION-SIG`, checked against a certificate and your webhook ID), but JustPush doesn't check that signature yet, so keep your endpoint URL private.
The code

What runs when the webhook arrives

Studio calls handleRequest(request) with the incoming webhook and sends the message it returns. It's yours after install; change anything.

transform.js
1// PayPal → CUSTOMER.DISPUTE.CREATED
2// Fires when a buyer opens a dispute or claim, or a card issuer files a chargeback.
3// Docs: https://developer.paypal.com/api/rest/webhooks/event-names/#disputes
4//
5// PayPal sends no event-type header, so the event is read from the body's event_type.
6
7// Readable dispute reasons. Unlisted ones (including OTHER) are left out.
8const REASONS = {
9 MERCHANDISE_OR_SERVICE_NOT_RECEIVED: "item not received",
10 MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED: "not as described",
11 UNAUTHORISED: "unauthorised payment",
12 CREDIT_NOT_PROCESSED: "refund not processed",
13 DUPLICATE_TRANSACTION: "duplicate payment",
14 INCORRECT_AMOUNT: "incorrect amount",
15 PAYMENT_BY_OTHER_MEANS: "paid by other means",
16 CANCELED_RECURRING_BILLING: "cancelled subscription still billed",
17 PROBLEM_WITH_REMITTANCE: "problem with remittance",
18}
19
20// Lifecycle stages past the inquiry, where PayPal decides the case.
21const CLAIM_STAGES = {
22 CHARGEBACK: true,
23 PRE_ARBITRATION: true,
24 ARBITRATION: true,
25}
26
27// Look a key up without tripping over inherited names such as "toString".
28function pick(table, key, fallback = null) {
29 return typeof key === "string" && Object.prototype.hasOwnProperty.call(table, key) ? table[key] : fallback
30}
31
32// Only link to real http(s) URLs.
33function link(url, cta) {
34 return typeof url === "string" && /^https?:\/\//.test(url) ? [{ cta, url }] : []
35}
36
37// A non-empty string, or null.
38function text(value) {
39 return typeof value === "string" && value.trim() ? value.trim() : null
40}
41
42function flag(query, name) {
43 return ["1", "true", "yes"].includes(String(query?.[name] ?? "").toLowerCase())
44}
45
46// PayPal amounts are decimal strings, already in major units: { value: "10.00", currency_code: "USD" }.
47// Zero-decimal currencies such as JPY simply come without decimals ("500").
48function money(amount) {
49 const raw = amount?.value
50 const currency = amount?.currency_code
51
52 // Don't invent a figure when the event doesn't carry one.
53 if ((typeof raw !== "string" && typeof raw !== "number") || raw === "" || typeof currency !== "string" || !currency) return null
54
55 const value = Number(raw)
56 if (!Number.isFinite(value)) return null
57
58 try {
59 return new Intl.NumberFormat("en-GB", { style: "currency", currency }).format(value)
60 } catch {
61 return `${raw} ${currency}`
62 }
63}
64
65// A date like "8 Oct", in UTC (PayPal's due dates are UTC timestamps).
66function day(iso) {
67 const date = typeof iso === "string" ? new Date(iso) : null
68 if (!date || Number.isNaN(date.getTime())) return null
69
70 return date.toLocaleDateString("en-GB", { day: "numeric", month: "short", timeZone: "UTC" })
71}
72
73// Events carry no sandbox flag, but their API links point at api(-m).sandbox.paypal.com.
74// ?sandbox=1 on the webhook URL forces it.
75function isSandbox(event, query) {
76 if (flag(query, "sandbox")) return true
77
78 const links = [event.links, event.resource?.links].filter(Array.isArray).flat()
79 return links.some((l) => typeof l?.href === "string" && /^https:\/\/api(-m)?\.sandbox\.paypal\.com\//.test(l.href))
80}
81
82function handleRequest(request) {
83 const event = request.body && typeof request.body === "object" ? request.body : {}
84 const dispute = event.resource
85
86 // Guard: only new disputes, so other PayPal events on this integration stay quiet.
87 if (event.event_type !== "CUSTOMER.DISPUTE.CREATED" || !dispute || typeof dispute !== "object") {
88 console.log(`Ignoring PayPal "${typeof event.event_type === "string" ? event.event_type : "unknown"}" event`)
89 return null
90 }
91
92 // External disputes are card chargebacks; internal ones start as an inquiry between you and
93 // the buyer and can be escalated to a claim, which PayPal calls the CHARGEBACK stage.
94 const chargeback = dispute.dispute_channel === "EXTERNAL"
95 const inquiry = !chargeback && dispute.dispute_life_cycle_stage === "INQUIRY"
96 const claim = !chargeback && pick(CLAIM_STAGES, dispute.dispute_life_cycle_stage, false)
97 const kind = chargeback ? "chargeback" : claim ? "claim" : "dispute"
98
99 const transaction = Array.isArray(dispute.disputed_transactions) ? dispute.disputed_transactions[0] : null
100 const amount = money(dispute.dispute_amount) ?? money(transaction?.gross_amount) ?? "A payment"
101 const buyer = text(transaction?.buyer?.name)
102 const reason = pick(REASONS, dispute.reason)
103 const due = day(dispute.seller_response_due_date)
104 const sandbox = isSandbox(event, request.query)
105 const web = sandbox ? "https://www.sandbox.paypal.com" : "https://www.paypal.com"
106
107 return {
108 title: `⚖️ New ${kind}` + (sandbox ? " (sandbox)" : ""),
109 message:
110 `${amount} disputed` +
111 (buyer ? ` by ${buyer}` : "") +
112 (reason ? `: ${reason}` : "") +
113 (due ? `. Respond by ${due}.` : ""),
114 topic: "PayPal",
115 // Highest for claims and chargebacks: PayPal holds the money and the evidence clock is ticking.
116 // High for an inquiry: the buyer is waiting on your reply, but nothing is decided yet.
117 // An unknown stage counts as urgent.
118 priority: inquiry ? 1 : 2,
119 buttons: link(`${web}/disputes/dashboard/`, "Respond"),
120 }
121}
Payload

The PayPal CUSTOMER.DISPUTE.CREATED webhook

This is what PayPal sends to your URL for customer.dispute.created. It is a sample, trimmed to the fields recipes use.

CUSTOMER.DISPUTE.CREATED · sample.json
1{
2 "id": "WH-4M0448861G563140B-9EX36365822141321",
3 "links": [
4 {
5 "rel": "self",
6 "href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-4M0448861G563140B-9EX36365822141321",
7 "method": "GET"
8 },
9 {
10 "rel": "resend",
11 "href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-4M0448861G563140B-9EX36365822141321/resend",
12 "method": "POST"
13 }
14 ],
15 "resource": {
16 "links": [
17 {
18 "rel": "self",
19 "href": "https://api-m.paypal.com/v1/customer/disputes/PP-R-AYP-10135034",
20 "method": "GET"
21 }
22 ],
23 "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
24 "status": "WAITING_FOR_SELLER_RESPONSE",
25 "dispute_id": "PP-R-AYP-10135034",
26 "create_time": "2026-09-18T09:46:54.926Z",
27 "update_time": "2026-09-18T09:46:54.926Z",
28 "dispute_amount": {
29 "value": "42.00",
30 "currency_code": "USD"
31 },
32 "dispute_channel": "INTERNAL",
33 "disputed_transactions": [
34 {
35 "buyer": {
36 "name": "Jane Doe"
37 },
38 "items": [
39 {
40 "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
41 "item_name": "Ceramic mug",
42 "item_type": "PRODUCT",
43 "item_quantity": "1"
44 }
45 ],
46 "seller": {
47 "name": "The Happy Store",
48 "email": "[email protected]",
49 "merchant_id": "HAAP3SNYZZ9NG"
50 },
51 "create_time": "2026-09-18T09:42:33.000Z",
52 "gross_amount": {
53 "value": "42.00",
54 "currency_code": "USD"
55 },
56 "transaction_status": "HELD",
57 "buyer_transaction_id": "7XB07472F52871902",
58 "seller_transaction_id": "8AW70038VH226914P"
59 }
60 ],
61 "dispute_life_cycle_stage": "INQUIRY",
62 "seller_response_due_date": "2026-10-08T09:46:54.926Z"
63 },
64 "event_type": "CUSTOMER.DISPUTE.CREATED",
65 "create_time": "2026-09-18T09:47:02.513Z",
66 "event_version": "1.0",
67 "resource_type": "dispute"
68}
FAQ

PayPal new dispute notifications: questions

Does this work on iPhone and Android?

Yes. Install the JustPush app from the App Store or Google Play and sign in. Every phone signed in to your account gets the notification.

Do I need to write code?

No. Install the recipe in Studio, paste your webhook URL into PayPal and you are done. The code is there if you want to change the text, the sound or the buttons.

Can I change what the notification says?

Yes. After install the recipe's code is yours. Edit it in Studio and test it against the sample payload before you save.

What does it cost?

JustPush is free for 30 days. After that it's $19.99 a year, or $39.99 once. There is no extra charge for recipes.

More recipes

More from PayPal

PayPal

Payment denied

Get a High-priority push notification when a PayPal payment you were waiting on is denied or declined, with the reason when PayPal gives one.

PAYMENT.CAPTURE.DENIEDButtons
PayPal

Payment received

Get a push notification with the amount and what you keep after fees every time a PayPal payment is captured, including subscription payments.

PAYMENT.CAPTURE.COMPLETEDSoundButtons
PayPal

Refund issued

Get a low-priority push notification when a PayPal payment is fully or partially refunded, with the reason you gave the buyer.

PAYMENT.CAPTURE.REFUNDEDButtons

All 4 PayPal recipes

Failed payments & disputes

More failed payments & disputes recipes

Adyen

Chargeback

Get a Highest-priority push notification when a shopper disputes an Adyen payment, with the reason and the defense deadline, plus pushes for requests for information, second chargebacks and reversals.

CHARGEBACK
Adyen

Payment received or refused

Get a push notification with the amount, method and your reference every time an Adyen payment is authorised, and a High-priority one when a payment is refused.

AUTHORISATIONSound
Chargebee

Payment failed

Get a High-priority push notification when a Chargebee payment fails, with the gateway's reason, the card and the next retry date.

payment_failedButtons

All failed payments & disputes recipes

Ready when you are

PayPal on your phone in two minutes.

Install the recipe, paste one URL, done. Free for 30 days, no credit card required.

Install in Studio Download for iOS Download for Android