TatShop Help

Integrations

Connect Stripe for online checkout and Square for in-store card payments. Enter credentials 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 (online checkout)

Stripe handles card payment on the storefront cart and online deposit links.

1. Get API keys

  1. Open the Stripe Dashboard.
  2. Use test mode while setting up, then switch to live before taking real payments.
  3. Go to Developers → API keys.
  4. Copy the Secret key (sk_…) and Publishable key (pk_…).

2. Add a webhook endpoint

  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. After creating the endpoint, open it and reveal the Signing secret (whsec_…).

3. Save in TatShop

In Settings → Integration, paste:

  1. Secret key
  2. Webhook secret
  3. Publishable key

Save. Leave a secret field blank when editing later to keep the stored value.

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.

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)

1. Create a Square application

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

  2. Create an application, or open the one you use for this shop.

  3. Switch the environment toggle to Production for live payments.

  4. From Credentials, copy:

    • Application ID
    • Access token

  5. Copy a Location ID for the shop location that will take payments (Locations in the Developer Console or Square Dashboard).

2. Register the POS web callback URL

This is not under Webhooks. It lives on the Point of Sale API page.

  1. In your Square application, open Point of Sale API in the left sidebar.

  2. Find the Web section / Web Callback URL.

  3. Set it exactly to:

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

  4. Save.

The URL must match your live website address character for character (https, correct host, no extra path, apex vs www as you actually use).

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

3. Add a Square payment webhook (recommended)

The POS callback is the normal path when Square returns to the browser. A webhook is the safety net if someone closes the Square app before it returns — the card may still be charged, and the webhook lets TatShop complete the order.

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

  2. Create a subscription (or edit an existing one).

  3. Notification URL — must match exactly:

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

  4. Subscribe to payment.updated. You may also include payment.created.

  5. Copy the subscription signature key.

4. Save in TatShop

In Settings → Integration, paste:

  1. Application ID
  2. Access token
  3. Location ID
  4. Webhook signature key

Save.

5. 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 an in-store Square payment

  1. Turn on in-store mode from the admin bar.
  2. Add in-store products to the cart and choose Square Payment.
  3. On the waiting page, tap Open Square.
  4. Complete the payment in Square Point of Sale and allow it to return to the browser (or wait — the waiting page updates when the webhook or callback completes).

Deposits can also be collected with Square from Deposits.

Checklist

  1. Website address is live HTTPS — Settings → System
  2. Stripe secret + publishable keys — Settings → Integration
  3. Stripe webhook checkout.session.completed → /api/webhooks/stripe — Stripe Dashboard
  4. Stripe webhook signing secret — Settings → Integration
  5. Square Application ID, access token, Location ID — Settings → Integration
  6. Square POS web callback → /api/square/pos/callback — Square Developer → Point of Sale API
  7. Square webhook payment.updated → /api/webhooks/square — Square Developer → Webhooks
  8. Square webhook signature key — Settings → Integration
  9. Square Point of Sale app installed and signed in — Phone

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.