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

- Company: PayPal (https://www.justpush.io/recipes/paypal)
- Event: `PAYMENT.CAPTURE.DENIED` (PAYMENT.CAPTURE.DENIED)
- Tags: Payments & billing, Failed payments & disputes
- Install: https://studio.justpush.io/recipes/paypal/payment-denied
- Web page: https://www.justpush.io/recipes/paypal/payment-denied

## 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.DENIED event and save.
5. 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.
6. 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.
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.DENIED (and PAYMENT.CAPTURE.DECLINED, PAYMENT.SALE.DENIED)
// Fires when a payment you were waiting on doesn't go through: a pending capture or sale is
// denied (for example, an eCheck bounces), or a capture is declined.
// 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 the word for what happened.
const EVENTS = {
    "PAYMENT.CAPTURE.DENIED": "denied",
    "PAYMENT.CAPTURE.DECLINED": "declined",
    "PAYMENT.SALE.DENIED": "denied",
}

// Readable reasons from status_details.reason (v2) or reason_code (v1). Unlisted reasons are left out.
const REASONS = {
    DECLINED_BY_RISK_FRAUD_FILTERS: "blocked by fraud filters",
    ECHECK: "eCheck didn't clear",
    BUYER_COMPLAINT: "buyer complaint",
    CHARGEBACK: "chargeback",
    PENDING_REVIEW: "failed PayPal's review",
    VERIFICATION_REQUIRED: "verification required",
    RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION: "needs manual action in your account",
    UNILATERAL: "payee has no PayPal account",
    INTERNATIONAL_WITHDRAWAL: "international withdrawal",
}

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

    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}`
    }
}

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

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

    const amount = money(payment.amount)
    const reason = pick(REASONS, payment.status_details?.reason ?? payment.reason_code)
    const invoice = text(payment.invoice_id) ?? text(payment.invoice_number)
    const sandbox = isSandbox(event, request.query)
    const web = sandbox ? "https://www.sandbox.paypal.com" : "https://www.paypal.com"

    return {
        title: `❌ Payment ${verb}` + (sandbox ? " (sandbox)" : ""),
        message:
            (amount ? `${amount} was ${verb}` : `A payment was ${verb}`) +
            (reason ? ` (${reason})` : "") +
            (invoice ? ` · Invoice ${invoice}` : ""),
        topic: "PayPal",
        priority: 1, // High: money you expected isn't coming, so hold any order that's waiting on it
        buttons: text(payment.id) ? link(`${web}/activity/payment/${encodeURIComponent(payment.id)}`, "View payment") : [],
    }
}
```

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

```json
{
  "id": "WH-7YX49823S2290830K-0JE13296W68552352",
  "links": [
    {
      "rel": "self",
      "href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-7YX49823S2290830K-0JE13296W68552352",
      "method": "GET"
    },
    {
      "rel": "resend",
      "href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-7YX49823S2290830K-0JE13296W68552352/resend",
      "method": "POST"
    }
  ],
  "resource": {
    "id": "7NW873794T343360M",
    "links": [
      {
        "rel": "self",
        "href": "https://api.paypal.com/v2/payments/captures/7NW873794T343360M",
        "method": "GET"
      },
      {
        "rel": "up",
        "href": "https://api.paypal.com/v2/checkout/orders/5O190127TN364715T",
        "method": "GET"
      }
    ],
    "amount": {
      "value": "249.00",
      "currency_code": "EUR"
    },
    "status": "DECLINED",
    "invoice_id": "INV-2026-0057",
    "create_time": "2026-09-24T10:15:22Z",
    "update_time": "2026-09-29T08:02:37Z",
    "final_capture": true,
    "status_details": {
      "reason": "ECHECK"
    },
    "supplementary_data": {
      "related_ids": {
        "order_id": "5O190127TN364715T"
      }
    }
  },
  "event_type": "PAYMENT.CAPTURE.DENIED",
  "create_time": "2026-09-29T08:02:41.117Z",
  "event_version": "1.0",
  "resource_type": "capture",
  "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.