SecureShieldJs is a plugin for secure online payments, designed to enhance credit card transaction security and reduce the risk of fraudulent transactions.

Installation

JavaScript

<script src="https://pay-cdn.pingpongx.com/production-fra/static/secure-shield/secureShield.min.js"></script>

// window.SecureShieldJs

Initialization

Define Initialization Parameters

Caution

For sandbox testing, set env=SANDBOX. For production environment, set env=PRODUCTION.

JavaScript

const options = {
    env: 'SANDBOX', // 'SANDBOX'|'PRODUCTION'
    accId: accId,
    clientId: clientId,
    requestId: requestId,
    merchantUserId: merchantUserId,
    merchantTransactionId: merchantTransactionId,
}

• requestId is passed during S2S integration, PingPong checkout should pass merchantTransactionId.

Complete Initialization

JavaScript

const secureShieldJs = SecureShieldJs.init(options, [avoidThreeDs=false])

Warning

You can pass true as the second parameter in init to disable 3Ds functionality. After disabling, the plugin will not collect 3D information, only browser information. To ensure payment security, you need to implement 3D logic yourself.

3DS init

The following method only takes effect when 3Ds functionality is enabled (enabled by default)

After completing plugin initialization, you can now call the triggerThreeDsInit method at an appropriate time to perform 3DS init.

JavaScript

secureShieldJs.triggerThreeDsInit(params)

When to call?

Scenario One

To collect complete and correct card numbers, you can call after the card number and card expiration date input fields lose focus. The plugin will automatically perform 3DS init operation. At this time, when calling the triggerThreeDsInit method, you need to pass cardInfo related parameters:

Property	Type	Required	Description
params.cardNumber	String(12)	No	International credit card number
params.cardExpireMonth	String(32)	No	Expiration month, 2 digits
params.cardExpireYear	String(64)	No	Expiration year, 4 digits

Example:

JavaScript

const cardNumberElement = document.querySelector('#cardNumber');
const expireDateElement = document.querySelector('#expireDate');

const triggerThreeDs = {
    threeDsParams: {
        cardNumber: cardNumberElement.value,
        expireDate: expireDateElement.value
    },
    // Proxy function to validate parameters before 3Ds init
    proxyThreeDsParams() {
        const proxyHandle = {
            get: (target, key) => {
                // Simple validation: return empty string when card number length <= 15
                if (key === 'cardNumber') {
                    return target[key].length <= 15 ? '' : target[key].replace(/\s+/g, '')
                }

                // Card expiration date parameter processing: return empty string if conditions not met, otherwise return processed parameter format
                if (key === 'expireDate') {
                    const expireDate = target[key].replace(/\s+/g, '')

                    if (expireDate.length === 5 && expireDate.indexOf('/') > -1) {

                        const [cardExpireMonth, cardExpireYear] = expireDate.split('/')

                        return {
                            cardExpireMonth,
                            cardExpireYear: `20${cardExpireYear}`
                        }
                    }
                    return ''
                }
                return '';
            }
        }
        return new Proxy(this.threeDsParams, proxyHandle)
    },
    getThreeDsInitParams(threeDsParams) {
        const { cardNumber, expireDate } = threeDsParams

        if (!cardNumber) return null;

        if (typeof expireDate === 'string') return null;

        const { cardExpireMonth, cardExpireYear } = expireDate

        return {
            cardNumber,
            cardExpireMonth,
            cardExpireYear
        }
    }
}

const _proxyThreeDsParams = triggerThreeDs.proxyThreeDsParams()

const handleBlur = (name) => {
    const { value } = event.target
    triggerThreeDs.threeDsParams[name] = value
    const params = triggerThreeDs.getThreeDsInitParams(_proxyThreeDsParams)
    // You don't need to call triggerThreeDsInit method when validation fails
    params && secureShieldJs.triggerThreeDsInit(params).then((data) => {})
}

cardNumberElement.addEventListener('blur', handleBlur.bind(this, 'cardNumber'), true)

expireDateElement.addEventListener('blur', handleBlur.bind(this, 'expireDate'), true)

The above is the native JavaScript implementation. If you use Vue, you can use watchEffect to monitor card number and card expiration date, then call the 3Ds init method after validating and integrating parameters;

Scenario Two

When your payment scenario includes card binding, you can directly pass cardToken for 3Ds init

Property	Type	Required	Description
params.cardToken	String(32)	No	Can be used to replace cardInfo

Example:

JavaScript

// When selecting a bound card:
document.querySelector('selectId').addEventListener('change', (event) => {
    const { value: card } = event.target
    const params = {
        cardToken: card.cardToken
    }
    secureShieldJs.triggerThreeDsInit(params)
})

Get generatedData

After completing 3Ds init, before actually initiating the payment request, you need to pass the 3Ds parameters and browserInfo (hereinafter referred to as generatedData) to the payment interface.

When 3Ds is disabled, the getGeneratedData method will only return browserInfo.

How to Get

• Through triggerThreeDsInit: When performing 3Ds init, triggerThreeDsInit is called, which returns a Promise. You can get generatedData when the Promise is Fulfilled.

Example:

JavaScript

const threeDsPromise = secureShieldJs.triggerThreeDsInit(params)

threeDsPromise.then(jsGeneratedData => {
    // Can be assigned to external variable for payment transmission
    this.myGeneratedData = jsGeneratedData
})

• Call the plugin's getGeneratedData method (recommended)

Example:

JavaScript

const generatedData = secureShieldJs.getGeneratedData()

// generatedData: 
{
    browserInfo: {
        acceptHeader: string
        colorDepth: number
        language: string
        screenHeight: number
        screenWidth: number
        jetLag: number
        userAgent: string
        javaEnabled: boolean
        javaScriptEnabled: boolean
    }
    jsGeneratedData: {
        channel: string
        version: string
        correlationId: string
        threeDInitTransId: string
        threeDSecureReferenceId: string
    }
}