Square

Adapter 0.1.0, documentation reviewed 2026-10-25. Overall status: limited.

Capabilities

Error decoding	supported
API response parsing	supported
Webhook / notification parsing	supported
Timeline	limited
Event correlation	limited
Diagnostic rules	limited

Supported input

Format	Description	Status
`square.error_response`	Payments and Refunds API error responses ({ errors: [{ category, code, detail, field }] }), optionally with the FAILED payment or refund	supported
`square.payment`	Payment objects, bare or wrapped as { payment: {...} }	supported
`square.refund`	PaymentRefund objects, bare or wrapped as { refund: {...} }	supported
`square.webhook`	payment.created, payment.updated, refund.created and refund.updated webhook events	supported
`square.webhook.other`	Other webhook event families (for example dispute.* or payout.*)	unsupported

Notification delivery

Repeated deliveries are recognized by event_id; Square documents that notifications can be delivered more than once.
Delivery order: not guaranteed by the provider.
Record processed event_id values and skip repeats before acting on a notification. Base state on the object's updated_at, not on arrival order.

Known limitations

Square does not document which ErrorCategory each ErrorCode belongs to. The category is read from the payload; PandaPayLens category and retry mappings are derived from the documented code descriptions.
Retry guidance is official only for RATE_LIMITED and TEMPORARY_ERROR. All other retry classes are PandaPayLens judgments.
Unknown ErrorCode values fall back to the payload's category with lower confidence, then to unknown.
card_details.status values (AUTHORIZED, CAPTURED, VOIDED, FAILED) are shown as provider status only. Square does not document their per-value meaning.
Webhook delivery order is not guaranteed. The timeline uses the object's updated_at, then the event's created_at. A single payload holds only the current snapshot of the object, not its history.
Webhook signatures (x-square-hmacsha256-signature) are not verified: that needs the subscription signature key and notification URL. The header is treated as sensitive.
Events are linked only by the payment id and refund.payment_id (and the refund id between refund events). order_id links to the Orders API and is not documented as unique per payment attempt, and reference_id is caller-supplied, so neither is used for correlation.
In Square's documented payment.created example, data.id differs from the payment id. PandaPayLens uses the payment's own id and falls back to data.id only when the payment id is missing.
idempotency_key is not echoed in responses, so an error response can only be linked to a payment when it includes the payment or refund object.
No documented example shows an error response that includes the FAILED payment or refund. This shape is supported from the documented rule and tested with synthetic data.
The refund webhook object's version field is not in the PaymentRefund reference. It is shown as an attribute only.
Square does not expose the issuer's raw decline code; only Square's own error code is available.
Webhook families other than payment.* and refund.* (for example dispute.* or payout.*) are recognized but not analyzed. Disputes, Terminal, Orders and the legacy v1 APIs are not covered.
HTTP status is documented only for some codes, and documentation is inconsistent for PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE (400 vs 404), so the HTTP status is not used for classification.

Examples

Square: declined card payment: An error response that includes the FAILED payment.
Square: payment and refund webhooks: payment.* and refund.* events grouped by payment id.

Provider documentation

PandaPayLens is not affiliated with Square. Pasted notifications are never treated as verified: PandaPayLens does not check webhook signatures.