# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://useepay.gitbook.io/developer/reference/api-reference-xin-yong-ka/embedded-cashier/javascript.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.