For the complete documentation index, see llms.txt. This page is also available as Markdown.

Signature

KwikPaisa APIs use HMAC SHA256 based request signing to authenticate and validate every API request securely.

Each request must include a generated signature in the X-SIGNATURE header. The signature helps verify:

  • Request authenticity

  • Payload integrity

  • Timestamp validity

  • Merchant authorization

This security mechanism protects APIs against unauthorized access, payload tampering, and replay attacks.


Signature Formula

HMAC_SHA256(payload + timestamp, secret_key)

How Signature Generation Works

To generate a valid signature:

  1. Prepare the request payload

  2. Recursively sort all payload keys

  3. Convert the payload into JSON format

  4. Generate current UNIX timestamp in seconds

  5. Concatenate:

  1. Generate HMAC SHA256 hash using your secret_key

Example Payload

Important Payload Rules

Before generating the signature:

  • Payload keys must be sorted recursively

  • JSON payload must remain unchanged

  • Use unescaped slashes in JSON encoding

  • Do not modify payload after signature generation

  • Generate a fresh timestamp for every request

Any mismatch between:

  • Request payload

  • Timestamp

  • Secret key

will result in authentication failure.

Common Authentication Errors

401 Unauthorized

Possible reasons:

  • Invalid signature

  • Wrong secret key

  • Expired timestamp

  • Incorrect payload format

  • Missing headers

Invalid Signature

This usually happens when:

  • Payload is modified after signing

  • Keys are not sorted correctly

  • JSON formatting differs

  • Timestamp mismatch occurs

Security Best Practices

  • Never expose your secret_key publicly

  • Always generate signatures on the server side

  • Use HTTPS for all API requests

  • Generate unique timestamps for every request

  • Rotate credentials periodically

  • Validate webhook signatures before processing callbacks

  1. Generate timestamp

  2. Prepare payload

  3. Generate signature

  4. Attach required headers

  5. Send API request

  6. Validate API response

Last updated