Set up Square

Confirm backend ownership

• Select the merchant and Carden environment used by the Square backend.
• Keep Square access tokens, application secrets, webhook signature keys, source tokens, and idempotency keys in that backend.
• Create a Carden key for the Square integration; a Stripe or QuickBooks key is rejected even if it has a similarly named scope.
• Choose linked QuickBooks preparation, inline CanonicalInvoice preparation, reporting only, or separate service keys.

Create an Order, then attach its Payment

1. Configure QuickBooks as a source, or supply a complete authoritative invoice inline.
2. Create a Square-integration Carden key with enrichment:write and payments:write; add invoices:read only for linked-source access.
3. Ask Carden to prepare Square Order context and review the exact total and source references.
4. Add the actual location_id and a Square idempotency_key, then call CreateOrder once.
5. Call CreatePayment once with its own idempotency key, payment source, returned order_id, and matching amount.
6. Persist the attempt and deliver a normalized report; later verified provider states become new immutable report events.

POST /api/v1/square/order-enrichment
POST /api/v1/square/order-enrichment/from-invoice
POST /api/v1/square/payment-reports

Do not merge Carden preparation metadata into CreateOrder. Save it beside the merchant attempt and use preparation.id only for later Carden correlation.

Supply provider-owned fields

• Use the merchant's actual Square location; Carden never chooses or fabricates one.
• Generate Square idempotency keys in the merchant payment system and keep Order and Payment identities separate.
• Use actual catalog IDs only when the merchant has established them; the Carden fragment uses factual ad hoc lines.
• Pass the actual Square order_id to CreatePayment and persist paymentId, orderId, and locationId for reconciliation.
• Verify Square provider webhook signatures with the exact configured notification URL, signature key, and raw body.

Validate before production

1. Prepare a known sandbox invoice and inspect Order arithmetic.
2. Create the Order and Payment once with merchant-owned idempotency.
3. Report APPROVED, COMPLETED, CANCELED, FAILED, PENDING, and refund cases through normalized fixtures.
4. Exercise duplicate Carden delivery, denied provider scope, ambiguous Square transport outcomes, and out-of-order provider events.
5. Confirm that a Carden report failure never repeats CreateOrder or CreatePayment.