Provider Callback Troubleshooting Guide

What this page is for

Provider callback troubleshooting guide explains how support and launch teams prove whether a third-party callback safely changed SquareOS records, why a staff action is disabled, and when staff must wait for verified provider evidence instead of bypassing the integration.

Who should use it

Owners, support, finance, communications admin, front desk leads, platform admin

Where to find it

Provider callback, webhook, dead-letter, and disabled-action troubleshooting across Commerce, Engagement, POS, and Biometric settings

Before you start

• Provider callback troubleshooting guide: use this guide whenever Razorpay, terminal, SMS, Email, WhatsApp, Facebook Leads, or access-device provider state does not match what staff see in SquareOS.
• Callback endpoints are POST /commerce/webhooks/razorpay, POST /commerce/webhooks/terminals/:provider, POST /engagement/sms/:provider/webhook, POST /engagement/email/:provider/webhook, GET/POST /engagement/meta-whatsapp/webhook, GET/POST /engagement/facebook-leads/webhook, and POST /commerce/devices/:deviceId/access/events.
• Before changing staff data, callback troubleshooting must verify tenant/provider account or device, provider reference, webhook event id or request id, signature/token verification result, normalized status, matched SquareOS record id, before/after status, and dead-letter/outbox state.
• Razorpay callback troubleshooting checks x-razorpay-signature, gateway account webhook secret, provider payment/payment_link id, invoice/payment allocation state, and gateway-processing dead letter state before manual finance action.
• Terminal callback troubleshooting checks provider RAZORPAY_POS/PAYTM_POS/PINE_LABS, external device id, terminal payment id, transaction/order reference, HMAC/checksum/shared-token verification, and prevents duplicate SquareOS payments for the same terminal transaction.
• Messaging callback troubleshooting checks fake mode off, provider message id, token/signature verification, delivery attempt, message, campaign log update, opt-out/quiet-hours suppression, and dead-letter rows before resuming campaigns.
• Meta callback troubleshooting checks WhatsApp x-hub-signature-256, verify-token challenge, WABA/phone id, approved template/status callback, inbound reply mapping, and Facebook Leads Page/form/app secret/Page token/leadgen Graph fetch.
• Access-event troubleshooting checks device id, Matrix COSEC/ZKTeco/Suprema provider mapping, token/HMAC signature, user identifier format, granted/denied status mapping, same-brand person resolution, and check-in bridge result CREATED/SKIPPED/FAILED.
• If verification fails, staff must keep affected action disabled, keep fake/safe mode or accepted limitation visible, create a follow-up issue, and never mark payment/message/lead/access success from an unsigned or unmatched callback.
• Real POS terminal and biometric hardware certification can be completed later with the actual device, but the configured callback endpoint, signature/token rule, idempotency rule, disabled-state copy, and evidence fields must be documented before handoff.

Daily workflow

• Start from the staff symptom: disabled Pay here, Razorpay link, POS terminal, Send SMS, Send WhatsApp, Email, Facebook lead import, Open gate, or access check-in. Record tenant, gym/location, actor role, provider, affected person/payment/message/lead/device, and request id if available.
• Open Admin integration settings for the provider. Confirm account or device status is active/connected, fake/safe mode state is intentional, callback URL/token/secret is present, and provider account/device id matches the provider dashboard or extraction checklist.
• For Razorpay, compare provider payment or payment_link id with SquareOS Payment, Invoice, PaymentAllocation, webhookEvent, audit, and gateway-processing dead-letter state. If signature failed or no local record matched, do not mark the invoice paid manually from that payload.
• For POS terminal callbacks, identify the terminal payment created by SquareOS before looking at the provider transaction. Match terminal payment id, external device id, transaction id, order/reference id, amount, method, and verification method before reconciling or escalating.
• For SMS and Email, find the provider message id on DeliveryAttempt. Confirm callback token or signature, normalized status, Message status, CampaignDeliveryLog status, opt-out/quiet-hours suppression, and any dead-letter row before resuming campaign or automation sends.
• For WhatsApp, verify the Meta challenge setup, signed status callback, phone number id, WABA id, template name/language, matching delivery attempt/message, and at least one inbound reply path when certifying two-way messaging.
• For Facebook Leads, verify the Meta app subscription, Page/form mapping, app secret signature, Page token, Graph API lead fetch, duplicate-safe person/opportunity/task creation, facebookLeadEvent row, and crm.facebook_lead.created.v1 outbox event.
• For Matrix COSEC, ZKTeco, or Suprema access events, verify device id, provider mapping, event token or signature, user identifier format, same-brand person resolution, access result mapping, Scheduling check-in creation or skip/failure reason, and command idempotency before enabling gate-driven check-ins.
• If the issue is real device dependent, mark the provider as Blocked or Accepted limitation, keep the staff action disabled or labelled, and attach the follow-up issue to the provider certification evidence row. Do not remove the integration contract from docs just because the device test is pending.

Watch out

• Do not copy raw provider payloads with secrets, tokens, signatures, full phone/email values, card details, or private identity data into support chat or launch notes.
• Do not solve callback mismatch by creating a second payment, second lead, second check-in, or manually changing delivery status unless the remediation is approved and linked to a verified provider event.
• Do not ask staff to collect online/POS payments as offline cash or UPI merely because a callback is failing. Use the configured disabled reason and finance-approved fallback path.
• Do not certify terminal or access hardware from fake-mode commands. Fake mode proves SquareOS workflow shape only; real device proof remains a later device certification gate.
• Do not retry open-gate commands without confirming the vendor adapter honors commandRequestId/idempotencyKey and the gym approved duplicate-open risk.

Related help

• Use the left menu to open related pages in Start Here.
• Use Ask Docs for questions that are already covered in this public documentation.