From 285cc3806fcce39343eb5756e35dca043001fea3 Mon Sep 17 00:00:00 2001 From: "Kumar,Monu" Date: Wed, 3 Dec 2025 12:04:51 +0530 Subject: [PATCH 1/2] added section for common pitfalls --- MLE.md | 219 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 213 insertions(+), 6 deletions(-) diff --git a/MLE.md b/MLE.md index fcc3f6c3..94e9de56 100644 --- a/MLE.md +++ b/MLE.md @@ -261,21 +261,228 @@ var merchantConfig = { ### (viii) Mixed Configuration (New and Deprecated Parameters) ```javascript -// Example showing both new and deprecated parameters (deprecated will be used as aliases) +// ⚠️ WRONG: Conflicting values between new and deprecated parameters var merchantConfig = { - // If both are set with same value, it works fine + // This will cause a ConfigException due to conflicting values enableRequestMLEForOptionalApisGlobally: true, - useMLEGlobally: true, // Deprecated but same value + useMLEGlobally: false, // Deprecated - CONFLICT! Different value will cause error - // Key alias - new parameter takes precedence if both are provided + // This will also cause a ConfigException requestMleKeyAlias: "New_Alias", - mleKeyAlias: "Old_Alias" // This will be ignored + mleKeyAlias: "Different_Alias" // CONFLICT! Different value will cause error }; ```
-## 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" +}; +``` + +
+ +## 6. JSON Configuration Examples ### (i) Minimal Request MLE From a85f154164d719510e45fcd3c127d5234d6f8249 Mon Sep 17 00:00:00 2001 From: "Kumar,Monu" Date: Wed, 3 Dec 2025 13:06:54 +0530 Subject: [PATCH 2/2] minor fixs --- MLE.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/MLE.md b/MLE.md index 94e9de56..d75da403 100644 --- a/MLE.md +++ b/MLE.md @@ -261,15 +261,15 @@ var merchantConfig = { ### (viii) Mixed Configuration (New and Deprecated Parameters) ```javascript -// ⚠️ WRONG: Conflicting values between new and deprecated parameters +// Example showing both new and deprecated parameters (deprecated will be used as aliases) var merchantConfig = { - // This will cause a ConfigException due to conflicting values + // If both are set with same value, it works fine enableRequestMLEForOptionalApisGlobally: true, - useMLEGlobally: false, // Deprecated - CONFLICT! Different value will cause error - - // This will also cause a ConfigException + useMLEGlobally: true, // Deprecated but same value + + // Key alias - new parameter takes precedence if both are provided requestMleKeyAlias: "New_Alias", - mleKeyAlias: "Different_Alias" // CONFLICT! Different value will cause error + mleKeyAlias: "Old_Alias" // This will be ignored }; ```