Reference · built on requestConnectorPayments, billing & fraud

Square

Payments, refunds, orders, invoices, disputes, customers, and payouts from Square's REST API and webhooks.

Request accessPricing ↗

About

Square runs card payments, point of sale, invoicing, and online checkout for sellers. Its REST API at connect.squareup.com exposes Payments, Refunds, Orders, Invoices, Disputes, Customers, Payouts, and Subscriptions, and its webhooks send events such as payment.updated, refund.updated, dispute.state.updated, invoice.payment_made, and payout.paid.

Through Fibric, an operator watches those events across your locations and proposes what to do next: complete a delayed-capture payment, refund a payment, submit dispute evidence before the due_at deadline, or chase a failed invoice charge. You approve each proposal. The connector then makes one call, carrying the unique key Square requires so a retried request cannot charge twice, and keeps the receipt.

This is a reference listing. It documents what Fibric would read from Square and what it could propose, based on the vendor's published interfaces. Fibric builds it under a managed deployment when you request it; selecting it here installs nothing.

Inputs

  • payment.created and payment.updated events, with GetPayment and ListPayments for the full payment record
  • refund.created and refund.updated events from the Refunds API
  • dispute.created, dispute.state.updated, and dispute.evidence.added events, plus reason, state, and due_at from RetrieveDispute
  • order.created, order.updated, and order.fulfillment.updated events from the Orders API
  • invoice.published, invoice.payment_made, invoice.scheduled_charge_failed, and invoice.refunded events
  • payout.sent, payout.paid, and payout.failed events, and customer.created and customer.updated

Proposed actions

  • Target capability: propose completing an approved delayed-capture payment through CompletePayment (POST /v2/payments/{payment_id}/complete)
  • Target capability: propose cancelling an approved payment through CancelPayment (POST /v2/payments/{payment_id}/cancel)
  • Target capability: propose a refund through the Refunds API
  • Target capability: propose uploading dispute evidence with CreateDisputeEvidenceFile or CreateDisputeEvidenceText, then SubmitEvidence
  • Target capability: propose accepting a dispute through AcceptDispute (POST /v2/disputes/{dispute_id}/accept)

Proposed actions are target capabilities. Every action runs propose-first and needs a validated deployment and the appropriate permissions.

What you can build

  • Submit dispute evidence before due_at

    dispute.created carries the reason and deadline. The operator gathers the payment, order, and fulfillment records, proposes text and file evidence, and after approval uploads and submits it once.

    With Chargeback Evidence

  • Tie payouts to payments

    payout.paid announces a deposit. The operator lists the payments and refunds behind it and flags any bank line that does not match.

    With Payout Reconciliation, Bank Reconciliation

  • Chase a failed scheduled invoice charge

    invoice.scheduled_charge_failed fires when an automatic charge fails. The operator proposes the next reminder step and the customer message for approval.

    With Dunning Cadence, Payment Retry

  • Release a delayed-capture payment

    For a payment left APPROVED pending review, the operator weighs the order and customer record and proposes CompletePayment or CancelPayment.

    With Order Risk

Requirements

  • A Square seller account and an application in the Developer Console
  • An access token: personal for a single account, or OAuth with the permissions each API needs, refreshed before it expires
  • A webhook subscription with an HTTPS notification URL, created in the Developer Console or through the Webhook Subscriptions API
  • The subscription's signature key, so each notification's x-square-hmacsha256-signature header can be checked
Authentication
A Bearer access token, either a personal access token for your own account or an OAuth access token with scopes such as DISPUTES_READ and DISPUTES_WRITE, sent with a Square-Version header.

Limits

  • Once evidence is uploaded through the API, the dispute can no longer be challenged or accepted from the Disputes Dashboard.
  • Webhook notifications are retried for up to 24 hours with exponential backoff, 11 attempts from 1 minute to 8-hour intervals; events can arrive late.
  • Sandbox and production use different base URLs and tokens; a sandbox token does not reach production data.
  • If no Square-Version header is sent, the application's default API version applies, which can change response shapes.

Access and pricing

Reference listing. Fibric builds the connector under a managed deployment when you request it. Your quote covers the build, capabilities, usage, and support.

Request Square ↗

Questions and answers

How does Square sign webhook notifications?
Each notification carries an x-square-hmacsha256-signature header: an HMAC-SHA-256 over the notification URL and the raw request body, keyed with the subscription's signature key. Square's SDKs include a WebhooksHelper that performs the comparison.
What happens if the listener is down?
Square resends the notification for up to 24 hours after the originating event, using exponential backoff. Retried notifications include square-retry-number and square-retry-reason headers, so the connector can tell a retry from a first delivery.
Which permissions do disputes need?
DISPUTES_READ to list and retrieve disputes and evidence, and DISPUTES_WRITE to upload evidence, submit it, or accept the dispute. A personal access token carries full access; an OAuth token must request these scopes.
Ask about Square

Ask about the capabilities and requirements in this listing.

For project-specific requirements, contact Fibric.

This connector listing is developed, published, and supported by Fibric. It describes integration with Square through published interfaces. Third-party names and logos identify the systems an integration connects to; they are the property of their respective owners, who are not affiliated with Fibric and do not sponsor or endorse this listing. Trademark policy