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. 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.

   ⤢
2. Name your application

   Give the application a name you will recognize (for example "Coin Moebius"), then click Next.

   ⤢
3. 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.

   ⤢

   The access token is secret, treat it like a password. Sandbox and Production have separate tokens, so do not mix them.

4. 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.

   ⤢
5. Open Webhooks → Subscriptions

   Square calls a webhook endpoint a "subscription." In the left menu, expand Webhooks, open Subscriptions, and click Add subscription.

   ⤢
6. Add the subscription and select events

   Give it a name (like "coin-moebius"). In Notification URL, paste your project’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 project id>

   ⤢

   Your project ID sits under the project name in the Coin Moebius dashboard; drop it into the address above. Extra events are harmless, we ignore anything we do not use. The connected provider card (last step) shows the same URL for reference.

7. 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.

   ⤢
8. 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.

   ⤢
9. Back in Coin Moebius: Add provider → Square

   In your project, open the Providers tab, click Add provider, choose Connect a service, and pick Square. 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.

   ⤢
10. You are connected

    Square now appears on your Providers tab with the date it connected. The card shows the same webhook URL you pasted into Square, plus Edit and Disconnect. Use the Test mode toggle to run a sandbox order through end to end before going live.

    ⤢

    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:

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? Join our Discord