# PayPal payment received notifications on your phone

> Get a push notification with the amount and what you keep after fees every time a PayPal payment is captured, including subscription payments.

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

## 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.COMPLETED event and save.
5. Tick **PAYMENT.CAPTURE.COMPLETED** (it may be listed as *Payment capture completed*). Taking **subscription payments**? Also tick **PAYMENT.SALE.COMPLETED**: PayPal Subscriptions report each payment as a sale, not a capture. This recipe handles both, and PayPal sends only one of them per payment.
6. Webhooks belong to one REST app and one environment. Add the webhook to the app your checkout actually uses, in **Sandbox** or **Live** to match. Payments made through a different app don't reach this URL.
7. Sandbox events are recognised from their API links and marked **(sandbox)**; add `?sandbox=1` to the URL to force that.
8. To try it, send a mock event from the [Webhooks simulator](https://developer.paypal.com/dashboard/webhooksSimulator/). Mock events carry made-up data.
9. 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.COMPLETED (and PAYMENT.SALE.COMPLETED)
// Fires when a payment capture completes (Orders v2 checkouts), or when a sale completes
// (subscription payments and older v1 integrations).
// 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 they carry a v2 capture or a v1 sale.
const EVENTS = {
    "PAYMENT.CAPTURE.COMPLETED": "capture",
    "PAYMENT.SALE.COMPLETED": "sale",
}

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

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

    const gross = money(payment.amount)
    // v2 captures carry the fee breakdown; v1 sales may carry receivable_amount.
    const net = money(payment.seller_receivable_breakdown?.net_amount)
    const invoice = text(payment.invoice_id) ?? text(payment.invoice_number)
    // A v1 sale with a billing agreement ID is a subscription payment.
    const subscription = kind === "sale" && text(payment.billing_agreement_id)
    const sandbox = isSandbox(event, request.query)
    const web = sandbox ? "https://www.sandbox.paypal.com" : "https://www.paypal.com"

    return {
        title: "💰 Payment received" + (sandbox ? " (sandbox)" : ""),
        message:
            (gross ? `${gross} received` : "A payment was received") +
            (net && net !== gross ? `, ${net} after fees` : "") +
            (invoice ? ` · Invoice ${invoice}` : "") +
            (subscription ? " · subscription payment" : ""),
        topic: "PayPal",
        priority: 0, // Normal: money in is good news, not an emergency
        sound: "cashregister",
        buttons: text(payment.id) ? link(`${web}/activity/payment/${encodeURIComponent(payment.id)}`, "View payment") : [],
    }
}
```

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

```json
{
  "id": "WH-3F562076HD293871E-75F399086E414290U",
  "links": [
    {
      "rel": "self",
      "href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-3F562076HD293871E-75F399086E414290U",
      "method": "GET"
    },
    {
      "rel": "resend",
      "href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-3F562076HD293871E-75F399086E414290U/resend",
      "method": "POST"
    }
  ],
  "summary": "Payment completed for $ 500.0 USD",
  "resource": {
    "id": "3Y662965014333303",
    "links": [
      {
        "rel": "self",
        "href": "https://api.paypal.com/v2/payments/captures/3Y662965014333303",
        "method": "GET"
      },
      {
        "rel": "refund",
        "href": "https://api.paypal.com/v2/payments/captures/3Y662965014333303/refund",
        "method": "POST"
      },
      {
        "rel": "up",
        "href": "https://api.paypal.com/v2/checkout/orders/9P99943869582473S",
        "method": "GET"
      }
    ],
    "payee": {
      "merchant_id": "QDGTZ7B92B9QT",
      "email_address": "receivingbusiness@example.com"
    },
    "amount": {
      "value": "500.00",
      "currency_code": "USD"
    },
    "status": "COMPLETED",
    "invoice_id": "INV-2026-0042",
    "create_time": "2026-09-28T09:30:00Z",
    "update_time": "2026-09-28T09:30:00Z",
    "final_capture": true,
    "seller_protection": {
      "status": "ELIGIBLE",
      "dispute_categories": [
        "ITEM_NOT_RECEIVED",
        "UNAUTHORIZED_TRANSACTION"
      ]
    },
    "supplementary_data": {
      "related_ids": {
        "order_id": "9P99943869582473S"
      }
    },
    "seller_receivable_breakdown": {
      "net_amount": {
        "value": "474.56",
        "currency_code": "USD"
      },
      "paypal_fee": {
        "value": "25.44",
        "currency_code": "USD"
      },
      "gross_amount": {
        "value": "500.00",
        "currency_code": "USD"
      }
    }
  },
  "event_type": "PAYMENT.CAPTURE.COMPLETED",
  "create_time": "2026-09-28T09:30:04.355Z",
  "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.