Skip to main content
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:
FieldDescription
customer_account_tokenThe token to use with IngoPay process calls for future disbursements.
funding_destinationThe 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:
FieldDescription
funding_destinationThe 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:
FieldDescription
funding_destinationThe funding destination being tokenized.
errorThe 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:
FieldDescription
content.pageName 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"
}
Account Verification
PageDescription
MAX_VERIFICATION_ATTEMPTS_EXCEEDEDMax failure exceeded page.
ACCOUNT_COULD_NOT_BE_VERIFIEDBillPay “I don’t have my card” termination page.
ACH Funding
PageDescription
ACH_FUNDINGBank account entry page.
ACH_FUNDING_CONFIRMBank account confirmation page.
ACH_FUNDING_TERMINAL_RVDMTerminal — Recipient Verification Data Matching failure.
ACH_FUNDING_TERMINAL_ANVTerminal — Account Number Validation failure.
ACH_FUNDING_TERMINAL_NAVTerminal — Name on Account Validation failure.
ACH_FUNDING_TERMINAL_RNVTerminal — Routing Number Validation failure.
ACH_FUNDING_TERMINAL_UNKNOWNTerminal — Unknown failure.
BillPay Funding
PageDescription
BILLPAY_FUNDINGBiller search page.
BILLPAY_FUNDING_CONFIRMBiller account confirmation page.
BILLPAY_FUNDING_SEARCH_RESULTSBiller search results page.
BILLPAY_FUNDING_NO_MATCH_FOUNDBiller search no-match termination page.
BILLPAY_FUNDING_TERMINAL_AVTerminal — Account verification failure.
BILLPAY_FUNDING_TERMINAL_UNKNOWNTerminal — Unknown failure.
Credit Card Funding
PageDescription
CREDIT_FUNDINGCredit card entry page.
CREDIT_FUNDING_CONFIRMCredit card confirmation page.
CREDIT_FUNDING_TERMINAL_RVDMTerminal — RVDM failure.
CREDIT_FUNDING_TERMINAL_AVSTerminal — Address Verification Service failure.
CREDIT_FUNDING_TERMINAL_CNSTerminal — Card Not Supported.
CREDIT_FUNDING_TERMINAL_CVVTerminal — CVV failure.
CREDIT_FUNDING_TERMINAL_CDTerminal — Check Digit failure.
CREDIT_FUNDING_TERMINAL_UNKNOWNTerminal — Unknown failure.
Debit Card Funding
PageDescription
DEBIT_FUNDINGDebit card entry page.
DEBIT_FUNDING_CONFIRMDebit card confirmation page.
DEBIT_FUNDING_TERMINAL_RVDMTerminal — RVDM failure.
DEBIT_FUNDING_TERMINAL_AVSTerminal — AVS failure.
DEBIT_FUNDING_TERMINAL_CNSTerminal — Card Not Supported.
DEBIT_FUNDING_TERMINAL_CVVTerminal — CVV failure.
DEBIT_FUNDING_TERMINAL_CDTerminal — Check Digit failure.
DEBIT_FUNDING_TERMINAL_UNKNOWNTerminal — Unknown failure.
PayPal Funding
PageDescription
PAYPAL_FUNDINGPayPal entry page.
PAYPAL_FUNDING_CONFIRMPayPal confirmation page.
PAYPAL_FUNDING_TERMINAL_LOGINTerminal — Login failure.
PAYPAL_FUNDING_TERMINAL_CONSENTTerminal — User consent rejection.
PAYPAL_FUNDING_TERMINAL_AVTerminal — Account verification failure.
PAYPAL_FUNDING_TERMINAL_UNKNOWNTerminal — Unknown failure.
Session Management
PageDescription
SESSION_UNAUTHORIZEDAuthorized URL has expired or funding destination is invalid.
SESSION_INVALIDSession has been canceled, terminated, or expired.
SESSION_COMPLETEDSession has already been completed.
SESSION_TIMEOUTUser’s web session expired due to inactivity.

​
PLUGIN_RESIZE

Fired when the dimensions of the plugin contents change. Additional payload fields:
FieldDescription
content.widthCurrent content width in pixels.
content.heightCurrent 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:
FieldDescription
browser.nameBrowser name.
browser.versionBrowser version.
browser.osOperating system name.
browser.os_versionOperating 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:
FieldDescription
error.messageDescription of the unhandled exception.
error.sourceSource file where the exception occurred.
error.linenoLine number of the exception.
error.colnoColumn number of the exception.
error.errException 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:
FieldDescription
content.pageSession error page name.
content.status_codeNumeric status code identifying the error.
Status codes:
CodeMeaning
13404Transaction session has expired.
13405Transaction has been canceled or terminated.
13412Unauthorized — invalid or expired authorized_url.
13413Transaction session has been completed.
13414User’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)

CodeConstantMeaning
0UNKNOWNUnknown error.
1ANVAccount Number Validation.
2NAVName on Account Validation.
3RNVRouting Number Validation.
4RVDMRecipient Verification Data Matching.

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

CodeConstantMeaning
0UNKNOWNUnknown error.
1AVSAddress Verification Service.
2CNSCard Not Supported.
4RVDMRecipient Verification Data Matching.
5CVVCard Verification Value.
6CDCheck Digit.

​
BillPay (IngoInstantPayments.ERROR_CODES.BILLPAY)

CodeConstantMeaning
0UNKNOWNUnknown error.
1AVAccount Verification.

​
PayPal (IngoInstantPayments.ERROR_CODES.PAYPAL)

CodeConstantMeaning
0UNKNOWNUnknown error.
1LOGINLogin Failure.
2CONSENTPayPal Consent Rejection.
3AVAccount Verification.