mangopay4-nodejs-sdk 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,3 +1,43 @@
+## [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.

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/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,6 +1,6 @@
 {
   "name": "mangopay4-nodejs-sdk",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "types": "./typings/index.d.ts",
   "description": "Mangopay Node.js SDK",
   "license": "MIT",
@@ -10,8 +10,8 @@
   "main": "./index.js",
   "dependencies": {
     "@types/node": "22.19.18",
-    "axios": "1.16.0",
-    "form-data": "4.0.5",
+    "axios": "1.17.0",
+    "form-data": "4.0.6",
     "promise": "8.3.0",
     "underscore": "1.13.8"
   },

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

package/typings/models/deposit.d.ts

@@ -18,6 +18,11 @@ export namespace deposit {
     import _3DSVersion = payIn._3DSVersion;
     import CardInfoData = card.CardInfoData;
     import AuthenticationResult = payIn.AuthenticationResult;
+    import FlowDescriptor = payIn.FlowDescriptor;
+    import ShippingPreference = payIn.ShippingPreference;
+    import PayPalWebTrackingData = payIn.PayPalWebTrackingData;
+    import LineItemData = payIn.LineItemData;
+    import CreateLineItem = payIn.CreateLineItem;
 
     type DepositStatus = ValueOf<enums.IDepositStatus>;
 
@@ -74,6 +79,86 @@ export namespace deposit {
          * Authentication result
          */
         AuthenticationResult?: AuthenticationResult;
+
+        /**
+         * Information about the payment flow and its Beneficiaries.
+         */
+        FlowDescriptor?: FlowDescriptor;
+
+        /**
+         * The unique identifier of the buyer's PayPal account, provided by PayPal.
+         */
+        PaypalPayerID?: string;
+
+        /**
+         * The unique identifier of the order on the PayPal side.
+         */
+        PaypalOrderID?: string;
+
+        /**
+         * The first name of the buyer, returned by PayPal.
+         */
+        BuyerFirstname?: string;
+
+        /**
+         * The last name of the buyer, returned by PayPal.
+         */
+        BuyerLastname?: string;
+
+        /**
+         * The phone number of the buyer, returned by PayPal.
+         */
+        BuyerPhone?: string;
+
+        /**
+         * The country of the buyer, returned by PayPal.
+         */
+        BuyerCountry?: CountryISO;
+
+        /**
+         * The email address of the buyer's PayPal account.
+         */
+        PaypalBuyerAccountEmail?: string;
+
+        /**
+         * The URL to which the user is returned after canceling the payment.
+         */
+        CancelURL?: string;
+
+        /**
+         * Information about the shipment trackings.
+         */
+        Trackings?: PayPalWebTrackingData[];
+
+        /**
+         * The shipping preference used for the PayPal payment.
+         */
+        ShippingPreference?: ShippingPreference;
+
+        /**
+         * The platform’s order reference for the transaction.
+         */
+        Reference?: string;
+
+        /**
+         * Information about the items bought by the buyer.
+         */
+        LineItems?: LineItemData[];
+
+        /**
+         * The URL to which the user is redirected to complete the payment.
+         */
+        RedirectURL?: string;
+
+        /**
+         * The URL to which the user is returned after the payment, whether successful or not.
+         */
+        ReturnURL?: string;
+
+        /**
+         * The unique identifier of the Data Collection object containing the data PayPal needs to process the pay-in.
+         */
+        DataCollectionId?: string;
     }
 
     interface CreateDeposit {
@@ -96,6 +181,86 @@ export namespace deposit {
         Billing?: CompleteBillingData;
 
         Shipping?: ShippingData;
+
+        /**
+         * Information about the payment flow and its Beneficiaries.
+         */
+        FlowDescriptor?: FlowDescriptor;
+    }
+
+    interface CreatePayPalDepositPreauthorization {
+        /**
+         * The unique identifier of the user at the source of the transaction.
+         */
+        AuthorId: string;
+
+        /**
+         * Information about the preauthorized funds.
+         */
+        DebitedFunds: MoneyData;
+
+        /**
+         * The URL to which the user is returned after the payment, whether the transaction is successful or not.
+         */
+        ReturnURL: string;
+
+        /**
+         * The URL to which the user is returned after canceling the payment.
+         * If not provided, the user is returned to the ReturnURL.
+         */
+        CancelURL?: string;
+
+        /**
+         * The unique identifier of the Data Collection object containing the data PayPal needs to process the pay-in.
+         */
+        DataCollectionId?: string;
+
+        /**
+         * The shipping preference for the payment.
+         * One of SET_PROVIDED_ADDRESS, GET_FROM_FILE, or NO_SHIPPING.
+         */
+        ShippingPreference?: ShippingPreference;
+
+        /**
+         * Information about the end user’s shipping address.
+         * Required if ShippingPreference is SET_PROVIDED_ADDRESS.
+         */
+        Shipping?: ShippingData;
+
+        /**
+         * The platform’s order reference for the transaction (max. 127 characters).
+         */
+        Reference?: string;
+
+        /**
+         * Custom data that you can add to this object (max. 255 characters).
+         */
+        Tag?: string;
+
+        /**
+         * Custom description to appear on the user’s bank statement (max. 10 characters, alphanumeric and spaces).
+         */
+        StatementDescriptor?: string;
+
+        /**
+         * The language in which the PayPal payment page is to be displayed, in ISO 639-1 format.
+         */
+        Culture?: CountryISO;
+
+        /**
+         * The reference to the profiling session used for fraud prevention.
+         */
+        ProfilingAttemptReference?: string;
+
+        /**
+         * Information about the items bought by the buyer.
+         */
+        LineItems?: CreateLineItem[];
+
+        /**
+         * Information about the payment flow and its Beneficiaries.
+         */
+        FlowDescriptor?: FlowDescriptor;
     }
 
     interface PayinsLinkedData {

package/typings/models/hook.d.ts

@@ -27,13 +27,18 @@ export namespace hook {
          * The event type
          */
         EventType: event.EventType;
+
+        /**
+         * Email
+         */
+        Email: string;
     }
 
-    interface CreateHook extends PickPartialRequired<HookData, "Tag", "EventType" | "Url"> {
+    interface CreateHook extends PickPartialRequired<HookData, "Tag" | "Email", "EventType" | "Url"> {
     }
 
     interface UpdateHook extends PickPartialRequired<HookData,
-        "EventType" | "Url" | "Tag" | "Status",
+        "EventType" | "Url" | "Tag" | "Status" | "Email",
         "Id"> {
     }
 }