API Signing Explained: MD5/HMAC Signature Mechanics and Eight Common Pitfalls

What Signing Actually Protects

A signature mechanism uses a shared app secret so the receiver can confirm two things at once: the request genuinely comes from an application holding the secret, and the parameters were not tampered with in transit. It does not encrypt the payload and it does not handle authorization — that is the token's job.

The Typical Signing Flow

Details vary across platforms such as WDT and Jushuitan, but the skeleton is identical:

1. Collect all business parameters plus common ones (app_key, timestamp, etc.), excluding the sign parameter itself;
2. Sort by parameter name in ASCII lexicographic order;
3. Concatenate as key1value1key2value2… or k1=v1&k2=v2…;
4. Wrap or prepend/append the app secret;
5. Hash with MD5 or HMAC-SHA256 — MD5 results are usually expected in uppercase hex;
6. Attach the result as the sign parameter.

The Eight Most Common Pitfalls

1. Wrong sort key — sort by parameter name, ASCII order, not by value or locale collation;
2. URL-encoding timing — some platforms sign pre-encoded values, others sign raw values; mixing the two always fails;
3. Non-ASCII characters — the hash input must be UTF-8 bytes; update(str, "utf8") in Node is not optional;
4. Empty values — whether empty parameters participate in signing differs per platform; one parameter off changes everything;
5. Case — MD5 output is often expected uppercase, HMAC hex lowercase;
6. Array/nested parameters — serialization rules (comma-joined? JSON?) differ; verify with live tests;
7. Clock skew — timestamps outside the platform's tolerance window (commonly ±5–15 minutes) get rejected as replays; run NTP on production hosts;
8. Secret in logs — redact signature material when debugging.

A Debugging Method That Works

Signature failures are deterministic — there is no mystery. Reproduce the platform's official sample request locally, diff your concatenated string against the platform's character by character, and the discrepancy will be in sorting, encoding or whitespace. Qeasy connectors encapsulate the signing implementation of mainstream platforms, so integrators only configure app_key/app_secret; if you integrate directly, write the signer as a pure function and unit-test it against the platform's official examples.