Square troubleshooting
Recover Square Order, Payment, source, identity, and reporting failures without repeating provider operations.
On this page
Identify the failed Square stage
- Confirm merchant, Carden environment, Square integration, Carden key, and provider environment.
- Save request ID, preparation.id, attemptId, eventId, and known orderId, paymentId, and locationId values.
- Separate source lookup, Carden preparation, CreateOrder, CreatePayment, Square webhook verification, Carden report delivery, and payout reconciliation.
- Inspect the authoritative system for that stage and retry only its safe operation.
Resolve Order preparation and arithmetic
| Symptom | Recovery |
|---|---|
| Wrong provider scope | Use a Square-integration Carden key; Stripe and QuickBooks keys are rejected. |
| Missing location or idempotency | Add the merchant's actual provider-owned values after Carden preparation. |
| 400 shape or field limit | Correct the strict request and factual references. |
| 422 quantity or arithmetic | Correct source quantities, tax, discount, shipping, and totals; never infer missing provider units. |
| 409 source or revision | Finish QuickBooks refresh and review the current immutable source revision. |
| Order total differs | Do not create the Payment until Square-computed Order total and intended amount are reconciled. |
Carden uses fixed tax, discount, and service-charge amounts to preserve source facts. It rejects overlong references and unsupported fractional quantities instead of silently truncating or guessing.
Reconcile ambiguous Payments
- Persist Square Order and Payment idempotency keys and returned IDs before relying on network delivery.
- Retrieve Payment state after a timeout; PENDING remains unknown until provider evidence establishes another state.
- Verify Square webhook signatures using the exact notification URL, signature key, and raw body.
- Use cumulative captured and refunded amounts and tolerate duplicate or out-of-order events.
- Keep separate attempt IDs for multiple Payments attached to one Order.
Recover Carden report delivery
| Response | Action |
|---|---|
| 2xx, including duplicate | Acknowledge the outbox event. |
| 408, 429, 5xx, timeout, connection | Retry the same eventId and body with bounded backoff. |
| 401 / 403 | Pause and repair the active Square-integration key and scope. |
| 400 / 422 | Quarantine and correct factual normalized fields; create a new event for a correction. |
| 409 | Reconcile event identity, payment aliases, cumulative amounts, currency, and occurrence order. |
Do not infer savings from bundled fees
Square processing_fee and payout entries can support reconciliation but do not by themselves establish network-level interchange qualification. Standard bundled pricing often prevents an underlying interchange reduction from changing merchant cost.
Escalate with safe Carden and Square IDs, response classes, actual timestamps, and payment impact. Keep access tokens, webhook keys, source tokens, raw card data, and unrestricted provider objects out of logs.