Added section for common pitfalls

MLE.md

@@ -266,7 +266,7 @@ var merchantConfig = {
   // If both are set with same value, it works fine
   enableRequestMLEForOptionalApisGlobally: true,
   useMLEGlobally: true,  // Deprecated but same value
-  
+
   // Key alias - new parameter takes precedence if both are provided
   requestMleKeyAlias: "New_Alias",
   mleKeyAlias: "Old_Alias"  // This will be ignored
@@ -275,7 +275,214 @@ var merchantConfig = {
 
 <br/>
 
-## 5. JSON Configuration Examples
+## 5. Common Pitfalls
+
+### ⚠️ Pitfall 1: Mixing New and Deprecated Parameters with Different Values
+
+**Problem**: Using both new and deprecated parameters with conflicting values causes a `ConfigException`.
+
+```javascript
+// ❌ WRONG - This will throw ConfigException
+var merchantConfig = {
+  enableRequestMLEForOptionalApisGlobally: true,
+  useMLEGlobally: false  // CONFLICT!
+};
+```
+
+**Solution**: Use only the new parameters, or ensure both have the same value.
+
+```javascript
+// ✅ CORRECT - Use new parameters only
+var merchantConfig = {
+  enableRequestMLEForOptionalApisGlobally: true
+};
+
+// ✅ CORRECT - Or use same values if you must use both
+var merchantConfig = {
+  enableRequestMLEForOptionalApisGlobally: true,
+  useMLEGlobally: true  // Same value - works but not recommended
+};
+```
+
+---
+
+### ⚠️ Pitfall 2: Using HTTP Signature Authentication with MLE
+
+**Problem**: MLE only works with JWT authentication. Using HTTP Signature will cause MLE to be silently disabled with a warning.
+
+```javascript
+// ❌ WRONG - MLE will not work with HTTP Signature
+var merchantConfig = {
+  authenticationType: 'http_signature',
+  enableRequestMLEForOptionalApisGlobally: true  // Will be ignored!
+};
+```
+
+**Solution**: Always use JWT authentication for MLE.
+
+```javascript
+// ✅ CORRECT
+var merchantConfig = {
+  authenticationType: 'jwt',
+  enableRequestMLEForOptionalApisGlobally: true
+};
+```
+
+---
+
+### ⚠️ Pitfall 3: Missing responseMleKID When Using Non-CyberSource P12/PFX
+
+**Problem**: When using a P12/PFX file that was NOT generated by CyberSource, you must explicitly provide `responseMleKID`. If you forget to provide it, decryption will fail.
+
+```javascript
+// ❌ WRONG - Missing responseMleKID with non-CyberSource P12
+var merchantConfig = {
+  enableResponseMleGlobally: true,
+  responseMlePrivateKeyFilePath: "/path/to/custom-key.p12",  // Non-CyberSource P12
+  responseMlePrivateKeyFilePassword: "password"
+  // Missing: responseMleKID!
+};
+```
+
+**Solution**: Always provide `responseMleKID` when using non-CyberSource P12 files. If using a CyberSource-generated P12, the KID will be auto-fetched.
+
+```javascript
+// ✅ CORRECT - With non-CyberSource P12, provide KID explicitly
+var merchantConfig = {
+  enableResponseMleGlobally: true,
+  responseMlePrivateKeyFilePath: "/path/to/custom-key.p12",
+  responseMlePrivateKeyFilePassword: "password",
+  responseMleKID: "your-key-id"  // Required for non-CyberSource P12!
+};
+
+// ✅ CORRECT - With CyberSource-generated P12, KID is optional (auto-fetched)
+var merchantConfig = {
+  enableResponseMleGlobally: true,
+  responseMlePrivateKeyFilePath: "/path/to/cybersource-generated.p12",
+  responseMlePrivateKeyFilePassword: "password"
+  // responseMleKID will be auto-fetched from CyberSource P12
+};
+```
+
+---
+
+### ⚠️ Pitfall 4: Providing Both Private Key Object and File Path
+
+**Problem**: Specifying both `responseMlePrivateKey` and `responseMlePrivateKeyFilePath` causes confusion and errors.
+
+```javascript
+// ❌ WRONG - Both private key sources provided
+var merchantConfig = {
+  enableResponseMleGlobally: true,
+  responseMlePrivateKey: privateKeyObject,
+  responseMlePrivateKeyFilePath: "/path/to/key.p12",  // Conflict!
+  responseMleKID: "your-key-id"
+};
+```
+
+**Solution**: Choose only one method to provide the private key.
+
+```javascript
+// ✅ CORRECT - Option 1: Use private key object
+var merchantConfig = {
+  enableResponseMleGlobally: true,
+  responseMlePrivateKey: privateKeyObject,
+  responseMleKID: "your-key-id"
+};
+
+// ✅ CORRECT - Option 2: Use private key file path
+var merchantConfig = {
+  enableResponseMleGlobally: true,
+  responseMlePrivateKeyFilePath: "/path/to/key.p12",
+  responseMlePrivateKeyFilePassword: "password",
+  responseMleKID: "your-key-id"
+};
+```
+
+---
+
+### ⚠️ Pitfall 5: Invalid mapToControlMLEonAPI Format
+
+**Problem**: Using incorrect format in `mapToControlMLEonAPI` values.
+
+```javascript
+// ❌ WRONG - Invalid formats
+var merchantConfig = {
+  enableRequestMLEForOptionalApisGlobally: true,
+  mapToControlMLEonAPI: {
+    "createPayment": "true:false",      // Wrong separator (single colon)
+    "capturePayment": "true::false::",  // Too many separators
+    "refundPayment": ""                 // Empty value
+  }
+};
+```
+
+**Solution**: Use correct string format with double colon separator.
+
+```javascript
+// ✅ CORRECT
+var merchantConfig = {
+  enableRequestMLEForOptionalApisGlobally: true,
+  mapToControlMLEonAPI: {
+    "createPayment": "true::false",   // Correct: double colon
+    "capturePayment": "false::true",  // Correct format
+    "refundPayment": "true",          // Correct: request only
+    "createCredit": "::true"          // Correct: response only
+  }
+};
+```
+
+---
+
+### ⚠️ Pitfall 6: Wrong File Path or Missing Files
+
+**Problem**: Providing incorrect file paths or missing certificate/key files.
+
+```javascript
+// ❌ WRONG - File doesn't exist or path is incorrect
+var merchantConfig = {
+  enableRequestMLEForOptionalApisGlobally: true,
+  mleForRequestPublicCertPath: "/wrong/path/cert.pem"  // File not found!
+};
+```
+
+**Solution**: Verify file paths and ensure files exist before configuration.
+
+```javascript
+// ✅ CORRECT - Use valid, absolute paths
+var merchantConfig = {
+  enableRequestMLEForOptionalApisGlobally: true,
+  mleForRequestPublicCertPath: "/absolute/path/to/cert.pem"  // Verify this exists!
+};
+```
+
+---
+
+### ⚠️ Pitfall 7: Using Deprecated Parameters in New Code
+
+**Problem**: Using deprecated parameters in new implementations.
+
+```javascript
+// ❌ NOT RECOMMENDED - Using deprecated parameters
+var merchantConfig = {
+  useMLEGlobally: true,          // Deprecated!
+  mleKeyAlias: "Custom_Alias"    // Deprecated!
+};
+```
+
+**Solution**: Always use the new parameter names for new code.
+
+```javascript
+// ✅ CORRECT - Use new parameters
+var merchantConfig = {
+  enableRequestMLEForOptionalApisGlobally: true,
+  requestMleKeyAlias: "Custom_Alias"
+};
+```
+
+<br/>
+
+## 6. JSON Configuration Examples
 
 ### (i) Minimal Request MLE