mangopay4-nodejs-sdk 1.66.1 → 1.68.0

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [1.68.0] - 2026-03-25
+### Added - Acquiring pay-in service
+- New `Acquiring` service with `createPayIn` (Card, iDEAL, Apple Pay, Google Pay, PayPal), `createPayInRefund`, `createPayPalDataCollection`, and `createCardValidation` methods
+- TypeScript typings under the `acquiring` namespace (`typings/models/acquiring.d.ts`, `typings/services/Acquiring.d.ts`)
+
+### Breaking change - Payconiq removed
+- Payconiq was discontinued on 4 December 2025; all related code has been removed: `PayInPaymentDetailsPayconiq` model, `PAYCONIQ` enum value, `createPayconiqWeb`/`getPayconiqWeb` methods, and associated TypeScript typings
+
+### Added - Klarna `Discount` field
+- Optional `Discount` field added to `LineItemData` and `CreateLineItem` interfaces in `payIn.d.ts`
+
+## [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/apiMethods.js

@@ -50,8 +50,6 @@ module.exports = {
     "payins_recurring_registration_put": ["/${apiVersion}/${clientId}/recurringpayinregistrations/${id}", "PUT"],
     "payins_create_recurring_card_direct": ["/${apiVersion}/${clientId}/payins/recurring/card/direct", "POST"],
     "payins_create_recurring_paypal": ["/${apiVersion}/${clientId}/payins/payment-methods/paypal/recurring", "POST"],
-    "payins_payconiq-web_create": ["/${apiVersion}/${clientId}/payins/payconiq/web", "POST"],
-    "payins_payconiqv2-web_create": ["/${apiVersion}/${clientId}/payins/payment-methods/payconiq", "POST"],
     "payins_create_card_pre_authorized_deposit": ["/${apiVersion}/${clientId}/payins/deposit-preauthorized/direct/full-capture", "POST"],
     "payins_deposit_preauthorized_prior_to_complement": ["/${apiVersion}/${clientId}/payins/deposit-preauthorized/direct/capture-with-complement", "POST"],
     "payins_deposit_preauthorized_complement": ["/${apiVersion}/${clientId}/payins/deposit-preauthorized/direct/complement", "POST"],
@@ -272,5 +270,14 @@ module.exports = {
     "recipients_validate": ["/${apiVersion}/${clientId}/users/${userId}/recipients/validate", "POST"],
     "recipients_deactivate": ["/${apiVersion}/${clientId}/recipients/${recipientId}", "PUT"],
 
-    "pay_by_bank_get_supported_banks": ["/${apiVersion}/${clientId}/payment-methods/openbanking/metadata/supported-banks", "GET"]
+    "pay_by_bank_get_supported_banks": ["/${apiVersion}/${clientId}/payment-methods/openbanking/metadata/supported-banks", "GET"],
+
+    "acquiring_payins_card-direct_create": ["/${apiVersion}/${clientId}/acquiring/payins/card/direct/", "POST"],
+    "acquiring_payins_ideal-web_create": ["/${apiVersion}/${clientId}/acquiring/payins/payment-methods/ideal", "POST"],
+    "acquiring_payins_applepay-direct_create": ["/${apiVersion}/${clientId}/acquiring/payins/payment-methods/applepay", "POST"],
+    "acquiring_payins_googlepay-direct_create": ["/${apiVersion}/${clientId}/acquiring/payins/payment-methods/googlepay", "POST"],
+    "acquiring_payins_paypal-web_create": ["/${apiVersion}/${clientId}/acquiring/payins/payment-methods/paypal", "POST"],
+    "acquiring_payins_paypal_data_collection_create": ["/${apiVersion}/${clientId}/acquiring/payins/payment-methods/paypal/data-collection", "POST"],
+    "acquiring_payins_createrefunds": ["/${apiVersion}/${clientId}/acquiring/payins/${id}/refunds", "POST"],
+    "acquiring_card_validation_create": ["/${apiVersion}/${clientId}/acquiring/cards/${id}/validation", "POST"],
 };

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/PayInPaymentType.js

@@ -6,7 +6,6 @@ module.exports = {
     PayPal: 'PAYPAL',
     ApplePay: 'APPLEPAY',
     GooglePay: 'GOOGLE_PAY',
-    Payconiq: 'PAYCONIQ',
     Mbway: 'MBWAY',
     Bancontact: 'BCMC',
     Bizum: 'BIZUM',

package/lib/models/ReportFilterV2.js

@@ -4,7 +4,8 @@ var ReportFilterV2 = Model.extend({
     defaults: {
         Currency: null,
         UserId: null,
-        WalletId: null
+        WalletId: null,
+        SettlementId: null
     }
 });
 

package/lib/services/Acquiring.js

@@ -0,0 +1,152 @@
+const _ = require('underscore');
+
+const Service = require('../service');
+
+const PayIn = require('../models/PayIn');
+const PayInPaymentDetailsBankWire = require('../models/PayInPaymentDetailsBankWire');
+const PayInPaymentDetailsCard = require('../models/PayInPaymentDetailsCard');
+const PayInPaymentDetailsDirectDebitDirect = require('../models/PayInPaymentDetailsDirectDebitDirect');
+const PayInPaymentDetailsDirectDebitWeb = require('../models/PayInPaymentDetailsDirectDebitWeb');
+const PayInPaymentDetailsPreAuthorized = require('../models/PayInPaymentDetailsPreAuthorized');
+const PayInPaymentDetailsPayPal = require('../models/PayInPaymentDetailsPayPal');
+const PayInExecutionDetailsWeb = require('../models/PayInExecutionDetailsWeb');
+const PayInExecutionDetailsDirect = require('../models/PayInExecutionDetailsDirect');
+const PayInExecutionDetailsBankingAlias = require('../models/PayInExecutionDetailsBankingAlias');
+const PayInPaymentDetailsApplePay = require('../models/PayInPaymentDetailsApplePay');
+const PayInPaymentDetailsGooglePay = require('../models/PayInPaymentDetailsGooglePay');
+const PayInPaymentDetailsMbway = require('../models/PayInPaymentDetailsMbway');
+const PayInPaymentDetailsBancontact = require('../models/PayInPaymentDetailsBancontact');
+const PayInPaymentDetailsBizum = require('../models/PayInPaymentDetailsBizum');
+const Refund = require('../models/Refund');
+const PayInPaymentDetailsMultibanco = require("../models/PayInPaymentDetailsMultibanco");
+const PayInPaymentDetailsSatispay = require("../models/PayInPaymentDetailsSatispay");
+const PayInPaymentDetailsBlik = require("../models/PayInPaymentDetailsBlik");
+const PayInPaymentDetailsKlarna = require("../models/PayInPaymentDetailsKlarna");
+const PayInPaymentDetailsIdeal = require("../models/PayInPaymentDetailsIdeal");
+const PayInPaymentDetailsGiropay = require("../models/PayInPaymentDetailsGiropay");
+const PayInPaymentDetailsSwish = require("../models/PayInPaymentDetailsSwish");
+const PayInPaymentDetailsTwint = require("../models/PayInPaymentDetailsTwint");
+const PayInPaymentDetailsPayByBank = require("../models/PayInPaymentDetailsPayByBank");
+const CardValidation = require('../models/CardValidation');
+
+
+const Acquiring = Service.extend({
+    /**
+     * Create new pay-in
+     * @param {Object}  payIn     PayIn object
+     * @param {Function} callback Callback function
+     * @param {Object} options    Request options
+     * @return {Object}           Request promise
+     */
+    createPayIn: function (payIn, callback, options) {
+        options = this._api._getOptions(callback, options, {
+            data: payIn,
+            dataClass: PayIn
+        });
+
+        const paymentKey = this.getPaymentKey(payIn);
+        const executionKey = this.getExecutionKey(payIn);
+
+        return this._api.method('acquiring_payins_' + paymentKey + '-' + executionKey + '_create', callback, options);
+    },
+
+    /**
+     * Create refund for pay-in object
+     * @param {number}  payInId   PayIn identifier
+     * @param {Object}  refund    Refund data
+     * @param {Function} callback Callback function
+     * @param {Object} options    Request options
+     * @return {Object}           Request promise
+     */
+    createPayInRefund: function (payInId, refund, callback, options) {
+        options = this._api._getOptions(callback, options, {
+            path: {
+                id: payInId
+            },
+            dataClass: Refund,
+            data: refund
+        });
+
+        return this._api.method('acquiring_payins_createrefunds', callback, options);
+    },
+
+    /**
+     * Send key pre-transaction data such as order details, buyer information,
+     * and merchant context before initiating a PayPal payment
+     *
+     * @param dataCollection The data collection to be created
+     * @param callback       Callback function
+     * @param options        Request options
+     * @returns {Object}     Request promise
+     */
+    createPayPalDataCollection: function (dataCollection, callback, options) {
+        options = this._api._getOptions(callback, options, {
+            data: dataCollection
+        });
+
+        return this._api.method('acquiring_payins_paypal_data_collection_create', callback, options);
+    },
+
+    /**
+     * Create card validation
+     * @param cardId         The ID of the card
+     * @param cardValidation The create card validation dto
+     * @param callback       Callback function
+     * @param options        Request promise
+     * @returns {Object}
+     */
+    createCardValidation: function (cardId, cardValidation, callback, options) {
+        options = this._api._getOptions(callback, options, {
+            path: {
+                id: cardId
+            },
+            data: cardValidation,
+            dataClass: CardValidation
+        });
+
+        return this._api.method('acquiring_card_validation_create', callback, options);
+    },
+
+    getPaymentKey: function (payIn) {
+        if (payIn.PaymentType) {
+            return payIn.PaymentType.toLowerCase().replaceAll('_', '');
+        }
+
+        if (payIn.PaymentDetails instanceof PayInPaymentDetailsBankWire) return 'bankwire';
+        if (payIn.PaymentDetails instanceof PayInPaymentDetailsCard) return 'card';
+        if (payIn.PaymentDetails instanceof PayInPaymentDetailsDirectDebitDirect) return 'directdebit';
+        if (payIn.PaymentDetails instanceof PayInPaymentDetailsDirectDebitWeb) return 'directdebit';
+        if (payIn.PaymentDetails instanceof PayInPaymentDetailsPreAuthorized) return 'preauthorized';
+        if (payIn.PaymentDetails instanceof PayInPaymentDetailsPayPal) return 'paypal';
+        if (payIn.PaymentDetails instanceof PayInPaymentDetailsApplePay) return 'applepay';
+        if (payIn.PaymentDetails instanceof PayInPaymentDetailsGooglePay) return 'googlepay';
+        if (payIn.PaymentDetails instanceof PayInPaymentDetailsMbway) return 'mbway';
+        if (payIn.PaymentDetails instanceof PayInPaymentDetailsBancontact) return 'bcmc';
+        if (payIn.PaymentDetails instanceof PayInPaymentDetailsBizum) return 'bizum';
+        if (payIn.PaymentDetails instanceof PayInPaymentDetailsMultibanco) return 'multibanco';
+        if (payIn.PaymentDetails instanceof PayInPaymentDetailsSatispay) return 'satispay';
+        if (payIn.PaymentDetails instanceof PayInPaymentDetailsBlik) return 'blik';
+        if (payIn.PaymentDetails instanceof PayInPaymentDetailsKlarna) return 'klarna';
+        if (payIn.PaymentDetails instanceof PayInPaymentDetailsIdeal) return 'ideal';
+        if (payIn.PaymentDetails instanceof PayInPaymentDetailsGiropay) return 'giropay';
+        if (payIn.PaymentDetails instanceof PayInPaymentDetailsSwish) return 'swish';
+        if (payIn.PaymentDetails instanceof PayInPaymentDetailsTwint) return 'twint';
+        if (payIn.PaymentDetails instanceof PayInPaymentDetailsPayByBank) return 'paybybank';
+
+        throw new Error(`PaymentType ${payIn.PaymentType} not handled`);
+    },
+
+    getExecutionKey: function (payIn) {
+        if (payIn.ExecutionType) {
+            return payIn.ExecutionType.toLowerCase();
+        }
+
+        if (payIn.ExecutionDetails instanceof PayInExecutionDetailsWeb) return 'web';
+        if (payIn.ExecutionDetails instanceof PayInExecutionDetailsDirect) return 'direct';
+        if (payIn.ExecutionDetails instanceof PayInExecutionDetailsBankingAlias) return 'bankingalias';
+
+        throw new Error(`ExecutionType ${payIn.ExecutionType} not handled`);
+    }
+});
+
+module.exports = Acquiring;

package/lib/services/PayIns.js

@@ -24,7 +24,6 @@ var PayInPaymentDetailsBancontact = require('../models/PayInPaymentDetailsBancon
 var PayInPaymentDetailsBizum = require('../models/PayInPaymentDetailsBizum');
 var Refund = require('../models/Refund');
 var PayInRecurringRegistration = require('../models/PayInRecurringRegistration');
-var PayInPaymentDetailsPayconiq = require('../models/PayInPaymentDetailsPayconiq');
 const RecurringPayIn = require('../models/RecurringPayIn');
 const PayInPaymentDetailsMultibanco = require("../models/PayInPaymentDetailsMultibanco");
 const PayInPaymentDetailsSatispay = require("../models/PayInPaymentDetailsSatispay");
@@ -359,22 +358,6 @@ var PayIns = Service.extend({
         return this._api.method('payins_card-web_get_details', callback, options);
     },
 
-    /**
-     * Create new pay-in Payconiq Web, using the latest API url (/payment-methods/payconiq)
-     * @param {Object}  payIn    PayIn object
-     * @param {Function} callback    Callback function
-     * @param {Object} options    Request options
-     * @return {Object}         Request promise
-     */
-    createPayconiq: function(payIn, callback, options) {
-        options = this._api._getOptions(callback, options, {
-            data: payIn,
-            dataClass: PayIn
-        });
-
-        return this._api.method('payins_payconiqv2-web_create', callback, options);
-    },
-
     /**
      * Create a pay in intent authorization
      * @param {Object}  payInIntentAuthorization    PayInIntentAuthorization object
@@ -745,7 +728,6 @@ var PayIns = Service.extend({
         if (payIn.PaymentDetails instanceof PayInPaymentDetailsPayPal) return 'paypal';
         if (payIn.PaymentDetails instanceof PayInPaymentDetailsApplePay) return 'applepay';
         if (payIn.PaymentDetails instanceof PayInPaymentDetailsGooglePay) return 'googlepay';
-        if (payIn.PaymentDetails instanceof PayInPaymentDetailsPayconiq) return 'payconiq';
         if (payIn.PaymentDetails instanceof PayInPaymentDetailsMbway) return 'mbway';
         if (payIn.PaymentDetails instanceof PayInPaymentDetailsBancontact) return 'bcmc';
         if (payIn.PaymentDetails instanceof PayInPaymentDetailsBizum) return 'bizum';

package/lib/services/index.js

@@ -30,5 +30,6 @@ module.exports = {
     IdentityVerifications: require('./IdentityVerifications'),
     Recipients: require('./Recipients'),
     ReportsV2: require('./ReportsV2'),
-    Settlements: require('./Settlements')
+    Settlements: require('./Settlements'),
+    Acquiring: require('./Acquiring'),
 };

package/package.json

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

package/test/helpers.js

@@ -1104,7 +1104,7 @@ module.exports = {
                 AuthorId: user.Id,
                 CreditedWalletId: wallet.Id,
                 DebitedFunds: {
-                    Amount: 1000,
+                    Amount: 990,
                     Currency: 'EUR'
                 },
                 Fees: {
@@ -1125,7 +1125,8 @@ module.exports = {
                         Quantity: 1,
                         UnitAmount: 500,
                         TaxAmount: 0,
-                        Description: "seller2 ID"
+                        Description: "seller2 ID",
+                        Discount: 10
                     }
                 ],
                 Country: "FR",