5.7.0

Release 5.7.0 (#472)

This release adds comprehensive support for Cash App Pay and enhanced customer information to the Payment Setups API, including updates to the API documentation and integration tests. The main changes include detailed JSDoc documentation for the new fields, support for customer device and identification fields, and new integration tests to ensure these features work as expected.

Cash App Pay and Customer Support Enhancements:

• Expanded the JSDoc documentation in payment-setups.js to describe the new payment_methods.cashapp object, including its request and response fields, and the new customer object fields (device, id, country, tax_number, etc.). This covers all endpoints: create, update, get, and confirm. [1] [2] [3] [4]
• Standardized documentation for existing fields by replacing dashes with colons for consistency (e.g., billing_descriptor: ...). [1] [2] [3]

Integration Tests:

• Added new integration tests in payment-setups-it.js to verify that customer device fields, customer identifiers, and Cash App Pay payment methods are correctly handled and echoed by the API. These tests also check the correct handling of the Cash App Pay initialization and status fields.

These changes ensure that the Payment Setups API now fully supports Cash App Pay and richer customer data, with clear documentation and robust test coverage.

5.6.0

Release 5.6.0 (#469)

This release significantly improves the documentation and test coverage for the Platforms API integration, with a special focus on onboarding sub-entities and uploading identity documents. The changes clarify how to use the API, especially regarding the handling of representative documents, and enhance tests to ensure correct behavior for file uploads and document submission.

Documentation improvements:

• Expanded and clarified JSDoc comments for PlatformFiles and Subentity classes, detailing required fields, API endpoints, and the handling of representative and top-level documents, including strictness and validation differences. [1] [2] [3] [4] [5] [6]

Test coverage enhancements:

• Added comprehensive tests for representative documents (including identity verification, proof of address, proof of registration, and certified authorised signatory) in onboarding and updating sub-entities, ensuring the SDK sends the correct structure to the API unchanged.
• Added a test to verify that the correct purpose values are sent in multipart file uploads for representative documents.

Consistency and correctness:

• Updated test cases to use the correct purpose value (identity_verification instead of identification) for file uploads, aligning with API requirements. [1] [2] [3]

These changes ensure developers have clear guidance on how to use the API and confidence that the SDK handles documents and file uploads as required by the platform.

5.5.0

Release/5.5.0 - Airline and accommodation sub-tree model alignment (#468)

This release updates the documentation and test cases for airline and accommodation data objects across multiple payment API endpoints, clarifying the differences in their accepted shapes, especially regarding the passenger field and address formats. The changes also improve test data to match the updated API field names and expected structures.

API Documentation and Behavior Clarifications:

Added detailed documentation for airline_data and accommodation_data fields in all payment-related endpoints (Payments, HostedPayments, PaymentLinks, PaymentSessions, PaymentContexts), specifying the required and optional fields, and clarifying which endpoints accept a single passenger object vs. an array. This includes a summary table of endpoint behaviors and advice for defensive coding when reading responses. [[1]](https://github.com/checkout/checkout-sdk-node/pull/465/files#diff-76578f44aeabef26fcd3c9e30dd28b350638ccfd14e2f8e027903d4543dc103bR81-R126) [[2]](https://github.com/checkout/checkout-sdk-node/pull/465/files#diff-76578f44aeabef26fcd3c9e30dd28b350638ccfd14e2f8e027903d4543dc103bR168-R172) [[3]](https://github.com/checkout/checkout-sdk-node/pull/465/files#diff-76578f44aeabef26fcd3c9e30dd28b350638ccfd14e2f8e027903d4543dc103bR208-R228) [[4]](https://github.com/checkout/checkout-sdk-node/pull/465/files#diff-85bd78abffa389dbea5f6766f8828567611980703de2f9612cff55e545639e5dR31-R48) [[5]](https://github.com/checkout/checkout-sdk-node/pull/465/files#diff-4a03b92adc23934e550253d4e4f0462248d9229860dd84b42cf71d576b563857R32-R49) [[6]](https://github.com/checkout/checkout-sdk-node/pull/465/files#diff-2b4d77715704a0b6567e52f52d77a970cb22da3119595db73cb218a99ef42aa1R35-R51) [[7]](https://github.com/checkout/checkout-sdk-node/pull/465/files#diff-2b4d77715704a0b6567e52f52d77a970cb22da3119595db73cb218a99ef42aa1R121-R127) [[8]](https://github.com/checkout/checkout-sdk-node/pull/465/files#diff-1805c66253fb18216ac51ceef961007303a3338e76e7e987860351d65ef40f7dR22-R44) [[9]](https://github.com/checkout/checkout-sdk-node/pull/465/files#diff-1805c66253fb18216ac51ceef961007303a3338e76e7e987860351d65ef40f7dR74-R85)

For PaymentContexts, explicitly documented that the stop_over_code field in flight_leg_details should not be sent, as it is rejected by the API, and clarified the difference in the AccommodationData schema compared to other endpoints.

Test Case Updates:

Updated test data in payment-setups-unit.js to use the correct field names (address_line1 instead of address_line_1), to use ISO country codes, and to match the updated array/object structures for airline and accommodation data. [[1]](https://github.com/checkout/checkout-sdk-node/pull/465/files#diff-ddab7c1168be8fa8283ceb4fda260cbec9c09656f8b53953f5d5e75796362dd2L467-R467) [[2]](https://github.com/checkout/checkout-sdk-node/pull/465/files#diff-ddab7c1168be8fa8283ceb4fda260cbec9c09656f8b53953f5d5e75796362dd2L484-R485) [[3]](https://github.com/checkout/checkout-sdk-node/pull/465/files#diff-ddab7c1168be8fa8283ceb4fda260cbec9c09656f8b53953f5d5e75796362dd2L516-R529) [[4]](https://github.com/checkout/checkout-sdk-node/pull/465/files#diff-ddab7c1168be8fa8283ceb4fda260cbec9c09656f8b53953f5d5e75796362dd2L655-R656) [[5]](https://github.com/checkout/checkout-sdk-node/pull/465/files#diff-ddab7c1168be8fa8283ceb4fda260cbec9c09656f8b53953f5d5e75796362dd2L672-R674) [[6]](https://github.com/checkout/checkout-sdk-node/pull/465/files#diff-ddab7c1168be8fa8283ceb4fda260cbec9c09656f8b53953f5d5e75796362dd2L704-R718)

Schema and Field Description Improvements:

Improved inline documentation for flight_leg_details in PaymentSetups to clarify field names, expected formats, and historical inconsistencies in SDKs.

These changes ensure developers are aware of endpoint-specific requirements and quirks, reducing integration errors and making the codebase more maintainable.

5.4.0

Release 5.4.0 (#462)

Note: small version number bump to align all other SDKs functionality minor version

⚠️ Breaking changes (see at the bottom)

This release adds support for pagination and asset retrieval in various identity verification APIs, and improves card update functionality with optional encrypted credential headers. The most significant changes are the introduction of paginated query parameters for listing attempts, new endpoints for retrieving attempt assets, and the ability to request encrypted card credentials via custom headers.

Identity Verification APIs

• Added optional pagination parameters (skip, limit) to all listAttempts methods for identity, ID document, address document, and face authentication verifications, and updated the Identities wrapper to support these parameters. [1] [2] [3] [4] [5] [6] [7] [8]
• Introduced new methods getAttemptAssets for ID document and address document verifications, allowing retrieval of uploaded document images for a specific attempt, with pagination support. These are also exposed in the Identities wrapper. [1] [2] [3] [4]
• Refactored query parameter handling by introducing a buildQueryParams utility to properly append query strings only when needed, avoiding unnecessary trailing question marks.

Issuing/Card APIs

• Enhanced the updateCard method to accept optional HTTP headers, enabling clients to request encrypted CVV values by setting return-encrypted-cvv and Encryption-Key headers. Updated documentation accordingly and propagated the change to the Issuing wrapper. [1] [2]

Other Improvements

• Changed the return value of getPDFReport in identity verifications to return a JSON object with a pre-signed PDF URL, instead of a raw CSV buffer, aligning with the updated API response.

⚠️ Breaking changes

Kind	Change
return type	identityVerifications.getPDFReport and identities.getIdentityVerificationPDFReport now resolve to the parsed JSON body carrying pdf_report, instead of a Buffer. The method previously requested text/csv and Buffer-wrapped a response the API sends as application/json, so pdf_report was unreachable
types	Promise -> Promise on the three getPDFReport declarations and the three aggregate delegates. For the address document and ID document variants the implementation always returned JSON, so those two are declaration corrections with no runtime change

Note: nothing else is breaking. The new params and headers arguments are trailing and optional in both the JavaScript and the type declarations.

5.2.1

Release 5.2.1 (#458)

This release adds a comprehensive set of constants for all OAuth 2.0 scopes supported by the Checkout.com API, making it easier and safer to specify scopes without hardcoding strings. It also introduces documentation, usage examples, and unit tests for these constants, and updates the SDK version to reflect the new feature.

New OAuth Scopes Constants:

• Added OAuthScopes export in src/oauth-scopes.js, providing all documented and operational OAuth 2.0 scopes as constants, alphabetically ordered and frozen to prevent modification.
• Updated src/index.js to export OAuthScopes for use in client code.

Documentation and Usage Improvements:

• Extended the README.md with a new section explaining how to use the OAuthScopes constants and how TypeScript users can type their scope lists.

Testing and Reliability:

• Added a new test suite in test/oauth-scopes/oauth-scopes-unit.js to verify that all scope constants are correct, unique, alphabetically ordered, and immutable.
• Updated test/issuing/issuing-common.js to use the new OAuthScopes constants instead of hardcoded scope strings, and removed references to retired/invalid scopes.

Versioning:

• Bumped the package version to 5.2.0 in package.json to reflect the addition of the new feature.

5.2.0

Release 5.2.0 (#456)

This release adds support for retrieving top-up bank instructions for sub-accounts (currency accounts) via a new method in the Balances API, including configuration changes and comprehensive unit tests. It also documents a new request field in payment sessions. The main focus is ensuring the correct URL is used for the new endpoint, which does not follow the existing /balances path convention.

Key changes include:

Balances API Enhancements:

• Added a new retrieveTopUpInstructions method to the Balances class, allowing retrieval of bank details and payment references needed to top up a sub-account. This method uses a new configuration property to target the correct base URL for the endpoint.
• Updated the configuration (src/config.js and src/special-urls.js) to introduce balancesHostUrl, distinguishing it from the standard balancesUrl, so endpoints not under /balances are correctly addressed. [1] [2]

Testing:

• Added a new unit test suite (test/balances/balances-topup-unit.js) covering successful retrievals (including different bank details scenarios) and error handling for authentication and not found errors.

Documentation:

• Updated JSDoc comments for the new retrieveTopUpInstructions method to describe its parameters, response shape, and usage notes.
• Documented the new amount_allocations field in the payment sessions API.

Minor Refactoring:

• Changed a let to const for queryParams in the retrieve method of Balances for code consistency.

5.1.0

Release 5.1.0 (#453)

This release adds full support for Bacs Direct Debit to the SDK, including API client, documentation, endpoint registration, and integration tests. It also expands and clarifies documentation for bank instrument creation, retrieval, updating, and payment flows, especially for Bacs, SEPA, and ACH. Finally, it enhances the method for retrieving bank account field requirements with new filtering options.

Bacs Direct Debit Support:

• Added a new Bacs class (src/api/apm-specific/bacs.js) to support sending Bacs Direct Debit pre-notifications via the /apms/bacs/notifications endpoint. This includes detailed request/response documentation and error handling.
• Registered the Bacs endpoint in the SDK factory (src/endpoints-factory.js), main index (src/index.js), and updated the README to document access via cko.bacs. [1] [2] [3]
• Added integration tests for Bacs pre-notification, including positive and negative cases (test/apm-specific/bacs-it.js).

Bank Instrument Documentation Improvements:

• Expanded and clarified JSDoc comments for instrument creation, retrieval, and updating in src/api/instruments/instruments.js, with detailed field requirements and response shapes for Bacs, SEPA, and ACH variants. [1] [2] [3]

Bank Account Field Formatting Enhancements:

• Enhanced getBankAccountFieldFormatting to accept optional filters (accountHolderType and paymentNetwork), supporting both camelCase and hyphenated parameter names.

Payments API Documentation:

• Updated src/api/payments/payments.js documentation to clarify how to use Bacs and SEPA sources for payments, including required fields and API quirks.

5.0.0

Release 5.0.0 (#451)

• The merchant-specific subdomain option is now required. Set it, or pass useLegacyDomain to keep using the shared checkout.com hosts.
• An invalid subdomain now throws instead of being silently ignored, including on the exported EnvironmentSubdomain class.
• Document optional amount on payment voids to support partial voids.
• Document the ISV (SaaS seller) payout schedule fields balance_minimum, carry_forward_enabled and payment_instrument_id.

4.1.0

Release 4.1.0 (#446)

Release 4.1.0 bundles three changes: the Forward secrets path fix (#443, INT-1666), the new Address Document Verification endpoints (#444, INT-1665) and the challenge indicator documentation alignment (#445, INT-1667).

Forward secrets path fix (behaviour change)

Swagger 2026-07-20 completed the rename of the Forward secrets endpoints. Requests now go to the Forward host root, without the /forward prefix:

• Collection endpoints (create, list) moved from /forward/secrets to /secrets.
• Item endpoints (PATCH, DELETE) moved from /forward/secrets/{name} to /secrets/{name}.
• src/config.js keeps a single Forward host root (FORWARD_SANDBOX_URL / FORWARD_LIVE_URL) with no trailing slash, and ForwardClient appends the forward and secrets path segments explicitly, matching every other SDK. Forward request URLs themselves are unchanged.
• Unit tests updated accordingly. (src/api/forward/forward.js, src/config.js, test/forward/forward-unit.js)

Anyone calling the secrets methods will now hit the new paths, so this is worth calling out in the release notes.

Address Document Verification (Adv) endpoints

Implements the Adv family from swagger 2026-07-16: POST/GET /address-document-verifications, anonymize, attempts (create, list, get) and pdf-report.

• New src/api/identities/address-document-verifications.js, wired into the identities client. (src/api/identities/identities.js)
• TypeScript definitions added. (types/dist/api/identities/address-document-verifications.d.ts, types/dist/api/identities/identities.d.ts)
• Unit tests under test/identities/address-document-verifications/.

Challenge indicator documentation alignment

Clarifies the allowed values of 3ds.challenge_indicator per endpoint. No runtime behaviour changes here, only JSDoc plus a new test.

• Documented in hosted-payments.js, payments-links.js, payment-sessions.js and payments.js that the field accepts only the four standard values (no_preference, no_challenge_requested, challenge_requested, challenge_requested_mandate), and that exemption values are not accepted on these endpoints.
• Documented in sessions.js that challenge_indicator uniquely accepts all nine values, including exemption requests, and explained the fallback behaviour when an exemption cannot be applied.
• Added test/sessions/challenge-indicator.js covering the accepted value sets.

4.0.0

Release 4.0.0 (#442)

GENERAL SECURITY UPDATE

This release updates several dependencies in the package.json file to their latest versions and introduces an overrides section to address specific sub-dependency versions, improving security and compatibility.

Dependency updates:

• Updated axios to ^1.18.0 and form-data to ^4.0.6 to incorporate the latest features and security fixes.
• Updated @babel/core to ^7.29.6 and uuid to ^13.0.1 to ensure compatibility with newer tooling and bug fixes. [1] [2]

Dependency management improvements:

• Added an overrides section to explicitly specify versions for several sub-dependencies (serialize-javascript, follow-redirects, picomatch, flatted, js-yaml, and @babel/plugin-transform-modules-systemjs), helping to mitigate potential security vulnerabilities and maintain consistent builds.