一、简述

1.1 页面展示

内嵌收银台，无需页面跳转。下图中的 卡号，MM/YY 和CVV/CVC 采集框为内嵌收银台提供

1.2 需要掌握知识

• 需要会 html 前端知识
• 需要会 服务端 知识
• 无需PCI

  二、对接流程

  2.1 时序图

sequenceDiagram
Customer->>Merchant frontend: 点击支付
Merchant frontend->> Merchant Server: 调用创建token接口
Merchant Server->> UseePay Server: 调用/cashier接口
UseePay Server->>Merchant frontend: 返回token
Merchant frontend->>UseePay JSSDK: 调用useepay.confirm
UseePay JSSDK->>UseePay Server: 请求支付
UseePay Server->>UseePay JSSDK: 返回支付结果
UseePay JSSDK->>Merchant frontend: useepay.confirm的回调，返回支付结果
Merchant frontend->>Merchant Server: 调用验签接口
Merchant Server->>Merchant frontend: 验签通过并展示支付结果
UseePay Server-->>Merchant Server: 异步通知支付结果

2.2 简述

1. 商户后端调用 Create Token后获取Token
   create token

2. 商户前端调用Jssdk中的confirm 方法进行支付

三、前端

3.1. 引入 UseePay CDN

访问 UseePay CDN 将 js 文件内容拷贝到您的项目对应目录即可

<script src="https://cashier.useepay.com/jssdk/1.0.5/useepay.min.js"></script>

3.2. 初始化

var useepay = UseePay({
    env: 'sandbox', 
    layout: 'multiLine',
    locale: window.navigator.language,
    merchantNo: 'YOU_MERCHANT_NO_IN_USEEPAY'
})

3.2.1 可配置参数

参数	说明	可选值
env	环境	sandbox, production
layout	卡输入框布局样式, 单行或多行	singleLine, multiLine 。LabeledMultiLine(该布局只能1.0.5以后的版本使用)
locale	语言	可从 navigator.language 中获取, 或者传递 ISO639 language code
merchantNo	UseePay分配的商户号

3.3. 挂载到元素上

您需要在显示 UseePay 卡信息的页面中有一个可以让 UseePay 卡输入页挂载上去的元素, 比如 div

<div id="cardElement"></div>

挂载到元素上:

useepay.mount(document.getElementById('cardElement'))

3.4. 支付

3.4.1 获取支付 Token （后端）

在确认支付前您需要先从您的 Server API 获取 Token，请参考create token

3.4.2 确认支付

useepay.confirm(TOKEN, function (resp) {...})

对象参数说明

参数名	描述
success	这次请求是完成，不表示支付是否成功, 比如卡号非法等错误，success 为 false
data	json 字符串
message	提示信息

data参数说明

参数	描述	示例	是否必须
version	max=5 交易异步通知报文版本，固定为：1.0	1.0	Y
merchantNo	max=16 商户编号，由USEEPAY 分配		Y
transactionId	max=64 商户订单号		Y
reference	max=32 USEEPAY 订单号		N
transactionType	max=64 交易类型： pay；authorization; refund; capture;authorizationVoid;		Y
amount	max=12 交易金额，单位为对应币种的最小货币单位(详见 ISO 4217)		N
currency	max=3 3 位 ISO 大写字母货币代码((详见 ISO 4217)
resultCode	max=32 业务结果（详见 业务结果码）		Y
errorCode	max=4 错误码（详见 错误码 errorCode）
errorMsg	max=256 错误码消息描述
echoParam	max=256 回声参数，响应报文会原样返回
signType	签名类型	MD5/RSA	Y

3.4.3 确认支付结果

将上一步获取到的json字符串发送给您的服务器进行验证合法性与支付结果
四 JSSDK APIS
这里描述了JSSDK API 的详细用法

四 JSSDK APIS

::: highlight green 💡
这里描述了JSSDK API 的详细用法
:::

4.1 validate

示例

useepay.validate(function(valid, code, message){...})

建议

在调用confirm方法之前，调用该方法验证参数的合法性

用例

用户点击支付按钮后，先校验用户卡输入信息是否正确

// 我只是个demo,请勿直接使用
$('#payBtn')
    .on('click', function() {
        $('#payBtn').attr('disable', true)
        useepay.validate(function(valid, code, message) {
            if (valid) {
                // 正确
                pay()
            } else {
                $('#errorTip').text(message)
            }
        })
    })

返回值说明

参数	说明	可选值
valid	验证输入的卡号、有效期与CVV的合法性，均合法则 valid 为 true, 否则为 false	true, false
code	错误码	0000: 成功, 0001: 卡号非法 0002: 有效期非法, 0003: CVV非法
message	错误描述	合法为空值，否则如: 请输入正确的卡号

4.2 on

示例

useepay.on(EVENT,function(valid, code, message){...})

建议

使用该方法实时监听消费者卡号等信息输入是否合法

用例

可以在前端页面添加该监听事件，可以实时监听消费者输入卡信息采集框数据的合法性。如果valid=true则允许消费者点击支付按钮，false,则禁用点击支付点击按钮。如下

  // 我只是个demo，不要直接使用
  useepay.on('change', function(valid, code, message) {
        if (valid) {
            $('#payBtn').attr('disabled', false)
            $('#errorTip').text('All input fields valid')
        } else {
            $('#payBtn').attr('disabled', true)
            $('#errorTip').text(message)
        }
    })

参数

参数	说明	可选值
EVENT	需要监听的事件名	目前只支持 change

返回值说明

参数	说明	可选值
valid	验证输入的卡号、有效期与CVV的合法性，均合法则 valid 为 true, 否则为 false	true, false
code	错误码	0000: 成功, 0001: 卡号非法 0002: 有效期非法, 0003: CVV非法
message	错误描述	合法为空值，否则如: 请输入正确的卡号

返回值说明
EVENT 为 change, 监听输入

五 、Demo 代码案例

欢迎访问我们的 Javascript SDK Demo

六、Changelog

1.0.5

优化3DS 指纹采集成功率

1.0.1

新增 validate 方法验证输入是否合法
新增 on('change', handler) 监听
修复 Firefox 86.0 兼容性问题

1.0.0

支持 sandbox 与 production 环境
支持交易与3DS交易
支持 singleLine 与 multiLine 两种布局
支持 locale