POS terminal collection, callback, and reconciliation lifecycle runbook

POS terminal collection, callback, and reconciliation lifecycle runbook explains the production operating flow after Razorpay POS, Paytm POS, or Pine Labs terminal setup: how staff create a terminal handoff, how callbacks update the existing terminal payment, how duplicate/unmatched events are handled, and what finance needs before treating terminal money as collected or refunded.

What this page is for

Who should use it

Owner, finance admin, front desk lead, platform admin, support

Where to find it

Commerce invoice, POS checkout, terminal collection, terminal webhook events, POS Terminal Setting

Before you start

POS terminal collection, callback, and reconciliation lifecycle runbook must be used for every in-gym terminal collection before front desk treats a card/UPI terminal slip as a SquareOS payment.
Terminal collection starts from a finalized SquareOS invoice and records deviceId, provider RAZORPAY_POS or PAYTM_POS or PINE_LABS, linked gym/location, paymentMethodId, invoice id, amountMinor, terminal reference, staff actor, request id, and disabled reason when collection is not allowed.
SquareOS creates exactly one terminal payment in PENDING for a terminal handoff unless staff enters an already-confirmed provider reference, and the handoff evidence must include payment id, provider, device id, externalDeviceId, providerOrderRef/reference, amount, and status.
Terminal callback finalization accepts only POST /commerce/webhooks/terminals/:provider callbacks that match an existing terminal payment by provider transaction id, order/reference id, or stored terminal reference and pass HMAC, checksum, or shared-token verification before changing payment or invoice state.
Successful terminal callbacks update the existing terminal payment, gatewayPaymentIntent when linked, payment allocation, invoice balance/status, paid subscription activation when applicable, terminal payment state transition, webhookEvent processed state, and audit row without creating a second payment.
Failed, canceled, pending, unsigned, mismatched, duplicate, or unmatched terminal callbacks must remain webhook/payment evidence with provider status, signatureVerified result, error text, and support next action instead of being marked collected manually.
Terminal duplicate prevention requires unique terminal reference per linked gateway account, idempotent callback handling by providerRef/providerOrderRef/reference, and a support check that one provider transaction maps to one SquareOS payment and one invoice allocation.
Terminal refund or reversal handling starts from a settled terminal payment and must follow refund policy, original terminal provider reference, gateway/device capability, finance approval, SquareOS refund/credit note, provider reversal/refund evidence when available, and audit trail before staff promise money returned.
Terminal real-device certification requires one Razorpay POS, Paytm POS, or Pine Labs physical-device transaction with fake mode off, verified callback/token/checksum, matching invoice/payment/allocation state transition, terminal receipt/provider log, settlement or batch evidence, and owner/finance sign-off.
Terminal operation secret handling forbids exposing terminal webhook secrets, Paytm merchant keys, Pine Labs adapter tokens, checksum values, raw callback payloads, terminal receipt PAN/UPI private data, onboarding screenshots, or adapter logs with credentials in mobile, support, analytics, crash logs, or public docs.

Daily workflow

Start from a finalized invoice or POS checkout that has a payable balance. Confirm the selected payment mode is Terminal device, the terminal device is active, linked to the correct gym/location, has an externalDeviceId, has callback verification configured, and is not in fake/safe mode for live certification.
Select the physical terminal the customer will use. Record deviceId, provider, terminal label, masked externalDeviceId, linked gatewayAccountId when present, paymentMethodId, invoice id, amountMinor, currency, staff actor, request id, and disabled reason when SquareOS blocks collection.
Click terminal collection only once for the invoice amount. SquareOS should create one PENDING terminal payment and a terminal handoff reference. Front desk should send the customer to the matching physical terminal and show pending/provider-processing until provider confirmation returns.
If staff already has a confirmed provider reference from a certified Staff app reconciliation path, entering that reference marks the terminal payment succeeded immediately and allocates the invoice. This must be treated as an audited exception, not the normal front-desk path.
For normal physical-device flow, wait for POST /commerce/webhooks/terminals/RAZORPAY_POS, POST /commerce/webhooks/terminals/PAYTM_POS, or POST /commerce/webhooks/terminals/PINE_LABS from the provider or certified adapter. The callback must include provider status plus transaction/order/reference values that match the pending SquareOS payment.
Razorpay POS callbacks must verify x-razorpay-signature against the terminal/gateway webhook secret. Paytm POS callbacks must verify CHECKSUMHASH or HMAC/checksum path using merchant key/checksum setup. Pine Labs callbacks must verify x-plural-signature, x-pinelabs-signature, x-signature, or the certified adapter shared token.
When a successful callback verifies and matches, SquareOS updates the existing terminal payment to SUCCEEDED, updates gatewayPaymentIntent if linked, applies one payment allocation, reduces invoice balance, marks invoice paid or partially paid, activates paid subscriptions when applicable, records a terminal payment state transition, marks webhookEvent processed, and writes an audit row.
When a callback reports failed, canceled, or pending, SquareOS records that provider status on the terminal payment/webhook evidence. Staff should either retry through a new backend-approved handoff, choose another payment method, or ask support to inspect provider logs; they should not overwrite the existing payment to success from a slip.
When a callback is unsigned, mismatched, duplicate, or unmatched, support must inspect webhookEvent signatureVerified, normalized providerRef/providerOrderRef/reference, provider event id, raw payload storage, linked device, gateway account, pending payment id, and dead-letter/outbox state before any manual finance action.
Duplicate-prevention review must prove one provider transaction maps to one SquareOS terminal payment and one invoice allocation. If a provider retries a callback, support should see either the same existing payment updated idempotently or failed duplicate/unmatched evidence, not a new customer payment.
Terminal refund or reversal begins from the settled terminal payment. Finance must check refund policy, original terminal provider reference, device/gateway capability, amount, reason, approval, provider reversal/refund evidence when available, SquareOS refund/credit note, payment status, and audit trail before promising money returned.
Settlement review for terminal collections should compare provider batch/settlement, terminal id, gross amount, fees, refunds/reversals, net amount, bank credit, invoice/payment ids, and mismatch reason before finance closes the business day.
Real-device certification must use fake mode off and a physical Razorpay POS, Paytm POS, or Pine Labs device. Capture the terminal receipt or provider log, callback verification result, webhookEvent id, payment id, invoice id, allocation id, before/after state, settlement or batch reference when available, and owner/finance sign-off.

Watch out

Do not let staff create multiple terminal handoffs for the same invoice because the terminal looked slow. Check pending provider-processing state and webhook evidence first.
Do not treat printed terminal slip, SMS from provider, dashboard screenshot, customer UPI app success screen, or manually typed transaction id as final payment without backend confirmation or audited Staff app reconciliation.
Do not expose raw callback payloads, checksum values, Paytm merchant key, Pine Labs adapter token, Razorpay terminal webhook secret, terminal receipt PAN/UPI private data, or onboarding screenshots in mobile or general support channels.
Do not promise reversal/refund completion until provider reversal/refund evidence, SquareOS refund/credit note, payment status, and finance approval are all recorded.
Do not mark a terminal device production-certified from fake-mode handoff or simulated callback. Physical-device proof is required before front desk training.
Do not reconcile a terminal callback to a different gym/location because the provider reference looks similar. Device, provider, tenant, invoice, and amount must match the SquareOS record.

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