# element.on()

> Use the element.on() or element.once() method to register event listeners for the Element instance.

  Use the `element.on()` or `element.once()` method to register event listeners for the Element instance. Depending on your business needs, perform one of the following actions: - If continuous listening is needed, call `element.on()` to register continuous listening, where the callback function is executed each time the event is triggered
- If you want the event to be handled only once, call `element.once()` to register one-time listening, where the listener is automatically canceled after the event is triggered once.

 After calling the method, when the corresponding event is triggered internally in the Element instance, the callback function will be executed.

 > **[INFO]** **Note**: Event names and specific data structures may vary slightly depending on product form and integration scenario. The following lists only typical usage.

## **Method signature** {#zThz7}

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

<!-- TabGroup -->

**Tab: JavaScript**

```javascript
element.on(event, callback)
element.once(event, callback)
```

**Tab: TypeScript**

```typescript
element.on(event: string, callback: (data: EventDataType) => void): offFunction
element.once(event: string, callback: (data: EventDataType) => void): void
```

<!-- /TabGroup -->

## Parameters {#zgIHY}

 | **Parameter** | **Data type** | **Required** | **Description** |
| --- | --- | --- | --- |
| *event* | String | Yes | The event name, such as   `['error'](#Ln5QF)`  . |
| *callback* | Function | Yes | Event callback function. The parameter is the data object corresponding to the event. |

### `error`   event {#Ln5QF}

 Used to monitor the web page loaded by the SDK, which contains the following parameters:

 | **Parameter** | **Data type** | **Required** | **Description** |
| --- | --- | --- | --- |
| *code* | String | Yes | Error code. For specific information, refer to the   [Error codes](#Wiybs)  . |
| *message* | String | Yes | Error message, describing the specific content of the error. |
| *type* | String | No | Error type, used to categorize the error. |
| *detail* | Any | No | Error details, which may include debugging information. |

## Return value {#rFd5T}

 - `element.on()`  : Returns an   `offFunction`  . Calling this function will unregister the event listener.
- `element.once()`  : No return value. The listener is automatically unregistered after the event is triggered once.

## Error codes {#Wiybs}

 The following are the relevant error codes captured when calling the   `element.on()`   method.

<!-- TabGroup -->

**Tab: element.mount() related**

| **Code** | **Description** | **Further action** |
| --- | --- | --- |
| `SUCCESS` | Success. | No further action. |
| `UNKNOWN_EXCEPTION` | The method call failed for an unknown reason. | Prompt the buyer to confirm the status of the related methods: - `[element.mount()](https://docs.antom.com/ac/sdks/web_element-mount.md)`  ​   : If rendering still fails after frontend retries, please contact Antom technical support. - `[antom.confirmCardSetup()](https://docs.antom.com/ac/sdks/web_antom-confirmCardSetup.md)`  ​   : Try polling the payment result from the server. |
| `PROCESS_FAIL` | A general business failure occurred. | Contact Antom Technical Support to investigate the issue. |
| `RISK_REJECT` | The transaction cannot be further processed because of risk control. If the user has already paid for the transaction, the transaction will be refunded. | Prompt the buyer for risk control. |
| `INQUIRY_PAYMENT_SESSION_FAILED` | Payment session expired. | The order has been closed out of time. Use the new     *paymentRequestId*     to reinitiate payment. |
| `UNKNOWN_ERROR` | Unknown exception. | Prompt the buyer to handle form errors themselves. |
| `API_GATEWAY_TIMEOUT` | The gateway timed out. | Prompt the buyer gateway timeout. |
| `API_TIMEOUT` | Interface response timed out. | Prompt the buyer interface response timeout. |
| `API_GATEWAY_ERROR` | The gateway is abnormal. | Prompt the buyer to handle form errors themselves. |
| `MOUNT_TIMEOUT` | The mount operation timed out. | It is recommended that buyers refresh the page and try again. |
| `MOUNT_MISSING_CONTAINER` | No container element was passed in. | Ensure that the container element is passed correctly. |
| `MOUNT_IFRAME_LOAD_ERROR` | Failed to load the iframe. | It is recommended that buyers refresh the page and try again. |
| `MOUNT_NOT_SUPPORT` | The current status does not support mounting. | Avoid multiple mounting, or destroy the instance before mounting. |
| `MOUNT_INITIAL_FAILED` | Mount initialization failed. | It is recommended that buyers refresh the page and try again. |
| `MISSING_PAYMENT_METHOD` | The rendering template has not been issued. | Contact Antom Technical Support to investigate the issue. |
| `USER_CLOSE_VAULTING` | The buyer closed the half-floating layer for card binding. | Prompt the buyer according to the business needs, or guide the buyer to rebind the card. |

**Tab: antom.createElement() related**

| **Code** | **Description** | **Further action** |
| --- | --- | --- |
| `NOT_SUPPORT_ELEMENT` | An unsupported element type has been created. | Create a supported Element. |
| `SESSION_DATA_INVALID` | Invalid     *sessionData*    . | Check whether the correct     *sessionData*     is being used. |
| `ELEMENT_INIT_FAILED` | Element initialization failed. | Contact Antom Technical Support to investigate the issue. |
| `GENERATE_ELEMENT_KEY_FAILED` | Element unique identifier generation failed. | Contact Antom Technical Support to investigate the issue. |
| `CANNOT_CREATE_SAME_ELEMENT_TWICE` | Two identical elements were created simultaneously. | Do not create two identical elements. |

**Tab: antom.confirmCardSetup() related**

| **Code** | **Description** | **Further action** |
| --- | --- | --- |
| `SUCCESS` | Success. | No further action. |
| `UNKNOWN_EXCEPTION` | The method call failed for an unknown reason. | Prompt the buyer to confirm the status of the related methods: - `[element.mount()](https://docs.antom.com/ac/sdks/web_element-mount.md)`  ​   : If rendering still fails after frontend retries, please contact Antom technical support. - `[antom.confirmCardSetup()](https://docs.antom.com/ac/sdks/web_antom-confirmCardSetup.md)`  ​   : Try polling the payment result from the server. |
| `PAYMENT_IN_PROCESS` | The payment is being processed. | Prompt the buyer to confirm the status of the related methods: - `[element.mount()](https://docs.antom.com/ac/sdks/web_element-mount.md)`  ​   : If rendering still fails after frontend retries, please contact Antom technical support. - `[antom.confirmCardSetup()](https://docs.antom.com/ac/sdks/web_antom-confirmCardSetup.md)`  : Try polling the payment result from the server. |
| `USER_BALANCE_NOT_ENOUGH` | Payment could not be completed due to insufficient buyer balance for the corresponding payment method. | Prompt the buyer that the balance is insufficient |
| `REPEAT_REQ_REJECT` | Repeat application. | Contact Antom Technical Support to investigate the issue. |
| `ASSET_ORDER_NOT_EXIST` | Order does not exist. | Contact Antom Technical Support to investigate the issue. |
| `PROCESS_FAIL` | A general business failure occurred. | Contact Antom Technical Support to investigate the issue. |
| `RISK_REJECT` | The transaction cannot be further processed because of risk control. If the user has already paid for the transaction, the transaction will be refunded. | Prompt the buyer for risk control. |
| `INQUIRY_PAYMENT_SESSION_FAILED` | Payment session has expired. | The order has timed out and been closed. Please initiate the payment again using a new     *paymentRequestId*    . |
| `ACCESS_DENIED` | Access denied. | Contact Antom Technical Support to investigate the issue. |
| `CARD_EXPIRED` | The bank card used for the transaction has expired. | No action is required from the merchant. |
| `INVALID_EXPIRY_DATE_FORMAT` | The     *expiryYear*     or     *expiryMonth*     is not in the correct format. | No action is required from the merchant. |
| `INVALID_EXPIRATION_DATE` | Invalid value for     *paymentMethod.paymentMethodMetaData.expiryYear*     or     *paymentMethod.paymentMethodMetaData.expiryDate*    . | No action is required from the merchant. |
| `INVALID_CVV` | The card CVV used for the transaction is invalid. | No action is required from the merchant. |
| `INVALID_CARD_NUMBER` | The bank card number used for the transaction is invalid. | No action is required from the merchant. |
| `SELECTED_CARD_BRAND_NOT_AVAILABLE` | The bank card brand designated by the merchant for the transaction is not supported. | Check the card brand by yourself. |
| `CARD_NOT_SUPPORTED` | The bank card used for the transaction is not supported. | No action is required from the merchant. |
| `CARD_BIN_QUERY_ERROR` | The bank card number used for the transaction is invalid. | No action is required from the merchant. |
| `VERIFICATION_IN_PROCESS` | Authentication is in process. | The   `PROCESSING`   status indicates that the authentication result has not been found after SDK polling. It is recommended to poll the payment result from the server. |
| `INVALID_AMOUNT` | Invalid amount | Contact Antom Technical Support to investigate the issue. |
| `CURRENCY_NOT_SUPPORT` | Currency is not supported. | Contact Antom Technical Support to investigate the issue. |
| `NO_PAY_OPTIONS` | No payment options are available. | Contact Antom Technical Support to investigate the issue. |
| `ORDER_IS_CLOSED` | The request you initiated has the same paymentRequestId as the closed transaction. | The order has timed out and been closed. Please initiate the payment again using a new     *paymentRequestId*    . |
| `PARAM_ILLEGAL` | A required parameter is missing or an illegal parameter exists. For example, a non-numeric input, an invalid date, or an argument of the wrong length and type. | Contact Antom Technical Support to investigate the issue. |
| `FRAUD_REJECT` | Due to the risk control, the transaction cannot be further processed. If the buyer has paid for the transaction, the transaction will be refunded. | If the buyer does not receive a refund within two weeks, contact Antom Technical Support to investigate the issue. |
| `AUTHENTICATION_FAIL` | Access denied. | Contact Antom Technical Support to investigate the issue. |
| `PAYMENT_METHOD_SYSTEM_ERROR` | Due to the risk control, the transaction cannot be further processed. If the buyer has paid for the transaction, the transaction will be refunded. | If the buyer does not receive a refund within two weeks, contact Antom Technical Support to troubleshoot the issue. |
| `VERIFICATION_AMOUNT_EXCEED_LIMIT` | Verify amount exceeds limit | Contact Antom Technical Support to investigate the issue. |
| `DO_NOT_HONOR` | Payment was refused by the issuing bank. | Prompt the buyer. |
| `UNKNOWN_ERROR` | Unknown exception. | Prompt the buyer to resolve form errors on their own. |
| `API_GATEWAY_TIMEOUT` | The gateway timed out. | Prompt the buyer gateway timeout. |
| `API_TIMEOUT` | Interface response timed out. | Prompt the buyer interface response timeout. |
| `API_GATEWAY_ERROR` | The gateway is abnormal. | Prompt the buyer to handle form errors themselves. |
| `VALIDATION_FAILED` | Form validation failed upon submission. | Prompt the merchant to modify the form and try again once it meets the requirements. |
| `INQUIRY_RESULT_TIMEOUT` | Query card binding result timed out. | Prompt the merchant to try again. |
| `MISSING_SUCCESS_REDIRECT_URL` | The redirect URL is missing upon successful redirection. | Contact Antom Technical Support to investigate the issue. |
| `MISSING_3D_REDIRECT_URL` | The 3D redirect link is missing. | Contact Antom Technical Support to investigate the issue. |
| `NOT_SUPPORT_SUBMIT` | This element does not support submission. | Contact Antom Technical Support to investigate the issue. |
| `INVALID_MODAL_URL` | Invalid modal url. | Contact Antom Technical Support to investigate the issue. |
| `INVALID_REDIRECT_URL` | Invalid redict url. | Contact Antom Technical Support to investigate the issue. |
| `DDC_UPLOAD_PARAM_ILLEGAL` | 3DE DDC error, incorrect parameters for DDC upload. | Contact Antom Technical Support to investigate the issue. |
| `DDC_UPLOAD_DATA_FAILED` | 3DE DDC error, channel page issue when submitting the FORM. | Contact Antom Technical Support to investigate the issue. |
| `DDC_QUERY_ID_MISSING` | 3DE DDC exception, ddcquery results do not meet requirements, no ID. | Contact Antom Technical Support to investigate the issue. |
| `DDC_QUERY_INFO_MISSING` | 3DE DDC exception, ddcquery results do not meet requirements, no ddcInf found. | Contact Antom Technical Support to investigate the issue. |
| `DDC_QUERY_INFO_UUID_MISSING` | 3DE DDC exception, missing required parameter ddcSubmit. | Contact Antom Technical Support to investigate the issue. |
| `DDC_PARAMETERS_INVALID` | 3DE DDC error, missing required parameters for 3DE. | Contact Antom Technical Support to investigate the issue. |
| `DDC_INQUIRY_3D_REDIRECT_URL_PARAMS_MISSING` | 3DE DDC error, missing necessary parameters for 3DE link query. | Contact Antom Technical Support to investigate the issue. |
| `DDC_QUERY_PAYMENT_REDIRECT_URL_TIMEOUT` | 3DE DDC error, ddc query redirection link timed out. | Contact Antom Technical Support to investigate the issue. |

<!-- /TabGroup -->

## Best practices {#VxKax}

 - Event name case rules: Please strictly pass in the event name as defined in the documentation or SDK.
- Multiple registrations: Calling   `element.on()`   multiple times for the same event will register multiple listeners, all of which will be triggered in the order they were registered. If no longer needed, please manage them according to business needs or cancel listening through other APIs.
- Destruction timing: After calling   `[element.destroy()](https://docs.antom.com/ac/sdks/web_element-destroy.md)`   or   `[element.unmount()](https://docs.antom.com/ac/sdks/web_element-unmount.md)`  , the event listeners for the corresponding Element will no longer be effective.