# Paddle payment failed notifications on your phone

> Get a High-priority push notification when a Paddle payment attempt fails, with the decline reason and card.

- Company: Paddle (https://www.justpush.io/recipes/paddle)
- Event: `transaction.payment_failed` (transaction.payment_failed)
- Tags: Finance, Payments
- Install: https://studio.justpush.io/recipes/paddle/transaction-payment-failed
- Web page: https://www.justpush.io/recipes/paddle/transaction-payment-failed

## 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 Paddle, go to Developer tools > Notifications and click New destination.
3. Choose Webhook as the type and paste your webhook URL (shown in Studio after install) as the URL.
4. Select the transaction.payment_failed event and save the destination.
5. The **View transaction** button opens the live Paddle dashboard. Paddle doesn't say in the event whether it came from sandbox or live, so if you're testing in sandbox, change `DASHBOARD` at the top of the code to `https://sandbox-vendors.paddle.com`.
6. Paddle signs each webhook with a `Paddle-Signature` header, but JustPush doesn't verify it yet. 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
// Paddle → transaction payment failed
// Fires when a payment attempt fails.
// Docs: https://developer.paddle.com/webhooks/overview
//
// Paste this into a JustPush Studio integration and add a Paddle notification destination
// for the "transaction.payment_failed" event pointing at the integration's endpoint URL.

// Paddle amounts are strings in the currency's smallest unit ("4900" = €49.00),
// except for zero-decimal currencies such as JPY, where "500" means ¥500.
const ZERO_DECIMAL = new Set(["jpy", "krw"])

function money(amount, currency) {
    const units = Number(amount)

    // Don't invent a figure when the event doesn't carry one.
    if (amount == null || amount === "" || !Number.isFinite(units) || !currency) return null

    const code = String(currency).toLowerCase()
    const value = ZERO_DECIMAL.has(code) ? units : units / 100

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

// Paddle events don't say whether they came from sandbox or live, so set this yourself.
// Sandbox: "https://sandbox-vendors.paddle.com"
const DASHBOARD = "https://vendors.paddle.com"

// Name what was bought, e.g. "AeroEdit Pro + 1 more".
function purchased(transaction) {
    const lines = transaction.details?.line_items ?? []
    const first = lines[0]?.product?.name ?? transaction.items?.[0]?.price?.name

    if (!first) return null

    const count = Math.max(lines.length, transaction.items?.length ?? 0)
    return count > 1 ? `${first} + ${count - 1} more` : first
}

function handleRequest(request) {
    const event = request.body

    // Guard: only handle this event type, so other Paddle events on this integration stay quiet.
    if (!event?.data || event.event_type !== "transaction.payment_failed") {
        console.log(`Ignoring Paddle event "${event?.event_type ?? "unknown"}"`)
        return null
    }

    const transaction = event.data
    const amount =
        money(
            transaction.details?.totals?.grand_total ?? transaction.details?.totals?.total,
            transaction.currency_code
        ) ?? "A payment"
    const what = purchased(transaction)
    // The failed attempt is the payment with an error code.
    const failed = (transaction.payments ?? []).find((payment) => payment.error_code)
    const reason = failed?.error_code?.replace(/_/g, " ")
    const card = failed?.method_details?.card
    const method = card?.last4 ? ` on ${card.type ?? "card"} ••${card.last4}` : ""

    return {
        title: "🚫 Payment failed",
        message: amount + (what ? ` for ${what}` : "") + (reason ? ` — ${reason}${method}` : ""),
        topic: "Paddle",
        priority: 1, // High — a customer tried to pay and couldn't
        buttons: [{ cta: "View transaction", url: `${DASHBOARD}/transactions-v2/${transaction.id}` }],
    }
}
```

## Paddle transaction.payment_failed webhook payload (sample)

```json
{
  "data": {
    "id": "txn_01jfailed",
    "items": [
      {
        "price": {
          "id": "pri_01jmonthly",
          "name": "Monthly",
          "product_id": "pro_01jaeroedit",
          "unit_price": {
            "amount": "3000",
            "currency_code": "EUR"
          },
          "description": "Monthly",
          "billing_cycle": {
            "interval": "month",
            "frequency": 1
          }
        },
        "quantity": 1
      }
    ],
    "origin": "web",
    "status": "ready",
    "details": {
      "totals": {
        "fee": "182",
        "tax": "630",
        "total": "3630",
        "discount": "0",
        "earnings": "2818",
        "subtotal": "3000",
        "grand_total": "3630",
        "currency_code": "EUR"
      },
      "line_items": [
        {
          "id": "txnitm_01jline",
          "product": {
            "id": "pro_01jaeroedit",
            "name": "AeroEdit Pro",
            "type": "standard",
            "status": "active"
          },
          "price_id": "pri_01jmonthly",
          "quantity": 1
        }
      ]
    },
    "payments": [
      {
        "amount": "3630",
        "status": "error",
        "created_at": "2026-09-28T09:29:58.000000Z",
        "error_code": "declined",
        "method_details": {
          "card": {
            "type": "visa",
            "last4": "0002",
            "expiry_year": 2028,
            "expiry_month": 1
          },
          "type": "card"
        }
      }
    ],
    "customer_id": "ctm_01jjane",
    "currency_code": "EUR"
  },
  "event_id": "evt_01jtransactionpaymentfa",
  "event_type": "transaction.payment_failed",
  "occurred_at": "2026-09-28T09:30:00.000000Z",
  "notification_id": "ntf_01jtransactionpaymentfa"
}
```

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