---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/risk/SecureShieldJs/index.md
description: >-
  SecureShieldJs是用于在线支付的安全插件，旨在提高信用卡交易安全性并降低欺诈风险。适用于需要增强支付安全性的网站。支持通过初始化参数配置环境（SANDBOX/PRODUCTION），并提供3DS验证功能，默认开启但可关闭。关键方法包括初始化、触发3DS验证及获取生成的数据，其中`trig
---
**SecureShieldJs** 一个用于在线安全支付的插件，旨在提高信用卡交易的安全性，降低欺诈交易的风险。

## 安装

::: code-tabs
@tab JavaScript

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

// window.SecureShieldJs
```

:::

## 初始化

### 定义初始化参数

::: danger
沙箱联调请填入`env`=`SANDBOX`, 生产环境请填入`env`=`PRODUCTION`。
:::

::: code-tabs
@tab JavaScript

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

:::

- `requestId`为S2S对接时传入的，pingpong收银台应传`merchantTransactionId`。

### 完成初始化

::: code-tabs
@tab JavaScript

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

:::

::: warning
你可以在 init 时传入第二个参数true来关闭 3Ds功能，关闭后，插件将不进行 3D 信息的采集, 只保留 browser 信息的采集。为保证支付安全性, 需要你自行实现 3D 逻辑。
:::

## 3DS init
以下方法仅在开启 3Ds功能时生效(默认开启)

在完成插件的初始化后，现在你可以在合适的时机调用 `triggerThreeDsInit`方法来进行 3DS init。

::: code-tabs
@tab JavaScript

```javascript
secureShieldJs.triggerThreeDsInit(params)
```

:::

何时调用？

### 场景一

为了收集完整正确的卡号，你可以在 卡号 和 卡有效期 input 失焦后调用，插件将自行进行3DS init操作
此时，调用 triggerThreeDsInit 方法需传入 cardInfo 相关参数：

| 属性                     | 类型         | 必填  | 描述         |
|------------------------|------------|-----|------------|
| params.cardNumber      | String(12) | C   | 国际信用卡卡号    |
| params.cardExpireMonth | String(32) | C   | 有效期-月，2位数字 |
| params.cardExpireYear  | String(64) | C   | 有效期-年，4位数字 |

示例：

::: code-tabs
@tab JavaScript

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

const triggerThreeDs = {
    threeDsParams: {
        cardNumber: cardNumberElement.value,
        expireDate: expireDateElement.value
    },
    // 代理函数, 在 3Ds init 前对参数进行校验
    proxyThreeDsParams() {
        const proxyHandle = {
            get: (target, key) => {
                // 简单校验: 卡号位数 <= 15 时返回空字符
                if (key === 'cardNumber') {
                    return target[key].length <= 15 ? '' : target[key].replace(/\s+/g, '')
                }

                // 卡号有效期参数处理: 不满足条件返回空字符, 反之为处理好的参数格式
                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)
    // 当校验不通过时, 你不需要调用 triggerThreeDsInit 方法
    params && secureShieldJs.triggerThreeDsInit(params).then((data) => {})
}

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

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

:::

以上为原生 Js 实现方式，如果你使用 Vue，可以使用 watchEffect 对卡号、卡有效期进行监听，校验、整合参数完成后调用 3Ds init 方法即可；

### 场景二

当你的支付场景中存在绑卡的场景时，你可以直接传入cardToken来进行 3Ds init

| 属性               | 类型         | 必填  | 描述             |
|------------------|------------|-----|----------------|
| params.cardToken | String(32) | C   | 可以用来替代cardInfo |

示例：

::: code-tabs
@tab JavaScript

```javascript
// 选择某个已绑定的卡时:
document.querySelector('selectId').addEventListener('change', (event) => {
    const { value: card } = event.target
    const params = {
        cardToken: card.cardToken
    }
    secureShieldJs.triggerThreeDsInit(params)
})
```

:::

## 获取generatedData

在完成 3Ds init 后，真正发起支付请求前, 需要将 3Ds 参数 和 browserInfo （以下均称其为 generatedData）传递给支付接口。

关闭 3Ds 时，`getGeneratedData` 方法只会返回 browserInfo。

### 如何获取
- 通过 triggerThreeDsInit：
在进行 3Ds init 时调用了 triggerThreeDsInit，该方法将返回一个Promise，你可以在 Promise Fulfilled 时获取 generatedData。

示例：
::: code-tabs
@tab JavaScript

```javascript
const threeDsPromise = secureShieldJs.triggerThreeDsInit(params)

threeDsPromise.then(jsGeneratedData => {
    // 可以赋值给外部变量，支付时传递
    this.myGeneratedData = jsGeneratedData
})
```

:::

- 调用插件提供的 getGeneratedData 方法（推荐）

示例：
::: 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
    }
}
```

:::