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

安装

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

// window.SecureShieldJs

初始化

定义初始化参数

警告

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

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

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

完成初始化

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

注意

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

3DS init

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

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

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位数字

示例：

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

示例：

// 选择某个已绑定的卡时:
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。

示例：

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