Getting started with Square
Prepare a Square Order fragment from one fresh, authoritative source invoice and preserve its evidence.
On this page
Link the source to Square
- Connect and reconcile a supported invoice source inside the same merchant and environment as Square.
- Resolve factual invoice and item-mapping exceptions before payment preparation.
- Enable the invoice source on the Square integration with authority over both providers.
- Issue a Square-integration Carden key with invoices:read and enrichment:write.
A Stripe-integration key cannot call Square preparation. Linking does not alter existing keys and does not grant source-management scopes to the Square service.
Prepare one stored invoice
POST /api/v1/square/order-enrichment/from-invoice| Input | Rule |
|---|---|
| invoice reference | Pass the known Carden invoiceId, or use an unambiguous invoiceNumber instead. |
| amountMinor / currency | Positive full invoice amount and exact lowercase source currency. |
| expectedRevision | Optional. Rejects changes since a reviewed revision; omit to use the current stored invoice. |
| idempotencyKey | Stable preparation key persisted before the first request. |
- The invoice must be open, positive, fully unpaid, and ready.
- The invoice source must be active, fresh, and free of pending refresh work.
- Fractional quantities, unresolved source facts, unsupported freight or deposits, and invalid arithmetic remain blocked.
- Partial allocations and combined invoices require a separately supported matching workflow.
Merge only the Order fragment
The response includes Square request fields in data and immutable source evidence in preparation. Save preparation.id, snapshotId, revision, source IDs, amount, currency, and diagnostic request ID with the payment attempt.
Add the merchant's real location_id and Square Order idempotency key outside the Carden fragment. Create the Order once, then call CreatePayment with the returned order_id and a separately idempotent provider request.
Report from saved preparation evidence
Use preparation.id as enrichmentRequestId when delivering the Square payment observation. Later captures, failures, cancellations, or refunds keep attemptId and preparation.id while using a new eventId and cumulative amounts.
A later source invoice edit or source disconnect cannot rewrite the historical snapshot. If actual Payment amount or currency differs, report the actual Square facts and retain the correlation exception for review.