# 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.

- Company: PayPal (https://www.justpush.io/recipes/paypal)
- Event: `CUSTOMER.DISPUTE.CREATED` (CUSTOMER.DISPUTE.CREATED)
- Tags: Payments & billing, Failed payments & disputes
- Install: https://studio.justpush.io/recipes/paypal/dispute-created
- Web page: https://www.justpush.io/recipes/paypal/dispute-created

## Setup

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 (shown in Studio after install) as the Webhook URL.
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.

## Code

Studio calls `handleRequest(request)` with the incoming webhook (`{ method, headers, body, query, raw }`) and sends the message object it returns. Returning `null` sends nothing.

```js
// PayPal → CUSTOMER.DISPUTE.CREATED
// Fires when a buyer opens a dispute or claim, or a card issuer files a chargeback.
// Docs: https://developer.paypal.com/api/rest/webhooks/event-names/#disputes
//
// PayPal sends no event-type header, so the event is read from the body's event_type.

// Readable dispute reasons. Unlisted ones (including OTHER) are left out.
const REASONS = {
    MERCHANDISE_OR_SERVICE_NOT_RECEIVED: "item not received",
    MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED: "not as described",
    UNAUTHORISED: "unauthorised payment",
    CREDIT_NOT_PROCESSED: "refund not processed",
    DUPLICATE_TRANSACTION: "duplicate payment",
    INCORRECT_AMOUNT: "incorrect amount",
    PAYMENT_BY_OTHER_MEANS: "paid by other means",
    CANCELED_RECURRING_BILLING: "cancelled subscription still billed",
    PROBLEM_WITH_REMITTANCE: "problem with remittance",
}

// Lifecycle stages past the inquiry, where PayPal decides the case.
const CLAIM_STAGES = {
    CHARGEBACK: true,
    PRE_ARBITRATION: true,
    ARBITRATION: true,
}

// Look a key up without tripping over inherited names such as "toString".
function pick(table, key, fallback = null) {
    return typeof key === "string" && Object.prototype.hasOwnProperty.call(table, key) ? table[key] : fallback
}

// Only link to real http(s) URLs.
function link(url, cta) {
    return typeof url === "string" && /^https?:\/\//.test(url) ? [{ cta, url }] : []
}

// A non-empty string, or null.
function text(value) {
    return typeof value === "string" && value.trim() ? value.trim() : null
}

function flag(query, name) {
    return ["1", "true", "yes"].includes(String(query?.[name] ?? "").toLowerCase())
}

// PayPal amounts are decimal strings, already in major units: { value: "10.00", currency_code: "USD" }.
// Zero-decimal currencies such as JPY simply come without decimals ("500").
function money(amount) {
    const raw = amount?.value
    const currency = amount?.currency_code

    // Don't invent a figure when the event doesn't carry one.
    if ((typeof raw !== "string" && typeof raw !== "number") || raw === "" || typeof currency !== "string" || !currency) return null

    const value = Number(raw)
    if (!Number.isFinite(value)) return null

    try {
        return new Intl.NumberFormat("en-GB", { style: "currency", currency }).format(value)
    } catch {
        return `${raw} ${currency}`
    }
}

// A date like "8 Oct", in UTC (PayPal's due dates are UTC timestamps).
function day(iso) {
    const date = typeof iso === "string" ? new Date(iso) : null
    if (!date || Number.isNaN(date.getTime())) return null

    return date.toLocaleDateString("en-GB", { day: "numeric", month: "short", timeZone: "UTC" })
}

// Events carry no sandbox flag, but their API links point at api(-m).sandbox.paypal.com.
// ?sandbox=1 on the webhook URL forces it.
function isSandbox(event, query) {
    if (flag(query, "sandbox")) return true

    const links = [event.links, event.resource?.links].filter(Array.isArray).flat()
    return links.some((l) => typeof l?.href === "string" && /^https:\/\/api(-m)?\.sandbox\.paypal\.com\//.test(l.href))
}

function handleRequest(request) {
    const event = request.body && typeof request.body === "object" ? request.body : {}
    const dispute = event.resource

    // Guard: only new disputes, so other PayPal events on this integration stay quiet.
    if (event.event_type !== "CUSTOMER.DISPUTE.CREATED" || !dispute || typeof dispute !== "object") {
        console.log(`Ignoring PayPal "${typeof event.event_type === "string" ? event.event_type : "unknown"}" event`)
        return null
    }

    // External disputes are card chargebacks; internal ones start as an inquiry between you and
    // the buyer and can be escalated to a claim, which PayPal calls the CHARGEBACK stage.
    const chargeback = dispute.dispute_channel === "EXTERNAL"
    const inquiry = !chargeback && dispute.dispute_life_cycle_stage === "INQUIRY"
    const claim = !chargeback && pick(CLAIM_STAGES, dispute.dispute_life_cycle_stage, false)
    const kind = chargeback ? "chargeback" : claim ? "claim" : "dispute"

    const transaction = Array.isArray(dispute.disputed_transactions) ? dispute.disputed_transactions[0] : null
    const amount = money(dispute.dispute_amount) ?? money(transaction?.gross_amount) ?? "A payment"
    const buyer = text(transaction?.buyer?.name)
    const reason = pick(REASONS, dispute.reason)
    const due = day(dispute.seller_response_due_date)
    const sandbox = isSandbox(event, request.query)
    const web = sandbox ? "https://www.sandbox.paypal.com" : "https://www.paypal.com"

    return {
        title: `⚖️ New ${kind}` + (sandbox ? " (sandbox)" : ""),
        message:
            `${amount} disputed` +
            (buyer ? ` by ${buyer}` : "") +
            (reason ? `: ${reason}` : "") +
            (due ? `. Respond by ${due}.` : ""),
        topic: "PayPal",
        // Highest for claims and chargebacks: PayPal holds the money and the evidence clock is ticking.
        // High for an inquiry: the buyer is waiting on your reply, but nothing is decided yet.
        // An unknown stage counts as urgent.
        priority: inquiry ? 1 : 2,
        buttons: link(`${web}/disputes/dashboard/`, "Respond"),
    }
}
```

## PayPal CUSTOMER.DISPUTE.CREATED webhook payload (sample)

```json
{
  "id": "WH-4M0448861G563140B-9EX36365822141321",
  "links": [
    {
      "rel": "self",
      "href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-4M0448861G563140B-9EX36365822141321",
      "method": "GET"
    },
    {
      "rel": "resend",
      "href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-4M0448861G563140B-9EX36365822141321/resend",
      "method": "POST"
    }
  ],
  "resource": {
    "links": [
      {
        "rel": "self",
        "href": "https://api-m.paypal.com/v1/customer/disputes/PP-R-AYP-10135034",
        "method": "GET"
      }
    ],
    "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
    "status": "WAITING_FOR_SELLER_RESPONSE",
    "dispute_id": "PP-R-AYP-10135034",
    "create_time": "2026-09-18T09:46:54.926Z",
    "update_time": "2026-09-18T09:46:54.926Z",
    "dispute_amount": {
      "value": "42.00",
      "currency_code": "USD"
    },
    "dispute_channel": "INTERNAL",
    "disputed_transactions": [
      {
        "buyer": {
          "name": "Jane Doe"
        },
        "items": [
          {
            "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
            "item_name": "Ceramic mug",
            "item_type": "PRODUCT",
            "item_quantity": "1"
          }
        ],
        "seller": {
          "name": "The Happy Store",
          "email": "shop@example.com",
          "merchant_id": "HAAP3SNYZZ9NG"
        },
        "create_time": "2026-09-18T09:42:33.000Z",
        "gross_amount": {
          "value": "42.00",
          "currency_code": "USD"
        },
        "transaction_status": "HELD",
        "buyer_transaction_id": "7XB07472F52871902",
        "seller_transaction_id": "8AW70038VH226914P"
      }
    ],
    "dispute_life_cycle_stage": "INQUIRY",
    "seller_response_due_date": "2026-10-08T09:46:54.926Z"
  },
  "event_type": "CUSTOMER.DISPUTE.CREATED",
  "create_time": "2026-09-18T09:47:02.513Z",
  "event_version": "1.0",
  "resource_type": "dispute"
}
```

## FAQ

### 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.