Releases · Adyen/adyen-node-api-library

14 Jul 08:40

v28.0.0

188715c

Latest

What's Changed

This release brings significant improvements, new features, and few breaking changes to the Adyen Node API Library. It marks a major milestone in aligning the library more closely with Adyen’s OpenAPI specifications and improving the ✨ Developer Experience ✨

Find below what's new as well as a detailed summary of the Breaking Changes, and what you should do or consider.

Please review the Breaking Changes and update your integrations accordingly. For any questions, feel free to open an issue or consult our API Explorer.

🚀 Highlights

Enhanced OpenAPI Code Generation: Source code is now more idiomatic, flexible, and better aligned with Adyen's OpenAPI specifications.
Automated Webhook Handler Generation: Webhook handlers and models are now automatically generated and updated with each release.
Refined Package Structure: Several APIs have been moved to more specific packages for better discoverability and maintainability.
Improved Error Handling: Make the API Error object available, alongside the raw JSON
Revised Enum Values Deserialization: During the response deserialization unknown enums are ignored, instead of causing an error affecting the integrations

🛠 Breaking Changes

🔒 Honouring required attributes

Mandatory attributes are no longer marked as optional, but are expected to be provided. Although this is the correct implementation, it is a ‼️ breaking change (previously the library didn't do that) #1502

🔁 Order of query parameters

A few method signatures have been updated to add the required query parameters before all optional parameters, to avoid causing an error (invalid order of parameters) #1515

This change affects only:

Transfers API getAllTransactions: the required params createdSince an createdUntil are the first 2 parameters, before all others.
Transfers API getAllTransfers: the required params createdSince an createdUntil are the first 2 parameters, before all others.

🔍 Important Changes

📦 Service Class Refactoring

The following services have been moved to their own folder.
Service classes in the old location are deprecated and will be removed in a future release.

Note: There are no changes in functionality (the same code is now available in the new location), please update your code accordingly.

Old Location	New Location
`services.storedValueApi`	`services.storedvalue.storedValueApi`
`services.binLookupApi`	`services.binlookup.binLookupApi`
`services.balanceControlApi`	`services.balancecontrol.balanceControlApi`
`services.dataProtectionApi`	`services.dataprotection.dataProtectionApi`
`services.disputesApi`	`services.disputes.disputesApi`
`services.paymentsAppApi`	`services.paymentsapp.paymentsAppApi`
`services.posMobileApi`	`services.posmobile.posMobileApi`

🪝 Webhook Handling

Webhook handling is now modernized and streamlined:

Automation: Auto-generated handlers ensure that webhook events and models stay aligned with the changes in the OpenAPI specs
Deprecated: Former bankingWebhookHandler and managementWebhooksHandler classes are now deprecated
Recommended: Use instead the dedicated handler in the Webhook package (AcsWebhooks, ReportWebhooksHandler, ConfigurationWebhooks, TransferWebhooks, TransactionWebhooks, etc..)

 const configurationWebhooksHandler = new ConfigurationWebhooksHandler(jsonString);
 const accountHolderNotificationRequest = configurationWebhooksHandler.getAccountHolderNotificationRequest();

⚠️ Deprecation of TerminalManagementAPI

Support for the "classic" POS Terminal Management API has stopped. To automate assigning terminals, you must use Management API.

☘️ Improved Error Handling

The APIError model is readily available in the HttpClientException object when an API call fails. This eliminates the need for manual parsing of the response body by library users. #1509
The library exports the HttpClientException class, allowing to try-catch the Adyen API exceptions without importing directly from the specific path within the library. #1526

💎 New Features & Enhancements

Session Authentication API

Add support for Session Authentication API to create the sessions required for integrating Adyen Platform components (#1435)

BalancePlatform

New: BalancesApi service now supports BalanceWebhookSetting for managing Balance Webhook criteria.
New: BalancesApi service now supports AuthorizedCardUsersApi to manage (add, get, delete and update) authorized users to a given card
Other changes:
- In PaymentInstrumentsApi add methods createNetworkTokenActivationData and getNetworkTokenActivationData to create and retrieve network token activation data for a payment instrument.
In AdditionalBankIdentification add new enums auBsbCode and caRoutingNumber
In AccountHoldersApi.getTaxFormResponse add optional parameter legalEntityId
Add NetworkTokenRequestor to NetworkToken
Add dataMissing enum to VerificationError
Add walletProviderDeviceType in TransactionRuleRestrictions
Add enum INTEREST in TransferRoute.CategoryEnum

ACS Webhooks

In RelayedAuthenticationRequest add new attributes threeDSRequestorAppURL, environment, timestamp, type

Checkout

Add capturePspReference to PaymentRefundRequest
Add businessDayOnly to PixRecurring
In PaymentMethodRequest add attributes browserInfo, shopperEmail, shopperIP and telephoneNumber
In SessionResultResponse add attributes:
- payments to provide a list of all authorised payments done for this session
- reference to provide the unique reference in the original /sessions request
- additionalData to provide additional information about the payment

Configuration Webhooks

Add NetworkTokenRequestor to NetworkTokenNotificationDataV2
Add Wallet class to provide information about the wallet for which the network token is provisioned.

Transfers API

New attribute: executionDate in TransferData
Add class BankAccountV3AccountIdentification

Transfers Webhooks

New attribute: executionDate in TransferData
Add class BankAccountV3AccountIdentification

Webhooks

In NotificationRequestItem add missing event codes INFORMATION_SUPPLIED, DISPUTE_DEFENSE_PERIOD_ENDED, ISSUER_RESPONSE_TIMEFRAME_EXPIRED, ISSUER_COMMENTS #1506

Changes in this release:

OpenAPI Generator v7: Webhooks by @gcatanese in #1512
WIP Typescript OpenAPI Generator v7 by @gcatanese in #1505
ApiError: Improving error handling by @gcatanese in #1509
OpenAPI v7 Generation: Classic Payments, BalanceControl, Disputes, StoredValue by @gcatanese in #1510
Make non-native attributes nullable by @gcatanese in #1520
Fix: Set ApplicationName correctly when client is instantiated by @Kwok-he-Chu in #1503
Checkout: mark mandatory query parameters by @gcatanese in #1502
HMAC Troubleshooting: script to calculate KCV by @gcatanese in #1508
Terminal API new Event Types by @gcatanese in #1507
OpenAPI Generator v7: generate LEM/Configuration/Transfers APIs by @gcatanese in #1511
Optional query params and code format by @gcatanese in #1513
Format code (adding method overloading) by @gcatanese in #1514
Transfers API: method signature with required query parameters by @gcatanese in #1515
OpenGenerator v7: Generate Management API by @gcatanese in #1516
Code format cleanup by @gcatanese in #1517
Add unit tests for parsing unexpected fields/enums by @gcatanese in #1518
Add test to verify request payload by @gcatanese in #1522
Code generation: update services and models by @AdyenAutomationBot in #1523
Sonar handle exceptions by @gcatanese in #1524
Tests serializat...

Contributors

gcatanese, AdyenAutomationBot, and Kwok-he-Chu

Assets 2

03 Jul 14:08

gcatanese

patch-v27.0.01

1fb7f97

v27.0.1

Features 💎

Terminal API
- Add NetworkConnected and NetworkDisconnected events in #1519

Assets 2

14 May 17:21

AdyenAutomationBot

v27.0.0

78f079d

Adyen Node API Library v27.0.0

Breaking Changes 🛠

Checkout API
- Dotpay: Removed the DotpayDetails class and all related references in CheckoutPaymentMethod and test files. Direct support for Dotpay is deprecated
- Giropay: Removed the GiropayDetails class and all related references in CheckoutPaymentMethod and test files. Direct support for Giropay is deprecated
- Paysafecard (from PaymentDetails TypeEnum): Removed Paysafecard from the TypeEnum in the PaymentDetails model
Classic Payments API
- In ResponseAdditionalDataCommon the TokenizationStoreOperationTypeEnum.AlreadyStored has been removed, and replaced by TokenizationStoreOperationTypeEnum.AlreadyExisting
Management API
- Remove GiroPayInfo
- Remove enum PAYSHOP from PaymentMethodResponse

Features 💎

Checkout API
- Rakuten Pay: Add support for Rakuten Pay payment method - RakutenPayDetails
- Add support for Surcharge in paymentRequest
- Add Donation type field supporting the following values: roundup, fixedAmounts
- Add email and phone number fields to AdditionalDataCommon and AdditionalDataSubMerchant
- Add SubMerchantEmail and SubMerchantPhoneNumber fields to AdditionalDataCommon
- Add SubMerchantSubSellerSubSellerNrEmail and SubMerchantSubSellerSubSellerNrPhoneNumber fields to AdditionalDataSubMerchant
- Add RequestedTestAcquirerResponseCode to AdditionalDataCommon to facilitate testing scenarios for specific acquirer responses
- Add EnhancedSchemeData property to PaymentRequest and PaymentCaptureRequest
- Add EncryptedCard property to PaymentMethodToStore to allow storing encrypted card details.
- Add the FraudRiskLevel enum and property to ResponseAdditionalDataCommon to indicate the risk level of a payment (e.g. VeryLow, Low, Medium, High, and VeryHigh)
- Add Bonus enum member to the PlansEnum in CheckoutSessionInstallmentOption and Installments
BalancePlatform API
- Add Bic enum in BankIdentification
- Add Pending enum in CreateSweepConfigurationV2
- Add message field in InvalidField
- Add replacedById and replacementOfId attributes in PaymentInstrument and UpdatePaymentInstrument
- Add walletProviderAccountScore and walletProviderDeviceScore attributes in TransactionRuleRestrictions
- Add class USInstantPayoutAddressRequirement
Transfer API
- Added IssuingTransactionData with captureCycleId that provides the captureCycleId associated with transfer event
- Add enumChargebackRemainder in PlatformPayment.platformPaymentType
- Add attribute externalReason in TransferData
- Add enum Pending in TransferData.reason
- Add attribute scaOnApproval in TransferReview
Management API
- Add supportEmail field in AfterpayTouchInfo
- Add enum PAYMENTDESIGNATORCONTRACT in JCBInfo
- Add PayByBankPlaidInfo
- Add enum PAYBYBANK_PLAID in PaymentMethodResponse
- Add domainSuffix field in Profile model
- In SplitConfigurationRule add enums CHARGED, DEFERRED_DEBIT and PREPAID (#1457)
- Add enableGratuities in Standalone model

Add support for Balance Webhooks

Webhooks
- Add ISSUER_COMMENTS webhook event code by @nickcarenza in #1488
Configuration Webhooks
- Add replacedById to PaymentInstrument
AcsWebhooks
- Enum value has changed:
  - Before: OTP_SMS
  - After: PWD_OTP_PHONE_FL - OTP flow via SMS
- Enum value has changed:
  - Before: OOB
  - After: OOB_TRIGGER_FL - Out-of-band trigger flow
- New:
- Add PWD_OTP_EMAIL_FL - OTP flow via Email

Fixes ⛑️

Fix null value in User-Agent HTTP header by @gcatanese in #1496
Fix union types deserialization in Transfer webhooks by @mercury2269 in #1489

Other Changes 🖇️

NotificationRequestItem enums: Remove legacy by @gcatanese in #1497
Set default timeout on the HTTP client by @gcatanese in #1490
Introduced a new HMAC troubleshooting utility for signature validation debugging (#1487). The tool calculates the HMAC signature given the HMAC key and the payload:

cd tools/hmac
npm install 

node calculateHmacPayments.js 11223344D785FBAE710E7F943F307971BB61B21281C98C9129B3D4018A57B2EB payload.json

Check the README