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.
Monday 5 October
9:41
JustPushnow
Refund issued
Get a low-priority push notification when a PayPal payment is fully or partially refunded, with the reason you gave the buyer.
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 PAYMENT.CAPTURE.REFUNDED.
STEP 03
Get a push on your phone
With the text, sound and buttons from the recipe.
How to set up the PayPal payment.capture.refunded webhook
- Click Install in Studio and sign in. The recipe is added to your account and you get a personal webhook URL.
- In the PayPal Developer Dashboard, open Apps & Credentials, switch to Sandbox or Live, and open the REST app that takes your payments.
- Under Webhooks, click Add Webhook and paste your webhook URL as the Webhook URL.https://••••••••/•••••••• your personal URL, shown after install
- Tick the PAYMENT.CAPTURE.REFUNDED event and save.
- 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.
- 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)*.
- Sandbox events are recognised from their API links and marked **(sandbox)**; add `?sandbox=1` to the URL to force that.
- 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.
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 → PAYMENT.CAPTURE.REFUNDED (and PAYMENT.SALE.REFUNDED)
2// Fires when you refund a captured payment (Orders v2), or a sale (subscription payments
3// and older v1 integrations), in full or in part.
4// Docs: https://developer.paypal.com/api/rest/webhooks/event-names/
5//
6// PayPal sends no event-type header, so the event is read from the body's event_type.
7
8// The events this recipe reacts to, and whether the resource is a v2 or v1 refund.
9const EVENTS = {
10 "PAYMENT.CAPTURE.REFUNDED": "v2",
11 "PAYMENT.SALE.REFUNDED": "v1",
12}
13
14// Look a key up without tripping over inherited names such as "toString".
15function pick(table, key, fallback = null) {
16 return typeof key === "string" && Object.prototype.hasOwnProperty.call(table, key) ? table[key] : fallback
17}
18
19// Only link to real http(s) URLs.
20function link(url, cta) {
21 return typeof url === "string" && /^https?:\/\//.test(url) ? [{ cta, url }] : []
22}
23
24// A non-empty string, or null.
25function text(value) {
26 return typeof value === "string" && value.trim() ? value.trim() : null
27}
28
29function flag(query, name) {
30 return ["1", "true", "yes"].includes(String(query?.[name] ?? "").toLowerCase())
31}
32
33// PayPal amounts are decimal strings, already in major units: v2 uses
34// { value: "10.00", currency_code: "USD" }, v1 uses { total: "10.00", currency: "USD" }.
35// Zero-decimal currencies such as JPY simply come without decimals ("500").
36function money(amount) {
37 const raw = amount?.value ?? amount?.total
38 const currency = amount?.currency_code ?? amount?.currency
39
40 // Don't invent a figure when the event doesn't carry one.
41 if ((typeof raw !== "string" && typeof raw !== "number") || raw === "" || typeof currency !== "string" || !currency) return null
42
43 // Refunds are shown as a positive amount, whichever sign the event uses.
44 const value = Math.abs(Number(raw))
45 if (!Number.isFinite(value)) return null
46
47 try {
48 return new Intl.NumberFormat("en-GB", { style: "currency", currency }).format(value)
49 } catch {
50 return `${raw} ${currency}`
51 }
52}
53
54// Events carry no sandbox flag, but their API links point at api(-m).sandbox.paypal.com.
55// ?sandbox=1 on the webhook URL forces it.
56function isSandbox(event, query) {
57 if (flag(query, "sandbox")) return true
58
59 const links = [event.links, event.resource?.links].filter(Array.isArray).flat()
60 return links.some((l) => typeof l?.href === "string" && /^https:\/\/api(-m)?\.sandbox\.paypal\.com\//.test(l.href))
61}
62
63function handleRequest(request) {
64 const event = request.body && typeof request.body === "object" ? request.body : {}
65 const version = pick(EVENTS, event.event_type)
66 const refund = event.resource
67
68 // Guard: only refunds, so other PayPal events on this integration stay quiet.
69 if (!version || !refund || typeof refund !== "object") {
70 console.log(`Ignoring PayPal "${typeof event.event_type === "string" ? event.event_type : "unknown"}" event`)
71 return null
72 }
73
74 const amount = money(refund.amount)
75 // v2 refunds say how much of the capture has been refunded so far, across all refunds.
76 const total = money(refund.seller_payable_breakdown?.total_refunded_amount)
77 const pending = String(refund.status ?? refund.state ?? "").toUpperCase() === "PENDING"
78 // The reason you gave the buyer: note_to_payer in the schema, note in PayPal's examples,
79 // description on v1 refunds.
80 const note = text(refund.note_to_payer) ?? text(refund.note) ?? text(refund.description)
81 const invoice = text(refund.invoice_id) ?? text(refund.invoice_number)
82 const sandbox = isSandbox(event, request.query)
83 const web = sandbox ? "https://www.sandbox.paypal.com" : "https://www.paypal.com"
84
85 return {
86 title: (pending ? "↩️ Refund pending" : "↩️ Refund issued") + (sandbox ? " (sandbox)" : ""),
87 message:
88 (amount ? `${amount} refunded` : "A payment was refunded") +
89 (total && total !== amount ? ` (${total} in total)` : "") +
90 (note ? ` · ${note}` : "") +
91 (invoice ? ` · Invoice ${invoice}` : ""),
92 topic: "PayPal",
93 priority: -1, // Low: you (or a teammate) most likely issued it yourself
94 buttons: text(refund.id) ? link(`${web}/activity/payment/${encodeURIComponent(refund.id)}`, "View refund") : [],
95 }
96}
The PayPal PAYMENT.CAPTURE.REFUNDED webhook
This is what PayPal sends to your URL for payment.capture.refunded. It is a sample, trimmed to the fields recipes use.
PAYMENT.CAPTURE.REFUNDED · sample.json
1{
2 "id": "WH-1GE84257G0350133W-6RW800890C634293G",
3 "links": [
4 {
5 "rel": "self",
6 "href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-1GE84257G0350133W-6RW800890C634293G",
7 "method": "GET"
8 },
9 {
10 "rel": "resend",
11 "href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-1GE84257G0350133W-6RW800890C634293G/resend",
12 "method": "POST"
13 }
14 ],
15 "resource": {
16 "id": "1JU08902781691411",
17 "note": "Defective product",
18 "links": [
19 {
20 "rel": "self",
21 "href": "https://api.paypal.com/v2/payments/refunds/1JU08902781691411",
22 "method": "GET"
23 },
24 {
25 "rel": "up",
26 "href": "https://api.paypal.com/v2/payments/captures/2GG279541U471931P",
27 "method": "GET"
28 }
29 ],
30 "amount": {
31 "value": "10.99",
32 "currency_code": "USD"
33 },
34 "status": "COMPLETED",
35 "invoice_id": "INVOICE-123",
36 "create_time": "2026-09-28T14:12:03Z",
37 "update_time": "2026-09-28T14:12:03Z",
38 "seller_payable_breakdown": {
39 "net_amount": {
40 "value": "10.66",
41 "currency_code": "USD"
42 },
43 "paypal_fee": {
44 "value": "0.33",
45 "currency_code": "USD"
46 },
47 "gross_amount": {
48 "value": "10.99",
49 "currency_code": "USD"
50 },
51 "total_refunded_amount": {
52 "value": "10.99",
53 "currency_code": "USD"
54 }
55 }
56 },
57 "event_type": "PAYMENT.CAPTURE.REFUNDED",
58 "create_time": "2026-09-28T14:12:07.201Z",
59 "event_version": "1.0",
60 "resource_type": "refund",
61 "resource_version": "2.0"
62}
PayPal refund issued 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.
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.