newebpay-query

The newebpay-query skill provides a standardized workflow for AI coding agents to integrate NewebPay's transaction query functionality into existing payment modules. It is designed for developers building e-commerce platforms, payment gateways, or merchant backends that utilize NewebPay (藍新金流) as their primary payment service provider. By automating the implementation of the QueryTradeInfo API, this skill helps developers ensure accurate order status synchronization, mitigate payment verification issues, and build automated reconciliation systems.

• Provides clear structural guidance for implementing SHA256-based CheckValue generation using HashKey and HashIV.

• Includes standardized logic for constructing API requests, handling timestamp synchronization, and processing JSON responses.

• Supports various integration scenarios, including real-time order status checks via API endpoints, customer-facing order history dashboards, and background cron jobs for daily batch reconciliation.

• Simplifies error handling for common API issues such as transaction not found (TRA10001), checksum validation failures (TRA10002), and timestamp mismatches.

• Users should ensure their environment has the necessary NEWEBPAY_MERCHANT_ID, NEWEBPAY_HASH_KEY, and NEWEBPAY_HASH_IV configured in their environment variables.

• The tool is intended for both test and production environments, with automated logic to switch between the test URL (https://ccore.newebpay.com/API/QueryTradeInfo) and production URL (https://core.newebpay.com/API/QueryTradeInfo).

• Typical inputs include the MerchantOrderNo and the transaction amount, which are required to compute the mandatory CheckValue parameter.

• The resulting data includes the TradeStatus (0 for pending, 1 for paid, 2 for failed, 3 for cancelled, 6 for refunded), allowing for seamless programmatic updates to internal order databases.