---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/riskManger/SecureShieldJs/index.md
---
**SecureShieldJs** is a plugin for secure online payments, designed to enhance credit card transaction security and reduce the risk of fraudulent transactions.

## Installation

::: code-tabs
@tab JavaScript

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

// window.SecureShieldJs
```

:::

## Initialization

### Define Initialization Parameters

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

::: code-tabs
@tab JavaScript

```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

::: code-tabs
@tab JavaScript

```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.

::: code-tabs
@tab JavaScript

```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:

::: code-tabs
@tab JavaScript

```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:

::: code-tabs
@tab JavaScript

```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:
::: code-tabs
@tab JavaScript

```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:
::: code-tabs
@tab JavaScript

```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
    }
}
```