mangopay4-nodejs-sdk 1.66.0 → 1.67.0

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+## [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
+
+https://github.com/Mangopay/mangopay2-nodejs-sdk/pull/535/changes/ca0d85f6d6f35aa9ebe1ee5e77aa1e8a7b342b20
+On [POST Create a Payout](/api-reference/payouts/create-payout), platforms can now request to pay all SWIFT fees using the `OUR` value of the new `ChargeBearer` property ([API release note](/release-notes/api/2026-02-16)):
+- Handle `ChargeBearer` param
+
+### Added - AuthenticationType response property on card pay-ins
+
+https://github.com/Mangopay/mangopay2-nodejs-sdk/pull/535/changes/ac2813ac69d495ede90328d859e5749feb1a266b
+- The `AuthenticationResult.AuthenticationType` response property is now returned on card pay-ins
+
+### Added - TelephoneOrder body parameter on recurring card pay-ins (CIT and MIT)
+
+https://github.com/Mangopay/mangopay2-nodejs-sdk/pull/535/changes/32178e20810720a44c20a75556cdd961e1505cd3
+To support the `TelephoneOrder` property on [POST Create a Recurring PayIn (MIT)](/api-reference/recurring-card-payins/create-recurring-payin-cit) and [POST Create a Recurring PayIn (CIT)](/api-reference/recurring-card-payins/create-recurring-payin-mit):
+- handle `PaymentCategory` param
+
 ## [1.66.0] - 2026-02-12
 ### FX
 

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/lib/models/AuthenticationResult.js

@@ -0,0 +1,7 @@
+var Model = require('../Model');
+
+module.exports = Model.extend({
+    defaults: {
+        AuthenticationType: null
+    }
+});

package/lib/models/CardPreAuthorization.js

@@ -120,7 +120,9 @@ var CardPreAuthorization = Model.extend({
         /*
          * Information about the card
          */
-        CardInfo: null
+        CardInfo: null,
+
+        AuthenticationResult: null
     },
 
     getSubObjects: function() {

package/lib/models/CardValidation.js

@@ -14,6 +14,7 @@ module.exports = EntityBase.extend({
         Type: null,
         Applied3DSVersion: null,
         ResultCode: null,
-        ResultMessage: null
+        ResultMessage: null,
+        AuthenticationResult: null
     }
 });

package/lib/models/Deposit.js

@@ -24,6 +24,7 @@ module.exports = EntityBase.extend({
         Shipping: null,
         Requested3DSVersion: null,
         Applied3DSVersion: null,
-        CardInfo: null
+        CardInfo: null,
+        AuthenticationResult: null
     }
 });

package/lib/models/PayIn.js

@@ -23,7 +23,11 @@ var PayIn = Transaction.extend({
         /**
          * The unique reference generated for the profiling session, used by the fraud prevention solution to produce recommendations for the transaction using the profiling data.
          */
-        ProfilingAttemptReference: null
+        ProfilingAttemptReference: null,
+        /**
+         * AuthenticationResult
+         */
+        AuthenticationResult: null
     }),
 
     getReadOnlyProperties: function() {

package/lib/models/PayOutPaymentDetailsBankWire.js

@@ -25,7 +25,9 @@ var PayOutPaymentDetailsBankWire = PayOutPaymentDetails.extend({
 
         Status: null,
 
-        FallbackReason: null
+        FallbackReason: null,
+
+        ChargeBearer: null
     }
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mangopay4-nodejs-sdk",
-  "version": "1.66.0",
+  "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;
@@ -680,8 +675,9 @@ describe('PayIns', function () {
 
         describe('Create a Recurring Payment', function() {
             var recurring;
+            var createdCit;
             before(function(done){
-                recurringPayin = {
+                const recurringPayin = {
                     AuthorId: john.Id,
                     CardId: cardId,
                     CreditedUserId: john.Id,
@@ -724,7 +720,7 @@ describe('PayIns', function () {
                 api.PayIns.createRecurringPayment(recurringPayin, function(data, response){
                     recurring = data;
                 }).then(function(){
-                    cit = {
+                    const cit = {
                         RecurringPayinRegistrationId: recurring.Id,
                         BrowserInfo: {
                             AcceptHeader: "text/html, application/xhtml+xml, application/xml;q=0.9, /;q=0.8",
@@ -752,18 +748,19 @@ describe('PayIns', function () {
                     };
 
                     api.PayIns.createRecurringPayInRegistrationCIT(cit, function(data, response){
-                        createCit = data;
+                        createdCit = data;
                         done();
-                    })
-                })
-            })
+                    });
+                });
+            });
 
             it('should be created', function() {
                 expect(recurring).to.not.be.null;
                 expect(recurring.FreeCycles).to.not.be.null;
-                expect(createCit).to.not.be.null;
-            })
-        })
+                expect(createdCit).to.not.be.null;
+                expect(createdCit.PaymentCategory).to.not.be.null;
+            });
+        });
 
         describe('Create a PayPal Recurring Payment CIT', function() {
             var recurring;

package/test/services/PayOuts.js

@@ -19,6 +19,7 @@ describe('PayOuts', function() {
         it('should be created', function(){
             expect(payOut.Id).to.exist;
             expect(payOut.PaymentType).to.equal('BANK_WIRE');
+            expect(payOut.ChargeBearer).to.not.be.undefined;
         });
     });
 

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);

package/typings/models/cardPreauthorization.d.ts

@@ -6,6 +6,7 @@ import { money } from "./money";
 import { securityInfo } from "./securityInfo";
 import { shipping } from "./shipping";
 import { card } from "./card";
+import { payIn } from "./payIn";
 
 export namespace cardPreAuthorization {
     import BillingData = billing.BillingData;
@@ -14,6 +15,7 @@ export namespace cardPreAuthorization {
     import SecurityInfoData = securityInfo.SecurityInfoData;
     import ShippingData = shipping.ShippingData;
     import CardInfoData = card.CardInfoData;
+    import AuthenticationResult = payIn.AuthenticationResult;
 
     type PreAuthorizationExecutionType = "DIRECT";
 
@@ -153,5 +155,10 @@ export namespace cardPreAuthorization {
          * TelephoneOrder – Payment received via mail order or telephone order (MOTO).
          */
         PaymentCategory: string;
+
+        /**
+         * Authentication result
+         */
+        AuthenticationResult?: AuthenticationResult;
     }
 }

package/typings/models/cardValidation.d.ts

@@ -6,6 +6,8 @@ import { payIn } from "./payIn";
 import { SecureMode } from "../types";
 
 export namespace cardValidation {
+    import AuthenticationResult = payIn.AuthenticationResult;
+
     interface CardValidationData extends entityBase.EntityBaseData {
         /**
          * The unique identifier of the user at the source of the transaction.
@@ -80,6 +82,11 @@ export namespace cardValidation {
          * TelephoneOrder – Payment received via mail order or telephone order (MOTO).
          */
         PaymentCategory: string;
+
+        /**
+         * Authentication result
+         */
+        AuthenticationResult?: AuthenticationResult;
     }
 
     interface CreateCardValidation {

package/typings/models/deposit.d.ts

@@ -17,6 +17,7 @@ export namespace deposit {
     import CompleteBillingData = billing.CompleteBillingData;
     import _3DSVersion = payIn._3DSVersion;
     import CardInfoData = card.CardInfoData;
+    import AuthenticationResult = payIn.AuthenticationResult;
 
     type DepositStatus = ValueOf<enums.IDepositStatus>;
 
@@ -68,6 +69,11 @@ export namespace deposit {
         Applied3DSVersion: _3DSVersion;
 
         CardInfo: CardInfoData;
+
+        /**
+         * Authentication result
+         */
+        AuthenticationResult?: AuthenticationResult;
     }
 
     interface CreateDeposit {

package/typings/models/payIn.d.ts

@@ -198,6 +198,11 @@ export namespace payIn {
          * Name of the end-user’s bank
          */
         BankName: string;
+
+        /**
+         * Authentication result
+         */
+        AuthenticationResult?: AuthenticationResult;
     }
 
     interface CardWebExtendedPayInData {
@@ -388,6 +393,11 @@ export namespace payIn {
          * TelephoneOrder – Payment received via mail order or telephone order (MOTO).
          */
         PaymentCategory: string;
+
+        /**
+         * Authentication result
+         */
+        AuthenticationResult?: AuthenticationResult;
     }
 
     interface MbwayWebPayInData extends BasePayInData {
@@ -1726,6 +1736,13 @@ export namespace payIn {
          * Information about the card
          */
         CardInfo: CardInfoData;
+
+        PaymentCategory?: string;
+
+        /**
+         * Authentication result
+         */
+        AuthenticationResult?: AuthenticationResult;
     }
 
     interface CreateRecurringPayInCIT {
@@ -1772,6 +1789,8 @@ export namespace payIn {
          * of the Recurring PayIn Registration. An amount must be transmitted during either registration or pay-in.
          */
         Fees?: MoneyData;
+
+        PaymentCategory?: string;
     }
 
     interface CreateRecurringPayPalPayInCIT {
@@ -1865,6 +1884,8 @@ export namespace payIn {
          * Custom data that you can add to this item
          */
         Tag?: string;
+
+        PaymentCategory?: string;
     }
 
     interface CreateRecurringPayPalPayInMIT {
@@ -2148,6 +2169,11 @@ export namespace payIn {
          * Custom data that you can add to this item
          */
         Tag: string;
+
+        /**
+         * Authentication result
+         */
+        AuthenticationResult?: AuthenticationResult;
     }
 
     interface ApplePayPaymentData {
@@ -2312,6 +2338,11 @@ export namespace payIn {
          * This is the URL where users are automatically redirected after the payment is validated
          */
         ReturnURL: string;
+
+        /**
+         * Authentication result
+         */
+        AuthenticationResult?: AuthenticationResult;
     }
 
     interface KlarnaWebPayInData extends BasePayInData {
@@ -4010,4 +4041,8 @@ export namespace payIn {
     interface UpdatePayInIntentDisputeOutcome {
         Decision: string;
     }
+
+    interface AuthenticationResult {
+        AuthenticationType?: string;
+    }
 }

package/typings/models/payOut.d.ts

@@ -49,6 +49,11 @@ export namespace payOut {
          * Null if BankAccountId is provided.
          */
         RecipientId?: string;
+
+        /**
+         * Possible values: OUR / SHA
+         */
+        ChargeBearer?: string;
     }
 
     interface CreatePayOut {
@@ -101,6 +106,11 @@ export namespace payOut {
          * but if any prerequisite is not met or another problem occurs, there is no fallback: the wallet is automatically refunded and the payout is not completed.
          */
         PayoutModeRequested?: PayoutModeRequestedType;
+
+        /**
+         * Possible values: OUR / SHA
+         */
+        ChargeBearer?: string;
     }
 
     interface CheckPayOutEligibility {