> ## Documentation Index
> Fetch the complete documentation index at: https://developers.ingopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Events

> All iFrame SDK event types, payloads, and error codes for the Ingo Instant Payments plugin.

Register event listeners using `webPlugin.addEventListener()` to track the recipient's progress through the iFrame and respond to outcomes. Every event payload includes `session_identifier`, `tracer_token`, and `event_name`. Additional fields are event-specific and documented below.

```js theme={null}
webPlugin.addEventListener(IngoInstantPayments.EVENTS.TOKEN_SUCCESS, function(data) {
  // handle event
});
```

***

## Base Events

These events represent the primary outcomes of the account capture flow. At minimum, your integration should handle `TOKEN_SUCCESS`, `TERMINAL_FAILURE`, and `MAX_VERIFICATION_ATTEMPTS_EXCEEDED`.

### `TOKEN_SUCCESS`

Fired when the recipient has successfully tokenized an account. This is the terminal success event — no further interaction is needed for this session.

**Additional payload fields:**

| Field                    | Description                                                           |
| ------------------------ | --------------------------------------------------------------------- |
| `customer_account_token` | The token to use with IngoPay process calls for future disbursements. |
| `funding_destination`    | The funding destination that was tokenized.                           |

```json theme={null}
{
  "session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
  "tracer_token": "12345_07834f31-9ff3-48ff-a7e7-072242331688",
  "customer_account_token": "0bef3f2d-3e17-4320-a865-39ffb6b96c2e",
  "event_name": "iip.webplugin.token_success",
  "funding_destination": "debit"
}
```

***

### `FUNDING_CANCELED`

Fired when the recipient cancels on the confirmation page or elects to choose a different funding option.

**Additional payload fields:**

| Field                 | Description                                       |
| --------------------- | ------------------------------------------------- |
| `funding_destination` | The funding destination that was being tokenized. |

```json theme={null}
{
  "session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
  "tracer_token": "12345_db4781bc-aff5-430b-9451-7821972a7079",
  "event_name": "iip.webplugin.funding_canceled",
  "funding_destination": "credit"
}
```

***

### `TERMINAL_FAILURE`

Fired when the plugin reaches a terminal failure page due to account verification. The session remains active and can be retried — re-initialize the session using idempotency and mount again with the desired funding destination.

**Additional payload fields:**

| Field                 | Description                                                          |
| --------------------- | -------------------------------------------------------------------- |
| `funding_destination` | The funding destination being tokenized.                             |
| `error`               | The error code that caused the failure. See error code tables below. |

```json theme={null}
{
  "session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
  "tracer_token": "12345_396ba7d7-303a-4b05-a6d5-952f7acc2719",
  "event_name": "iip.webplugin.terminal_failure",
  "funding_destination": "credit",
  "error": "4"
}
```

***

### `TERMINAL_FAILURE_ACKNOWLEDGED`

Fired when the recipient has acknowledged the terminal failure page and pressed the continue button. The session remains active.

**Additional payload fields:** same as `TERMINAL_FAILURE`.

```json theme={null}
{
  "session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
  "tracer_token": "12345_0df67d09-5670-45de-a87b-ba54bd58f6ed",
  "event_name": "iip.webplugin.terminal_failure_acknowledged",
  "funding_destination": "credit",
  "error": "4"
}
```

***

### `MAX_VERIFICATION_ATTEMPTS_EXCEEDED`

Fired when the recipient exceeds the maximum allowed verification failures. The session is **permanently terminated** and cannot be reused. A new session must be created.

```json theme={null}
{
  "session_identifier": "54f59bcb-040d-40d8-928d-39895b4ad455",
  "tracer_token": "12345_f63b668e-bb3e-4e70-9df1-1215b1fe7dc8",
  "event_name": "iip.webplugin.max_verification_attempts_exceeded"
}
```

***

## BillPay Events

These events fire only when `FUNDING_DESTINATIONS.BILLPAY` is mounted.

### `ACCOUNT_COULD_NOT_BE_VERIFIED`

Fired when a recipient does not have their card present during BillPay account verification.

```json theme={null}
{
  "session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
  "tracer_token": "12345_db4781bc-aff5-430b-9451-7821972a7079",
  "event_name": "iip.webplugin.account_could_not_be_verified",
  "funding_destination": "billpay"
}
```

### `BILLPAY_SEARCH_NO_MATCH_FOUND`

Fired when the recipient exceeds the allowed number of no-result biller searches. The session is **permanently terminated**. A new session must be created.

```json theme={null}
{
  "session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
  "tracer_token": "12345_db4781bc-aff5-430b-9451-7821972a7079",
  "event_name": "iip.webplugin.billpay_search_no_match_found",
  "funding_destination": "billpay"
}
```

***

## Informative Events

These events provide visibility into the recipient's progress through the iFrame but do not represent outcomes.

### `PAGE_LOAD`

Fired each time a new page loads within the iFrame as the recipient navigates through the flow.

**Additional payload fields:**

| Field          | Description                                                        |
| -------------- | ------------------------------------------------------------------ |
| `content.page` | Name of the current plugin page. See plugin pages reference below. |

```json theme={null}
{
  "session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
  "tracer_token": "12345_01467df7-d00b-42a6-a824-f620fd93ef51",
  "content": { "page": "DebitFunding" },
  "event_name": "iip.webplugin.page_load"
}
```

<Accordion title="Plugin pages reference">
  **Account Verification**

  | Page                                 | Description                                      |
  | ------------------------------------ | ------------------------------------------------ |
  | `MAX_VERIFICATION_ATTEMPTS_EXCEEDED` | Max failure exceeded page.                       |
  | `ACCOUNT_COULD_NOT_BE_VERIFIED`      | BillPay "I don't have my card" termination page. |

  **ACH Funding**

  | Page                           | Description                                              |
  | ------------------------------ | -------------------------------------------------------- |
  | `ACH_FUNDING`                  | Bank account entry page.                                 |
  | `ACH_FUNDING_CONFIRM`          | Bank account confirmation page.                          |
  | `ACH_FUNDING_TERMINAL_RVDM`    | Terminal — Recipient Verification Data Matching failure. |
  | `ACH_FUNDING_TERMINAL_ANV`     | Terminal — Account Number Validation failure.            |
  | `ACH_FUNDING_TERMINAL_NAV`     | Terminal — Name on Account Validation failure.           |
  | `ACH_FUNDING_TERMINAL_RNV`     | Terminal — Routing Number Validation failure.            |
  | `ACH_FUNDING_TERMINAL_UNKNOWN` | Terminal — Unknown failure.                              |

  **BillPay Funding**

  | Page                               | Description                              |
  | ---------------------------------- | ---------------------------------------- |
  | `BILLPAY_FUNDING`                  | Biller search page.                      |
  | `BILLPAY_FUNDING_CONFIRM`          | Biller account confirmation page.        |
  | `BILLPAY_FUNDING_SEARCH_RESULTS`   | Biller search results page.              |
  | `BILLPAY_FUNDING_NO_MATCH_FOUND`   | Biller search no-match termination page. |
  | `BILLPAY_FUNDING_TERMINAL_AV`      | Terminal — Account verification failure. |
  | `BILLPAY_FUNDING_TERMINAL_UNKNOWN` | Terminal — Unknown failure.              |

  **Credit Card Funding**

  | Page                              | Description                                      |
  | --------------------------------- | ------------------------------------------------ |
  | `CREDIT_FUNDING`                  | Credit card entry page.                          |
  | `CREDIT_FUNDING_CONFIRM`          | Credit card confirmation page.                   |
  | `CREDIT_FUNDING_TERMINAL_RVDM`    | Terminal — RVDM failure.                         |
  | `CREDIT_FUNDING_TERMINAL_AVS`     | Terminal — Address Verification Service failure. |
  | `CREDIT_FUNDING_TERMINAL_CNS`     | Terminal — Card Not Supported.                   |
  | `CREDIT_FUNDING_TERMINAL_CVV`     | Terminal — CVV failure.                          |
  | `CREDIT_FUNDING_TERMINAL_CD`      | Terminal — Check Digit failure.                  |
  | `CREDIT_FUNDING_TERMINAL_UNKNOWN` | Terminal — Unknown failure.                      |

  **Debit Card Funding**

  | Page                             | Description                     |
  | -------------------------------- | ------------------------------- |
  | `DEBIT_FUNDING`                  | Debit card entry page.          |
  | `DEBIT_FUNDING_CONFIRM`          | Debit card confirmation page.   |
  | `DEBIT_FUNDING_TERMINAL_RVDM`    | Terminal — RVDM failure.        |
  | `DEBIT_FUNDING_TERMINAL_AVS`     | Terminal — AVS failure.         |
  | `DEBIT_FUNDING_TERMINAL_CNS`     | Terminal — Card Not Supported.  |
  | `DEBIT_FUNDING_TERMINAL_CVV`     | Terminal — CVV failure.         |
  | `DEBIT_FUNDING_TERMINAL_CD`      | Terminal — Check Digit failure. |
  | `DEBIT_FUNDING_TERMINAL_UNKNOWN` | Terminal — Unknown failure.     |

  **PayPal Funding**

  | Page                              | Description                              |
  | --------------------------------- | ---------------------------------------- |
  | `PAYPAL_FUNDING`                  | PayPal entry page.                       |
  | `PAYPAL_FUNDING_CONFIRM`          | PayPal confirmation page.                |
  | `PAYPAL_FUNDING_TERMINAL_LOGIN`   | Terminal — Login failure.                |
  | `PAYPAL_FUNDING_TERMINAL_CONSENT` | Terminal — User consent rejection.       |
  | `PAYPAL_FUNDING_TERMINAL_AV`      | Terminal — Account verification failure. |
  | `PAYPAL_FUNDING_TERMINAL_UNKNOWN` | Terminal — Unknown failure.              |

  **Session Management**

  | Page                   | Description                                                   |
  | ---------------------- | ------------------------------------------------------------- |
  | `SESSION_UNAUTHORIZED` | Authorized URL has expired or funding destination is invalid. |
  | `SESSION_INVALID`      | Session has been canceled, terminated, or expired.            |
  | `SESSION_COMPLETED`    | Session has already been completed.                           |
  | `SESSION_TIMEOUT`      | User's web session expired due to inactivity.                 |
</Accordion>

***

### `PLUGIN_RESIZE`

Fired when the dimensions of the plugin contents change.

**Additional payload fields:**

| Field            | Description                       |
| ---------------- | --------------------------------- |
| `content.width`  | Current content width in pixels.  |
| `content.height` | Current content height in pixels. |

```json theme={null}
{
  "session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
  "tracer_token": "12345_bf5f2aa7-2b25-494d-8cb7-1bc1773caa4c",
  "content": { "width": 800, "height": 600 },
  "event_name": "iip.webplugin.plugin_resize"
}
```

***

### `UNSUPPORTED_BROWSER_DETECTED`

Fired when the recipient's browser is not supported by the SDK.

**Additional payload fields:**

| Field                | Description               |
| -------------------- | ------------------------- |
| `browser.name`       | Browser name.             |
| `browser.version`    | Browser version.          |
| `browser.os`         | Operating system name.    |
| `browser.os_version` | Operating system version. |

```json theme={null}
{
  "session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
  "tracer_token": "",
  "event_name": "iip.webplugin.unsupported_browser_detected",
  "browser": {
    "name": "Internet Explorer",
    "version": "9.0",
    "os": "Windows",
    "os_version": "7"
  }
}
```

***

## Warning / Error Events

### `PLUGIN_ERROR`

Fired when an unhandled exception occurs inside the plugin.

**Additional payload fields:**

| Field           | Description                               |
| --------------- | ----------------------------------------- |
| `error.message` | Description of the unhandled exception.   |
| `error.source`  | Source file where the exception occurred. |
| `error.lineno`  | Line number of the exception.             |
| `error.colno`   | Column number of the exception.           |
| `error.err`     | Exception name.                           |

```json theme={null}
{
  "session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
  "tracer_token": "",
  "event_name": "iip.webplugin.plugin_error",
  "error": {
    "message": "Uncaught error",
    "source": "...",
    "lineno": 1,
    "colno": 1,
    "err": "Error message"
  }
}
```

***

### `SESSION_ERROR`

Fired when the plugin reaches a session error page. The `content.status_code` identifies the specific error.

**Additional payload fields:**

| Field                 | Description                                |
| --------------------- | ------------------------------------------ |
| `content.page`        | Session error page name.                   |
| `content.status_code` | Numeric status code identifying the error. |

**Status codes:**

| Code    | Meaning                                             |
| ------- | --------------------------------------------------- |
| `13404` | Transaction session has expired.                    |
| `13405` | Transaction has been canceled or terminated.        |
| `13412` | Unauthorized — invalid or expired `authorized_url`. |
| `13413` | Transaction session has been completed.             |
| `13414` | User's web session expired due to inactivity.       |

```json theme={null}
{
  "session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
  "tracer_token": "",
  "event_name": "iip.webplugin.session_error",
  "content": {
    "page": "SessionExpired",
    "status_code": 13414
  }
}
```

***

## Error codes by payment type

These codes appear in the `error` field of `TERMINAL_FAILURE` and `TERMINAL_FAILURE_ACKNOWLEDGED` events.

### ACH (`IngoInstantPayments.ERROR_CODES.ACH`)

| Code | Constant  | Meaning                               |
| ---- | --------- | ------------------------------------- |
| `0`  | `UNKNOWN` | Unknown error.                        |
| `1`  | `ANV`     | Account Number Validation.            |
| `2`  | `NAV`     | Name on Account Validation.           |
| `3`  | `RNV`     | Routing Number Validation.            |
| `4`  | `RVDM`    | Recipient Verification Data Matching. |

### Card — Credit & Debit (`IngoInstantPayments.ERROR_CODES.CARD`)

| Code | Constant  | Meaning                               |
| ---- | --------- | ------------------------------------- |
| `0`  | `UNKNOWN` | Unknown error.                        |
| `1`  | `AVS`     | Address Verification Service.         |
| `2`  | `CNS`     | Card Not Supported.                   |
| `4`  | `RVDM`    | Recipient Verification Data Matching. |
| `5`  | `CVV`     | Card Verification Value.              |
| `6`  | `CD`      | Check Digit.                          |

### BillPay (`IngoInstantPayments.ERROR_CODES.BILLPAY`)

| Code | Constant  | Meaning               |
| ---- | --------- | --------------------- |
| `0`  | `UNKNOWN` | Unknown error.        |
| `1`  | `AV`      | Account Verification. |

### PayPal (`IngoInstantPayments.ERROR_CODES.PAYPAL`)

| Code | Constant  | Meaning                   |
| ---- | --------- | ------------------------- |
| `0`  | `UNKNOWN` | Unknown error.            |
| `1`  | `LOGIN`   | Login Failure.            |
| `2`  | `CONSENT` | PayPal Consent Rejection. |
| `3`  | `AV`      | Account Verification.     |