# Square invoice paid notifications on your phone

> Get a push notification when a customer pays a Square invoice, in full or in part, with the amount, the customer and the invoice title.

- Company: Square (https://www.justpush.io/recipes/square)
- Event: `invoice.payment_made` (invoice.payment_made)
- Tags: Payments & billing, Payments
- Install: https://studio.justpush.io/recipes/square/invoice-paid
- Web page: https://www.justpush.io/recipes/square/invoice-paid

## 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 Square Developer Console (developer.squareup.com/apps), open your application (create a free one if you have none) and switch to Production.
3. Under Webhooks, choose Subscriptions and click Add subscription.
4. Paste your webhook URL (shown in Studio after install) as the notification URL, tick the invoice.payment_made event, and save.
5. Tick **invoice.payment_made**. It fires for every payment on an invoice, so an invoice with a deposit and a balance gives two pushes: "partly paid", then "paid".
6. An invoice payment is also a regular Square payment, so if you use the Payment received recipe too, you'll get a push from both.
7. Sandbox deliveries are marked **(sandbox)**.
8. Square signs every notification with an `x-square-hmacsha256-signature` header (an HMAC-SHA256 of your notification URL and the body, keyed with the subscription's signature key), 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
// Square → invoice.payment_made
// Fires each time a customer pays (part of) a Square invoice: a deposit, an instalment or
// the balance.
// Docs: https://developer.squareup.com/reference/square/invoices-api/webhooks/invoice.payment_made

// Header names can arrive in any case.
function header(request, name) {
    const headers = request.headers || {}
    const key = Object.keys(headers).find((k) => k.toLowerCase() === name)
    const value = key ? headers[key] : null
    return Array.isArray(value) ? value[0] : value
}

// Only link to real http(s) URLs.
function link(url, cta) {
    return typeof url === "string" && /^https?:\/\//.test(url) ? [{ cta, url }] : []
}

// Square Money is { amount, currency } with amount in the currency's smallest unit
// (cents for USD/EUR/GBP, whole yen for JPY). Returns null when there's no amount.
function money(value) {
    const amount = value?.amount
    const currency = value?.currency

    if (typeof amount !== "number" || !Number.isFinite(amount) || typeof currency !== "string" || !currency) return null

    try {
        const format = new Intl.NumberFormat("en-GB", { style: "currency", currency })
        return format.format(amount / 10 ** format.resolvedOptions().maximumFractionDigits)
    } catch {
        return null
    }
}

// Adds up one Money field across the invoice's payment requests. Returns null when a
// request is missing it or the currencies don't match, so we never show a wrong total.
function sum(requests, field) {
    if (!Array.isArray(requests) || requests.length === 0) return null

    let amount = 0
    let currency = null

    for (const request of requests) {
        const value = request?.[field]
        if (typeof value?.amount !== "number" || typeof value.currency !== "string") return null
        if (currency && value.currency !== currency) return null
        currency = value.currency
        amount += value.amount
    }

    return { amount, currency }
}

// "Amelia Earhart", else the company, else the email address.
function customer(recipient) {
    const name = [recipient?.given_name, recipient?.family_name].filter((part) => typeof part === "string" && part).join(" ")
    return name || recipient?.company_name || recipient?.email_address || null
}

function handleRequest(request) {
    const body = request.body && typeof request.body === "object" ? request.body : {}
    const invoice = body.data?.object?.invoice

    // Guard: only invoice.payment_made, so other invoice events on this integration stay quiet.
    if (body.type !== "invoice.payment_made" || !invoice || typeof invoice !== "object") {
        console.log(`Ignoring Square event "${typeof body.type === "string" ? body.type : "unknown"}"`)
        return null
    }

    const paid = money(sum(invoice.payment_requests, "total_completed_amount_money"))
    const total = money(sum(invoice.payment_requests, "computed_amount_money"))
    const partly = invoice.status === "PARTIALLY_PAID"
    const who = customer(invoice.primary_recipient)
    const what = [invoice.title, invoice.invoice_number ? `(${invoice.invoice_number})` : null].filter(Boolean).join(" ")
    const sandbox = String(header(request, "square-environment") ?? "").toLowerCase() === "sandbox" ? " (sandbox)" : ""

    return {
        title: partly ? "🧾 Invoice partly paid" : "🧾 Invoice paid",
        message:
            (partly && paid && total
                ? `${paid} of ${total} paid` + (who ? ` by ${who}` : "")
                : (paid ?? total ?? "An invoice payment") + (who ? ` from ${who}` : "")) +
            (what ? ` — ${what}` : "") +
            sandbox,
        topic: "Square",
        priority: 0, // Normal — money in is good news, not an emergency
        sound: "cashregister",
        buttons: link(invoice.public_url, "View invoice"),
    }
}
```

## Square invoice.payment_made webhook payload (sample)

```json
{
  "data": {
    "id": "inv:0-ChCHu2mZEabLeeHahQnXDjZQECY",
    "type": "invoice",
    "object": {
      "invoice": {
        "id": "inv:0-ChCHu2mZEabLeeHahQnXDjZQECY",
        "title": "Event Planning Services",
        "status": "PAID",
        "version": 3,
        "order_id": "CAISENgvlJ6jLWAzERDzjyHVybY",
        "timezone": "America/Los_Angeles",
        "created_at": "2026-09-18T17:45:13Z",
        "updated_at": "2026-09-18T18:23:11Z",
        "description": "We appreciate your business!",
        "location_id": "ES0RJRZYEC39A",
        "invoice_number": "inv-100",
        "delivery_method": "EMAIL",
        "payment_requests": [
          {
            "uid": "2da7964f-f3d2-4f43-81e8-5aa220bf3355",
            "due_date": "2026-10-24",
            "request_type": "BALANCE",
            "tipping_enabled": false,
            "computed_amount_money": {
              "amount": 10000,
              "currency": "USD"
            },
            "automatic_payment_source": "NONE",
            "total_completed_amount_money": {
              "amount": 10000,
              "currency": "USD"
            }
          }
        ],
        "primary_recipient": {
          "given_name": "Amelia",
          "customer_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
          "family_name": "Earhart",
          "email_address": "amelia@example.com"
        },
        "sale_or_service_date": "2026-09-24",
        "accepted_payment_methods": {
          "card": true,
          "bank_account": false,
          "cash_app_pay": false,
          "square_gift_card": false,
          "buy_now_pay_later": false
        },
        "store_payment_method_enabled": false
      }
    }
  },
  "type": "invoice.payment_made",
  "event_id": "891e3589-462f-4215-9b61-f6df2d4432b7",
  "created_at": "2026-09-18T18:23:11Z",
  "location_id": "ES0RJRZYEC39A",
  "merchant_id": "031FEV2Q6VMPK"
}
```

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