mangopay4-nodejs-sdk 1.68.0 → 2.1.0

package/CHANGELOG.md

@@ -1,3 +1,71 @@
+## [2.1.0] - 2026-06-24
+This release adds unified recurring pay-ins, PayPal deposit preauthorizations, and several new model fields. Some methods are now marked `@deprecated` in favour of new names.
+
+### Added - Unified recurring pay-in method
+- New `PayIns.createRecurringPayIn(recurringPayIn)` method that creates a recurring pay-in for Card, PayPal, Apple Pay, and Google Pay using the same object structure as the non-recurring pay-in methods. It routes to the correct endpoint based on the payment and execution type:
+  - `payins/recurring/card/direct`
+  - `payins/payment-methods/paypal/recurring`
+  - `payins/payment-methods/applepay/recurring`
+  - `payins/payment-methods/googlepay/recurring`
+- New recurring registration methods `getRecurringPayInRegistration`, `updateRecurringPayInRegistration`, and `createRecurringPayInRegistration`.
+
+### Deprecated - Older recurring pay-in methods
+The following are now deprecated (still functional) in favour of the unified methods above:
+- `createRecurringPayInRegistrationCIT`, `createRecurringPayInRegistrationMIT`, `createRecurringPayPalPayInCIT`, `createRecurringPayPalPayInMIT` → use `createRecurringPayIn`
+- `getRecurringPayin` → use `getRecurringPayInRegistration`
+- `updateRecurringPayin` → use `updateRecurringPayInRegistration`
+- `createRecurringPayment` → use `createRecurringPayInRegistration`
+
+### Added - PayPal deposit preauthorization support
+- New `Deposits.createPayPalPreauthorization(deposit)` method, backed by the `deposit-preauthorizations/payment-methods/paypal` endpoint
+- New `PayPalDepositPreauthorization` model and `CreatePayPalDepositPreauthorization` TypeScript typing (fields include `PaypalPayerID`, `PaypalOrderID`, `Buyer*`, `Trackings`, `ShippingPreference`, `LineItems`, `DataCollectionId`, etc.)
+- New `PayIns.createDepositPreauthorizedPayInWithoutComplement(payIn)` method, backed by the `payins/deposit-preauthorized/direct/full-capture` endpoint
+- `PayIns.createCardPreAuthorizedDepositPayIn` is now deprecated in favour of `createDepositPreauthorizedPayInWithoutComplement`
+
+### Added - `FlowDescriptor` parameter
+- New `FlowDescriptor` object (`FlowId`, `Beneficiaries[].UserId`) added to pay-in, recurring pay-in registration, card preauthorization, and deposit create/data typings, allowing payment flow and beneficiary information to be passed
+
+### Added - `Email` property on Hook
+- The `Hook` model and `hook` typings now support an `Email` property on create and update
+
+### Added - `DateRangeBy` on Report V2
+- The Report V2 model (`ReportsV2.create`) now supports the `DateRangeBy` field (e.g. `"ExecutionDate"`), with a matching `DateRangeBy?: string` typing on `ReportV2Data`.
+
+### Added - Virtual account local account fields
+- `LocalAccount` typings gained `BankCode`, `BSBCode`, and `BCNumber` fields, with documentation updates to existing local account fields
+
+### Changed - Dependency upgrades
+- `axios` `1.16.0` → `1.17.0`
+- `form-data` `4.0.5` → `4.0.6`
+
+## [2.0.0] - 2026-05-27
+
+> **⚠️ Breaking release.** This version raises the minimum required Node.js version and bumps several dependencies. The runtime API of the SDK is unchanged — no method signatures, models, or TypeScript typings were modified — but please review the notes below before upgrading.
+
+### Breaking change - Minimum Node.js version raised to 22
+- `engines.node` is now `>=22.0.0` (previously `>= v0.10.0`).
+- Installing the SDK on Node < 22 will produce an `EBADENGINE` warning and is no longer supported. Upgrade your runtime before installing `2.0.0`.
+- `@types/node` is now pinned to `22.19.18`. Projects on older `@types/node` may see type drift in transitive types and should align their version.
+
+### Breaking change - Dependency upgrades
+Runtime and dev dependencies have been bumped to current versions to clear transitive vulnerabilities and align with the new Node 22 baseline:
+
+- Runtime: `axios` `1.12.0` → `1.16.0`, `form-data` `4.0.4` → `4.0.5`, `promise` `8.1.x` → `8.3.0`, `underscore` `1.12.x` → `1.13.8`, `@types/node` `14.14.x` → `22.19.18`.
+- Dev: `mocha` `9.2.0` → `11.7.5`, `chai` `4.2.x` → `4.5.0`, `sinon` `9.2.x` → `21.0.1`, `typescript` `4.1.x` → `6.0.3`, `ts-node` `^9.1.1` → `10.9.2`, `tsd` `^0.30.4` → `0.33.0`.
+- Projects that depend on the older transitive versions (for example, code relying on Axios `1.12` request/response shapes) should re-test their integration against `2.0.0`.
+
+### Changed - Source repository no longer on GitHub
+- The source repository has been moved off GitHub. The previous `github.com/Mangopay/mangopay2-nodejs-sdk` location is no longer maintained and will not receive new commits, issues, or pull requests.
+- The `repository` field has been removed from `package.json`.
+- This change does not affect consumption: `npm install mangopay4-nodejs-sdk` continues to work exactly as before.
+
+### Fixed - Garbled comment in `CardPreAuthorization`
+- Replaced non-UTF-8 characters in the `IpAddress` JSDoc comment of `lib/models/CardPreAuthorization.js`. No behavior change.
+
+### Notes for upgraders
+- If your project is on Node 16/18/20, upgrade to Node 22 (or newer) before installing `2.0.0`. The `1.x` line remains available on npm for environments that cannot upgrade their runtime yet.
+- No application code changes are required for SDK callers — all service methods, models, and TypeScript typings are unchanged from `1.68.0`.
+
 ## [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

package/README.md

@@ -244,12 +244,6 @@ Sample usage of Mangopay SDK installed with npm in a Node.js project
 -------------------------------------------------
 Don't forget to check examples folder !
 
-Contributing
--------------------------------------------------
-    npm start                       // installs dependencies and global mocha for testing and jsdox for documentation
-    npm test                        // runs the mocha tests
-    npm run-script documentation    // update documentation using jsdox, make sure to have it installed globally
-
 Unit Tests
 -------------------------------------------------
 Mocha tests are placed under ``/test/`` folder. To run the tests, make sure you have all dependencies installed.

package/lib/apiMethods.js

@@ -49,8 +49,12 @@ module.exports = {
     "payins_recurring_registration_get": ["/${apiVersion}/${clientId}/recurringpayinregistrations/${id}", "GET"],
     "payins_recurring_registration_put": ["/${apiVersion}/${clientId}/recurringpayinregistrations/${id}", "PUT"],
     "payins_create_recurring_card_direct": ["/${apiVersion}/${clientId}/payins/recurring/card/direct", "POST"],
+    "payins_recurring_card-direct_create": ["/${apiVersion}/${clientId}/payins/recurring/card/direct", "POST"],
     "payins_create_recurring_paypal": ["/${apiVersion}/${clientId}/payins/payment-methods/paypal/recurring", "POST"],
-    "payins_create_card_pre_authorized_deposit": ["/${apiVersion}/${clientId}/payins/deposit-preauthorized/direct/full-capture", "POST"],
+    "payins_recurring_paypal-web_create": ["/${apiVersion}/${clientId}/payins/payment-methods/paypal/recurring", "POST"],
+    "payins_recurring_applepay-direct_create": ["/${apiVersion}/${clientId}/payins/payment-methods/applepay/recurring", "POST"],
+    "payins_recurring_googlepay-direct_create": ["/${apiVersion}/${clientId}/payins/payment-methods/googlepay/recurring", "POST"],
+    "payins_deposit_preauthorized_without_complement": ["/${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"],
     "payins_mbway-web_create": ["/${apiVersion}/${clientId}/payins/payment-methods/mbway", "POST"],
@@ -237,6 +241,7 @@ module.exports = {
     "countries_get_all": ["/${apiVersion}/countries/authorizations", "GET"],
 
     "deposits_create": ["/${apiVersion}/${clientId}/deposit-preauthorizations/card/direct", "POST"],
+    "deposits_paypal_create": ["/${apiVersion}/${clientId}/deposit-preauthorizations/payment-methods/paypal", "POST"],
     "deposits_get": ["/${apiVersion}/${clientId}/deposit-preauthorizations/${depositId}", "GET"],
     "deposits_update": ["/${apiVersion}/${clientId}/deposit-preauthorizations/${depositId}", "PUT"],
     "deposits_get_all_for_card": ["/${apiVersion}/${clientId}/cards/${cardId}/deposit-preauthorizations", "GET"],

package/lib/models/CardPreAuthorization.js

@@ -93,8 +93,8 @@ var CardPreAuthorization = Model.extend({
         MultiCapture: null,
 
         /**
-         *  Is not Mandatory for 3DSv1 (flag �Use 3DSV2 Scenario� OFF)
-         *  Is mandatory when the flag �Use 3DSV2 Scenario� is active for (FORCE/DEFAULT/FRICTIONLESS both 3)
+         *  Is not Mandatory for 3DSv1 (flag Use 3DSV2 Scenario OFF)
+         *  Is mandatory when the flag Use 3DSV2 Scenario is active for (FORCE/DEFAULT/FRICTIONLESS both 3)
          */
         IpAddress: null,
 

package/lib/models/Hook.js

@@ -14,6 +14,7 @@ module.exports = EntityBase.extend({
          * Validity: VALID, INVALID
          */
         Validity: null,
-        EventType: null
+        EventType: null,
+        Email: null
     }
 });

package/lib/models/PayInRecurringRegistration.js

@@ -30,7 +30,8 @@ var PayInRecurringRegistration = EntityBase.extend({
         CycleNumber: null,
         FreeCycles: null,
         CurrentState: null,
-        PaymentType: null
+        PaymentType: null,
+        PaymentData: null,
     },
 
     /**

package/lib/models/PayPalDepositPreauthorization.js

@@ -0,0 +1,21 @@
+var Deposit = require('./Deposit');
+
+module.exports = Deposit.extend({
+    defaults: {
+        PaypalPayerID: null,
+        PaypalOrderID: null,
+        BuyerFirstname: null,
+        BuyerLastname: null,
+        BuyerPhone: null,
+        BuyerCountry: null,
+        PaypalBuyerAccountEmail: null,
+        CancelURL: null,
+        Trackings: null,
+        ShippingPreference: null,
+        Reference: null,
+        LineItems: null,
+        RedirectURL: null,
+        ReturnURL: null,
+        DataCollectionId: null
+    }
+});

package/lib/models/ReportV2.js

@@ -15,7 +15,8 @@ var ReportV2 = EntityBase.extend({
         AfterDate: null,
         BeforeDate: null,
         Filters: null,
-        Columns: null
+        Columns: null,
+        DateRangeBy: null
     },
 
     getSubObjects: function () {

package/lib/services/Deposits.js

@@ -1,5 +1,6 @@
 var Service = require('../service');
 var Deposit = require('../models/Deposit');
+var PayPalDepositPreauthorization = require('../models/PayPalDepositPreauthorization');
 
 var Deposits = Service.extend({
     /**
@@ -14,6 +15,18 @@ var Deposits = Service.extend({
         return this._api.method('deposits_create', callback, options);
     },
 
+    /**
+     * Create a PayPal Deposit Preauthorization
+     */
+    createPayPalPreauthorization: function(deposit, callback, options) {
+        options = this._api._getOptions(callback, options, {
+            data: deposit,
+            dataClass: PayPalDepositPreauthorization
+        });
+
+        return this._api.method('deposits_paypal_create', callback, options);
+    },
+
     /**
      * Get a Deposit
      */

package/lib/services/PayIns.js

@@ -61,12 +61,33 @@ var PayIns = Service.extend({
         return this._api.method('payins_' + paymentKey + '-' + executionKey + '_create', callback, options);
     },
 
+    /**
+     * Create new recurring pay-in (Card, ApplePay, GooglePay, PayPal),
+     * following the same pattern (object structure) as non-recurring payins
+     * @param {Object}  recurringPayIn PayIn object
+     * @param {Function} callback      Callback function
+     * @param {Object} options         Request options
+     * @return {Object}                Request promise
+     */
+    createRecurringPayIn: function(recurringPayIn, callback, options) {
+        options = this._api._getOptions(callback, options, {
+            data: recurringPayIn,
+            dataClass: RecurringPayIn
+        });
+
+        var paymentKey = this.getPaymentKey(recurringPayIn);
+        var executionKey = this.getExecutionKey(recurringPayIn);
+
+        return this._api.method('payins_recurring_' + paymentKey + '-' + executionKey + '_create', callback, options);
+    },
+
      /**
      * Get recurring pay-in
      * @param {number}  payInId    PayIn identifier
      * @param {Function} callback    Callback function
      * @param {Object} options    Request options
      * @return {Object}         Request promise
+      * @deprecated Use 'getRecurringPayInRegistration' instead
      */
      getRecurringPayin: function(payInId, callback, options) {
         options = this._api._getOptions(callback, options, {
@@ -79,6 +100,24 @@ var PayIns = Service.extend({
         return this._api.method('payins_recurring_registration_get', callback, options);
     },
 
+    /**
+     * Get recurring PayIn registration
+     * @param {number}  recurringPayInRegistrationId Recurring PayIn registration identifier
+     * @param {Function} callback                    Callback function
+     * @param {Object} options                       Request options
+     * @return {Object}                              Request promise
+     */
+    getRecurringPayInRegistration: function(recurringPayInRegistrationId, callback, options) {
+        options = this._api._getOptions(callback, options, {
+            path: {
+                id: recurringPayInRegistrationId
+            },
+            dataClass: PayInRecurringRegistration
+        });
+
+        return this._api.method('payins_recurring_registration_get', callback, options);
+    },
+
      /**
      * Update recurring pay-in
      * @param {number}  payInId    PayIn identifier
@@ -86,6 +125,7 @@ var PayIns = Service.extend({
      * @param {Function} callback    Callback function
      * @param {Object} options    Request options
      * @return {Object}         Request promise
+      * @deprecated Use 'updateRecurringPayInRegistration' instead
      */
     updateRecurringPayin: function(payInId, toUpdate, callback, options) {
         options = this._api._getOptions(callback, options, {
@@ -99,12 +139,32 @@ var PayIns = Service.extend({
         return this._api.method('payins_recurring_registration_put', callback, options);
     },
 
+    /**
+     * Update recurring PayIn Registration
+     * @param {Object} recurringPayInRegistration Object to be updated. Must contain the id.
+     * @param {Function} callback                 Callback function
+     * @param {Object} options                    Request options
+     * @return {Object}                           Request promise
+     */
+    updateRecurringPayInRegistration: function(recurringPayInRegistration, callback, options) {
+        options = this._api._getOptions(callback, options, {
+            path: {
+                id: recurringPayInRegistration.Id
+            },
+            data: recurringPayInRegistration,
+            dataClass: PayInRecurringRegistration
+        });
+
+        return this._api.method('payins_recurring_registration_put', callback, options);
+    },
+
     /**
      * Create Payin Registration
      * @param {Object}  payIn    PayInRecurringRegistration object
      * @param {Function} callback    Callback function
      * @param {Object} options    Request options
      * @return {Object}         Request promise
+     * @deprecated Use 'createRecurringPayInRegistration' instead
      */
     createRecurringPayment: function(recurringPayin, callback, options) {
         options = this._api._getOptions(callback, options, {
@@ -115,12 +175,29 @@ var PayIns = Service.extend({
         return this._api.method('payins_recurring_registration', callback, options);
     },
 
+    /**
+     * Create Recurring Payin Registration
+     * @param {Object} recurringPayinRegistration PayInRecurringRegistration object
+     * @param {Function} callback                 Callback function
+     * @param {Object} options                    Request options
+     * @return {Object}                           Request promise
+     */
+    createRecurringPayInRegistration: function(recurringPayinRegistration, callback, options) {
+        options = this._api._getOptions(callback, options, {
+            data: recurringPayinRegistration,
+            dataClass: PayInRecurringRegistration
+        });
+
+        return this._api.method('payins_recurring_registration', callback, options);
+    },
+
     /**
      * Create new recurring pay-in CIT
      * @param {Object}  payIn    PayIn object
      * @param {Function} callback    Callback function
      * @param {Object} options    Request options
      * @return {Object}         Request promise
+     * @deprecated Use 'createRecurringPayIn' instead
      */
     createRecurringPayInRegistrationCIT: function(payIn, callback, options) {
         options = this._api._getOptions(callback, options, {
@@ -137,6 +214,7 @@ var PayIns = Service.extend({
      * @param {Function} callback    Callback function
      * @param {Object} options    Request options
      * @return {Object}         Request promise
+     * @deprecated Use 'createRecurringPayIn' instead
      */
     createRecurringPayInRegistrationMIT: function(payIn, callback, options) {
         options = this._api._getOptions(callback, options, {
@@ -153,6 +231,7 @@ var PayIns = Service.extend({
      * @param {Function} callback    Callback function
      * @param {Object} options    Request options
      * @return {Object}         Request promise
+     * @deprecated Use 'createRecurringPayIn' instead
      */
     createRecurringPayPalPayInCIT: function(payIn, callback, options) {
         options = this._api._getOptions(callback, options, {
@@ -169,6 +248,7 @@ var PayIns = Service.extend({
      * @param {Function} callback    Callback function
      * @param {Object} options    Request options
      * @return {Object}         Request promise
+     * @deprecated Use 'createRecurringPayIn' instead
      */
     createRecurringPayPalPayInMIT: function(payIn, callback, options) {
         options = this._api._getOptions(callback, options, {
@@ -239,6 +319,7 @@ var PayIns = Service.extend({
 
     /**
      * Create new Card PreAuthorized Deposit PayIn without complement
+     * @deprecated Use 'createDepositPreauthorizedPayInWithoutComplement' instead
      */
     createCardPreAuthorizedDepositPayIn: function(payIn, callback, options) {
         options = this._api._getOptions(callback, options, {
@@ -246,7 +327,19 @@ var PayIns = Service.extend({
             dataClass: PayIn
         });
 
-        return this._api.method('payins_create_card_pre_authorized_deposit', callback, options);
+        return this._api.method('payins_deposit_preauthorized_without_complement', callback, options);
+    },
+
+    /**
+     * Create new Deposit PreAuthorized PayIn without complement
+     */
+    createDepositPreauthorizedPayInWithoutComplement: function(payIn, callback, options) {
+        options = this._api._getOptions(callback, options, {
+            data: payIn,
+            dataClass: PayIn
+        });
+
+        return this._api.method('payins_deposit_preauthorized_without_complement', callback, options);
     },
 
     /**

package/package.json

@@ -1,40 +1,32 @@
 {
   "name": "mangopay4-nodejs-sdk",
-  "version": "1.68.0",
+  "version": "2.1.0",
   "types": "./typings/index.d.ts",
   "description": "Mangopay Node.js SDK",
-  "repository": "https://github.com/Mangopay/mangopay2-nodejs-sdk.git",
   "license": "MIT",
-  "keywords": [
-    "mangopay",
-    "nodejs",
-    "sdk",
-    "credit cards",
-    "api"
-  ],
   "engines": {
-    "node": ">= v0.10.0"
+    "node": ">=22.0.0"
   },
   "main": "./index.js",
   "dependencies": {
-    "@types/node": "14.14.x",
-    "axios": "1.12.0",
-    "form-data": "4.0.4",
-    "promise": "8.1.x",
-    "underscore": "1.12.x"
+    "@types/node": "22.19.18",
+    "axios": "1.17.0",
+    "form-data": "4.0.6",
+    "promise": "8.3.0",
+    "underscore": "1.13.8"
   },
   "devDependencies": {
-    "chai": "4.2.x",
-    "mocha": "9.2.0",
-    "sinon": "9.2.x",
-    "tsd": "^0.30.4",
-    "ts-node": "^9.1.1",
-    "typescript": "4.1.x"
+    "c8": "11.0.0",
+    "chai": "4.5.0",
+    "mocha": "11.7.5",
+    "sinon": "21.0.1",
+    "ts-node": "10.9.2",
+    "tsd": "0.33.0",
+    "typescript": "6.0.3"
   },
   "scripts": {
-    "start": "npm install -g mocha && npm install -g jsdox && npm install",
-    "documentation": "jsdox -t docs/templates/ -i README -o docs lib/services",
     "test": "mocha 'test/**/*.js' --recursive --timeout 30000 --ui bdd",
+    "test:coverage": "c8 --reporter=lcov --reporter=text pnpm test",
     "test:types": "tsd"
   }
-}
+}

package/typings/enums.d.ts

@@ -28,7 +28,9 @@ export namespace enums {
 
     interface IRecurringPayInRegistrationPaymentType {
         CardDirect: "CARD_DIRECT";
-        PayPal: "PAYPAL"
+        PayPal: "PAYPAL";
+        ApplePay: "APPLEPAY";
+        GooglePay: "GOOGLE_PAY";
     }
 
     interface IMandateStatus {

package/typings/models/cardPreauthorization.d.ts

@@ -16,6 +16,7 @@ export namespace cardPreAuthorization {
     import ShippingData = shipping.ShippingData;
     import CardInfoData = card.CardInfoData;
     import AuthenticationResult = payIn.AuthenticationResult;
+    import FlowDescriptor = payIn.FlowDescriptor;
 
     type PreAuthorizationExecutionType = "DIRECT";
 
@@ -24,7 +25,7 @@ export namespace cardPreAuthorization {
     type PreAuthorizationStatus = "CREATED" | "SUCCEEDED" | "FAILED";
 
     type CreateCardPreAuthorization = PickPartialRequired<CardPreAuthorizationData,
-        "Tag" | "Billing" | "SecureMode" | "Culture" | "StatementDescriptor" | "Shipping" | "PaymentCategory", "AuthorId" | "DebitedFunds" | "CardId" | "SecureModeReturnURL" | "IpAddress" | "BrowserInfo">;
+        "Tag" | "Billing" | "SecureMode" | "Culture" | "StatementDescriptor" | "Shipping" | "PaymentCategory" | "FlowDescriptor", "AuthorId" | "DebitedFunds" | "CardId" | "SecureModeReturnURL" | "IpAddress" | "BrowserInfo">;
 
     type UpdateCardPreAuthorization = PickPartialRequired<CardPreAuthorizationData,
         "Tag",
@@ -160,5 +161,10 @@ export namespace cardPreAuthorization {
          * Authentication result
          */
         AuthenticationResult?: AuthenticationResult;
+
+        /**
+         * Information about the payment flow and its Beneficiaries.
+         */
+        FlowDescriptor?: FlowDescriptor;
     }
 }