Payments

Tablescale POSTs JSON to your webhook URL. All requests include signed headers (see Signature verification).

Example payload

{
  "event": "payment.requested",
  "id": "evt_abc123",
  "created_at": "2026-06-13T12:00:00Z",
  "data": {
    "payment_session_id": "clx...",
    "order_id": "clx...",
    "order_display_id": "42",
    "amount_cents": 2450,
    "price": "24.50",
    "currency": "EUR",
    "line_items": [
      {
        "name": "Margherita Pizza",
        "quantity": 2,
        "unit_price_cents": 850,
        "options": [{ "name": "Extra cheese", "price_cents": 150 }]
      }
    ],
    "table": "Table 5",
    "expires_at": "2026-06-13T12:02:00Z"
  }
}

Verify that webhooks came from Tablescale using the webhook secret from Settings → Payments.

The snippet below is exemplary JavaScript for decoding and verifying the X-Tablescale-Signature header. Adapt it to your stack — Node.js crypto, Deno, browser Web Crypto, or your language's HMAC utilities.

const crypto = require("crypto");

function verifyTablescaleSignature(payload, signatureHeader, secret) {
  const parts = signatureHeader.split(",");
  const timestamp = parts.find((p) => p.startsWith("t="))?.slice(2);
  const signature = parts.find((p) => p.startsWith("v1="))?.slice(3);
  if (!timestamp || !signature) return false;

  const signed = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signed)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signature, "hex")
  );
}

Headers: X-Tablescale-Signature, X-Tablescale-Event-Id, X-Tablescale-Timestamp, X-Tablescale-Test-Mode

POST to /api/integrations/payments/callback when your POS finishes processing. Authenticate with your API key in the Authorization header.

Example request

POST /api/integrations/payments/callback
Authorization: Bearer ts_live_...
Content-Type: application/json

{
  "payment_session_id": "clx...",
  "status": "success",
  "payment_method": "CARD",
  "external_ref": "pos-txn-12345"
}

Request body fields

Duplicate callbacks with the same session and status are idempotent and return the existing result. All payment activity appears in Settings → Payments → Payment logs, including outbound webhooks, inbound callbacks (callback.success / callback.fail), and internal state changes (payment.success / payment.fail). The Mode column in Payment logs shows Live or Test. Error codes: 400, 401, 404, 409.

If your POS receives the payment.requested webhook but prefers not to call the callback endpoint — or wants to confirm the final status after reporting — poll the session using the payment_session_id from the webhook payload:

GET /api/integrations/payments/sessions/{payment_session_id}
Authorization: Bearer ts_live_...

Polling does not replace webhooks: Tablescale has no list-or-discover endpoint, so your system must receive the initial webhook (or use a relay that forwards the session ID) to learn which session to poll.

POST /api/integrations/payments/sessions/{payment_session_id}/cancel
Authorization: Bearer ts_live_...

# After sending a test webhook, report success:
curl -X POST https://your-tablescale-domain.com/api/integrations/payments/callback \
  -H "Authorization: Bearer ts_test_..." \
  -H "Content-Type: application/json" \
  -d '{"payment_session_id":"SESSION_ID","status":"success"}'

Test tools in Settings → Payments are rate limited per organization (10 sends per minute). Live production endpoints (/callback, /sessions/*) are not rate limited. When exceeded, you receive 429 Too Many Requests with a Retry-After header.

{ "error": "Rate limit exceeded" }

Tip: reuse the test session ID from a single webhook instead of sending repeated test webhooks in a loop.

• Respond to webhooks within 10 seconds (return 2xx quickly, process async if needed).
• Verify webhook signatures before processing.
• Use the payment_session_id to correlate requests — Tablescale may retry failed deliveries.
• Handle idempotent callbacks — your endpoint may receive the same result more than once.