Interface Rules

Protocol Rules

• Transmission Method: HTTP is used for transmission (HTTPS is recommended for production environments)
• Content Type: application/json
• Character Encoding: UTF-8
• Signature Algorithm: RSA2 (2048-bit key length)
• Signature Purpose: To ensure the integrity and authenticity of request/response data
• Key Pair: Both the platform and merchants each hold a pair of keys (private key for signing, public key for signature verification)

Parameter Specifications

• Merchant Order Number: Order numbers under the same merchant number must be unique
• Application Id: Obtained by creating an app in the merchant backend after registration
• Interface Version: The current version is fixed as v1.0
• Signature Type: Only RSA2 is supported in the current v1.0 version
• Transaction Amount: Supports up to 6 decimal places
• Enumerated Types: ChainTypeEnum (chain), CurrencyTypeEnum (currency)

Signature Algorithm

1. Collect Parameters to be Signed

• Extract all non-null parameters from the request (exclude null or empty string "")

• Do not include the sign field itself (to avoid self-signing)

• Example of payment system request parameters:

  {
      "mchNo": "M1751937702",
      "appId": "688acab1e4b06988f93da059",
      "mchOrderNo": "4f-2359-4995-b5b6-e3e41ccd40d8",
      "amount": 12.11,
      "currency": "USDC",
      "network": "Tron",
      "goods": {
          "goodsName": "T-Shirt",
          "goodsDetail": "A comfortable cotton t-shirt with a modern design.",
          "goodsType": "shop"
      },
      "mchUserId": "McDonald's",
      "bizCode": 0,
      "version":"v1.0",
      "signType":"RSA2"
  }

2. Parameter Sorting

• Sort by ASCII code ascending order of parameter names (lexicographical order)
• Example after sorting: amount → appId → bizCode → currency → goods → mchNo → mchOrderNo → mchUserId → network → signType → version

3. Concatenate into Signature String

• Format: key1=value1&key2=value2&...&keyN=valueN

• Notes:

  • Key-value pairs are concatenated directly without spaces

  • Note the decimal places for amount values.

  • Must convert Goods to a standard JSON string (serialization order: goods={"goodsName":"XX","goodsDetail":"XX","goodsType":"XX"}).

  • bizCode (business type) is mandatory【Integer type】: 0-stablecoin payment, 1-fiat currency payment.

  • Example as follows:

    amount=12.11&appId=688acab1e4b06988f93da059&bizCode=0&currency=USDC&goods={"goodsName":"T-Shirt","goodsDetail":"A comfortable cotton t-shirt with a modern design.","goodsType":"shop"}&mchNo=M1751937702&mchOrderNo=4f-2359-4995-b5b6-e3e41ccd40d8&mchUserId=McDonald's&network=Tron&signType=RSA2&version=1.0

4. Generate Signature

• Use the merchant's private key to perform RSA2 signature on the above string (SHA256 hash + RSA encryption)
• The signature result needs to be Base64 encoded

5. Attach Signature to Request

• Put the generated signature into the sign field and send it together with other parameters

• The final request parameters include sign

  {
      "mchNo": "M1751937702",
      "appId": "688acab1e4b06988f93da059",
      "mchOrderNo": "4f-2359-4995-b5b6-e3e41ccd40d8",
      "amount": 12.11,
      "currency": "USDC",
      "network": "Tron",
      "goods": {
          "goodsName": "T-Shirt",
          "goodsDetail": "A comfortable cotton t-shirt with a modern design.",
          "goodsType": "shop"
      },
      "mchUserId": "McDonald's",
      "bizCode": 0,
      "version":"v1.0",
      "signType":"RSA2", 
      "sign":"SLvwl4CZ5AaG+ebwitK4PHtvMhqXKEOVJnpgENOdmvv3BGhEG/kQesTksDgG7MJd4SScMvXqAzCA5LX/FS3vLb4u35FB/08+9PPX4CSsFQNM6iRKvBQ1YAxMHO4lIlaJCAU+BpX8h0N/qqR8v23H8OEEYlk1vYerZmy3wTuPvsV4nVdhb3bGI73UIfHau+MOVPPcxRTiy4TCj7g+M19hK1JJdyAw5OMjpeljna98hayYj0aiTxHsl/bTI55Yc+QbyVXnZYMQ0xzvyOMH569JFM8RPhVmlxMq1N1y1dwtiFlK9gDmO/IB6SV9V22GOs5xbZ7CCrukQjSrRc0LXgQjqA=="
  }

Return Codes

code	Description
0	Success
9999	Abnormal, please refer to the msg field for specific errors