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.
Monday 5 October
9:41
JustPushnow
New dispute
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.
Three steps to your first push
STEP 01
Install the recipe
One click in Studio gives you a personal webhook URL.
STEP 02
Paste your URL into Square
Add it as a webhook for dispute.created.
STEP 03
Get a push on your phone
With the text, sound and buttons from the recipe.
How to set up the Square dispute.created webhook
- Click Install in Studio and sign in. The recipe is added to your account and you get a personal webhook URL.
- In the Square Developer Console (developer.squareup.com/apps), open your application (create a free one if you have none) and switch to Production.
- Under Webhooks, choose Subscriptions and click Add subscription.
- Paste your webhook URL as the notification URL, tick the dispute.created event, and save.https://••••••••/•••••••• your personal URL, shown after install
- 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.
- Sandbox deliveries are marked **(sandbox)** and get no Dashboard button.
- 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.
What runs when the webhook arrives
Studio calls handleRequest(request) with the incoming webhook and sends the message it returns. It's yours after install; change anything.
transform.js
1// Square → dispute.created
2// Fires when a cardholder's bank opens a chargeback (or an inquiry) on one of your payments.
3// Docs: https://developer.squareup.com/docs/disputes-api/process-disputes#webhook-notifications
4
5// Square's DisputeReason values, in plain words.
6const REASONS = {
7 AMOUNT_DIFFERS: "amount differs",
8 CANCELLED: "cancelled",
9 DUPLICATE: "duplicate charge",
10 NO_KNOWLEDGE: "not recognised",
11 NOT_AS_DESCRIBED: "not as described",
12 NOT_RECEIVED: "not received",
13 PAID_BY_OTHER_MEANS: "paid by other means",
14 CUSTOMER_REQUESTS_CREDIT: "customer requests credit",
15 EMV_LIABILITY_SHIFT: "EMV liability shift",
16}
17
18const BRANDS = {
19 VISA: "Visa",
20 MASTERCARD: "Mastercard",
21 AMERICAN_EXPRESS: "American Express",
22 DISCOVER: "Discover",
23 DISCOVER_DINERS: "Diners Club",
24 JCB: "JCB",
25 CHINA_UNIONPAY: "UnionPay",
26 INTERAC: "Interac",
27 EFTPOS: "eftpos",
28}
29
30// Header names can arrive in any case.
31function header(request, name) {
32 const headers = request.headers || {}
33 const key = Object.keys(headers).find((k) => k.toLowerCase() === name)
34 const value = key ? headers[key] : null
35 return Array.isArray(value) ? value[0] : value
36}
37
38// Table lookup that ignores inherited names such as "toString".
39function pick(table, key, fallback) {
40 return typeof key === "string" && Object.prototype.hasOwnProperty.call(table, key) ? table[key] : fallback
41}
42
43// Only link to real http(s) URLs.
44function link(url, cta) {
45 return typeof url === "string" && /^https?:\/\//.test(url) ? [{ cta, url }] : []
46}
47
48// Square Money is { amount, currency } with amount in the currency's smallest unit
49// (cents for USD/EUR/GBP, whole yen for JPY). Returns null when there's no amount.
50function money(value) {
51 const amount = value?.amount
52 const currency = value?.currency
53
54 if (typeof amount !== "number" || !Number.isFinite(amount) || typeof currency !== "string" || !currency) return null
55
56 try {
57 const format = new Intl.NumberFormat("en-GB", { style: "currency", currency })
58 return format.format(amount / 10 ** format.resolvedOptions().maximumFractionDigits)
59 } catch {
60 return null
61 }
62}
63
64// "4 Mar" from an RFC 3339 timestamp; null when it doesn't parse.
65function day(value) {
66 const date = typeof value === "string" ? new Date(value) : null
67 if (!date || Number.isNaN(date.getTime())) return null
68 return date.toLocaleDateString("en-GB", { day: "numeric", month: "short", timeZone: "UTC" })
69}
70
71function handleRequest(request) {
72 const body = request.body && typeof request.body === "object" ? request.body : {}
73 const dispute = body.data?.object?.dispute
74
75 // Guard: only dispute.created, so the dispute.state.updated and evidence events stay quiet.
76 if (body.type !== "dispute.created" || !dispute || typeof dispute !== "object") {
77 console.log(`Ignoring Square event "${typeof body.type === "string" ? body.type : "unknown"}"`)
78 return null
79 }
80
81 // An inquiry is the bank asking questions before a chargeback; the money hasn't moved yet.
82 const inquiry = typeof dispute.state === "string" && dispute.state.startsWith("INQUIRY")
83 const amount = money(dispute.amount_money) ?? "A payment"
84 const brand = pick(BRANDS, dispute.card_brand, null)
85 const reason = pick(REASONS, dispute.reason, null)
86 const due = day(dispute.due_at)
87 const sandbox = String(header(request, "square-environment") ?? "").toLowerCase() === "sandbox"
88
89 return {
90 title: inquiry ? "❓ Dispute inquiry" : "⚖️ New dispute",
91 message:
92 amount +
93 (brand ? ` ${brand} payment` : "") +
94 (inquiry ? " questioned by the bank" : " disputed") +
95 (reason ? ` as "${reason}"` : "") +
96 "." +
97 (due ? ` Respond by ${due}.` : "") +
98 (sandbox ? " (sandbox)" : ""),
99 topic: "Square",
100 // Highest for a chargeback: the money is held and the evidence clock is ticking.
101 // High for an inquiry: it still needs an answer, but nothing has been taken yet.
102 priority: inquiry ? 1 : 2,
103 buttons: sandbox ? [] : link("https://app.squareup.com/dashboard", "Open Dashboard"),
104 }
105}
The Square dispute.created webhook
This is what Square sends to your URL for dispute.created. It is a sample, trimmed to the fields recipes use.
dispute.created · sample.json
1{
2 "data": {
3 "id": "ORSEVtZAJxb37RA1EiGw",
4 "type": "dispute",
5 "object": {
6 "dispute": {
7 "id": "ORSEVtZAJxb37RA1EiGw",
8 "state": "EVIDENCE_REQUIRED",
9 "due_at": "2026-10-04T00:00:00.000Z",
10 "reason": "AMOUNT_DIFFERS",
11 "version": 1,
12 "card_brand": "VISA",
13 "created_at": "2026-09-19T21:24:53.258Z",
14 "updated_at": "2026-09-19T21:24:53.258Z",
15 "location_id": "VJDQQP3CG14EY",
16 "reported_at": "2026-09-19T00:00:00.000Z",
17 "amount_money": {
18 "amount": 8801,
19 "currency": "USD"
20 },
21 "brand_dispute_id": "r9rKGSBBQbywBNnWWIiGFg",
22 "disputed_payment": {
23 "payment_id": "fbmsaEOpoARDKxiSGH1fqPuqoqFZY"
24 }
25 }
26 }
27 },
28 "type": "dispute.created",
29 "event_id": "ce8464b5-6628-4ac2-9264-e06c34df3e82",
30 "created_at": "2026-09-19T21:24:53.258Z",
31 "location_id": "VJDQQP3CG14EY",
32 "merchant_id": "0HPGX5JYE6EE1"
33}
Square new dispute notifications: questions
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.
Ready when you are
Square on your phone in two minutes.
Install the recipe, paste one URL, done. Free for 30 days, no credit card required.