Skip to main content

Hook Payment Channels Configuration

Hook payment channels are non-official unsigned modes. They primarily use technical solutions to monitor incoming transaction notifications on "personal收款码" (personal receipt QR codes) or "经营收款码" (business receipt QR codes), thereby simulating automated payment callbacks.

Core Limitations & Notes for Hook Mode
  1. Queued Competition for Same Amounts: Since personal receipt QR codes do not contain merchant order IDs, the backend relies completely on the "exact paid amount" to match orders. Therefore, two players cannot initiate payments for the exact same amount at the exact same time. For example, if two players both want to purchase an item costing 1.00 USD, the second player must wait for the first player's payment to complete or time out before they can place their order.
  2. Multi-server Deployment Suggestions: Due to the queuing nature, Hook modes are best suited for niche, light, or medium-load servers. In multi-server cluster setups, do not merge traffic from multiple servers into a single Hook WeChat account.
  3. Security Warning: Hook endpoints do not have additional security signature verification. Never expose the embedded backend's WebSocket port (default 62233) to the public internet.

1. Alipay Hook Configuration (No Client Listener Software Required)​

Alipay Hook runs on the Alipay Open Platform. It monitors transaction events generated by your "经营收款码" (business receipt QR code) directly on the platform, eliminating the need to keep any desktop/mobile Hook listener software running on your server or local PC.

(1) Preparing the Business Receipt QR Code​

  1. In the Alipay mobile app, tap 收付款 (Pay/Receive) -> 收钱 (Receive Money) -> 经营收钱 (Business Receipt).
  2. Save the QR code image from this page (Note: It must be a Business Receipt QR code; ordinary personal receipt QR codes cannot be monitored by the Open Platform!).
  3. Use an online QR code decoding tool (such as Cli QR Code Decoder) to scan the image and extract the text URL, which should look like https://qr.alipay.com/2m611859....
  4. Copy this text and fill it in as your base QR code under payment_url.
  5. (Optional) On the Alipay Receive page, set specific pre-defined amounts (e.g., 1.00, 6.00, 32.00) and decode them in the same manner, then populate them inside the payment_urls map. Note that amounts must preserve two decimal places.

(2) Backend config.json Alipay Hook Settings​

Copy the Web Application credentials you created in the Official Alipay Channel under hook.alipay, and fill in the seller_id:

"hook": {
  "enable": true,
  "end_point": "/api/hook/receive",
  "alipay": {
    "enable": true,
    "app_id": "2021000000000000",
    "seller_id": "2088000000000000",
    "private_key": "file:secrets/alipay/private.txt",
    "alipay_public_key": "file:secrets/alipay/public.txt",
    "payment_url": "https://qr.alipay.com/2m611859woopehfqucwqwb2",
    "payment_urls": {
      "1.00": "https://qr.alipay.com/example_1_usd_business_qr_code_url",
      "6.00": "https://qr.alipay.com/example_6_usd_business_qr_code_url"
    }
  }
}

Tip: You can get your seller_id by logging into the Alipay Open Platform console and copying the "合作伙伴身份 (PID)" (Partner ID, a 16-digit number starting with 2088).

2. WeChat Hook v3 Configuration (WeChatFerry Solution)​

WeChat Hook v3 is built upon the WeChatFerry open-source module. It monitors payment receipt notifications by injecting a DLL into the PC WeChat process.

Environment Requirements
  • Fixed WeChat PC Version: Only compatible with WeChat PC Standalone Installer Version 3.9.12.51.

(1) Compiling the Binaries​

  1. In the project source code directory wechat-hook/v3/, open the solution Hook.sln using Visual Studio 2022.
  2. Switch the build configuration to Release mode.
  3. Click Build -> Build Solution.
  4. Once completed, locate the compiled WSXPay.Hook.WeChat.exe in the Out/ directory.

(2) Configuration & Execution​

  1. Create a new text file named config.properties in the Out/ directory, and enter the following: 
    # Hook endpoint URL (pointing to the embedded backend's receiver path)
    api_url=http://127.0.0.1:62233/api/hook/receive
  2. Start WeChat PC 3.9.12.51 and log into the WeChat account designated to receive payments (or a clerk account).
  3. Run WSXPay.Hook.WeChat.exe with Administrator privileges, and keep this console window open.

3. WeChat Hook v4 Configuration (wx_key Database Decryption Solution)​

WeChat Hook v4 is developed based on the principles of the echotrace project. It decodes and monitors the local Windows WeChat chat database in real-time. It does not inject any DLL patches into the WeChat process, providing high security and minimal intrusion.

Environment & WeChat Account Requirements
  • Supported WeChat PC Versions: Only compatible with WeChat Windows versions between 4.1.0.34 and 4.1.2.17.
  • WeChat Account Setup: The logged-in account can be either the primary payment receiving account or an added cashier clerk account.
  • High-Risk Path Restriction: The Win32 API is extremely sensitive to spaces and Chinese characters! Ensure the Hook executable directory does not contain any spaces or Chinese characters.
  • Following Receipt Helper: The logged-in WeChat account must follow and pin the official service account 微信收款助手 (WeChat Receipt Helper). If this service account is disabled or messages are only routed to "微信支付" (WeChat Pay), the Hook will fail to capture notifications.

(1) Extracting Decryption Keys & Database Settings​

  1. Download and extract the wx_key extraction tool.
  2. Ensure that WeChat is completely closed.
  3. Run wx_key.exe with Administrator privileges, and click 开始提取密钥 (Start Extracting Key).
  4. Follow the prompts, wait for WeChat to start automatically, and log in.
  5. A 64-character hex string "微信密钥 (Hex String)" will display in the tool window. Copy and save it securely, then close the tool and WeChat immediately.

(2) Compiling and Running the Hook​

  1. Under the project source code directory wechat-hook/v4/, run the build.cmd build script.
  2. All compiled output files will be copied into the Out/ directory.
  3. Create a config.properties configuration file in the Out/ directory: 
    api_url=http://127.0.0.1:62233/api/hook/receive
    wechat_key=Your_64_Character_WeChat_Key
    database_folder=auto

    About the Database Path: Setting database_folder to auto will automatically locate the path. If the log displays path warnings, explicitly specify your WeChat chat database path: C:/Users/Username/Documents/WeChat Files/wxid_xxxx/db_storage/message.

  4. Log into WeChat.
  5. Start WSXPay.Hook.WeChat.exe. The program will read and decrypt biz_message_*.db chat databases in real-time, automatically extracting notifications from the Receipt Helper.

(3) Adjusting Timeout for Database Latency​

Critical Configuration Tweak

Due to the persistence mechanism of the local WeChat database, it takes about 10 seconds or longer for the PC client to write messages into local database files after the mobile app receives a payment notification. Therefore, when using the Hook v4 channel, you must increase the timeout in config.yml on the plugin side (we recommend 200 seconds or more); otherwise, players will easily trigger timeouts while waiting for decryption:

# config.yml
payment:
  timeout: 200

(4) Backend config.json WeChat Hook Settings​

"hook": {
  "enable": true,
  "end_point": "/api/hook/receive",
  "wechat": {
    "require_process": "WSXPay.Hook.WeChat.exe",
    "enable": true,
    "payment_url": "wxp://f2f03hYFhDSFVo-F4nu5FDF0q6Q52eYHL2ydi5Iqwpt5ruk",
    "payment_urls": {
      "1.00": "wxp://f2f1pUjNG21clhI_6IugMMPNf9uCvH-_VxwoVjbz4Xik9RBQo1h7lt0t5eO4OL7X4DpN",
      "6.00": "wxp://f2f1noHjiC53rfbMJySvXSE8qm_GFPwSbSmEi8y8fNM_LyuIYaF3L6dfFQjm7PVVVnwj"
    }
  }
}
  • require_process: Defaults to "WSXPay.Hook.WeChat.exe". The embedded backend verifies whether this process exists in the server's system process list when creating WeChat Hook payments. If your Hook helper and your Minecraft server are not running on the same machine, make sure to set this to an empty string "" to bypass the process validation.
  • payment_url: The decrypted wxp://... URL of your personal WeChat收款码 (personal receipt QR code, scan your receipt QR code image using a decoding tool to obtain it).
  • payment_urls: Decoded URLs of WeChat receipt QR codes with pre-set fixed amounts (amounts must be set before saving, preserving two decimal places).
WeChat Appreciation Code (赞赏码) Support

WeChat Appreciation Codes are often much more lenient than personal receipt QR codes. If you want to display an Appreciation Code in payment_url:

  1. Save your Appreciation Code image on your mobile device, crop out the white spaces (we recommend cropping to 280x280 pixels).
  2. Upload the image to the server, e.g., under D:/resources/reward-code.png.
  3. Reference the image file using file:File_Path in payment_url: 
    "payment_url": "file:D:/resources/reward-code.png"