> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mangopay.com/release-notes/sdk/nodejs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.

# NodeJS SDK

**Package:** [mangopay4-nodejs-sdk](https://www.npmjs.com/package/mangopay4-nodejs-sdk)

---

## 2.5.0 - Oct 1, 2026

#### [2.5.0 - Oct 1, 2026](/release-notes/sdk/nodejs/2-5-0)

Added

* Extended Preauthorization feature to rename Deposit Preauthorization
* Extended Preauthorization event types
* Settlement event types
* `ProfilingAttemptReference`

Deprecated

* Deposit Preauthorization feature deprecated

Changed

* Internal cleanup
* Bumped Axios version

## 2.4.0 - Sep 2, 2026

#### [2.4.0 - Sep 2, 2026](/release-notes/sdk/nodejs/2-4-0)

Added

* `KycInformation` containing `KycRenewalDeadline` on regulatory user
* Retrieve PayPal data collection
* Account funding on card direct pay-in
* `AMEX` card type

## 2.3.0 - Aug 18, 2026

#### [2.3.0 - Aug 18, 2026](/release-notes/sdk/nodejs/2-3-0)

Added

* Support for multi-session PSC flow on hosted KYB for Business
* Identity verification event types
* GET List Intent external providers
* `Tag` on intents and splits

Changed

* Bumped Axios version

## 2.2.0 - Jul 14, 2026

#### [2.2.0 - Jul 14, 2026](/release-notes/sdk/nodejs/2-2-0)

Fixed

* Echo Settlement validation errors response mapping

Deprecated

* Non-SCA User endpoints
* Deposit PayIn complement endpoints

## 2.1.0 - Jun 24, 2026

#### [2.1.0 - Jun 24, 2026](/release-notes/sdk/nodejs/2-1-0)

Added

* `FlowDescriptor` for declaring pay-in `Beneficiaries`
* Unified recurring pay-in method
* Support for PayPal deposit preauthorizations
* Support for `Email` on webhooks
* `DateRangeBy` on `Report V2`
* Virtual account local account fields

Deprecated

* Older recurring pay-in methods

Changed

* Dependency upgrades

## 2.0.0 - Jun 2, 2026

#### [2.0.0 - Jun 2, 2026](/release-notes/sdk/nodejs/2-0-0)

Breaking change

* Minimum Node.js version raised to 22
* Dependency upgrades

Fixed

* Garbled comment in `CardPreAuthorization`

## 1.68.0 - Mar 30, 2026

#### [1.68.0 - Mar 30, 2026](/release-notes/sdk/nodejs/1-68-0)

Breaking change

* Payconiq PayIn removed following discontinuation

Added

* Klarna discount property on line items

---

## 1.67.0 - Mar 23, 2026

### Added

#### Support for mTLS authentication

To support mTLS authentication for [SCA on platforms](/guides/sca/platform), which is required for platforms taking [SCA-triggering action under proxy](/guides/sca/proxy-management):

* Added `cert`, `key`, `ca`, `certFilePath`, `keyFilePath`, `caFilePath` to `config.js`
* Added `_buildHttpsAgent()` method to `api.js` which returns a HttpAgent that may contain the certificate configuration
* Update the TS typings to reflect the new properties
* Updated the requests logic to add the mTLS certificate if present
* Updated `README.md` file with details on [how to configure mTLS for the SDK](/guides/sca/platform#4-integrate-mtls-in-the-sdk)

**Note:** The SDK requires **TLS 1.2+** for TLS compliance, even for non-mTLS connections, in line with [Mangopay's security guidelines](/security#2-a-tls-and-https).

## 1.66.1 - Feb 23, 2026

### Added

#### ChargeBearer body parameter on payouts

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

* Added `ChargeBearer` param (String) to `PayOutData` and `CreatePayOut` interfaces
* Updated tests

### Added

#### AuthenticationType response property on card pay-ins

The `AuthenticationResult.AuthenticationType` response property is now returned on card pay-ins ([API release note](/release-notes/api/2026-02-23)):

* Added the `AuthenticationResult` interface
* Added `AuthenticationResult` param (Object containing AuthenticationType) to `CardPreauthorizationData`, `CardValidationData`, `DepositData`, `CardWebPayInData`, `CardDirectPayInData`, `RecurringPayInData`, `ApplePayPayInData`, `GooglePayDirectPayInData` interfaces
* Updated tests

### Added

#### TelephoneOrder body parameter on recurring card pay-ins (CIT and MIT)

To support the `TelephoneOrder` property on [POST Create a Recurring PayIn](/api-reference/recurring-card-payins/create-recurring-card-payin) (both CIT and MIT payloads):

* Added `PaymentCategory` (String) to `RecurringPayInData`, `CreateRecurringPayInCIT`, `CreateRecurringPayInMIT` interfaces
* Updated tests

## 1.66.0 - Feb 12, 2026

### FX

### Breaking change

#### Custom fees

To support percentage-based FX fees ([API release note](/release-notes/api/2026-02-11)):

> **Warning**
>
> **Caution - Breaking change**
>
> * The `CreateInstantConversion.Fees` type is now `CustomMoneyData` instead of `MoneyData`, to support the new FX fees structure of `Type` (`PERCENTAGE` | `FIXED`) and `Value`
> * The `CreateInstantConversion.CreditedFunds` type is now `MoneyDataOptionalAmount` instead of `MoneyData`

* Added `Fees` to `CreateQuote`
* Added `Fees, RequestedFees` to `QuoteData`
* Added `RequestedFees` to `ConversionData`

### Added

#### User margin

To support the FX user margin ([API release note](/release-notes/api/2026-02-11)):

* Added `UserMargin` to `CreateInstantConversion` and `CreateQuote`
* Added `MarginsResponse` to `ConversionData` and `QuoteData`

### Echo

### Breaking change

#### Settlement upload endpoints

To support the new behavior of the [POST Create a Settlement](/api-reference/settlements/create-settlement) endpoint to obtain an `UploadUrl`:

* Updated `settlement_sample.csv` and tests
* Added `FileName` and `UploadUrl` to `SettlementData`
* Added `GenerateSettlementUploadUrl` interface

> **Warning**
>
> **Caution - Breaking change**
>
> * Replaced `upload` method in `Settlements` with `generateUploadUrl`:
>
> ```javascript NodeJS
>  api.Settlements.generateUploadUrl({FileName: "settlement_sample.csv"})
> ```

> **Warning**
>
> **Caution - Breaking change**
>
> * Replaced `update` method in `Settlements` with: `generateNewUploadUrl`
>
> ```javascript NodeJS
>   api.Settlements.generateNewUploadUrl(settlement.SettlementId, {FileName: "settlement_sample_updated.csv"})
> ```

### Added

#### GET validations for a Settlement endpoint

To support the [GET View validation errors for a Settlement](/api-reference/settlements/view-settlement-validations) endpoint:

* Added `SettlementValidation`, `SettlementValidationFooter`, `SettlementValidationLine` interfaces
* Added `getValidations` method to `Settlements`

**`NodeJS`**

```javascript NodeJS
 api.Settlements.getValidations(settlement.SettlementId)
```

#### PUT Cancel a Settlement endpoint

To support the [PUT Cancel a Settlement](/api-reference/settlements/cancel-settlement) endpoint:

* Added `cancel` method to `Settlements`

**`NodeJS`**

```javascript NodeJS
api.Settlements.cancel(settlement.SettlementId)
```

#### Intent unfunded amounts and source wallet

* Added `SplitOriginWalletId` to `PayInIntentLineItem`, `PayInIntentSplitData`, `CreatePayIntentSplit`
* Added `UnfundedSellerAmount` to `PayInIntentLineItem`
* Added `UnfundedAmount` to `PayInIntentData`, `CreatePayInIntentAuthorization`

#### POST Create an Intent Refund

To support [POST Create an Intent Refund](/api-reference/intents/create-intent-refund):

* Added `Refund` and `Capture` to `PayInIntentData`
* Added `createPayInIntentRefund` method to `Payins`

**`NodeJS`**

```javascript NodeJS
 api.PayIns.createPayInIntentRefund(intent.Id, refundDto)
```

#### POST Reverse an Intent Refund

To support [POST Reverse an Intent Refund](/api-reference/intents/create-intent-refund):

* Added `reversePayInIntentRefund` method to `Payins`

**`NodeJS`**

```javascript NodeJS
api.PayIns.reversePayInIntentRefund(intent.Id, intent.Refund.Id, reverseDto)
```

#### POST Create an Intent Dispute

To support [POST Create an Intent Dispute](/api-reference/intents/create-intent-refund):

* Added `Dispute` to `PayInIntent`
* Added `createPayInIntentDispute` method to `PayInApi`

**`NodeJS`**

```javascript NodeJS
api.PayIns.createPayInIntentDispute(intent.Id, intent.Capture.Id, disputeDto)
```

#### PUT Update an Intent Dispute

To support [PUT Update an Intent Dispute](/api-reference/intents/create-intent-dispute):

* Added `Decision` to `PayInIntent`
* Added `UpdatePayInIntentDisputeOutcome` interface
* Added `updatePayInIntentDisputeOutcome` method to `PayIns`

**`NodeJS`**

```javascript NodeJS
api.PayIns.updatePayInIntentDisputeOutcome(intent.Id, intent.Capture.Id, intent.Dispute.Id, dto)
```

## 1.65.0 - Jan 30, 2026

### Added

#### Support for new SCA status endpoint

The SDK now supports the new [GET View the SCA status of a User](/api-reference/users/view-user-sca-status) endpoint.

Added new method in lib/services/Users.js:

**`expandable`**

```js expandable
    /**
    * Get SCA status
    * @param {number}  userId  User identifier
    * @param {Function} callback    Callback function
    * @param {Object} options    Request options
    * @return {Object}        Request promise
    */
   getScaStatus: function(userId, callback, options) {
       options = this._api._getOptions(callback,
           options,
           {
               path: {
                   id: userId
               }
           });

       return this._api.method('users_get_sca_status', callback, options);
   }
```

Added lib/models/ScaStatus.js:

**`expandable`**

```js expandable
module.exports = EntityBase.extend({
   defaults: {
       UserStatus: null,
       IsEnrolled: null,
       LastEnrollmentDate: null,
       LastConsentCollectionDate: null,
       ConsentScope: null
   }
});
```

Updated test/services/Users.js:

**`expandable`**

```js expandable
    describe('Get Sca status', function() {
        const activeUserId = "user_m_01JKZW095BFB2TRQMCZ8GE7M8D";
        var scaStatus;

        before(function(done){
            api.Users.getScaStatus(activeUserId, function (data, response) {
                scaStatus = data;
                done();
            });
        });

        it('John should be the same', function(){
            expect(scaStatus).to.not.be.undefined;
            expect(scaStatus.IsEnrolled).to.be.true;
            expect(scaStatus.LastEnrollmentDate).to.not.be.undefined;
            expect(scaStatus.ConsentScope.ContactInformationUpdate).to.not.be.undefined;
        });
    });
```

Added corresponding typings in typings/models/user.d.ts:

**`expandable`**

```js expandable
interface ScaStatus {
       UserStatus: string;
       IsEnrolled: boolean;
       LastEnrollmentDate?: Timestamp;
       LastConsentCollectionDate?: Timestamp;
       ConsentScope?: ConsentScope;
   }

   interface ConsentScope {
       ContactInformationUpdate?: string;
       RecipientRegistration?: string;
       Transfer?: string;
       ViewAccountInformation?: string;
   }
```

Added corresponding typing in typings/services/Users.d.ts:

```js
   /**
    * Get SCA status
    * @param {string} userId User identifier
    * @param {Function} callback Callback function
    * @param {Object} options Request options
    * @return {Object} Request promise
    */
   getScaStatus: MethodOverload<string, user.ScaStatus>
```

#### RecipientId property on payouts

New `RecipientId` property added to payOut.d.ts.

#### New event types

Added new event types to typings/models/event.d.ts:

```js
    type EventType =
        | "SCA_CONTACT_INFORMATION_UPDATE_CONSENT_GIVEN"
        | "SCA_CONTACT_INFORMATION_UPDATE_CONSENT_REVOKED"
        | "SCA_TRANSFER_CONSENT_GIVEN"
        | "SCA_TRANSFER_CONSENT_REVOKED"
        | "SCA_RECIPIENT_REGISTRATION_CONSENT_GIVEN"
        | "SCA_RECIPIENT_REGISTRATION_CONSENT_REVOKED"
        | "SCA_VIEW_ACCOUNT_INFORMATION_CONSENT_GIVEN"
        | "SCA_VIEW_ACCOUNT_INFORMATION_CONSENT_REVOKED"
        | "SCA_EMAIL_VERIFIED"
        | "SCA_PHONE_NUMBER_VERIFIED"
```

## 1.64.0 - Nov 26, 2025

### Changed

* changed naming convention to mangopay4

## 1.62.2 - Nov 25, 2025

### Added

* Support for `ScaContext` on [POST Create a Recipient](/api-reference/recipients/create-recipient) for platforms taking action by [proxy with consent](/guides/sca/proxy-management) from the user ([API release note](/release-notes/api/2025-11-17))

## 1.62.1 - Oct 31, 2025

### Fixed

* Upgraded `form-data` library version
* Upgraded `axios` library version

## 1.62.0 - Oct 27, 2025

### Added

* New [POST Manage proxy consent for a User](/api-reference/users/manage-proxy-consent) endpoint to obtain and manage user consent via the hosted SCA experience (if proxy is activated). A proxy and user consent are now required to use the `USER_NOT_PRESENT` value for `ScaContext` ([API release note](/release-notes/api/2025-10-23))
* `ScaContext` request parameter newly added on all user POST and PUT endpoints, enabling the platform to request these actions with `USER_NOT_PRESENT` – provided the proxy is in place, activated, and the user has given consent ([API release note](/release-notes/api/2025-10-23#sca%3A-scacontext-request-parameter-on-user-endpoints))
* Support for the `Licensor` property on [GET View a Client](/api-reference/client/view-client)

### Changed

* `x-tenant-id` deprecated as no longer necessary for UK platforms; the parameter is ignored by Mangopay

## 1.61.0 - Oct 1, 2025

### Added

* [Verification of Payee (VOP)](/guides/vop/recipients-payouts) API response fields (`RecipientVerificationOfPayee` and sub-properties) on the endpoints [GET View a Recipient](/api-reference/recipients/view-recipient), [POST Create a Recipient](/api-reference/recipients/create-recipient), [POST Create a Payout](/api-reference/payouts/create-payout) ([API release note](/release-notes/api/2025-09-30))
* Support for the [POST Cancel an Intent](/api-reference/intents/cancel-intent) endpoint for [Echo](/guides/echo), Mangopay's solution for platforms working with another third-party PSP for funds acquisition
* Support for [POST Submit data for a PayPal PayIn](/api-reference/paypal/submit-data-paypal-payin) endpoint

## 1.60.4 - Sep 26, 2025

### Improved

* Method for building the OAuth token URL, fixing a potential issue introduced in 1.42.1

## 1.60.3 - Sep 23, 2025

### Added

* Support for `ProfilingAttemptReference` on all payment methods for Mangopay's Fraud Prevention solution
* Webhook event types for [Echo](/guides/echo), Mangopay's solution for third-party PSP integrations: `INTENT_AUTHORIZED`,`INTENT_CAPTURED`,`INTENT_REFUNDED`,`INTENT_REFUND_REVERSED`,`INTENT_DISPUTE_CREATED`,`INTENT_DISPUTE_DEFENDED`,`INTENT_DISPUTE_WON`,`INTENT_DISPUTE_LOST`,`INTENT_SETTLED_NOT_PAID`,`INTENT_PAID`,`SPLIT_CREATED`,`SPLIT_PENDING_FUNDS_RECEPTION`,`SPLIT_AVAILABLE`,`SPLIT_REJECTED`,`SPLIT_REVERSED`
* Support for `VirtualAccountPurpose` on Banking Alias object

### Improved

* Added missing `OptionsHelper` in TypeScript
* Add new library for unit tests

## 1.60.2 - Sep 2, 2025

### Added

* `XK` to country ISO values

### Fixed

* Typescript function definition
* Typings for `BankingAliases.getAll`
* Missing `CreationDate` with `toJSON()`
* Missing fields in `CreateTransferRefund`
* Missing `getBlockStatus` definition
* Tests

## 1.60.1 - Aug 14, 2025

### Added

* Types for user `getRegulatory` function
* Support for [POST Create a Quoted Conversion between Client Wallets](/api-reference/conversions/create-quoted-conversion-client-wallets) and [POST Create an Instant Conversion between Client Wallets](/api-reference/conversions/create-instant-conversion-client-wallets)
* Missing `MarketRateDate` param to FX `conversionRate`
* Support for [POST Create a Bank Wire to the Repudiation Wallet](/api-reference/dispute-settlement/create-bank-wire-payin-to-repudiation-wallet)
* Missing keys for legacy Wallets Report

## 1.60.0 - Aug 7, 2025

### Added

Support for new Splits endpoints for Echo ([API release note](/release-notes/api/2025-07-16)):

* [PUT Update an Intent Split](/api-reference/intents/update-intent-split)
* [POST Execute an Intent Split](/api-reference/intents/execute-intent-split)
* [POST Reverse an Intent Split](/api-reference/intents/reverse-intent-split)
* [GET View an Intent Split](/api-reference/intents/view-intent-split)

New `ReportTypes` for Echo ([API release note](/release-notes/api/2025-08-06)):

* `ECHO_INTENT`
* `ECHO_INTENT_ACTION`
* `ECHO_SETTLEMENT`
* `ECHO_SPLIT`

## 1.59.1 - Jul 28, 2025

### Added

* `Sku` parameter on LineItem, for [Klarna PayIns](/api-reference/klarna/create-klarna-payin)
* support for new endpoint [View supported banks for Pay by Bank](/api-reference/pay-by-bank/view-supported-banks-pay-by-bank), to enable presentation of banks to user before Pay by Bank payment request

## 1.59.0 - Jul 18, 2025

### Added

Endpoints for [Mangopay Echo](/guides/echo), a solution for platforms working with another third-party PSP for funds acquisition (including via the Mirakl Connector):

* [POST Create an Intent](/api-reference/intents/create-intent)
* [GET View an Intent](/api-reference/intents/view-intent)
* [POST Create a Capture for an Intent](/api-reference/intents/create-intent-capture)
* [POST Create a Settlement](/api-reference/settlements/create-settlement)
* [PUT Update a Settlement](/api-reference/settlements/update-settlement)
* [GET View a Settlement](/api-reference/settlements/view-settlement)
* [POST Create an Intent Split](/api-reference/intents/create-intent-split)

## 1.58.0 - Jul 3, 2025

### Added

* New endpoint [POST Create a Bizum PayIn](/api-reference/bizum/create-bizum-payin)
* New webhook event types for SCA enrollment ([API release note](/release-notes/api/2025-06-23)), note that these are triggered on enrollment not authentication:
  * `SCA_ENROLLMENT_SUCCEEDED`
  * `SCA_ENROLLMENT_FAILED`
  * `SCA_ENROLLMENT_EXPIRED`
* New webhook event types for `UserCategory` change ([API release note](/release-notes/api/2025-06-23)):
  * `USER_CATEGORY_UPDATED_TO_OWNER`
  * `USER_CATEGORY_UPDATED_TO_PAYER`
  * `USER_CATEGORY_UPDATED_TO_PLATFORM`
* Support for `PLATFORM` value to `UserCategory` enum

## 1.57.1 - Jun 17, 2025

### Added

* [US and CA virtual accounts](/release-notes/api/2025-06-12) for local pay-in collection

## 1.57.0 - Jun 10, 2025

### Added

Endpoints for [new Reporting Service](/release-notes/api/2025-06-05) feature:

* [POST Create a Report](/api-reference/reporting/create-report)
* [GET View a Report](/api-reference/reporting/view-report)
* [GET List all Reports](/api-reference/reporting/list-reports)

Webhook event types for new Reporting Service:

* `REPORT_GENERATED`
* `REPORT_FAILED`

Support for [GET List Disputes for a PayIn](/api-reference/disputes/list-disputes-payin) endpoint.

## 1.56.1 - Jun 6, 2025

### Added

* Support for `RecipientScope` query parameter on [GET List Recipients for a User](/api-reference/recipients/list-recipients-user)
* [POST Validate the format of User data](/api-reference/user-data-format/validate-user-data-format)

### Fixed

* `Status` enum value on Identity Verification object changed from `OUTDATED` to `OUT_OF_DATE`