Developers

Requirements

A listener must be installed in the merchant’s website to relay the resulting JavaScript to the merchant so that it can be examined by the external analytics tool.

The mechanism for transferring data from the Nuvei IFrame to the parent page will be postMessage.

Implementation

The following must be implemented by the merchant in coordination with the Nuvei Tech Support team. The merchant’s external analytics tool account will begin collecting and displaying data immediately in a standard format established by Nuvei.

Instructions

1. The merchant must acquire a valid account with the external analytics tool of choice.
2. The merchant must establish a post messaging system in order to send information from one window to another located on a different domain.
3. The specific code must be added to serialize the data and to signify the target origin of data to be sent.
4. The merchant must notify Nuvei so that Nuvei can make the necessary modifications to the merchants account to enable an external analytics tool.
5. The mechanism for transferring data from the Nuvei IFrame to the parent page will be postMessage. To make things work, the merchant should provide the parameter to the IFrame URL, i.e. “parent_url“, which is the domain name of the parent page. The parameter is later used as second parameter of postMessage function.

Events and Corresponding Data Structures

Below is the list of events and corresponding data structures that will be sent by postMessage and made available to the merchants:

1. The first instance when some element in the IFrame is interacted with – Page load (IFrame load).
2. The first instance when some element in the IFrame is interacted with – first use click.
3. Whenever a user completes a field and blurs from it without inline validation errors – on blur without errors.
4. Whenever a user completes a field and blurs from it and throws inline validation errors.
5. Whenever a user attempts to submit their details to make a payment – on deposit click.
6. Whenever a user successfully makes a deposit.
7. Whenever a user attempts to submit their details to make a payment and the payment fails.

The following is a sample of code for listener as described above:

window.addEventListener("message", receiveMessage, false); 

function receiveMessage(event) 
{ 
var origin = event.origin || event.originalEvent.origin; // For Chrome, the origin property is in the event.originalEvent object. 
if (origin !== "https://secure.safecharge.com") 
return; 
// ... 
}

Nuvei Tracking Implementation Details

To facilitate the process, the merchant should provide the IFrame URL parameter, parent_url, which is the domain name of the parent page.

The parameter is later used as a second parameter of the postMessage function.

Below is a list of events and corresponding data structures that will be sent by postMessage, i.e. window.postMessage ( { action: “<action>”, label: “<label>” ,…}, parent_url):

1. The first instance when some element in the IFrame is interacted with – Page load (IFrame load):

{
    'action':'analytics', 
    'payload':
    { 
       'action':'saw', 
       'label':'payments iframe - ' + ,
       'cd3':'payments - ' + 
     }  
}

2. The first instance when some element in the IFrame is interacted with – first use click:

{
    'action':'analytics', 
    'payload':
    { 
        'action':'started deposit' | 'started first deposit', 
        'label':'safecharge', 
        'cd3':'payments - ' + 
     } 
}

Nuvei will provide “started first deposit” when a user has no defined user payment methods, afterwards known as “started deposit”.

3. Whenever a user completes a field and blurs from it without inline validation errors – on blur without errors:

{
    'action':'analytics', 
    'payload':
    { 
        'action':'started deposit' | 'started first deposit', 
        'label':'safecharge', 
        'cd3':'payments - ' + 
     } 
}

4. Whenever a user completes a field and blurs from it and throws inline validation errors:

{
    'action':'analytics', 
    'payload':
    { 
        'action':'field error', 
        'label': + 'error - '+,
        'cd3' : 'payments - ' + 
     } 
}

5. Whenever a user pastes (CTRL + V) a credit card number in the input field for credit card:

{
    "action":"cc_pasted",
    "payload":{
        "payment_method": 
    }
}

Payments Events

1. Whenever a user attempts to submit their details to make a payment – on deposit click:

{
    'action':'analytics',
    'payload':
    { 
        'action': 'attempted deposit'|'attempted first deposit', 
        'label': , 
        'deposit_amount':, 
        'currency': ,
        'cd3' : 'payments - ' + 
     } 
}

2. Whenever a user’s deposit is pending:

{
    'action':'analytics', 
    'payload':
    { 
        'action': 'pending deposit'|'pending first deposit', 
        'label': , 
        'deposit_amount': ,
        'currency': ,
        'cd3' : 'payments - ' + 
    } 
}

3. Whenever a user successfully makes a deposit:

{
    'action':'analytics', 
    'payload':
    { 
        'action': 'made deposit'|'made first deposit', 
        'label': , 
        'deposit_amount': ,
        'currency': ,
        'cd3' : 'payments - ' + 
    } 
}

4. Whenever a user attempts to submit their details to make a payment and the payment fails:

{
    'action':'analytics', 
    'payload':
    { 
        'action': 'failed deposit'|'failed first deposit', 
        'label': , 
        'deposit_amount': , 
        'currency': ,
        'cd3' : 'payments - ' + 
    } 
}

Registration Events

1. Failed Card Registration – Once a card registration is attempted but fails, Nuvei sends the following post message:

{
    "payload": "failedRegistration",
    "label": "cc_card"
}

2. Successful Card Registration – Once a card registration is done, Nuvei sends the following post message:

{
    "payload": "successfulRegistration",
    "label": "cc_card",
    "verification_status": 'New'
}

3. Contact support in Decline recovery – Once the decline recovery lightbox is shown and the “Contact Support” option is selected, the following message is sent to the parent window:

{	
    "action": "contactSupport"
}

4. Alternative Verification post message – Once a user clicks an alternative verification button to start the process, the following post message is to be sent:

{
     "action": "alternativeVerification",
     "verification_status" : "New" | "Pending" | "Verified" | "Not Verified",
     "method_status" : "Active" | "InActive",
     "label" : "",
     "userPaymentOptionId" : 
}

Withdraw Events

1. Successful cancel withdrawal request:

{
    "payload":"successfulCancelWithdrawal",
    "payment_method":,
    "amount":,
    "currency": ,
    "method_status":,
    "verification_status": 
}

2. Successful withdrawal request:

{
    "payload":"successfulWithdrawalRequest",
    "payment_method":,
    "amount":,
    "currency": ,
    "method_status":,
    "verification_status": 
}

3. Failed withdrawal request:

{
    "payload":"failedWithdrawalRequest",
    "payment_method":,
    "amount":,
    "currency": ,
    "method_status":,
    "verification_status": 
}