Square SDK usage
Prepare Square Order context and report Payment outcomes with Node.js, Ruby, Python, PHP, Java, Go, .NET, or direct HTTP.
On this page
Keep the SDK around Square execution
Carden does not execute the provider operation
The SDK prepares factual context and reports observations while the merchant backend owns Square.
Prepare
Request an Order fragment
Use an inline invoice or an exact linked QuickBooks selector.
Order
Create the Square Order
Add actual location and provider idempotency before CreateOrder.
Pay
Create the Payment
Use the merchant payment source, order_id, amount, and separate idempotency.
Report
Deliver the observation
Persist a normalized event and retry Carden independently.
Initialize a Carden client in a trusted server process with a Square-integration key. Provider access tokens and signature keys remain in the merchant's Square code.
Prepare a linked invoice for Square
A linked-invoice service needs invoices:read and enrichment:write. The method accepts the same exact invoice selector, amount, currency, expected revision, and preparation idempotency used by the stored-invoice model.
Prepare a linked invoice for Square
const invoice = await carden.invoices.retrieve(invoiceId);
const prepared = await carden.square.createOrderEnrichmentFromInvoice({
invoiceId: invoice.id,
amountMinor: 11300,
currency: "usd",
expectedRevision: invoice.revision,
idempotencyKey: "square_prepare_attempt_1042_1",
});
await attemptStore.attachPreparation(attemptId, prepared.preparation);Every language returns a Square Order fragment plus immutable preparation metadata and a diagnostic request ID in its native shape. Save preparation.id, merge only enrichment, and add provider-owned location and idempotency fields yourself.
Deliver a saved Square payment report
Report the actual Square payment state with stable eventId and attemptId, lowercase currency, cumulative amounts, actual occurrence time, and factual provider references when known.
Deliver a saved Square payment report
const receipt = await carden.square.reportPayment(squareReport, {
maxRetries: 0,
timeoutMs: 5000,
});
await reportOutbox.markDelivered(squareReport.eventId, receipt);Understand the method boundary
| Method family | Responsibility |
|---|---|
| createOrderEnrichment | Validate an inline CanonicalInvoice and return a mergeable Square Order fragment. |
| createOrderEnrichmentFromInvoice | Read one authorized QuickBooks invoice and return enrichment plus immutable preparation metadata. |
| reportPayment | Validate and deliver one immutable normalized Square observation. |
| trackPayment, where available | Run one merchant operation and attempt a report without turning report failure into a provider retry. |
| paymentObservationFromSquarePayment, where available | Normalize a local Square Payment snapshot without verifying webhook trust. |
Language naming follows native conventions, as shown in the tabs. Provider-specific helpers do not accept Square credentials and do not call CreateOrder or CreatePayment.
Test errors and recovery
- Reject a Carden key issued for Stripe or QuickBooks even if its scope names match.
- Correct factual 400 and 422 request failures without inventing source or provider data.
- Reconcile 409 identity or cumulative-amount conflicts instead of blind retry.
- Retry safe preparation or immutable reporting after 408, 429, 5xx, timeout, or connection failures.
- Exercise ambiguous Square transport outcomes and out-of-order provider events without an extra payment.