@adyen/api-library 28.0.0

Adyen Node API Library v28.0.0

on Node.js NPM

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.

🪝 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.

💎 New Features & Enhancements

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

• New:

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

Transfers Webhooks

• Added IssuingTransactionData with captureCycleId that provides the captureCycleId associated with transfer event
• New enum: ChargebackRemainder in PlatformPayment.platformPaymentType
• New attribute: executionDate in TransferData

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

Fixes ⛑️

• Fix: Set ApplicationName correctly when client is instantiated by @Kwok-he-Chu in #1503

Other Changes 🖇️

• Checkout: mark mandatory query parameters by @gcatanese in #1502
• NotificationRequestItem: add missing event codes by @gcatanese in #1506
• 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 serialization additional data by @gcatanese in #1525
• Export HttpClientException by @gcatanese in #1526
• Release v28.0.0 by @AdyenAutomationBot in #1504

New Contributors

• @Kwok-he-Chu made their first contribution in #1503

Full Changelog: v27.0.0...v28.0.0