on()

2026-04-17 09:24

This method allows you to listen for component events.

Note: This method is not applicable to Express Element.

Method signature

When calling this method, please use the following standard method signature format.

JavaScript

TypeScript

copy
on(event, callback)

Parameters

This method takes a configuration object as its parameter, which is used to specify the events to listen for and their corresponding handling logic. The detailed parameter descriptions are as follows:

Parameter	Data type	Required	Description
event	String	Yes	Event type, used to specify the event to listen for. The following events are supported: `paymentMethodChanged`: Payment method changes event. `billingAddressChanged`: Billing address data change event. Note: This is only available in Payment Element scenarios. Calling it in other business scenarios will trigger a console error: `Event "${event}" is not allowed.`
callback	Function	Yes	Event callback function, used to receive parameters when the event is triggered. The callback parameter structures vary depending on the event type, as shown below: `paymentMethodChanged` event: The callback function receives a payload parameter, which contains payment method change–related data. `billingAddressChanged` event: The callback function receives a payload parameter, which contains the latest billing address form data.

Parameter

Data type

Required

Description

event

String

Yes

Event type, used to specify the event to listen for. The following events are supported:

paymentMethodChanged: Payment method changes event.
billingAddressChanged: Billing address data change event.

Note: This is only available in Payment Element scenarios. Calling it in other business scenarios will trigger a console error: `Event "${event}" is not allowed.`

callback

Function

Yes

Event callback function, used to receive parameters when the event is triggered. The callback parameter structures vary depending on the event type, as shown below:

paymentMethodChanged event: The callback function receives a payload parameter, which contains payment method change–related data.
billingAddressChanged event: The callback function receives a payload parameter, which contains the latest billing address form data.

`paymentMethodChanged` (Payment method changes)

Triggered when the buyer switches the payment method. The payload is an object containing the payment method changes data:

Parameter	Data type	Required	Description
type	String	Yes	Payment method type. For specific values, refer to Enumeration values of payment methods or APO payment methods.
name	String	Yes	Payment method name.

`billingAddressChanged` (Billing address form changes)

Triggered when the buyer edits the billing address form data. The payload is an object that contains the form input results.

Parameter	Data type	Required	Description
sameAsShipping	Boolean	No	Indicate whether to check the sameAsShipping.
billingAddress	Object	No	Billing address.

billingAddress

Parameter	Data type	Required	Description
region	String	No	Two-letter country or region code compliant with the ISO 3166 Country Codes standard.
state	String	No	State, province, or region code consisting of two to three letters compliant with the ISO 3166-2standard.
city	String	No	City name.
address1	String	No	Address line 1.
address2	String	No	Address line 2.
zipCode	String	No	ZIP or postal code.
phoneNo	String	No	Buyer’s phone number in E.164 format.
name	Object	No	Buyer’s name.

name

Parameter	Data type	Required	Description
firstName	String	No	Buyer’s first name.
lastName	String	No	Buyer’s last name.
middleName	String	No	Buyer’s middle name (if any).

Return values

This method does not return any value. After it is called, the event listener is registered internally, and subsequent event triggers are handled by the callback function. There is no need to wait for or process any return result.