SDK Events

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.

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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

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

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.

`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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

Overview

Session Management

SDK Reference

Webhooks

Base Events

`TOKEN_SUCCESS`

`FUNDING_CANCELED`

`TERMINAL_FAILURE`

`TERMINAL_FAILURE_ACKNOWLEDGED`

`MAX_VERIFICATION_ATTEMPTS_EXCEEDED`

BillPay Events

`ACCOUNT_COULD_NOT_BE_VERIFIED`

`BILLPAY_SEARCH_NO_MATCH_FOUND`

Informative Events

`PAGE_LOAD`

`PLUGIN_RESIZE`

`UNSUPPORTED_BROWSER_DETECTED`

Warning / Error Events

`PLUGIN_ERROR`

`SESSION_ERROR`

Error codes by payment type

ACH (`IngoInstantPayments.ERROR_CODES.ACH`)

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

BillPay (`IngoInstantPayments.ERROR_CODES.BILLPAY`)

PayPal (`IngoInstantPayments.ERROR_CODES.PAYPAL`)

​Base Events

​TOKEN_SUCCESS

​FUNDING_CANCELED

​TERMINAL_FAILURE

​TERMINAL_FAILURE_ACKNOWLEDGED

​MAX_VERIFICATION_ATTEMPTS_EXCEEDED

​BillPay Events

​ACCOUNT_COULD_NOT_BE_VERIFIED

​BILLPAY_SEARCH_NO_MATCH_FOUND

​Informative Events

​PAGE_LOAD

​PLUGIN_RESIZE

​UNSUPPORTED_BROWSER_DETECTED

​Warning / Error Events

​PLUGIN_ERROR

​SESSION_ERROR

​Error codes by payment type

​ACH (IngoInstantPayments.ERROR_CODES.ACH)

​Card — Credit & Debit (IngoInstantPayments.ERROR_CODES.CARD)

​BillPay (IngoInstantPayments.ERROR_CODES.BILLPAY)

​PayPal (IngoInstantPayments.ERROR_CODES.PAYPAL)

Base Events

`TOKEN_SUCCESS`

`FUNDING_CANCELED`

`TERMINAL_FAILURE`

`TERMINAL_FAILURE_ACKNOWLEDGED`

`MAX_VERIFICATION_ATTEMPTS_EXCEEDED`

BillPay Events

`ACCOUNT_COULD_NOT_BE_VERIFIED`

`BILLPAY_SEARCH_NO_MATCH_FOUND`

Informative Events

`PAGE_LOAD`

`PLUGIN_RESIZE`

`UNSUPPORTED_BROWSER_DETECTED`

Warning / Error Events

`PLUGIN_ERROR`

`SESSION_ERROR`

Error codes by payment type

ACH (`IngoInstantPayments.ERROR_CODES.ACH`)

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

BillPay (`IngoInstantPayments.ERROR_CODES.BILLPAY`)

PayPal (`IngoInstantPayments.ERROR_CODES.PAYPAL`)