> For the complete documentation index, see [llms.txt](https://useepay.gitbook.io/developer/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://useepay.gitbook.io/developer/reference/api-reference-xin-yong-ka/embedded-cashier/javascript.md).

# JavaScript

## 一、简述

### 1.1 页面展示

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

<figure><img src="/files/jMXFU6hrCj61hHltAGpj" alt=""><figcaption></figcaption></figure>

### 1.2 需要掌握知识

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

## 二、对接流程

### 2.1 时序图

<figure><img src="/files/90YjMzAImMjYYW3g9sS3" alt=""><figcaption><p>内嵌收银台</p></figcaption></figure>

### 2.2 简述

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

{% content-ref url="/pages/wE8BEQBKhclWaTxNUKSJ" %}
[Create Token](/developer/reference/api-reference-xin-yong-ka/embedded-cashier/create-token.md)
{% endcontent-ref %}

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

## 三、前端

### 3.1. 引入 UseePay CDN

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

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

### 3.2. 初始化

```javascript
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                                |
| locale     | 语言              | 可从 navigator.language 中获取, 或者传递 ISO639 language code |
| merchantNo | UseePay分配的商户号   |                                                      |

### 3.3. 挂载到元素上

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

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

挂载到元素上:

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

### 3.4. 支付

#### 3.4.1 获取支付 Token （后端）

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

{% content-ref url="/pages/wE8BEQBKhclWaTxNUKSJ" %}
[Create Token](/developer/reference/api-reference-xin-yong-ka/embedded-cashier/create-token.md)
{% endcontent-ref %}

#### 3.4.2 确认支付

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

#### 4.2.1 参数说明

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

data参数详细说明

<table><thead><tr><th>参数</th><th width="249.33333333333331">描述</th><th>示例</th><th data-type="checkbox">必要</th></tr></thead><tbody><tr><td>version</td><td>max=5 交易异步通知报文版本，固定为：1.0</td><td>1.0</td><td>true</td></tr><tr><td>merchantNo</td><td>max=16 商户编号，由USEEPAY 分配</td><td></td><td>true</td></tr><tr><td>transactionId</td><td>max=64 商户订单号</td><td></td><td>true</td></tr><tr><td>originalTransactionId</td><td>max=64 原始商户订单号</td><td></td><td>false</td></tr><tr><td>reference</td><td>max=32 USEEPAY 订单号</td><td></td><td>false</td></tr><tr><td>transactionType</td><td>max=64 交易类型： pay；authorization; refund; capture;authorizationVoid;</td><td></td><td>true</td></tr><tr><td>amount</td><td>max=12 交易金额，单位为对应币种的最小货币单位(详见 ISO 4217)</td><td></td><td>false</td></tr><tr><td>currency</td><td>max=3 3 位 ISO 大写字母货币代码((详见 ISO 4217)</td><td></td><td>false</td></tr><tr><td>resultCode</td><td>max=32 业务结果（详见 业务结果码）</td><td></td><td>true</td></tr><tr><td>errorCode</td><td>max=4 错误码（详见 错误码 errorCode）</td><td></td><td>false</td></tr><tr><td>errorMsg</td><td>max=256 错误码消息描述</td><td></td><td>false</td></tr><tr><td>echoParam</td><td>max=256 回声参数，响应报文会原样返回</td><td></td><td>false</td></tr><tr><td>reserved</td><td>max=256 预留字段，值同请求报文</td><td></td><td>false</td></tr><tr><td>signType</td><td>MD5/RSA</td><td></td><td>true</td></tr><tr><td>sign</td><td>max=256 商户请求参数的签名串</td><td></td><td>true</td></tr><tr><td>issuerResponse</td><td>发卡行返回的新 Json String的格式</td><td>{"issuerResponseMsg":"Not sufficient funds","issuerResponseCode":"51"}</td><td>false</td></tr></tbody></table>

#### 3.4.3 确认支付结果

将上一步获取到的json字符串发送给您的服务器进行验证合法性与支付结果

## 四 JSSDK APIS

这里描述了JSSDK API 的详细用法

### 4.1 validate

#### 示例

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

#### 建议

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

#### 用例

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

```html
// 我只是个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

**示例**

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

#### 返回值说明

1. EVENT 为 change, 监听输入

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

## 五 、Demo 代码案例

欢迎访问我们的 [Javascript SDK Demo](https://github.com/UseePayOffical/js-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