# PayPal refund issued notifications on your phone

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

- Company: PayPal (https://www.justpush.io/recipes/paypal)
- Event: `PAYMENT.CAPTURE.REFUNDED` (PAYMENT.CAPTURE.REFUNDED)
- Tags: Payments & billing, Refunds
- Install: https://studio.justpush.io/recipes/paypal/payment-refunded
- Web page: https://www.justpush.io/recipes/paypal/payment-refunded

## 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 PAYMENT.CAPTURE.REFUNDED event and save.
5. Tick **PAYMENT.CAPTURE.REFUNDED** (it may be listed as *Payment capture refunded*). Refunding **subscription payments**? Also tick **PAYMENT.SALE.REFUNDED**: PayPal Subscriptions report payments as sales, so their refunds arrive under that name. This recipe handles both.
6. It fires for refunds made through the API and from your PayPal business account. A partial refund shows the running total too, e.g. *US$5.00 refunded (US$15.00 in total)*.
7. Sandbox events are recognised from their API links and marked **(sandbox)**; add `?sandbox=1` to the URL to force that.
8. 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 → PAYMENT.CAPTURE.REFUNDED (and PAYMENT.SALE.REFUNDED)
// Fires when you refund a captured payment (Orders v2), or a sale (subscription payments
// and older v1 integrations), in full or in part.
// Docs: https://developer.paypal.com/api/rest/webhooks/event-names/
//
// PayPal sends no event-type header, so the event is read from the body's event_type.

// The events this recipe reacts to, and whether the resource is a v2 or v1 refund.
const EVENTS = {
    "PAYMENT.CAPTURE.REFUNDED": "v2",
    "PAYMENT.SALE.REFUNDED": "v1",
}

// 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: v2 uses
// { value: "10.00", currency_code: "USD" }, v1 uses { total: "10.00", currency: "USD" }.
// Zero-decimal currencies such as JPY simply come without decimals ("500").
function money(amount) {
    const raw = amount?.value ?? amount?.total
    const currency = amount?.currency_code ?? amount?.currency

    // 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

    // Refunds are shown as a positive amount, whichever sign the event uses.
    const value = Math.abs(Number(raw))
    if (!Number.isFinite(value)) return null

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

// 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 version = pick(EVENTS, event.event_type)
    const refund = event.resource

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

    const amount = money(refund.amount)
    // v2 refunds say how much of the capture has been refunded so far, across all refunds.
    const total = money(refund.seller_payable_breakdown?.total_refunded_amount)
    const pending = String(refund.status ?? refund.state ?? "").toUpperCase() === "PENDING"
    // The reason you gave the buyer: note_to_payer in the schema, note in PayPal's examples,
    // description on v1 refunds.
    const note = text(refund.note_to_payer) ?? text(refund.note) ?? text(refund.description)
    const invoice = text(refund.invoice_id) ?? text(refund.invoice_number)
    const sandbox = isSandbox(event, request.query)
    const web = sandbox ? "https://www.sandbox.paypal.com" : "https://www.paypal.com"

    return {
        title: (pending ? "↩️ Refund pending" : "↩️ Refund issued") + (sandbox ? " (sandbox)" : ""),
        message:
            (amount ? `${amount} refunded` : "A payment was refunded") +
            (total && total !== amount ? ` (${total} in total)` : "") +
            (note ? ` · ${note}` : "") +
            (invoice ? ` · Invoice ${invoice}` : ""),
        topic: "PayPal",
        priority: -1, // Low: you (or a teammate) most likely issued it yourself
        buttons: text(refund.id) ? link(`${web}/activity/payment/${encodeURIComponent(refund.id)}`, "View refund") : [],
    }
}
```

## PayPal PAYMENT.CAPTURE.REFUNDED webhook payload (sample)

```json
{
  "id": "WH-1GE84257G0350133W-6RW800890C634293G",
  "links": [
    {
      "rel": "self",
      "href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-1GE84257G0350133W-6RW800890C634293G",
      "method": "GET"
    },
    {
      "rel": "resend",
      "href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-1GE84257G0350133W-6RW800890C634293G/resend",
      "method": "POST"
    }
  ],
  "resource": {
    "id": "1JU08902781691411",
    "note": "Defective product",
    "links": [
      {
        "rel": "self",
        "href": "https://api.paypal.com/v2/payments/refunds/1JU08902781691411",
        "method": "GET"
      },
      {
        "rel": "up",
        "href": "https://api.paypal.com/v2/payments/captures/2GG279541U471931P",
        "method": "GET"
      }
    ],
    "amount": {
      "value": "10.99",
      "currency_code": "USD"
    },
    "status": "COMPLETED",
    "invoice_id": "INVOICE-123",
    "create_time": "2026-09-28T14:12:03Z",
    "update_time": "2026-09-28T14:12:03Z",
    "seller_payable_breakdown": {
      "net_amount": {
        "value": "10.66",
        "currency_code": "USD"
      },
      "paypal_fee": {
        "value": "0.33",
        "currency_code": "USD"
      },
      "gross_amount": {
        "value": "10.99",
        "currency_code": "USD"
      },
      "total_refunded_amount": {
        "value": "10.99",
        "currency_code": "USD"
      }
    }
  },
  "event_type": "PAYMENT.CAPTURE.REFUNDED",
  "create_time": "2026-09-28T14:12:07.201Z",
  "event_version": "1.0",
  "resource_type": "refund",
  "resource_version": "2.0"
}
```

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