Razorpay POS, Paytm POS, and Pine Labs terminal setup runbook

What this page is for

Razorpay POS, Paytm POS, and Pine Labs terminal setup runbook explains exactly which provider terminal values, callback verification fields, SquareOS device fields, pending-payment behavior, and go-live evidence are required before front desk can collect in-gym card/UPI payments through a physical POS terminal.

Who should use it

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

Where to find it

Razorpay POS dashboard or onboarding sheet, Paytm POS business portal/onboarding sheet, Pine Labs Plutus portal/API handoff, SquareOS Admin / POS Terminal Setting

Before you start

• Razorpay POS, Paytm POS, and Pine Labs terminal setup runbook: complete one terminal extraction row and one live/certified callback evidence row for every physical terminal before staff use terminal collection in production.
• Razorpay POS setup records Razorpay merchant/account id, POS device id, terminal serial number, linked gateway account, store or location mapping, webhook callback URL POST /commerce/webhooks/terminals/RAZORPAY_POS, and terminal webhook signature secret.
• Paytm POS setup records MID, TID or POS_ID, terminal serial number, linked merchant account, Paytm checksum or merchant key setup, callback URL POST /commerce/webhooks/terminals/PAYTM_POS, and CHECKSUMHASH callback verification evidence.
• Pine Labs setup records Plutus client id, store id, terminal id or POS id, terminal reference, base serial or asset number, callback/status-postback URL POST /commerce/webhooks/terminals/PINE_LABS, and x-plural-signature or adapter-token verification evidence.
• SquareOS POS terminal fields map provider values to Commerce Device type Payment terminal, provider RAZORPAY_POS or PAYTM_POS or PINE_LABS, name, code, externalDeviceId, serialNumber, linked gym/location, linked gatewayAccountId when required, metadata webhookSecret or paytmMerchantKey or callbackSecret, webhookToken, and active status.
• Terminal collection proof starts from a SquareOS-created pending terminal payment and must match provider, device id, payment id, transaction id, order/reference id, amount, method, status, webhookEvent.signatureVerified, and one invoice/payment state transition.
• Terminal webhook verification must reject unsigned or mismatched callbacks, must not create duplicate SquareOS payments for one provider transaction, and must leave unmatched callbacks in failed webhook/dead-letter evidence for support review.
• Real-device certification can be completed later, but the runbook must record the configured provider account, physical device/location, callback endpoint, signature or token rule, idempotency/duplicate-payment rule, disabled-state copy, and owner accepted limitation before handoff.
• POS terminal secret handling forbids exposing terminal webhook secrets, Paytm merchant keys, Pine Labs adapter tokens, checksum values, raw callback payloads, or terminal onboarding screenshots containing credentials in launch notes, mobile screens, support tickets, analytics, or crash logs.
• If Razorpay POS, Paytm POS, or Pine Labs portal values come from a partner onboarding sheet instead of a self-serve dashboard, the extraction row must record vendor ticket id, partner contact, copied value, SquareOS field, masked secret handling, and verification action.

Daily workflow

• Confirm which terminal provider is contracted for the gym and which physical device is installed at which location. Register only installed or scheduled devices; do not create a generic active terminal for a future branch.
• For Razorpay POS, open the Razorpay POS dashboard or the Razorpay onboarding sheet. Record merchant/account id, POS device id, serial number, store/location mapping, linked Razorpay gateway account, callback URL, and terminal webhook signature secret. If Razorpay supplies a terminal-specific webhook secret separate from gateway webhooks, store it separately.
• For Paytm POS, open the Paytm POS/business portal or onboarding sheet. Record MID, TID or POS_ID, terminal serial, linked merchant account, callback URL, checksum or merchant-key setup, callback status, and any environment flag. Paytm verification evidence should include the CHECKSUMHASH header or payload value being verified by the configured merchant key.
• For Pine Labs, open Pine Labs Plutus Cloud/wired integration portal or partner handoff. Record client id, store id, terminal id or POS id, terminal reference, base serial or asset number, callback/status-postback URL, x-plural-signature secret or adapter token, and settlement/reference fields returned by the adapter.
• In SquareOS Admin / POS Terminal Setting, create a Commerce Device with type Payment terminal, provider RAZORPAY_POS, PAYTM_POS, or PINE_LABS, user-facing name, stable code, externalDeviceId from the provider, serialNumber, linked gym/location, linked gatewayAccountId where the provider settles through a Razorpay/gateway account, and active status only after installation is confirmed.
• In device metadata, store only approved secret references or write-only values for webhookSecret, terminalWebhookSecret, paytmMerchantKey, merchantKey, callbackSecret, signatureSecret, webhookToken, callbackToken, or adapter token. Use the provider-specific field names so support can understand which verification path is expected.
• From Commerce or POS, create a low-value invoice and start terminal collection. The SquareOS result should create a pending terminal payment; front desk must tell the customer to complete payment on the physical terminal and wait for provider confirmation.
• Send or wait for one real provider callback or certified adapter callback to POST /commerce/webhooks/terminals/RAZORPAY_POS, POST /commerce/webhooks/terminals/PAYTM_POS, or POST /commerce/webhooks/terminals/PINE_LABS. Match provider, external device id, SquareOS terminal payment id, provider transaction id, provider order/reference id, amount, method, and status.
• Confirm SquareOS creates or updates webhookEvent with signatureVerified true for the tested device, updates exactly one pending terminal payment, changes invoice/payment state once, and leaves no terminal dead-letter or duplicate payment for the same provider transaction.
• If the real terminal is not available yet, keep the device inactive or mark provider certification as Blocked/Accepted limitation, keep terminal collection disabled or labelled, record the vendor ticket id, and do not train front desk to mark terminal slips as paid in mobile.
• Record official source references used for the extraction row: Razorpay POS/webhook/signature documentation, Paytm POS or checksum callback documentation, Pine Labs Plutus integration/status-postback documentation, and any partner onboarding sheet or support-ticket attachment.

Watch out

• Do not use gateway payment webhook secrets as terminal secrets unless the provider and platform team explicitly confirm the same signing path.
• Do not mark an invoice paid from a printed terminal slip alone. SquareOS needs either a verified terminal callback or approved Staff app reconciliation with provider transaction id and audit evidence.
• Do not create a second SquareOS payment when a terminal callback is delayed. Reconcile the existing pending terminal payment or inspect webhook/dead-letter state.
• Do not activate two live terminal integrations for the same gym counter unless finance has a documented settlement/reconciliation reason.
• Do not expose Paytm merchant keys, Pine Labs adapter tokens, Razorpay terminal secrets, checksum values, or raw callback payloads in screenshots, chat, analytics, mobile cache, or support attachments.
• Do not claim real-device certification from fake-mode handoff, simulated callback, or manually typed provider reference. Fake mode proves workflow shape only.

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.