PayPal payment denied notifications on your phone.
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.
Monday 5 October
9:41
JustPushnow
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.
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.DENIED.
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.denied 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.DENIED event and save.
- Tick **PAYMENT.CAPTURE.DENIED** (it may be listed as *Payment capture denied*). PayPal also has **PAYMENT.CAPTURE.DECLINED** (Payments v2) and **PAYMENT.SALE.DENIED** (subscription and v1 payments). Tick those too if you want them; this recipe handles all three and names the push *denied* or *declined* to match.
- These events mostly follow a **pending** payment, for example an eCheck that later bounces. If you shipped on `PAYMENT.CAPTURE.PENDING`, this is your cue to hold the order.
- 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.DENIED (and PAYMENT.CAPTURE.DECLINED, PAYMENT.SALE.DENIED)
2// Fires when a payment you were waiting on doesn't go through: a pending capture or sale is
3// denied (for example, an eCheck bounces), or a capture is declined.
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 the word for what happened.
9const EVENTS = {
10 "PAYMENT.CAPTURE.DENIED": "denied",
11 "PAYMENT.CAPTURE.DECLINED": "declined",
12 "PAYMENT.SALE.DENIED": "denied",
13}
14
15// Readable reasons from status_details.reason (v2) or reason_code (v1). Unlisted reasons are left out.
16const REASONS = {
17 DECLINED_BY_RISK_FRAUD_FILTERS: "blocked by fraud filters",
18 ECHECK: "eCheck didn't clear",
19 BUYER_COMPLAINT: "buyer complaint",
20 CHARGEBACK: "chargeback",
21 PENDING_REVIEW: "failed PayPal's review",
22 VERIFICATION_REQUIRED: "verification required",
23 RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION: "needs manual action in your account",
24 UNILATERAL: "payee has no PayPal account",
25 INTERNATIONAL_WITHDRAWAL: "international withdrawal",
26}
27
28// Look a key up without tripping over inherited names such as "toString".
29function pick(table, key, fallback = null) {
30 return typeof key === "string" && Object.prototype.hasOwnProperty.call(table, key) ? table[key] : fallback
31}
32
33// Only link to real http(s) URLs.
34function link(url, cta) {
35 return typeof url === "string" && /^https?:\/\//.test(url) ? [{ cta, url }] : []
36}
37
38// A non-empty string, or null.
39function text(value) {
40 return typeof value === "string" && value.trim() ? value.trim() : null
41}
42
43function flag(query, name) {
44 return ["1", "true", "yes"].includes(String(query?.[name] ?? "").toLowerCase())
45}
46
47// PayPal amounts are decimal strings, already in major units: v2 uses
48// { value: "10.00", currency_code: "USD" }, v1 uses { total: "10.00", currency: "USD" }.
49// Zero-decimal currencies such as JPY simply come without decimals ("500").
50function money(amount) {
51 const raw = amount?.value ?? amount?.total
52 const currency = amount?.currency_code ?? amount?.currency
53
54 // Don't invent a figure when the event doesn't carry one.
55 if ((typeof raw !== "string" && typeof raw !== "number") || raw === "" || typeof currency !== "string" || !currency) return null
56
57 const value = Number(raw)
58 if (!Number.isFinite(value)) return null
59
60 try {
61 return new Intl.NumberFormat("en-GB", { style: "currency", currency }).format(value)
62 } catch {
63 return `${raw} ${currency}`
64 }
65}
66
67// Events carry no sandbox flag, but their API links point at api(-m).sandbox.paypal.com.
68// ?sandbox=1 on the webhook URL forces it.
69function isSandbox(event, query) {
70 if (flag(query, "sandbox")) return true
71
72 const links = [event.links, event.resource?.links].filter(Array.isArray).flat()
73 return links.some((l) => typeof l?.href === "string" && /^https:\/\/api(-m)?\.sandbox\.paypal\.com\//.test(l.href))
74}
75
76function handleRequest(request) {
77 const event = request.body && typeof request.body === "object" ? request.body : {}
78 const verb = pick(EVENTS, event.event_type)
79 const payment = event.resource
80
81 // Guard: only denied or declined payments, so other PayPal events on this integration stay quiet.
82 if (!verb || !payment || typeof payment !== "object") {
83 console.log(`Ignoring PayPal "${typeof event.event_type === "string" ? event.event_type : "unknown"}" event`)
84 return null
85 }
86
87 const amount = money(payment.amount)
88 const reason = pick(REASONS, payment.status_details?.reason ?? payment.reason_code)
89 const invoice = text(payment.invoice_id) ?? text(payment.invoice_number)
90 const sandbox = isSandbox(event, request.query)
91 const web = sandbox ? "https://www.sandbox.paypal.com" : "https://www.paypal.com"
92
93 return {
94 title: `❌ Payment ${verb}` + (sandbox ? " (sandbox)" : ""),
95 message:
96 (amount ? `${amount} was ${verb}` : `A payment was ${verb}`) +
97 (reason ? ` (${reason})` : "") +
98 (invoice ? ` · Invoice ${invoice}` : ""),
99 topic: "PayPal",
100 priority: 1, // High: money you expected isn't coming, so hold any order that's waiting on it
101 buttons: text(payment.id) ? link(`${web}/activity/payment/${encodeURIComponent(payment.id)}`, "View payment") : [],
102 }
103}
The PayPal PAYMENT.CAPTURE.DENIED webhook
This is what PayPal sends to your URL for payment.capture.denied. It is a sample, trimmed to the fields recipes use.
PAYMENT.CAPTURE.DENIED · sample.json
1{
2 "id": "WH-7YX49823S2290830K-0JE13296W68552352",
3 "links": [
4 {
5 "rel": "self",
6 "href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-7YX49823S2290830K-0JE13296W68552352",
7 "method": "GET"
8 },
9 {
10 "rel": "resend",
11 "href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-7YX49823S2290830K-0JE13296W68552352/resend",
12 "method": "POST"
13 }
14 ],
15 "resource": {
16 "id": "7NW873794T343360M",
17 "links": [
18 {
19 "rel": "self",
20 "href": "https://api.paypal.com/v2/payments/captures/7NW873794T343360M",
21 "method": "GET"
22 },
23 {
24 "rel": "up",
25 "href": "https://api.paypal.com/v2/checkout/orders/5O190127TN364715T",
26 "method": "GET"
27 }
28 ],
29 "amount": {
30 "value": "249.00",
31 "currency_code": "EUR"
32 },
33 "status": "DECLINED",
34 "invoice_id": "INV-2026-0057",
35 "create_time": "2026-09-24T10:15:22Z",
36 "update_time": "2026-09-29T08:02:37Z",
37 "final_capture": true,
38 "status_details": {
39 "reason": "ECHECK"
40 },
41 "supplementary_data": {
42 "related_ids": {
43 "order_id": "5O190127TN364715T"
44 }
45 }
46 },
47 "event_type": "PAYMENT.CAPTURE.DENIED",
48 "create_time": "2026-09-29T08:02:41.117Z",
49 "event_version": "1.0",
50 "resource_type": "capture",
51 "resource_version": "2.0"
52}
PayPal payment denied 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.