¶ iFrame Interaction Event Descriptions
There are a number of javascript callback functions that can be registered while invoking the plugin.
Use of the callback functions will allow you to have more information about the customer experience while a consumer is entering account data into the IngoPay iFrame. Additional details regarding each of these events are provided in the sections below.
webPlugin.addEventListener(IngoInstantPayments.EVENTS.PAGE_LOAD, function(data) {
console.log(data.content.page); // “CreditFunding”
});
¶ Base Events
¶ TOKEN_SUCCESS
This event is triggered when a funding token has been generated and confirmed by the user.
Additional data properties included are:
- customer_account_token – The funding destination token used for processing payments
- funding_destination – The funding destination requested to be tokenized
In a nominal use case, this will be the final event in the plugin UX, whereas a customer_account_token has been successfully created for use in subsequent PayAPI process requests.
{
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: "credit"
}
¶ Example TOKEN_SUCCESS PlugIn Event Flows
¶ FUNDING_CANCELED
This event is triggered when a user cancels or elects to choose another funding option on the confirmation page.
Additional data properties included are:
- funding_destination – The funding destination requested to be 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"
}
¶ Example FUNDING_CANCELED PlugIn Event Flow
¶ TERMINAL_FAILURE
This event is triggered when the plugin reaches a terminal failure page due to account verification. The session will remain active and can be re-attempted by re-initializing the session, and mounting the plugin with the desired funding destination.
Additional data properties included are:
- funding_destination – The funding destination requested to be tokenized (see: IngoInstantPayments.FUNDING_DESTINATIONS)
- error – The account verification error that caused the terminal failure (see: IngoInstantPayments.ERROR_CODES)
{
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"
}
IngoInstantPayments.ERROR_CODES.ACH
A list of potential error codes that may occur during ACH tokenization.
Available options are:
- UNKNOWN - An unknown error has occurred (0)
- ANV - Account Number Validation (1)
- NAV - Name on Account Validation (2)
- RNV - Routing Number Validation (3)
- RVDM - Recipient Verification Data Matching (4)
IngoInstantPayments.ERROR_CODES.BILLPAY
A list of potential error codes that may occur during PayPal tokenization.
Available options are:
- UNKNOWN - An unknown error has occurred (0)
- AV - Account Verification (1)
IngoInstantPayments.ERROR_CODES.CARD
A list of potential error codes that may occur during card tokenization.
Available options are:
- UNKNOWN - An unknown error has occurred (0)
- AVS - Address Verification Service (1)
- CNS - Card Not Supported (2)
- RVDM - Recipient Verification Data Matching (4)
- CVV - Card Verification Value (5)
- CD - Check Digit (6)
IngoInstantPayments.ERROR_CODES.PAYPAL
A list of potential error codes that may occur during PayPal tokenization.
Available options are:
- UNKNOWN - An unknown error has occurred (0)
- LOGIN - Login Failure (1)
- CONSENT - PayPal Consent Rejection (2)
- AV - Account Verification (3)
¶ Example TERMINAL_FAILURE PlugIn Event Flows
¶ TERMINAL_FAILURE_ACKNOWLEDGED
This event is triggered when the customer has acknowledged their terminal failure and presses the continue button.
Additional data properties included are:
- funding_destination – The funding destination requested to be tokenized (see: IngoInstantPayments.FUNDING_DESTINATIONS)
- error – The account verification error that caused the terminal failure (see: IngoInstantPayments.ERROR_CODES
{
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"
}
¶ Example TERMINAL_FAILURE_ACKNOWLEGED PlugIn Event Flows
¶ MAX_VERIFICATION_ATTEMPTS_EXCEEDED
This event is triggered when the customer exceeds the max account verification failure limit. At this point, the transaction session is terminated, and can no longer be used. A new transaction session will have to be initialized.
{
session_identifier: "54f59bcbf-040d-40d8-928d-39895b4ad455",
tracer_token: "12345_f63b668e-bb3e-4e70-9df1-1215b1fe7dc8",
event_name: "iip.webplugin.max_verification_attempts_exceeded"
}
¶ Example MAX_VERIFICATION_ATTEMPTS_EXCEEDED PlugIn Event Flows
¶ Additional Base Events - BillPay ONLY
¶ ACCOUNT_COULD_NOT_BE_VERIFIED
This event is triggered when a user a customer does not have their card present during a 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: "credit"
}
¶ Example ACCOUNT_COULD_NOT_BE_VERIFIED PlugIn Event Flow
¶ BILLPAY_SEARCH_NO_MATCH_FOUND
This event is triggered when a customer exceeds their no results found search during a BillPay search. At this point, the transaction session is terminated, and can no longer be used. A new transaction session will have to be initialized.
{
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"
}
¶ Example BILLPAY_SEARCH_NO_MATCH_FOUND PlugIn Event Flow
¶ Informative Events
¶ PAGE_LOAD
This event is triggered when the page has successfully loaded with the web plugin. It will be triggered each time the page changes and loads within the web plugin as the user interacts with the web plugin.
Additional data properties included are:
content(object) -
page(string) – Name of the current web plugin page loaded
{
session_identifier: "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
tracer_token: "12345_01467df7-d00b-42a6-a824-f620fd93ef51",
content: {
page: "DebitFunding"
},
event_name: "iip.webplugin.page_load"
}
A list of available pages that may be
returned in the IngoInstantPayments.EVENTS.PAGE_LOAD event.
Available IngoInstantPayments.PLUGIN_PAGES options
are:
ACCOUNT VERIFICATION
- MAX_VERIFICATION_ATTEMPTS_EXCEEDED – The max account verification failure exceeded page
- ACCOUNT_COULD_NOT_BE_VERIFIED – The account verification error / could not be verified termination page. Occurs when: "I don’t have my card"
ACH FUNDING
- ACH_FUNDING – The bank account tokenization / funding page
- ACH_FUNDING_CONFIRM – The bank account tokenization confirmation page
- ACH_FUNDING_TERMINAL_RVDM – The bank account terminal page due to RVDM failure
- ACH_FUNDING_TERMINAL_ANV – The bank account terminal page due to ANV failure
- ACH_FUNDING_TERMINAL_NAV – The bank account terminal page due to NAV failure
- ACH_FUNDING_TERMINAL_RNV – The bank account terminal page due to RNV failure
- ACH_FUNDING_TERMINAL_UNKNOWN – The bank account terminal page due to an unknown failure
BILLPAY FUNDING
- BILLPAY_FUNDING – The billpay biller search page
- BILLPAY_FUNDING_CONFIRM – The billpay account tokenization confirmation page
- BILLPAY_FUNDING_SEARCH_RESULTS – The billpay biller search results page
- BILLPAY_FUNDING_NO_MATCH_FOUND – The “no match” biller search termination page
- BILLPAY_FUNDING_TERMINAL_AV – The billpay account could not be verified page
- BILLPAY_FUNDING_TERMINAL_UNKNOWN – A downstream processor error occurred while verifying billpay account page
CREDIT FUNDING
- CREDIT_FUNDING – The credit card tokenization / funding page
- CREDIT_FUNDING_CONFIRM – The credit card tokenization confirmation page
- CREDIT_FUNDING_TERMINAL_RVDM – The credit card terminal page due to RVDM failure
- CREDIT_FUNDING_TERMINAL_AVS – The credit card terminal page due to AVS failure
- CREDIT_FUNDING_TERMINAL_CNS – The credit card terminal page due to CNS failure
- CREDIT_FUNDING_TERMINAL_CVV – The credit card terminal page due to CVV failure
- CREDIT_FUNDING_TERMINAL_CD – The credit card terminal page due to CD failure
- CREDIT_FUNDING_TERMINAL_UNKNOWN – The credit card terminal page due to an unknown failure
DEBIT FUNDING
- DEBIT_FUNDING – The debit card tokenization / funding page
- DEBIT_FUNDING_CONFIRM – The debit card tokenization confirmation page
- DEBIT_FUNDING_TERMINAL_RVDM – The debit card terminal page due to RVDM failure
- DEBIT_FUNDING_TERMINAL_AVS – The debit card terminal page due to AVS failure
- DEBIT_FUNDING_TERMINAL_CNS – The debit card terminal page due to CNS failure
- DEBIT_FUNDING_TERMINAL_CVV – The debit card terminal page due to CVV failure
- DEBIT_FUNDING_TERMINAL_CD – The debit card terminal page due to CD failure
- DEBIT_FUNDING_TERMINAL_UNKNOWN – The debit card terminal page due to an unknown failure
PAYPAL FUNDING
- PAYPAL_FUNDING - The PayPal tokenization / funding page
- PAYPAL_FUNDING_CONFIRM - The PayPal tokenization confirmation page
- PAYPAL_FUNDING_TERMINAL_LOGIN - The PayPal terminal page due to login failure
- PAYPAL_FUNDING_TERMINAL_CONSENT - The PayPal terminal page due to user consent rejection.
- PAYPAL_FUNDING_TERMINAL_AV - The PayPal terminal page due to AV failure
- PAYPAL_FUNDING_TERMINAL_UNKNOWN - The PayPal terminal page due to an unknown failure
SESSION MANAGEMENT
- SESSION_UNAUTHORIZED – The session error page when attempting to mount an invalid funding destination or the authorized url has expired
- SESSION_INVALID – The session error page when attempting to mount a transaction session that has been canceled, terminated, or expired
- SESSION_COMPLETED – The session error page when attempting to mount a transaction session that has been completed
- SESSION_TIMEOUT – The session error page when the user’s web session has expired due to inactivity
¶ Example PAGE_LOAD PlugIn Event Flows
¶ PLUGIN_RESIZE
This event is triggered when dimensions of the plugin contents change.
Additional data properties included are:
content (object)
- width – Current width of the contents in the web plugin
- height – Current height of the contents in the web plugin
{
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"
}
¶ Example PLUGIN_RESIZE PlugIn Event Flow
¶ UNSUPPORTED_BROWSER_DETECTED
This event is triggered when a user is using a legacy browser not included in our supported browsers list.
Additional data properties included are:
browser (object)
- name – The user’s internet browser name
- version – The user’s internet browser version
- os – The user’s operating system name
- os_version – The user’s 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"
}
}
¶ Example UNSUPPORTED_BROWSER_DETECTED PlugIn Event Flows
¶ Warning / Error Events
¶ PLUGIN_ERROR
This event is triggered when an unhandled exception
occurs in the plugin.
Additional data properties included are:
error (object)
- message – Description of the unhandled exception
- source – Source of the unhandled exception
- lineno – Line number where the exception occurred
- colno – Column number where the exception occurred
- err – The name of the unhandled exception
{
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"
}
}
¶ Example PLUGIN_ERROR PlugIn Event Flow
¶ SESSION_ERROR
This event is triggered when the plugin reaches a session error page (see: IngoInstantPayments.PLUGIN_PAGES)
[SESSION_UNAUTHORIZED | SESSION_INVALID | SESSION_COMPLETED | SESSION_TIMEOUT]
Additional data properties included are:
content (object)
- page – Name of the current web plugin page loaded [see: IngoInstantPayments.PLUGIN_PAGES]
- status_code – Session error status code
• 13404 – Transaction session has expired
• 13405 – Transaction has been canceled or terminated
• 13412 – Unauthorized
• 13413 – Transaction session has been completed
• 13414 – The user’s web session has expired due to inactivity
{
session_identifier: "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
tracer_token: "",
event_name: "iip.webplugin.session_error",
content: {
page: "UnauthorizedError",
status_code: 13412
}
}
{
session_identifier: "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
tracer_token: "",
event_name: "iip.webplugin.session_error",
content: {
page: "SessionExpired",
status_code: 13414
}
}
