SecureShieldJs 一个用于在线安全支付的插件，旨在提高信用卡交易的安全性，降低欺诈交易的风险。

安装

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

// window.SecureShieldJs

// Make sure to add code blocks to your code group

初始化

定义初始化参数

警告

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

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

// Make sure to add code blocks to your code group

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

完成初始化

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

// Make sure to add code blocks to your code group

注意

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

3DS init

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

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

secureShieldJs.triggerThreeDsInit(params)

// Make sure to add code blocks to your code group

何时调用？

场景一

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

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

示例：

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)

// Make sure to add code blocks to your code group

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

场景二

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

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

示例：

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

// Make sure to add code blocks to your code group

获取generatedData

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

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

如何获取

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

示例：

const threeDsPromise = secureShieldJs.triggerThreeDsInit(params)

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

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

示例：

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