mangopay4-nodejs-sdk 1.66.1 → 1.67.0

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## [1.67.0] - 2026-03-19
+### Added - mTLS certificates support
+- mTLS certificates are now configurable in the SDK via file paths or encoded strings
+
 ## [1.66.1] - 2026-02-23
 ### Added - ChargeBearer body parameter on payouts
 

package/README.md

@@ -34,7 +34,84 @@ Supported options
 |connectionTimeout|30000|Set the connection timeout limit (in milliseconds)|
 |responseTimeout|80000|Set the response timeout limit (in milliseconds)|
 |apiVersion|'v2.01'|API Version|
-|errorHandler|```function(options, err) {console.error(options, err)}```|Set a custom error handler
+|errorHandler|```function(options, err) {console.error(options, err)}```|Set a custom error handler|
+|cert|null|Base64-encoded string of the mTLS certificate `.pem` file content|
+|key|null|Base64-encoded string of the mTLS private `.key` file content|
+|ca|null|Base64-encoded string of the private or custom certificate authority (optional)|
+|passphrase|null|Passphrase for an encrypted mTLS private key (optional)|
+|certFilePath|null|Path to the mTLS certificate `.pem` file (takes precedence over `cert` if set)|
+|keyFilePath|null|Path to the mTLS private `.key` file (takes precedence over `key` if set)|
+|caFilePath|null|Path to the private or custom certificate authority file (takes precedence over `ca` if set)|
+
+
+mTLS
+-------------------------------------------------
+### Set the base URL for mTLS
+
+Using mTLS authentication requires your integration to call a base URL with a different hostname from the standard API:
+
+* Sandbox: `https://api-mtls.sandbox.mangopay.com`
+* Production: `https://api-mtls.mangopay.com`
+
+If using mTLS, your integration should use the `api-mtls` URLs for all API calls, including OAuth token generation.
+
+**Caution:** Ensure you set the mTLS base URL, as shown in the configuration examples below. If you don’t, the mTLS certificate will not be transferred to Mangopay. When mTLS is enforced, your integration will result in an error.
+
+### Configure the SDK’s mTLS properties
+
+The Node.js SDK allows you to load Base64-encoded strings from your environment variables. You can also load locally stored file paths, which may be useful during testing.
+
+**Caution:** The file path properties take precedence if both are set.
+
+#### Base64-encoded strings
+
+When your `.pem` certificate and private `.key` are stored as encoded strings in a secrets manager, you can load them using the following configuration properties.
+
+**Best practice:** Use this option in Production.
+
+  | Property     | Type              | Description                                                                   |
+  | ------------ | ----------------- |-------------------------------------------------------------------------------|
+  | `cert`       | string            | Base64-encoded string of the certificate `.pem` file content.                 |
+  | `key`        | string            | Base64-encoded string of the private `.key` file content.                     |
+  | `ca`         | string (optional) | Base64-encoded string of the private or custom certificate authority, if used. |
+  | `passphrase` | string (optional) | String of the passphrase for an encrypted private key.                        |
+
+  ```jsx  theme={null}
+  const mangopay = new Mangopay({
+    clientId: 'your-mangopay-client-id',
+    clientApiKey: 'your-api-key',
+    baseUrl: 'https://api-mtls.sandbox.mangopay.com', // mTLS base URL
+    cert: process.env.CERTIFICATE_PEM_B64,      // Base64-encoded
+    key: process.env.PRIVATE_KEY_B64,        // Base64-encoded 
+    ca: process.env.YOUR_CUSTOM_CA,          // Base64-encoded (optional)
+    passphrase: process.env.YOUR_CERT_PASSPHRASE, // (optional)
+  });
+  ```
+
+#### File paths
+
+If your `.pem` certificate and private `.key` are stored locally, for example during testing, you can load them using the following properties.
+
+**Caution:** If the file path properties are set, they take precedence and the Base64-encoded equivalents are ignored.
+
+  | Property       | Type              | Description                                                   |
+  | -------------- | ----------------- | ------------------------------------------------------------- |
+  | `certFilePath` | string            | Path to the certificate `.pem` file.                          |
+  | `keyFilePath`  | string            | Path to the private `.key` file.                              |
+  | `caFilePath`   | string (optional) | Path to the private or custom certificate authority, if used. |
+  | `passphrase`   | string (optional) | String of the passphrase for an encrypted private key.         |
+
+  ```jsx  theme={null}
+  const mangopay = new Mangopay({
+    clientId: 'your-mangopay-client-id',
+    clientApiKey: 'your-api-key',
+    baseUrl: 'https://api-mtls.sandbox.mangopay.com', // mTLS base URL
+    certFilePath: '/path/to/certificate.pem',
+    keyFilePath: '/path/to/private.key',
+    caFilePath: '/path/to/custom-ca.crt',          // optional
+    passphrase: 'your-cert-passphrase',   // optional
+  });
+  ```
 
 Documentation
 -------------------------------------------------

package/lib/api.js

@@ -1,6 +1,8 @@
 var _ = require('underscore');
 var Promise = require('promise');
 var querystring = require('querystring');
+var https = require('https');
+var fs = require('fs');
 
 var apiMethods = require('./apiMethods');
 var apiModels = require('./models');
@@ -20,6 +22,29 @@ function _getBasicAuthHash(username, apiKey) {
     return 'Basic ' + Buffer.from(username + ':' + apiKey).toString('base64');
 }
 
+function _buildHttpsAgent(config) {
+    var agentOptions = {
+        minVersion: 'TLSv1.2'
+    };
+
+    var cert = (config.cert && Buffer.from(config.cert, 'base64').toString('utf8')) || (config.certFilePath && fs.readFileSync(config.certFilePath));
+    var key = (config.key && Buffer.from(config.key, 'base64').toString('utf8')) || (config.keyFilePath && fs.readFileSync(config.keyFilePath));
+    var ca = (config.ca && Buffer.from(config.ca, 'base64').toString('utf8')) || (config.caFilePath && fs.readFileSync(config.caFilePath));
+
+    if (cert && key) {
+        agentOptions.cert = cert;
+        agentOptions.key = key;
+        if (ca) {
+            agentOptions.ca = ca;
+        }
+        if (config.passphrase) {
+            agentOptions.passphrase = config.passphrase;
+        }
+    }
+
+    return new https.Agent(agentOptions);
+}
+
 var Api = function (config) {
     var defaultConfig = require('./config');
     config = this.config = _.extend({}, defaultConfig, config);
@@ -30,6 +55,8 @@ var Api = function (config) {
 
     this.errorHandler = config.errorHandler;
 
+    this.httpsAgent = _buildHttpsAgent(config);
+
     this.rateLimits = [];
 
     // Add default request configuration options
@@ -244,7 +271,8 @@ Api.prototype = {
                 data: requestOptions.data,
                 headers: requestOptions.headers,
                 params: requestOptions.parameters,
-                signal: abortSignal
+                signal: abortSignal,
+                httpsAgent: self.httpsAgent
             })
                 .then(function (response) {
                     var resolveArgument = (resolveWithFullResponse) ?
@@ -357,7 +385,8 @@ Api.prototype = {
                 headers: _.extend({}, self.requestOptions.headers, {
                     'Authorization': _getBasicAuthHash(self.config.clientId, self.config.clientApiKey),
                     'Content-Type': 'application/x-www-form-urlencoded',
-                })
+                }),
+                httpsAgent: self.httpsAgent
             })
                 .then(function (response) {
                     // Authorization succeeded

package/lib/config.js

@@ -53,5 +53,18 @@ module.exports = {
      */
     errorHandler: function(options, err) {
         console.error(options, err);
-    }
+    },
+
+    // mTLS – base64-encoded PEM content
+    cert: null,
+    key: null,
+    ca: null,
+
+    // mTLS – file paths (SDK reads them at init)
+    certFilePath: null,
+    keyFilePath: null,
+    caFilePath: null,
+
+    // optional passphrase for encrypted private key
+    passphrase: null
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mangopay4-nodejs-sdk",
-  "version": "1.66.1",
+  "version": "1.67.0",
   "types": "./typings/index.d.ts",
   "description": "Mangopay Node.js SDK",
   "repository": "https://github.com/Mangopay/mangopay2-nodejs-sdk.git",

package/test/services/Idempotency.js

@@ -2,12 +2,7 @@ var expect = require('chai').expect;
 var api = require('../main');
 
 var helpers = require('../helpers');
-var mangopay = require('../../index');
-
-var api = global.api = new mangopay({
-    clientId: 'sdk-unit-tests',
-    clientApiKey: 'cqFfFrWfCcb7UadHNxx2C9Lo6Djw8ZduLi7J9USTmu8bhxxpju'
-});
+var api = require('../main');
 
 describe('Idempotency', function () {
     var idempotencyKey = helpers.generateRandomString();

package/test/services/PayIns.js

@@ -1,12 +1,7 @@
 var expect = require('chai').expect;
 
 var helpers = require('../helpers');
-var mangopay = require('../../index');
-
-var api = global.api = new mangopay({
-    clientId: 'sdk-unit-tests',
-    clientApiKey: 'cqFfFrWfCcb7UadHNxx2C9Lo6Djw8ZduLi7J9USTmu8bhxxpju'
-});
+var api = require('../main');
 
 describe('PayIns', function () {
     var payIn;

package/test/services/RateLimit.js

@@ -1,11 +1,6 @@
 var expect = require('chai').expect;
 var helpers = require('../helpers');
-const mangopay = require("../../index");
-
-var api = global.api = new mangopay({
-    clientId: 'sdk-unit-tests',
-    clientApiKey: 'cqFfFrWfCcb7UadHNxx2C9Lo6Djw8ZduLi7J9USTmu8bhxxpju'
-});
+var api = require('../main');
 
 describe('Rate Limits', function () {
     expect(api.rateLimits).to.be.empty;

package/test/services/UboDeclarations.js

@@ -6,12 +6,7 @@ var Ubo = require('../../lib/models/Ubo');
 var UboDeclarationStatus = require('../../lib/models/UboDeclarationStatus');
 var UserNatural = require('../../lib/models/UserNatural');
 var UserLegal = require('../../lib/models/UserLegal');
-var mangopay = require('../../lib/mangopay');
-
-var api = global.api = new mangopay({
-    clientId: 'sdk-unit-tests',
-    clientApiKey: 'cqFfFrWfCcb7UadHNxx2C9Lo6Djw8ZduLi7J9USTmu8bhxxpju'
-});
+var api = require('../main');
 
 describe('UBO Declarations', function () {
     var user = new UserLegal(helpers.data.getUserLegal());

package/typings/base.d.ts

@@ -64,6 +64,47 @@ export namespace base {
          * @default `console.error`
          */
         errorHandler?(options: any, err: any): void;
+
+        /**
+         * Client certificate for mTLS (PEM string or Buffer).
+         * Use either this or `certFilePath`.
+         */
+        cert?: string | Buffer;
+
+        /**
+         * Client private key for mTLS (PEM string or Buffer).
+         * Use either this or `keyFilePath`.
+         */
+        key?: string | Buffer;
+
+        /**
+         * CA certificate for mTLS (PEM string or Buffer).
+         * Use either this or `caFilePath`.
+         */
+        ca?: string | Buffer;
+
+        /**
+         * Path to client certificate file for mTLS.
+         * Read at initialization time. Ignored if `cert` is set.
+         */
+        certFilePath?: string;
+
+        /**
+         * Path to client private key file for mTLS.
+         * Read at initialization time. Ignored if `key` is set.
+         */
+        keyFilePath?: string;
+
+        /**
+         * Path to CA certificate file for mTLS.
+         * Read at initialization time. Ignored if `ca` is set.
+         */
+        caFilePath?: string;
+
+        /**
+         * Passphrase for an encrypted private key (`key` or `keyFilePath`).
+         */
+        passphrase?: string;
     }
 
     interface RequestOptions {

package/typings/index.test-d.ts

@@ -12,6 +12,25 @@ const validConfig: Mangopay.base.Config = {
     baseUrl: "https://api.mangopay.com"
 };
 
+// mTLS config — file paths
+const mtlsConfigPaths: Mangopay.base.Config = {
+    clientId: "your_client_id",
+    clientApiKey: "your_client_api_key",
+    certFilePath: "/path/to/cert.pem",
+    keyFilePath: "/path/to/key.pem",
+    caFilePath: "/path/to/ca.pem",
+    passphrase: "secret"
+};
+
+// mTLS config — raw content
+const mtlsConfigRaw: Mangopay.base.Config = {
+    clientId: "your_client_id",
+    clientApiKey: "your_client_api_key",
+    cert: "base64_string",
+    key: "base64_string",
+    passphrase: "secret"
+};
+
 // API instance tests
 const api = new Mangopay(validConfig);
 expectType<Mangopay>(api);