TatShop Help

Integrations

Connect Stripe for online and in-store card payments, and Square for in-store card via Point of Sale. Start under Settings → Integration.

Your website address under Settings → System must be the live HTTPS URL customers (and payment apps) use. Callback and webhook URLs are built from that address.

Stripe

Stripe handles:

  • Online checkout (storefront cart, emailed deposit links, gift card purchases)
  • Stripe QR in store — POS, deposits, gift cards, and booking settle when enabled under Settings → Fulfillment

Connect Stripe (recommended)

  1. Open the Stripe Dashboard. Use test mode while setting up, then switch to live before taking real payments.
  2. From Developers → API keys, copy the Secret key (sk_…).
  3. In Settings → Integration, paste the secret key and choose Connect Stripe.
  4. When your website address is a reachable HTTPS URL, TatShop can create the webhook endpoint and store the signing secret for you.

If connect cannot create the webhook automatically (for example a local or unreachable URL), use Advanced to paste a webhook secret you create in Stripe, or finish setup once the live domain is set.

Manual webhook (if needed)

  1. In Stripe, go to Developers → Webhooks → Add endpoint.

  2. Endpoint URL:

    https://YOUR-SHOP-DOMAIN/api/webhooks/stripe

    Replace YOUR-SHOP-DOMAIN with your website address (same host as Settings → System), with no trailing slash on the domain.

  3. Subscribe to the event checkout.session.completed.

  4. Reveal the Signing secret (whsec_…) and save it under Integration → Advanced if it was not created automatically.

Online orders are fulfilled when Stripe sends checkout.session.completed. The order success page can also confirm payment if the customer returns to your shop before the webhook arrives.

We recommend only enabling instant payment methods in your Stripe dashboard like cards, Afterpay and similar. Deferred methods such as direct debit may cause issues with order fulfillment in TatShop.

Stripe QR in store

Once Stripe is connected, leave Stripe QR enabled under Settings → Fulfillment → Integrated payments. In Take payment / Collect flows, choose Stripe QR to show a QR code (or open the pay link) so the customer completes Stripe Checkout on their phone. You can combine it with manuals and gift cards in a split payment.

Square (in-store card payments)

Square Point of Sale takes the card at the counter. TatShop sends the amount to the Square POS app, then records the sale when Square returns (and via webhook if the return is missed).

You need:

  1. A Square Developer application
  2. The Point of Sale app on the phone (not Square for Retail)
  3. A registered POS web callback URL
  4. A payment webhook (recommended; often created during Set up Square)

Set up Square (recommended)

  1. Open the Square Developer Console (not the seller Square Dashboard).

  2. Create an application, or open the one you use for this shop. Switch to Production for live payments.

  3. From Credentials, copy the Application ID and Access token. Copy a Location ID for the shop location that will take payments.

  4. In Settings → Integration, paste those values and choose Set up Square (or Finish Square setup if a location is still needed).

  5. When possible, TatShop creates the payment webhook subscription for you. Register the POS web callback URL once in Square (shown on the Integration page after connect):

    https://YOUR-SHOP-DOMAIN/api/square/pos/callback

    This lives under Point of Sale API → Web Callback URL — not under Webhooks. It must match your live website address character for character.

Manual Square webhook (if needed)

  1. In the Square Developer Console, open your application → Webhooks.

  2. Notification URL — must match exactly:

    https://YOUR-SHOP-DOMAIN/api/webhooks/square

  3. Subscribe to payment.updated (you may also include payment.created).

  4. Copy the subscription signature key into Integration → Advanced if it was not stored automatically.

The POS callback is the normal path when Square returns to the browser. The webhook is the safety net if someone closes the Square app before it returns.

If Square shows “The web callback URL does not match the one in your application settings”, the callback registered in Point of Sale API does not match the URL TatShop sent. Fix that URL (or your website address) so they match, then try again.

Phone setup

  1. Install Square Point of Sale from the App Store or Google Play.
  2. Sign in with the same Square seller account / location as your Location ID.
  3. Enable Tap to Pay or pair your card reader in the Square app as needed.

Taking card payment in TatShop

Use the admin POS screen, booking Settle booking, deposit Collect payment, or gift card Take payment:

  1. Build the sale (or open the payment step) and choose Square or Stripe QR.
  2. For Square: confirm and continue — on the waiting page, tap Open Square, complete payment, and allow return to the browser (or wait for the webhook).
  3. For Stripe QR: show the QR to the customer (or open the pay link); wait until TatShop records completion.

Manual methods and gift card tenders can be combined via Split payment. Turn Square or Stripe QR off under Settings → Fulfillment without disconnecting credentials. See Point of sale and Bookings.

Checklist

  1. Website address is live HTTPS — Settings → System
  2. Stripe connected (secret key + webhook) — Settings → Integration
  3. Stripe webhook checkout.session.completed → /api/webhooks/stripe
  4. Square Application ID, access token, Location ID — Settings → Integration
  5. Square POS web callback → /api/square/pos/callback — Square Developer → Point of Sale API
  6. Square webhook payment.updated → /api/webhooks/square
  7. Square Point of Sale app installed and signed in — Phone
  8. Integrated payments (Square / Stripe QR) as you want them — Settings → Fulfillment

Common problems

Square: callback URL does not match — Update Point of Sale API → Web Callback URL so it matches https://YOUR-SHOP-DOMAIN/api/square/pos/callback exactly (including www vs apex).

Square: Open Square does nothing useful on Android — Use a current TatShop build that opens the Android Intent URL; install Square Point of Sale (not Retail).

Paid in Square but TatShop still waiting — Prefer finishing the return to the browser. With the payment webhook configured, the waiting page should update when Square reports the payment complete. Confirm the webhook notification URL and signature key match.

Online order paid but missing in Orders — Confirm the Stripe webhook endpoint and signing secret. Check Stripe’s webhook delivery logs for failures.

Stripe QR not offered — Confirm Stripe is connected and Settings → Fulfillment → Stripe QR is enabled.