EPay Signature Verification Failed: Causes and Fixes

A signature error is the most common EPay integration problem, and it nearly always comes down to one of four things: the wrong key, URL-encoded values, empty parameters included in the signature, or the key appended the wrong way. This page works through them from easiest to hardest.

  • Signature error
  • MD5 signing
  • EPay V1
  • Updated

Which case are you in

Your situationGo to
You use an existing system (card shop, panel, API relay) and wrote no codeIt can only be configuration. See “Existing systems”
You wrote the integration and the gateway rejects your orderSee “Your own code”
Orders work, but your system rejects the notificationSee “Notification signatures”

Existing systems: check the settings

  1. Copy key again, paste and save. Make sure there are no leading or trailing spaces or line breaks.
  2. Make sure pid and key come from the same integration app. Do not mix values from two apps.
  3. Make sure the key is in the right field. In legacy Dujiaoka, for example, the key goes into 商户密钥 while 商户 KEY holds the order URL.
  4. If the key was reset, the old one no longer works and every system using it must be updated.

For what goes into each field, see the guide for your system: Dujiaoka, ACG-Faka, New-API, One-Hub, Xboard / V2Board.

Your own code: follow the signing rules

Signing has four steps. Check them one by one:

  1. Filter: drop sign, sign_type and any parameter with an empty value.
  2. Sort: order by parameter name, ASCII ascending (a→z).
  3. Join: build k1=v1&k2=v2 without URL-encoding the values.
  4. Sign: append the merchant key directly to the end, with no &key= separator, then take the 32-character lowercase MD5.

Test your code with the data below. The key is a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6. If you do not get the same result, the bug is in your signing function:

String to sign (then append the key directly):
clientip=1.2.3.4&money=1.00&name=VIP会员&notify_url=https://shop.com/notify&out_trade_no=MCH20260728001&pid=100001&return_url=https://shop.com/return&type=alipay

MD5 result:
77c46b1a2cb7063f4d01003379863f5e
Common mistakeDetails
URL-encoding values before signingThe most common one. Non-ASCII text, :// and & are signed as-is; encoding happens only when the request is sent
Including empty parametersIf you send an empty parameter such as param=, it must not appear in the string to sign
Adding &key= before the keyEPay appends the key right after the last value with no separator
Uppercase MD5It must be 32 lowercase characters
Sending a different value than you signedA product name with surrounding spaces or angle brackets, or an amount signed as 1.00 but sent as 1, causes intermittent failures

The full step-by-step example is under Signing, and ready-made code is under Code samples.

Notification signatures

The async notification is a GET request to your notify_url with parameters in the query string. It is verified by the same rules, plus three things to watch:

  1. Verify with the URL-decoded values. Most frameworks decode them for you, so use those values rather than parsing the raw URL yourself.
  2. Use only the parameters the platform sent. Parameters added by your framework or rewrite rules, such as routing parameters, must not be included.
  3. Drop sign, sign_type and empty parameters here as well.

Still failing

Send official support the string to sign without the key together with the sign you computed. Never expose the key in a group chat or screenshot; if you already did, ask support to reset it.

For other errors see Troubleshooting; for protocol details see Signing and Async notification.

More integration docs

Get your merchant ID and key

Contact official support to open an integration app. Your gateway URL, pid and key are issued directly, with hands-on help during testing.

Contact support