Generate Signature

To ensure the security and integrity of every transaction, the CommercePay API requires a digital signature in the cap-signature header for all API requests except Authentication endpoint. This signature allows our server to verify that the request body has not been tampered with and originated from an authorized source.

Field name matching is case-insensitive, so your actual HTTP request body does not strictly need to use camelCase keys. What matters is that the signature calculation below is always performed on a camelCase, recursively-sorted representation of your payload — we still recommend sending your request body in camelCase too, simply to avoid confusion between what you send and what you sign.

Encoding rules for the string you sign

Do not escape non-ASCII characters. Sign the raw characters (e.g. 陈大文, Café), not \uXXXX escape sequences. Many JSON libraries escape non-ASCII by default (for example Python’s json.dumps — set ensure_ascii=False; .NET’s System.Text.Json — use an unescaped encoder). The signature is verified against the unescaped form, so an escaped string will be rejected with “Invalid Signature”. Your actual HTTP body may contain either form; only the string you sign matters.
Do not escape anything beyond what JSON requires. Only ", \ and control characters are escaped. Characters such as +, <, >, & and ' must appear as-is (some serializers, e.g. System.Text.Json by default, turn a+b@x.com into a+b@x.com).
Encode as UTF-8. Convert both the final string and your Secret Key to UTF-8 bytes before computing HMAC-SHA256.
Lowercasing applies to every character, including non-ASCII letters (e.g. É becomes é). Use a Unicode-aware lowercase function, not an A–Z-only one.

POST Signature Generation
GET Signature Generation

POST Signature Generation

Follow these 6 steps to generate the cap-signature for your request.

Construct JSON (camelCase)

Prepare your request payload as a JSON object. Ensure all property names use camelCase (e.g., currencyCode, referenceCode).Omit any field that is null or was not provided — at every level, including inside nested objects. Do not include it as "key": null; leave it out of the JSON entirely before you move to the next step. (An empty string "" is a value, not null, and must be kept.)

Recursive Sorting (Ascending)

Sort all keys in the JSON object in ascending (A-Z) alphabetical order.Important: This must be done recursively. If your payload contains nested objects (like the customer object), their internal keys must also be sorted alphabetically.

Form the Signature String

Concatenate the Full Endpoint URL and the Sorted JSON string from Step 2 into one continuous string. Do NOT add any spaces between the URL and the JSON.Format: [FULL_URL][SORTED_JSON_STRING]

Normalize to Lowercase

Convert the entire combined string from Step 3 to lowercase. This ensures that minor casing differences in URLs or data do not cause a signature mismatch.

Generate HMAC-SHA256 Hash

Sign the lowercased string using the HMAC-SHA256 algorithm. Use your Secret Key as the cryptographic key.

Set the Header

Convert the resulting hash into a hexadecimal string. Place this value in the cap-signature header of your HTTP request.

Integration Example

Staging URL: https://staging-payments.commerce.asia/api/services/app/PaymentGateway/RequestPaymentSecret Key: bd90787d8e2340b49757438d66eed86d209e6a36a32d865a8287f90b033b815dRaw Request Payload

{
    "currencyCode": "MYR",
    "amount": 100,
    "referenceCode": "TEST-111",
    "customer": {
        "name": "Test User",
        "email": "test.user@example.com"
    }
}

Transformation Walkthrough

Step	Output / Action
1 & 2	Sorted JSON: `{"amount":100,"currencyCode":"MYR","customer":{"email":"test.user@example.com","name":"Test User"},"referenceCode":"TEST-111"}`
3	Combined: `https://staging-payments.commerce.asia/api/services/app/PaymentGateway/RequestPayment{"amount":100,"currencyCode":"MYR","customer":{"email":"test.user@example.com","name":"Test User"},"referenceCode":"TEST-111"}`
4	Lowercased: `https://staging-payments.commerce.asia/api/services/app/paymentgateway/requestpayment{"amount":100,"currencycode":"myr","customer":{"email":"test.user@example.com","name":"test user"},"referencecode":"test-111"}`
5 & 6	Final Hash: `477d7efe6d3c319a722bd202d3434dbfde3fe19877febb0e5c62ef85e7d30efd`

Example with non-ASCII characters

Same endpoint and Secret Key as above, with customer.name changed to 陈大文 Café.Raw Request Payload

{
    "currencyCode": "MYR",
    "amount": 100,
    "referenceCode": "TEST-111",
    "customer": {
        "name": "陈大文 Café",
        "email": "test.user@example.com"
    }
}

Step	Output / Action
1 & 2	Sorted JSON (raw UTF-8, not escaped): `{"amount":100,"currencyCode":"MYR","customer":{"email":"test.user@example.com","name":"陈大文 Café"},"referenceCode":"TEST-111"}`
3 & 4	Combined and lowercased: `https://staging-payments.commerce.asia/api/services/app/paymentgateway/requestpayment{"amount":100,"currencycode":"myr","customer":{"email":"test.user@example.com","name":"陈大文 café"},"referencecode":"test-111"}`
5 & 6	Final Hash: `d6bb6d6b0e502ff08161655323df67deefddddb92088d2e144194ebfd18ead28`

If you escape the non-ASCII characters ("name":"陈大文 café") you will compute 3ae10f257f2f5a85716f875132801794bf61c3c5688905fea51d9d29d7402768 instead, which the server rejects as an invalid signature.

Troubleshooting “Invalid Signature”

If you are receiving a 401 Unauthorized or Signature Mismatch error, check the following:

Minification: Ensure your JSON string is “minified” (no extra spaces, tabs, or newlines). The signature for {"a":1} is different from {"a": 1}.
Full URL: Ensure you are using the absolute URL (including https://) exactly as it is sent in the request.
Nested Keys: Double-check that nested objects like customer or billingAddress are sorted internally.
Lowercasing: Ensure the entire concatenated string (URL + JSON) is passed through a lowercase function before hashing.
Secret Key: Verify that you are using the correct Secret Key for the environment (Staging vs. Production).
Investigate payment signatures via the Signature Validator Tool.

GET Signature Generation

For GET requests, the cap-signature is generated by converting your URL query parameters into a canonical JSON format before hashing. This ensures that the parameters cannot be tampered with in the URL.Follow these steps precisely to generate the signature for any GET request.

Convert Query Parameters to JSON (camelCase)

Take all parameters from your query string and represent them as a JSON object. Ensure all keys are in camelCase.Original URL: …?merchantId=MICH-01&amount=100Result: {"merchantId":"MICH-01","amount":100}Omit any parameter that is null or was not supplied — at every level, including inside nested objects. Do not include it as "key": null; leave it out of the JSON entirely. (An empty string "" is a value, not null, and must be kept.)

Recursive Sorting (Ascending)

Sort all keys in the JSON object in ascending (A-Z) alphabetical order. If any parameters contain nested objects or arrays, these must also be sorted internally.

Form the Signature String

Concatenate the Full Endpoint URL (excluding the query string itself) and the Sorted JSON string from Step 2.Format: [FULL_URL_WITHOUT_QUERY_STRING][SORTED_JSON_STRING]

Normalize to Lowercase

Convert the entire combined string from Step 3 to lowercase.

Generate HMAC-SHA256 Hash

Sign the lowercased string using the HMAC-SHA256 algorithm with your Secret Key.

Set the Header

Convert the resulting hash into a hexadecimal string and place it in the cap-signature header.

GET Integration Example

Base URL: https://staging-payments.commerce.asia/api/services/app/PaymentGateway/QuerySecret Key: bd90787d8e2340b49757438d66eed86d209e6a36a32d865a8287f90b033b815dQuery Params: ?TransactionNumber=20003D2625A16279BAB260115&Timestamp=1621851652617

Transformation Walkthrough

Step	Output / Action
1 & 2	Convert Query Params and Sorted JSON: `{"timestamp":1621851652617,"transactionNumber":"20003D2625A16279BAB260115"}`
3	Combined: `https://staging-payments.commerce.asia/api/services/app/PaymentGateway/Query{"timestamp":1621851652617,"transactionNumber":"20003D2625A16279BAB260115"}`
4	Lowercased: `https://staging-payments.commerce.asia/api/services/app/paymentgateway/query{"timestamp":1621851652617,"transactionnumber":"20003d2625a16279bab260115"}`
5 & 6	Final `cap-signature: a4f50b21c6e29ea7d93357906637a90a5ccf01016a61c52c218686b7ab0d2798`

Troubleshooting GET Requests “Invalid Signature”

The “Base URL” Rule: When forming the string in Step 3, do NOT include the ? or the parameters in the URL portion. The parameters are only represented within the JSON string.
Minification: Ensure your JSON string contains NO extra whitespace (spaces, tabs, or newlines). {"a":1} is valid; {"a": 1} will fail.
Data Types: Numeric values (like timestamp or amount) should be represented as numbers in the JSON, not strings (no quotes), unless specified otherwise.
Case Sensitivity: Step 4 (Lowercasing) is mandatory. Even if your URL is already lowercase, the entire concatenated string must be processed through a lowercase function.
Investigate payment signatures via the Signature Validator Tool.

Get Started

Payins

Payouts

Refunds

Encoding rules for the string you sign

POST Signature Generation

Integration Example

Transformation Walkthrough

Example with non-ASCII characters

Troubleshooting “Invalid Signature”

GET Signature Generation

GET Integration Example

Transformation Walkthrough

Troubleshooting GET Requests “Invalid Signature”