> ## Documentation Index
> Fetch the complete documentation index at: https://docs.commercepay.asia/llms.txt
> Use this file to discover all available pages before exploring further.
# Generate Signature
> How to generate the cap-signature header for POST and GET requests.
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
Follow these 6 steps to generate the cap-signature for your request.
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.)
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.
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]`
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.
Sign the lowercased string using the HMAC-SHA256 algorithm. Use your Secret Key as the cryptographic key.
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/RequestPayment](https://staging-payments.commerce.asia/api/services/app/PaymentGateway/RequestPayment)
**Secret Key:** bd90787d8e2340b49757438d66eed86d209e6a36a32d865a8287f90b033b815d
**Raw Request Payload**
```json theme={null}
{
"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**
```json theme={null}
{
"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](https://staging-backoffice-payments.commerce.asia/app/paymentgateway/signaturevalidator).
## 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.
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=100
**Result:** `{"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.)
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.
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]`
Convert the entire combined string from Step 3 to lowercase.
Sign the lowercased string using the HMAC-SHA256 algorithm with your Secret Key.
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/Query`
**Secret Key:** `bd90787d8e2340b49757438d66eed86d209e6a36a32d865a8287f90b033b815d`
**Query 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](https://staging-backoffice-payments.commerce.asia/app/paymentgateway/signaturevalidator).