# Square new dispute notifications on your phone

> Get a Highest-priority push notification the moment a customer disputes a Square card payment, with the amount, reason and the date you must respond by.

- Company: Square (https://www.justpush.io/recipes/square)
- Event: `dispute.created` (dispute.created)
- Tags: Payments & billing, Failed payments & disputes
- Install: https://studio.justpush.io/recipes/square/dispute-created
- Web page: https://www.justpush.io/recipes/square/dispute-created

## 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 dispute.created event, and save.
5. Tick **dispute.created**. The recipe ignores **dispute.state.updated** and the evidence events, so you can add them to the same subscription without extra pushes.
6. Sandbox deliveries are marked **(sandbox)** and get no Dashboard button.
7. 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 → dispute.created
// Fires when a cardholder's bank opens a chargeback (or an inquiry) on one of your payments.
// Docs: https://developer.squareup.com/docs/disputes-api/process-disputes#webhook-notifications

// Square's DisputeReason values, in plain words.
const REASONS = {
    AMOUNT_DIFFERS: "amount differs",
    CANCELLED: "cancelled",
    DUPLICATE: "duplicate charge",
    NO_KNOWLEDGE: "not recognised",
    NOT_AS_DESCRIBED: "not as described",
    NOT_RECEIVED: "not received",
    PAID_BY_OTHER_MEANS: "paid by other means",
    CUSTOMER_REQUESTS_CREDIT: "customer requests credit",
    EMV_LIABILITY_SHIFT: "EMV liability shift",
}

const BRANDS = {
    VISA: "Visa",
    MASTERCARD: "Mastercard",
    AMERICAN_EXPRESS: "American Express",
    DISCOVER: "Discover",
    DISCOVER_DINERS: "Diners Club",
    JCB: "JCB",
    CHINA_UNIONPAY: "UnionPay",
    INTERAC: "Interac",
    EFTPOS: "eftpos",
}

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

// Table lookup that ignores inherited names such as "toString".
function pick(table, key, fallback) {
    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 }] : []
}

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

// "4 Mar" from an RFC 3339 timestamp; null when it doesn't parse.
function day(value) {
    const date = typeof value === "string" ? new Date(value) : null
    if (!date || Number.isNaN(date.getTime())) return null
    return date.toLocaleDateString("en-GB", { day: "numeric", month: "short", timeZone: "UTC" })
}

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

    // Guard: only dispute.created, so the dispute.state.updated and evidence events stay quiet.
    if (body.type !== "dispute.created" || !dispute || typeof dispute !== "object") {
        console.log(`Ignoring Square event "${typeof body.type === "string" ? body.type : "unknown"}"`)
        return null
    }

    // An inquiry is the bank asking questions before a chargeback; the money hasn't moved yet.
    const inquiry = typeof dispute.state === "string" && dispute.state.startsWith("INQUIRY")
    const amount = money(dispute.amount_money) ?? "A payment"
    const brand = pick(BRANDS, dispute.card_brand, null)
    const reason = pick(REASONS, dispute.reason, null)
    const due = day(dispute.due_at)
    const sandbox = String(header(request, "square-environment") ?? "").toLowerCase() === "sandbox"

    return {
        title: inquiry ? "❓ Dispute inquiry" : "⚖️ New dispute",
        message:
            amount +
            (brand ? ` ${brand} payment` : "") +
            (inquiry ? " questioned by the bank" : " disputed") +
            (reason ? ` as "${reason}"` : "") +
            "." +
            (due ? ` Respond by ${due}.` : "") +
            (sandbox ? " (sandbox)" : ""),
        topic: "Square",
        // Highest for a chargeback: the money is held and the evidence clock is ticking.
        // High for an inquiry: it still needs an answer, but nothing has been taken yet.
        priority: inquiry ? 1 : 2,
        buttons: sandbox ? [] : link("https://app.squareup.com/dashboard", "Open Dashboard"),
    }
}
```

## Square dispute.created webhook payload (sample)

```json
{
  "data": {
    "id": "ORSEVtZAJxb37RA1EiGw",
    "type": "dispute",
    "object": {
      "dispute": {
        "id": "ORSEVtZAJxb37RA1EiGw",
        "state": "EVIDENCE_REQUIRED",
        "due_at": "2026-10-04T00:00:00.000Z",
        "reason": "AMOUNT_DIFFERS",
        "version": 1,
        "card_brand": "VISA",
        "created_at": "2026-09-19T21:24:53.258Z",
        "updated_at": "2026-09-19T21:24:53.258Z",
        "location_id": "VJDQQP3CG14EY",
        "reported_at": "2026-09-19T00:00:00.000Z",
        "amount_money": {
          "amount": 8801,
          "currency": "USD"
        },
        "brand_dispute_id": "r9rKGSBBQbywBNnWWIiGFg",
        "disputed_payment": {
          "payment_id": "fbmsaEOpoARDKxiSGH1fqPuqoqFZY"
        }
      }
    }
  },
  "type": "dispute.created",
  "event_id": "ce8464b5-6628-4ac2-9264-e06c34df3e82",
  "created_at": "2026-09-19T21:24:53.258Z",
  "location_id": "VJDQQP3CG14EY",
  "merchant_id": "0HPGX5JYE6EE1"
}
```

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