What you need
| Field | What it does |
|---|---|
| Access token | Lets us call Square to create the checkout link. Secret. |
| Webhook signature key | Confirms a webhook truly came from Square. Secret. |
| Location ID | The Square location that receives the payment. Sets the currency. |
| Success URL / Cancel URL | Where the buyer lands after paying or backing out. |
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
- Open the Square Developer dashboard
Sign in at developer.squareup.com. Each application has its own credentials, and a free Sandbox is created alongside it for testing. This guide walks the Sandbox; the Live flow is identical, just flip the Sandbox / Production toggle and use your production credentials. To make a new app, click the + tile on the Applications screen.
Square Developer → Applications - Name your application
Give the application a name you will recognize (for example "Coin Moebius"), then click Next.
Square → Name your application - Copy your access token
Open the app and go to Credentials. Confirm the Sandbox / Production toggle at the top matches the environment you are setting up. Click the copy icon next to the Access token and set it aside.
Square → Credentials The access token is secret, treat it like a password. Sandbox and Production have separate tokens, so do not mix them.
- Copy your Location ID
In the left menu, open Locations. Copy the Location ID of the location that should receive payments. It sets the checkout currency, so pick the one whose currency you want to charge in.
Square → Locations - Open Webhooks → Subscriptions
Square calls a webhook endpoint a "subscription." In the left menu, expand Webhooks, open Subscriptions, and click Add subscription.
Square → Webhooks → Subscriptions → Add subscription - Add the subscription and select events
Give it a name (like "coin-moebius"). In Notification URL, paste your store’s Square webhook address (below). Then, under Events, search and check the events Coin Moebius listens for, and click Save.
- One-time payments: payment.created, payment.updated, refund.created, refund.updated, dispute.created, dispute.state.updated.
- Subscriptions (only if you sell them): subscription.created, subscription.updated, subscription.canceled, subscription.deactivated, invoice.payment_made, invoice.scheduled_charge_failed. If you are not billing on a recurring basis, skip these.
https://api.coinmoebius.com/webhook/square/<your store id>Square → Add a webhook subscription Your Store id is on the Store settings page in the Coin Moebius dashboard; drop it into the address above. Extra events are harmless, we ignore anything we do not use. Once Square is connected, its card’s ⋯ menu has Copy webhook URL for the same address.
- Open the subscription you just created
Square saves the subscription and lists it under Webhooks with status Enabled. Click its name to open the details panel where the signing key lives.
Square → Webhooks → your subscription (Enabled) - Copy the Signature key
In the subscription’s Properties panel, click the copy icon next to Signature key. This is the value Coin Moebius uses to confirm each webhook truly came from Square. It only exists once the subscription is created, which is why the webhook came before the connect step.
Square → your subscription → Signature key - Back in Coin Moebius: Connect a provider → Square
Open Providers in the left menu and click Connect a provider. Type Square in the search box, or scroll down to it, and click it. The form opens on Connect with Square, which signs you in to Square and sets up payment notifications for you. To paste the values from this guide instead, switch to the Enter keys manually tab and set your Success URL and Cancel URL. On the Live tab, paste your Access token, Webhook signature key, and Location ID, then click Save. Setting up with sandbox credentials first? Paste them on the Test tab instead, then add live credentials later from Edit connection.
Coin Moebius → Connect a provider → Square - You are connected
Square now appears on your Providers page. Its ⋯ menu has Edit connection, Copy webhook URL and Disconnect. To run a sandbox order through end to end before going live, set a product’s Environment to Test.
Coin Moebius → Providers → Square (connected) Sandbox cards never charge a real card. Use card 4111 1111 1111 1111, CVV 111, any future expiration, any valid postal code (for example 94103).
After you connect
Run one test payment before going live:
- Create a product and set its Environment to Test. That runs the product on your sandbox credentials, so you can place a full order without moving money. (A Test product only runs on sandbox credentials, so add them first.)
- Place the buy button on a page (a local HTML file works) pointed at your store.
- Complete checkout with the sandbox test card from above.
- Open Transactions in your store and turn on Show test payments. A new row appears, marked Test. When its status reads Paid, 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. Saved secrets stay hidden. To change one, choose Replace and enter the new value.
Questions? Join our Discord