Skip to main content

​
Overview

Gateway.js is a JavaScript library that enables advanced payment processing features including 3D Secure authentication and Kount fraud detection. This library provides merchants with additional layers of security and fraud prevention capabilities.
Gateway.js is designed for modular integration, allowing merchants to activate only the security features they need.

​
Core Services

Implements 3D Secure authentication for enhanced card payment security.Key Benefits:
  • Shift liability for fraudulent transactions
  • Increase approval rates for authenticated transactions
  • Meet regulatory requirements (e.g., PSD2 SCA)
  • Reduce chargebacks
Supported Versions:
  • 3D Secure 1.0
  • 3D Secure 2.0 (EMV 3DS)

​
Installation

Include Gateway.js in your page: 
<script src="https://api.ionicfi.com/js/Gateway.js"></script>

​
Gateway Object Reference

The Gateway object provides access to all Gateway.js services:

​
Gateway.create()

Creates and initializes a Gateway instance: 
const gateway = Gateway.create({
    apiKey: 'YOUR_PUBLIC_API_KEY',
    environment: 'sandbox' // or 'production'
});

​
Gateway.get3DSecure()

Retrieves the 3D Secure service instance: 
const threeDSecure = gateway.get3DSecure();

​
Gateway.getKount()

Retrieves the Kount fraud detection service instance: 
const kount = gateway.getKount();

​
Gateway.on()

Registers event handlers: 
gateway.on('ready', function() {
    console.log('Gateway services initialized');
});

gateway.on('error', function(error) {
    console.error('Gateway error:', error);
});

​
3D Secure Integration

1

Initialize Gateway

Create a Gateway instance with your API credentials
2

Get 3D Secure Service

Retrieve the 3D Secure service from the Gateway instance
3

Initiate Authentication

Start the 3D Secure authentication flow
4

Handle Authentication Result

Process the authentication result and submit to Payment API

​
Implementation Example

// Initialize Gateway
const gateway = Gateway.create({
    apiKey: 'YOUR_PUBLIC_API_KEY',
    environment: 'sandbox'
});

// Get 3D Secure service
const threeDSecure = gateway.get3DSecure();

// Configure authentication
threeDSecure.configure({
    amount: '99.99',
    currency: 'USD',
    billingAddress: {
        firstName: 'John',
        lastName: 'Doe',
        address1: '123 Main St',
        city: 'New York',
        state: 'NY',
        zip: '10001',
        country: 'US'
    }
});

// Collect.js callback
CollectJS.configure({
    callback: function(token) {
        // Start 3DS authentication
        threeDSecure.authenticate(token, function(result) {
            if (result.authenticated) {
                // Submit to Payment API with 3DS data
                submitPayment({
                    payment_token: token,
                    cardholder_auth: result.cardholder_auth,
                    cavv: result.cavv,
                    xid: result.xid,
                    eci: result.eci
                });
            } else {
                // Handle authentication failure
                console.error('3DS authentication failed');
            }
        });
    }
});

​
3D Secure Response Fields

After authentication, submit these fields to the Payment API:
FieldDescription
cardholder_authAuthentication indicator
cavvCardholder Authentication Verification Value
xidTransaction identifier
eciElectronic Commerce Indicator

​
Kount Fraud Detection

1

Initialize Gateway

Create a Gateway instance with Kount enabled
2

Get Kount Service

Retrieve the Kount service from the Gateway instance
3

Collect Device Data

Gather device fingerprinting data
4

Submit with Transaction

Include Kount session ID with your payment request

​
Implementation Example

// Initialize Gateway with Kount
const gateway = Gateway.create({
    apiKey: 'YOUR_PUBLIC_API_KEY',
    environment: 'sandbox'
});

const kount = gateway.getKount();

// Start device data collection
kount.collectDeviceData(function(sessionId) {
    console.log('Kount Session ID:', sessionId);

    // Submit payment with Kount session
    submitPayment({
        type: 'sale',
        amount: '99.99',
        ccnumber: '4111111111111111',
        ccexp: '1225',
        kount_session_id: sessionId
    });
});

​
Fraud Score Interpretation

Kount returns a fraud score with each transaction:
  • 0-20: Low risk (approve)
  • 21-40: Medium-low risk (approve with monitoring)
  • 41-60: Medium risk (review required)
  • 61-80: Medium-high risk (decline or review)
  • 81-100: High risk (decline)
Configure your fraud thresholds in the merchant control panel based on your risk tolerance and business model.

​
Combined Integration

Use both 3D Secure and Kount together for maximum protection: 
const gateway = Gateway.create({
    apiKey: 'YOUR_PUBLIC_API_KEY',
    environment: 'sandbox'
});

const threeDSecure = gateway.get3DSecure();
const kount = gateway.getKount();

// Collect Kount device data
kount.collectDeviceData(function(kountSessionId) {

    // Collect payment token
    CollectJS.configure({
        callback: function(token) {

            // Perform 3DS authentication
            threeDSecure.authenticate(token, function(threeDSResult) {

                if (threeDSResult.authenticated) {
                    // Submit with both 3DS and Kount data
                    submitPayment({
                        payment_token: token,
                        cardholder_auth: threeDSResult.cardholder_auth,
                        cavv: threeDSResult.cavv,
                        xid: threeDSResult.xid,
                        eci: threeDSResult.eci,
                        kount_session_id: kountSessionId
                    });
                }
            });
        }
    });
});

​
Testing

​
3D Secure Testing

Use these test scenarios:
Card Number3DS Result
4000000000001000Successful authentication
4000000000001018Authentication unavailable
4000000000001034Failed authentication

​
Kount Testing

In sandbox mode, Kount returns predictable scores based on email patterns:

​
Event Reference

Gateway.js emits various events you can listen to: 
gateway.on('ready', handler);           // Services initialized
gateway.on('error', handler);           // Error occurred
gateway.on('3ds-start', handler);       // 3DS authentication started
gateway.on('3ds-complete', handler);    // 3DS authentication completed
gateway.on('kount-collected', handler); // Kount data collected

​
Next Steps

Payment API

Submit authenticated transactions

Collect.js

Combine with tokenization

Customer Vault

Use with stored credentials

Testing Guide

Test your fraud prevention setup