Square API
Prepare Square Order fields and submit normalized Square Payment observations with a provider-scoped Carden key.
On this page
Endpoints and authorization
| Method | Path | Required Carden scope |
|---|---|---|
| POST | /api/v1/square/order-enrichment | enrichment:write on a Square integration key |
| POST | /api/v1/square/order-enrichment/from-invoice | invoices:read + enrichment:write on a Square integration key |
| POST | /api/v1/square/payment-reports | payments:write on a Square integration key |
Every endpoint rejects a Carden key issued for another provider. Authorization fixes organization, integration, and environment. Square paymentId, orderId, and locationId are business references and never tenant selectors.
Send application/json over HTTPS with Authorization: Bearer <CARDEN_API_KEY>. Never send Square access tokens, application secrets, payment source tokens, card numbers, or raw Square objects.
Prepare from an inline invoice
POST /api/v1/square/order-enrichmentThe body contains invoice: CanonicalInvoice and optional orderReference, taxRepresentation, and discountRepresentation options. All money uses safe integer minor units. The adapter validates line arithmetic, invoice arithmetic, field limits, unique sequences, and positive integral quantity strings.
Success returns object: square.order_enrichment, api_version: v1, and data containing reference_id, line_items, and applicable taxes, discounts, service_charges, and metadata. Square Money currencies are uppercase. The result is an Order fragment, not a complete CreateOrder request.
Prepare from linked QuickBooks
POST /api/v1/square/order-enrichment/from-invoiceSupply exactly one invoiceId, quickbooksInvoiceId, or invoiceNumber; positive amountMinor; lowercase currency; stable idempotencyKey; and optional expectedRevision. QuickBooks must be linked to this Square integration, fresh, active, and authorized.
Only an open, fully unpaid invoice whose total, balance, and currency match the intended payment can be prepared. Save response preparation.id with the attempt and use it as enrichmentRequestId. The diagnostic HTTP request ID can differ across an accepted idempotent retry.
Submit a Payment observation
POST /api/v1/square/payment-reports| Field | Rule |
|---|---|
| eventId / attemptId | Required stable references. Retry one event unchanged; later events reuse attemptId. |
| paymentId / orderId / locationId | Optional actual Square identifiers; omit unknown values. |
| status | requires_action, authorized, captured, partially_refunded, refunded, failed, canceled, or unknown. |
| currency | Three lowercase letters used by all report amounts. |
| amountMinor / capturedAmountMinor / refundedAmountMinor | Required coherent nonnegative cumulative safe integers. |
| occurredAt | Required timezone-aware event time no more than five minutes in the future. |
| enrichmentRequestId / invoiceReference | Optional preparation and source correlation. |
| providerEventId / source | Optional provider event and required sdk, merchant_webhook, or api reporting path. |
Success returns square.payment_report with data.id and data.duplicate. duplicate: true acknowledges the identical accepted event. An accepted event ID with different payload produces 409.
Normalize Square states
| Square state | Carden state |
|---|---|
| APPROVED | authorized |
| COMPLETED | captured, partially_refunded, or refunded according to cumulative refunded_money |
| CANCELED | canceled |
| FAILED | failed |
| PENDING or ambiguous transport | unknown until a retrieved Payment or verified event establishes state |
A Square Order can have multiple Payments. Carden therefore uses paymentId and merchant attemptId as payment identities; orderId is correlation evidence and never merges distinct payments by itself.
Verify provider events and retry safely
- Verify x-square-hmacsha256-signature in the merchant handler using the raw body, configured notification URL, and signature key.
- Retrieve current Payment state when an event is ambiguous or out of order.
- Persist only the normalized allowlisted Carden report, not the raw provider object.
- Retry immutable report delivery independently of Square execution.
- Reconcile reports separately from payout and network-qualification evidence.
Correct 400 and 422 factual request failures. Repair 401 and 403 credentials or provider scope. Reconcile 409 identity or cumulative totals. Retry 408, 429, transport errors, and 5xx responses under a bounded policy without repeating CreatePayment.