newebpay-query_skill

Overview

This skill implements NewebPay transaction query functionality using the QueryTradeInfo API. It provides helpers to generate the required SHA256 CheckValue and to perform single-trade queries against NewebPay test and production endpoints. Use it to add reliable order status checks, reconciliation, or backup payment confirmation flows.

How this skill works

The skill generates the CheckValue by composing the IV, Amt, MerchantID, MerchantOrderNo, and Key into the required string, then computes an uppercase SHA256 hash. It then sends a JSON request to the QueryTradeInfo endpoint (test or production) with MerchantID, Version, RespondType, CheckValue, TimeStamp, MerchantOrderNo, and Amt. The response includes TradeStatus codes that map to payment states (0: unpaid, 1: paid, 2: failed, 3: canceled, 6: refunded).

When to use it

• Add an API endpoint to expose order status to clients or admin panels
• Implement server-side verification when receiving asynchronous notify callbacks
• Run scheduled reconciliation or batch queries for daily accounting
• Support customer service tools to look up payment results on demand
• Validate payment state before shipping or granting access

Best practices

• Keep HashKey and HashIV secure and out of source control (use env vars or secure config)
• Always verify CheckValue and compare the TradeStatus and Amt to your records
• Use server-side requests (not client-side) to prevent key exposure
• Handle and log common error codes (e.g., TRA10001, TRA10002, TRA10003) and retry transient failures
• Normalize and map TradeStatus codes into your system’s order lifecycle

Example use cases

• GET /api/orders/:orderNo/status endpoint that calls queryTrade(orderNo, amount) and returns normalized status
• Admin order detail page showing real-time payment status and raw response for troubleshooting
• Scheduled cron job to query all unsettled transactions for daily reconciliation
• Fallback verification: when NotifyURL delivery fails, use a query to confirm payment before refunding or canceling