[jakubjasinsky]

Summary

processout_dynamic_checkout_apple_pay_new_session and processout_dynamic_checkout_apple_pay_session_error are documented but never fired: Dynamic Checkout passed the dispatchers as callbacks to applePay.newSession(), which has always ignored them.

Changes

• ApplePay gets two optional handlers, onmerchantvalidated and onmerchantvalidationerror (same pattern as oncancel / onpaymentauthorizedPostprocess); Dynamic Checkout uses them to dispatch the events
• apple_pay_new_session fires once the merchant is validated; apple_pay_session_error fires when merchant validation fails or the ApplePaySession constructor throws
• apple_pay_session_error payload is now error_type / error_message, as documented, instead of the spread raw exception
• Tests cover the new handlers and pin the existing newSession behaviour
• Version bump to 1.9.21

Impact

• No change for merchants calling applePay.newSession() directly: its callbacks are still accepted and still never called (onsuccess is now optional in the type)
• Merchants listening to the two events will see them fire for the first time
• A merchant validation failure now emits apple_pay_session_error followed by the existing payment_error, so listeners on both get both

Additional Context

• Making newSession() honour its callbacks was rejected as a backward-compatibility risk: integrations passing tokenization-style handlers there would have them run at merchant validation
• Not verified in Safari with a real Apple Pay sheet

[Copilot]

🟢 Approval recommended

No active review issues are identified for the Apple Pay session-event changes.

No open issues 🎉

What changed in this PR

This PR enables the documented Apple Pay session events in Dynamic Checkout while preserving the existing behavior of callbacks passed to newSession().

Changes:

• Adds merchant-validation handlers and connects them to session success and error events.
• Standardizes session error payloads to error_type and error_message, including constructor failures.
• Adds regression tests and bumps the version to 1.9.21.

File	Description
test/​support/​loadNamespace.ts	Adds an Apple Pay loader with an injectable browser session.
test/​processout/​applepay.test.ts	Tests validation handlers and existing callback behavior.
test/​dynamic-checkout/​wallet-events.test.ts	Tests session event dispatch and error payloads.
src/​processout/​applepay.ts	Adds validation handlers and shared validation-error handling.
src/​processout/​applepay-wrapper.ts	Makes the unused success callback optional and documents compatibility.
src/​dynamic-checkout/​utils/​events.ts	Normalizes Apple Pay session error payloads.
src/​dynamic-checkout/​clients/​apple-pay.ts	Wires validation events and reports constructor failures.
package.json	Bumps the version to 1.9.21.

_{Review effort: Balanced}

[tomasz-pazdziurek-cko]

Does it make sense to add @deprecated as well?

As far as I understand, we cannot just remove them, because this constructor function may be used by the external callers directly (i.e. merchants)?