Getting startedRelease notesSDK

NodeJS SDK

Package: mangopay4-nodejs-sdk

2.0.0 - Jun 2, 2026

2.0.0 - Jun 2, 2026
Breaking change
  • Minimum Node.js version raised to 22
  • Dependency upgrades
Changed
  • Source repository no longer on GitHub
Fixed
  • Garbled comment in CardPreAuthorization

1.68.0 - Mar 30, 2026

1.68.0 - Mar 30, 2026
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, which is required for platforms taking SCA-triggering action under proxy:

  • 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

Note: The SDK requires TLS 1.2+ for TLS compliance, even for non-mTLS connections, in line with Mangopay’s security guidelines.

1.66.1 - Feb 23, 2026

Added

ChargeBearer body parameter on payouts

On POST Create a Payout, platforms can now request to pay all SWIFT fees using the OUR value of the new ChargeBearer property (API release note):

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

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

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

  • 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 endpoint to obtain an UploadUrl:

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

Caution - Breaking change

  • Replaced upload method in Settlements with generateUploadUrl:
NodeJS
1 api.Settlements.generateUploadUrl({FileName: "settlement_sample.csv"})

Caution - Breaking change

  • Replaced update method in Settlements with: generateNewUploadUrl
NodeJS
1  api.Settlements.generateNewUploadUrl(settlement.SettlementId, {FileName: "settlement_sample_updated.csv"})

Added

GET validations for a Settlement endpoint

To support the GET View validations for a Settlement endpoint:

  • Added SettlementValidation, SettlementValidationFooter, SettlementValidationLine interfaces
  • Added getValidations method to Settlements
NodeJS
1 api.Settlements.getValidations(settlement.SettlementId)

PUT Cancel a Settlement endpoint

To support the PUT Cancel a Settlement endpoint:

  • Added cancel method to Settlements
NodeJS
1api.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:

  • Added Refund and Capture to PayInIntentData
  • Added createPayInIntentRefund method to Payins
NodeJS
1 api.PayIns.createPayInIntentRefund(intent.Id, refundDto)

POST Reverse an Intent Refund

To support POST Reverse an Intent Refund:

  • Added reversePayInIntentRefund method to Payins
NodeJS
1api.PayIns.reversePayInIntentRefund(intent.Id, intent.Refund.Id, reverseDto)

POST Create an Intent Dispute

To support POST Create an Intent Dispute:

  • Added Dispute to PayInIntent
  • Added createPayInIntentDispute method to PayInApi
NodeJS
1api.PayIns.createPayInIntentDispute(intent.Id, intent.Capture.Id, disputeDto)

PUT Update an Intent Dispute

To support PUT Update an Intent Dispute:

  • Added Decision to PayInIntent
  • Added UpdatePayInIntentDisputeOutcome interface
  • Added updatePayInIntentDisputeOutcome method to PayIns
NodeJS
1api.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 endpoint.

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

expandable
1    /**
2    * Get SCA status
3    * @param {number}  userId  User identifier
4    * @param {Function} callback    Callback function
5    * @param {Object} options    Request options
6    * @return {Object}        Request promise
7    */
8   getScaStatus: function(userId, callback, options) {
9       options = this._api._getOptions(callback,
10           options,
11           {
12               path: {
13                   id: userId
14               }
15           });
16
17       return this._api.method('users_get_sca_status', callback, options);
18   }

Added lib/models/ScaStatus.js:

expandable
1module.exports = EntityBase.extend({
2   defaults: {
3       UserStatus: null,
4       IsEnrolled: null,
5       LastEnrollmentDate: null,
6       LastConsentCollectionDate: null,
7       ConsentScope: null
8   }
9});

Updated test/services/Users.js:

expandable
1    describe('Get Sca status', function() {
2        const activeUserId = "user_m_01JKZW095BFB2TRQMCZ8GE7M8D";
3        var scaStatus;
4
5        before(function(done){
6            api.Users.getScaStatus(activeUserId, function (data, response) {
7                scaStatus = data;
8                done();
9            });
10        });
11
12        it('John should be the same', function(){
13            expect(scaStatus).to.not.be.undefined;
14            expect(scaStatus.IsEnrolled).to.be.true;
15            expect(scaStatus.LastEnrollmentDate).to.not.be.undefined;
16            expect(scaStatus.ConsentScope.ContactInformationUpdate).to.not.be.undefined;
17        });
18    });

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

expandable
1interface ScaStatus {
2       UserStatus: string;
3       IsEnrolled: boolean;
4       LastEnrollmentDate?: Timestamp;
5       LastConsentCollectionDate?: Timestamp;
6       ConsentScope?: ConsentScope;
7   }
8
9   interface ConsentScope {
10       ContactInformationUpdate?: string;
11       RecipientRegistration?: string;
12       Transfer?: string;
13       ViewAccountInformation?: string;
14   }

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

1   /**
2    * Get SCA status
3    * @param {string} userId User identifier
4    * @param {Function} callback Callback function
5    * @param {Object} options Request options
6    * @return {Object} Request promise
7    */
8   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:

1    type EventType =
2        | "SCA_CONTACT_INFORMATION_UPDATE_CONSENT_GIVEN"
3        | "SCA_CONTACT_INFORMATION_UPDATE_CONSENT_REVOKED"
4        | "SCA_TRANSFER_CONSENT_GIVEN"
5        | "SCA_TRANSFER_CONSENT_REVOKED"
6        | "SCA_RECIPIENT_REGISTRATION_CONSENT_GIVEN"
7        | "SCA_RECIPIENT_REGISTRATION_CONSENT_REVOKED"
8        | "SCA_VIEW_ACCOUNT_INFORMATION_CONSENT_GIVEN"
9        | "SCA_VIEW_ACCOUNT_INFORMATION_CONSENT_REVOKED"
10        | "SCA_EMAIL_VERIFIED"
11        | "SCA_PHONE_NUMBER_VERIFIED"

1.64.0 - Nov 26, 2025

Changed

  • changed naming convention to mangopay4

1.62.2 - Nov 25, 2025

Added

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 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)
  • 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)
  • Support for the Licensor property on GET View a 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

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, 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

1.60.0 - Aug 7, 2025

Added

Support for new Splits endpoints for Echo (API release note):

New ReportTypes for Echo (API release note):

  • ECHO_INTENT
  • ECHO_INTENT_ACTION
  • ECHO_SETTLEMENT
  • ECHO_SPLIT

1.59.1 - Jul 28, 2025

Added

1.59.0 - Jul 18, 2025

Added

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

1.58.0 - Jul 3, 2025

Added

  • New endpoint POST Create a Bizum PayIn
  • New webhook event types for SCA enrollment (API release note), 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):
    • 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

1.57.0 - Jun 10, 2025

Added

Endpoints for new Reporting Service feature:

Webhook event types for new Reporting Service:

  • REPORT_GENERATED
  • REPORT_FAILED

Support for GET List Disputes for a PayIn endpoint.

1.56.1 - Jun 6, 2025

Added

Fixed

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