A UTR or provider reference is useful settlement evidence, but it should not be the only key in your application model. Your client_txn_id connects the checkout to your local order, while gateway order_id and verified amount confirm the payment session. UTR can then support investigation and settlement tracing when it is available from the provider record.
Support agents should never approve a screenshot alone. Start from authenticated server records, normalize the reference, constrain the search to the correct merchant tenant and time range, and compare amount and status. Mask references in customer-facing views and keep full values available only to authorized operators.
Design principles
The boundaries that keep this flow reliable
Server records beat screenshots
A screenshot can be edited or belong to another transaction. Use verified payment and provider records as the source of truth.
Layer the evidence
Require merchant tenant, client transaction ID or gateway order, exact amount, reasonable time window, and UTR/provider reference agreement.
Protect reference data
Mask full UTR and customer identifiers in normal UI, logs, analytics, and support messages unless the role requires them.
Implementation workflow
From request to a durable result
- 1
Locate the local order
Start with the customer's authenticated order or support reference, not a global search over all merchants.
- 2
Load verified payment evidence
Compare client_txn_id, gateway order_id, expected and paid amount, payment status, and event timestamps.
- 3
Compare the provider reference
Normalize whitespace/case if appropriate, then compare the stored UTR or provider reference exactly within the tenant.
- 4
Record the conclusion
Mark matched, not found, conflicting, duplicate, or escalated and preserve the evidence IDs and operator reason.
Tenant-scoped reference lookup
sqlSELECT
o.id AS order_id,
o.client_txn_id,
o.expected_amount_paise,
p.amount_paise,
p.status,
p.provider_reference
FROM orders o
JOIN verified_payments p
ON p.tenant_id = o.tenant_id
AND p.client_txn_id = o.client_txn_id
WHERE o.tenant_id = :authorized_tenant
AND p.provider_reference = :normalized_reference
LIMIT 2;Production checklist
Verify before going live
- Lookup is tenant-scoped and role-authorized
- Reference is compared with local and gateway order identifiers
- Exact amount and verified status are checked
- Ambiguous multiple results are never auto-approved
- Search and manual decisions are audit logged
Failure recovery
Unsafe matching methods
Screenshot-only approval
Request a support reference, then verify the transaction in authenticated merchant records. Do not fulfil from an image.
Global UTR search
A support role could leak another merchant's data. Always enforce tenant scope before query execution.
Amount and time only
Popular prices create collisions. Require stable order references and verified provider evidence.
FAQ
Questions developers ask
Is UTR the same as client_txn_id?
No. client_txn_id is your merchant order reference. UTR or provider reference is payment-system evidence associated with the verified transaction.
Can a screenshot prove a UPI payment?
No. Use authenticated payment status and provider evidence; screenshots are customer-provided context only.
What if one UTR appears against multiple records?
Treat it as a data-integrity exception, stop automatic fulfilment, and escalate with tenant-scoped audit evidence.