Square

What you need

Why we ask for each field

Access token

Authorizes creating the checkout link, so the charge runs through your account.

Webhook signature key

Proves an incoming webhook is genuinely from Square, so nobody can forge a "paid" event. It is a separate value from the access token.

Location ID

Tells Square which location receives the money, and sets the checkout currency. Not secret.

Success and Cancel URL

Plain settings: where the buyer lands after paying or backing out. Not secret.

Set up

1. Create a free developer account (no payment)

   Square’s developer account is free and includes a built-in sandbox with test locations.

   1. Sign in at developer.squareup.com.
   2. Open or create an application. Each has a Production side and a Sandbox side. Set up sandbox first, then repeat in production.
2. Copy your credentials
   • Access token: the Credentials page (Production or Sandbox).
   • Location ID: the Locations page. Copy the location that should receive payments.

   

3. Add the webhook
   1. Webhooks → Subscriptions, add an endpoint.
   2. Set the notification URL to your project webhook address (below).
   3. Subscribe to events. One-time payments: payment.created, payment.updated, refund.created, refund.updated, dispute.created, dispute.state.updated. Subscriptions: subscription.created, subscription.updated, subscription.canceled, subscription.deactivated, invoice.payment_made, invoice.scheduled_charge_failed. Extra events are harmless.
   4. Copy the endpoint Signature key. Set up a separate endpoint in sandbox and in production.

   https://<your Coin Moebius host>/webhook/square/<your project id>

   

4. Test with a sandbox card

   Sandbox cards never charge a real card. Card 4111 1111 1111 1111, CVV 111, any future expiration, any valid postal code (for example 94103).

5. Connect in the dashboard

   Add provider → Square. Enter Success URL, Cancel URL, and the Live group (Access token, Webhook signature key, Location ID). Add the optional Sandbox group to test. The Sandbox group is all-or-nothing: all three fields, or none. Live and sandbox are checked separately.

After you connect

Run one test payment before going live:

1. Create a product and set its Environment to Testing. That runs the product on your sandbox credentials, so you can place a full order without moving money. (If you skipped the sandbox set, a Testing product falls back to live, so add it first.)
2. Place the buy button on a page (a local HTML file works) pointed at your project.
3. Complete checkout with the sandbox test card from above.
4. Open the Transactions tab. A new row appears, tagged Testing. When its status reaches succeeded, your credentials and webhook are both working end to end.

Switch the product Environment to Live when you are ready for real payments.

Troubleshooting

Start with Verify. In the dashboard, click Verify (or Verify test credentials) to check your access token and location.

Verify fails.

Re-copy the access token and Location ID. Production and Sandbox have separate tokens, so do not mix them.

Signature verification fails, or the order stays pending.

Square signs over the exact notification URL plus the body. The URL you register in Square must match your webhook URL character for character, with no trailing slash and no extra query string. Then re-copy the signature key from that same endpoint.

Confirm it end to end.

Square Developer Console → Webhooks → your subscription → Send Test Event, then watch the order update.

Good to know

Currency follows the location. The checkout charges in the currency of the location whose id you provide.

Rotating secrets. Roll the access token or signature key anytime, then paste the new value. Secret fields stay blank on edit.

Questions? [email protected]