billingHelp

Square

From a Square account to live payments — the developer application, Application ID, access token and location, the webhook subscription and signature key.

Create the account#

  1. Sign up at squareup.com and complete the identity and bank verification. Square accounts used here must settle in US dollars.
  2. Open the Developer Console (developer.squareup.com) with the same login and create an application named after your store.

Copy the credentials#

In your application, switch the toggle to Sandbox first:

  • Credentials → Application ID (sandbox-sq0idb-…) and Access token.
  • Locations → the Location ID that should receive payments.

Paste them into a new Square credential set with environment Test. Verify reads the location; it fails unless the location settles in USD, and reports whether card processing is enabled.

Register the webhook#

Application → Webhooks → Subscriptions → Add subscription:

  1. Notification URL — paste it exactly as shown on your set; Square signs the URL together with the body, so one different character breaks every delivery:
  1. Choose the latest API version and these events:
  • payment.created
  • payment.updated
  • refund.created
  • refund.updated
  • subscription.created
  • subscription.updated
  • invoice.payment_made
  • invoice.scheduled_charge_failed
  • dispute.created
  • dispute.state.updated
  1. Save, open the subscription, and Show the Signature key. Paste it into the set.

Then Put in service (Test).

Test in the sandbox#

Pay with Square's sandbox card 4111 1111 1111 1111, any future date, CVV 111, any postal code. Square adds its processing fee a moment after the payment; the fee then appears on the payment.

What Square does differently#

  • No free trials through Square: a plan with trial days does not show the Square tile.
  • Cancel always takes effect at the end of the paid period.
  • Square retries failed renewals itself; there is no "retry now".
  • Dispute evidence is submitted in Square's dashboard; record it here afterwards.

Go live#

  • [ ] Toggle the application to Production: production Application ID (sq0idp-…), access token and Location ID in a live set.
  • [ ] A production webhook subscription with the live set's URL, the same events, and its own signature key.
  • [ ] Products switched to the live set.
  • [ ] One small real payment and refund.

Common errors#

MessageFix
Verify: location does not settle in USDChoose a US location, or this account cannot be used.
Webhook deliveries answer 400The subscription URL differs from the set's URL, or the signature key is from another subscription. Each subscription has its own key.
Application ID belongs to the other environmentSandbox IDs start sandbox-; production IDs do not.

Technical details#

Credentials. Go to developer.squareup.com → your application → Credentials, using Sandbox or Production.

  • Application ID.
  • Access token, stored sealed.
  • The Location ID from the Locations tab.

Verify reads the location. It fails unless the location settles in USD, and it reports whether card processing is enabled. Requests pin Square-Version: 2025-10-16.

Webhook. Go to Webhooks → Subscriptions → Add subscription. Paste the URL exactly as shown (https://encrypted.com/webhooks/square.php?cs=…), because Square signs the URL together with the body. If the site's base URL changes, update the subscription. Select these events:

  • payment.created, payment.updated
  • refund.created, refund.updated
  • subscription.created, subscription.updated
  • invoice.payment_made, invoice.scheduled_charge_failed
  • dispute.created, dispute.state.updated

Copy the subscription's Signature key into the set. The check is base64(HMAC-SHA256(key, notification URL + raw body)).

One-time flow. A payment link is created from an order whose reference_id is our checkout id; the link's payment_note carries it as well. payment.updated with status COMPLETED marks the payment Paid. APPROVED or PENDING shows Processing; FAILED or CANCELED marks it Failed. Square usually adds processing_fee a little after completion: the later payment.updated fills in the fee without changing the paid time.

Subscriptions.

  • A SUBSCRIPTION_PLAN (per product) and a SUBSCRIPTION_PLAN_VARIATION (per price, STATIC pricing; cadence MONTHLY, QUARTERLY or ANNUAL) are created once and cached.
  • The payment link uses quick_pay with the phase price and checkout_options.subscription_plan_id = the variation id. Square's documentation names the field subscription_plan_id, but it takes the variation id.
  • After payment Square creates the customer, the card on file and the subscription. The subscription is found with SearchSubscriptions (same customer and variation).
  • If Square has not created it yet, the webhook answers 500 and Square retries.
  • Renewals arrive as invoice.payment_made. Each charge is keyed by the Square payment id, so the first invoice and the checkout payment are never counted twice.
  • invoice.scheduled_charge_failed means Past due. DEACTIVATED means Unpaid.

Free trials are not offered through Square. Square's hosted checkout supports a free phase, but how quick_pay pricing interacts with a free first phase is not verified. A trial plan with Square is refused before any checkout is created, with a clear message. Use PayPal, Stripe or Authorize.net for trials.

Cancellation. Square cancels at the end of the paid period. The subscription shows cancels at period end until then.

Refunds and disputes. Refunds go through the Refunds API and are confirmed by refund.updated with COMPLETED. REJECTED or FAILED refunds are not counted. Disputes: created means Disputed; LOST or ACCEPTED means Chargeback; WON means Paid again.