• Documentation
  • API Reference
  • Documentation
  • API Reference
Expand All Collapse All
  • Payment Overview
    • Introduction
    • Choosing an Integration Method
  • Accept Payment
    • Payment Page
      • Quick Start
      • Input Parameters
      • Output Parameters
    • Web SDK
      • Quick Start
      • Nuvei Fields
        • Styling
      • Additional Functions
      • APM Payments
      • Tokenization-Only Flow
      • Scenarios
      • Using ReactJS
        • Full Samples
        • Sandbox Examples
      • FAQs
    • Checkout
      • Quick Start
      • UI Customization
      • Payment Customization
      • Advanced Controls
      • Checkout Examples
    • Server-to-Server
    • Payment Scenarios
    • Mobile SDKs (Beta Release)
      • Android Mobile SDK (Beta Release)
      • iOS Mobile SDK (Beta Release)
    • Flow Diagrams
    • Plugins
      • Magento
        • Rebilling with Magento
      • WooCommerce
        • Rebilling with WooCommerce
      • PrestaShop
        • Rebilling with PrestaShop
      • OpenCart
      • Shopify (via AsiaBill)
      • Mirakl
      • Salesforce
      • SAP
      • WIX
    • Marketplaces
  • Features
    • Authentication
    • Financial Operations
      • Refund
      • Void
      • Auth and Settle
      • Partial Approval
      • Currency Conversion (DCC and MCP)
    • Card Operations
      • Card-on-File
      • PCI and Tokenization
      • Zero-Authorization
      • Merchant-Initiated Transactions (MIT)
      • Blocking Cards
    • Subscription (Rebilling)
    • 3D-Secure
      • 3D-Secure Explained
      • 3DS Implementations
        • 3DS MPI-Only Web SDK
        • 3DS MPI-Only REST
        • 3DS External MPI
        • 3DS Responses
      • 3DS Functions
        • 3D-Secure Fingerprinting
        • 3D-Secure Authentication Challenge
    • Callbacks (DMNs)
      • Configuring the Events API
  • Guides
    • Testing Cards, APIs and APMs
      • Testing Cards
      • Testing APIs with Postman
      • Testing APMs
    • Response Handling
    • Alternative Payment Guides (APMs)
    • Airline Ticket Guides
      • Airline Addendum
      • External Authorization Addendum
    • Payment Facilitators (PayFac)
    • Cashier
      • Cashier Events Guide
      • Cashier Features
    • Withdrawal Guide
    • Risk Guide
      • Appendix 1: Transaction Types
      • Appendix 2: Credits and Payouts
      • Appendix 3: Fraud to Sale Programs
      • Appendix 4: Compliance Programs
      • Appendix 5: Chargebacks
    • eKYC Guide
    • Server SDKs
      • Java SDK
      • .NET SDK
      • PHP SDK
      • Node.JS SDK
    • Fast Track Onboarding Developer Guide
    • Currency Conversion Guides
      • Multiple Currency Pricing (MCP)
      • Dynamic Currency Conversion (DCC)
        • DCC in Cashier or Payment Page
        • DCC in REST API Workflows
        • DCC in Web SDK Workflows
    • Website Compliance Guides
  • Additional Links
    • FAQs
    • API Reference
    • Release Notes
    • Country and Currency Codes

Cashier Events Guide

On this page:
  • Requirements
  • Implementation
  • Instructions
  • Events and Corresponding Data Structures
  • Tracking Implementation Details
  • Payments Events
  • Registration Events
  • Withdraw Events

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 is 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 begins 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 is postMessage. To make things work, the merchant should provide the parameter to the IFrame URL,  “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 are 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; 
// ... 
}

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 are 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 provides “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": 
}
2022 Nuvei. All rights reserved.