# pingpp-js

> Ping++ HTML5 SDK

Latest version **2.5.0** (published 2026-06-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install pingpp-js
pnpm add pingpp-js
yarn add pingpp-js
bun add pingpp-js
```

## Health

**Score 50/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 2.5.0 |
| Published | 2026-06-24 |
| First published | 2016-06-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 393.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 261 |
| Author | Afon |
| Maintainers | pingppdev, afon |
| Keywords | javascript, payment, library, browser |

## Links

- npm: https://www.npmjs.com/package/pingpp-js
- Repository: https://github.com/PingPlusPlus/pingpp-js
- Homepage: https://www.pingxx.com
- Issues: https://github.com/PingPlusPlus/pingpp-js/issues
- npm.io page: https://npm.io/package/pingpp-js

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 2.5.0 (latest) — 2026-06-24
- 2.3.1 — 2024-05-27
- 2.3.0 — 2023-08-25
- 2.2.27 — 2022-06-24
- 2.2.26 — 2022-04-07
- 2.2.25 — 2022-02-18
- 2.2.24 — 2021-12-01
- 2.2.23 — 2021-11-09
- 2.2.22 — 2020-12-29
- 2.2.21 — 2020-04-21
- 2.2.19 — 2020-02-12
- 2.2.18 — 2019-12-06
- 2.2.17 — 2019-11-28
- 2.2.16 — 2019-11-05
- 2.2.15 — 2019-09-11
- … 27 more at https://npm.io/package/pingpp-js/versions

## README

# Pingpp HTML5 SDK

## 目录

* [1. 使用 Ping++ SDK 标准版](#1)
	* [1.1 支持的渠道](#1.1)
	* [1.2 如何构建](#1.2)
	* [1.3 使用说明](#1.3)
	* [1.4 接入注意事项](#1.4)

* [2. 常见问题](#2)

## <h2 id='1'>使用 Ping++ SDK 标准版</h2>

### <h3 id='1.1'>支持的渠道</h3>

- 手机网页支付
    1. 支付宝手机网页支付（alipay_wap）
    2. 百度钱包手机网页支付（bfb_wap）
    3. 银联全渠道手机网页支付（upacp_wap）
    4. 微信WAP支付（wx_wap）
    5. 微信小程序支付（wx_lite）
    6. 易宝手机网页支付（yeepay_wap）
    7. 京东手机网页支付（jdpay_wap）
    8. 招行一网通支付（cmb_wallet）

- PC 网页支付
    1. 支付宝电脑网站支付 (alipay_pc_direct)
    2. 银联网关支付 (upacp_pc)
    3. 银联企业网银支付 (cp_b2b)
    4. 拉卡拉网联B2C/B2B支付

- 微信公众账号支付(wx_pub)
- QQ 公众号支付 (qpay_pub)
- 支付宝口碑 (alipay_qr)
- 线下扫码支付(isv_wap)
- 线下小程序支付(isv_lite)

### <h3 id='1.2'>如何构建</h3>

[dist](/dist) 目录下提供了已经构建好的 SDK，使用的命令是 `gulp build --alipay_in_weixin --agreement`。

#### 全局安装 gulp

``` bash
npm install -g gulp
```

#### 默认构建

默认会包含所有渠道

``` bash
npm run build
```

#### 自定义构建

安装依赖

``` bash
npm install
```

##### --channels

选择渠道，渠道字段用空格或者英文逗号分割，例：

``` bash
gulp build --channels="alipay_wap wx_pub upacp_wap"
```

可选的渠道模块请查看 [src/channels](/src/channels) 目录下的文件名

###### wx_lite

因为微信小程序中 不能使用其他支付渠道，构建时请添加该参数

``` bash
gulp build --channels=wx_lite
```

##### --name

设置对象变量名

``` bash
gulp build --name="pingppPc" --channels="alipay_pc_direct upacp_pc"
```

##### --alipay_in_weixin

如果要在微信内使用支付宝手机网页支付，请添加该参数

``` bash
gulp build --alipay_in_weixin
```

同时，将 [`alipay_in_weixin`](/alipay_in_weixin) 目录下的 [pay.htm](/alipay_in_weixin/pay.htm) 放于你服务器可访问的路径下，如下两种方法：

- 默认情况下，访问该文件的 URL 需要与你的支付页面时同级的。例：  
支付页面 URL：http://localhost/project/payment?a=b&c=d  
该文件 URL：http://localhost/project/pay.htm

- 你也可以调用 `setAPURL` 方法来自定义该文件 URL。

``` js
pingpp.setAPURL('http://localhost/your/custom/url');
```

该文件([pay.htm](/alipay_in_weixin/pay.htm))内的 `CURRENT_PAGE_URL` 变量也设置为相同的值。

##### --wx_jssdk

如果想使用微信的 JS-SDK 来调起支付，请添加该参数

``` bash
gulp build --wx_jssdk
```

##### --agreement

如果需要使用签约接口，请添加该参数

``` bash
gulp build --agreement
```

### <h3 id='1.3'>使用说明</h3>

#### 引入 JS 文件

- Browserify 打包方式

    首先使用 `npm` 下载

    ``` bash
    npm install pingpp-js
    ```

    使用

    ``` javascript
    var pingpp = require('pingpp-js');
    ```

- script 标签方式

    ``` html
    <script src="/path/to/pingpp.js"></script>
    ```

#### 使用服务端创建的 [charge](https://www.pingxx.com/docs/overview) 调用接口

``` javascript
// 参数一：支付参数 charge/order/recharge
// 参数二：支付结果回调
pingpp.createPayment(data, function(result, err) {
  if (result == "success") {
    // 只有微信公众账号 (wx_pub)、微信小程序 (wx_lite)、QQ 公众号 (qpay_pub)、支付宝口碑 (alipay_qr)
    // 支付成功的结果会在这里返回，其他的支付结果都会跳转到 extra 中对应的 URL。
  } else if (result == "fail") {
    // data 不正确或者微信公众账号/微信小程序/QQ 公众号/支付宝口碑支付失败时会在此处返回
  } else if (result == "cancel") {
    // 微信公众账号、微信小程序、QQ 公众号、支付宝口碑支付取消支付
  }
});
```

如果 `charge` 正确的话，会跳转到相应的支付页面，要求用户进行付款。

用户支付成功后，会跳转到创建 `charge` 时定义的 `result_url` 或者 `success_url`。如果用户取消支付，则会跳转到 `result_url` 或者 `cancel_url`（具体情况根据渠道不同会有所变化）。

#### 如果不想直接跳转到支付页面，而是获取支付页面地址

在调用 `pingpp.createPayment` 之前，调用

```javascript
pingpp.setUrlReturnCallback(callback, channels);
```

##### 参数 callback

回调函数

- 第一个参数接受错误信息，没有错误时为 null。
- 第二个参数为支付界面地址的值。

##### 参数 channels

需要启用该功能的渠道列表，类型为 `array`。默认值为 `['alipay_pc_direct']`。

##### 示例

```javascript
pingpp.setUrlReturnCallback(function (err, url) {
  // 自行处理跳转或者另外打开支付页面地址(url)
  // window.location.href = url;
}, ['alipay_pc_direct', 'alipay_wap']);
```

#### 调用签约接口

从服务端获取 `agreement` 对象之后，调用

```js
pingpp.signAgreement(agreement, callback);
```

签约接口在对象不正确等情况下，会回调 `callback`。

如果对象正确，则会跳转到相应的签约页面，签约结果**不会**在 `callback` 返回，需要商户自己调用服务端接口查询 `agreement` 状态。

### <h3 id='1.4'>微信公众号接入注意事项</h3>

_以下示例中，Server-SDK 以 `php` 为例，其他语言请参考各语言 SDK 的文档或者示例_

#### 关于 open_id

##### 用 Server-SDK 取得 `open_id`（微信公众号授权用户唯一标识）。

先跳转到微信获取`授权 code`，地址由下方代码生成，`$wx_app_id` 是你的`微信公众号应用唯一标识`，`$redirect_url` 是用户确认授权后跳转的地址，用来接收 `code`。

```php
<?php
$url = \Pingpp\WxpubOAuth::createOauthUrlForCode($wx_app_id, $redirect_url);
header('Location: ' . $url);
```

用户确认授权后，使用 `code` 获取 `open_id`，其中 `$wx_app_secret` 是你的`微信公众号应用密钥`

```php
<?php
$code = $_GET['code'];
$open_id = \Pingpp\WxpubOAuth::getOpenid($wx_app_id, $wx_app_secret, $code);
```

##### 将 `open_id` 作为创建 `charge` 时的 `extra` 参数，具体方法参考[技术文档](https://www.pingxx.com/api#%E6%94%AF%E4%BB%98%E6%B8%A0%E9%81%93-extra-%E5%8F%82%E6%95%B0%E8%AF%B4%E6%98%8E)，例：

```json
{
  "order_no":  "1234567890",
  "app":       {"id": "app_1234567890abcDEF"},
  "channel":   "wx_pub",
  "amount":    100,
  "client_ip": "127.0.0.1",
  "currency":  "cny",
  "subject":   "Your Subject",
  "body":      "Your Body",
  "extra": {
    "open_id": open_id
  }
}
```

##### 得到 `charge` 后，在页面中引用 `pingpp.js`，调用 `pingpp.createPayment`，结果会直接在 `callback` 中返回。

```js
pingpp.createPayment(charge, function(result, err) {
  if (result=="success") {
    // payment succeeded
  } else {
    console.log(result+" "+err.msg+" "+err.extra);
  }
});
```

### 微信小程序接入注意事项

_以下示例中，Server-SDK 以 `php` 为例，其他语言请参考各语言 SDK 的文档或者示例_

#### 关于 open_id

##### 小程序的 `code` 获取跟公众号的有些不同，小程序是有自己的 `API` 可以在客户端直接获取 `code`。

```js
wx.login({
  success: function(res) {
    if(res.code){
      console.log('code = ' + res.code);
    }else{
     console.log('获取用户登录态失败！' + res.errMsg);
    }
  }
});
```

##### 得到 `code` 之后 以 `GET`的方式，请求你自己的服务端。然后在服务端使用 `code` 来获取 `open_id`，其中 `$wx_app_id` 是你的`微信AppID(小程序ID) ` ，`$wx_app_secret` 是你的`微信小程序密钥` 。

```php
<?php
$code = $_GET['code'];
$open_id = \Pingpp\WxpubOAuth::getOpenid($wx_app_id, $wx_app_secret, $code);
```

##### 将 `open_id` 作为创建 `charge` 时的 `extra` 参数，具体方法参考[技术文档](https://www.pingxx.com/api#%E6%94%AF%E4%BB%98%E6%B8%A0%E9%81%93-extra-%E5%8F%82%E6%95%B0%E8%AF%B4%E6%98%8E)，例：

```json
{
  "order_no":  "1234567890",
  "app":       {"id": "app_1234567890abcDEF"},
  "channel":   "wx_lite",
  "amount":    100,
  "client_ip": "127.0.0.1",
  "currency":  "cny",
  "subject":   "Your Subject",
  "body":      "Your Body",
  "extra": {
    "open_id": open_id
  }
}
```

##### 得到 `charge` 后，在页面中引用 `pingpp.js` ，调用 `pingpp.createPayment`，结果会直接在 `callback` 中返回。

```js
pingpp.createPayment(charge, function(result, err) {
  if (result=="success") {
    // payment succeeded
  } else {
    console.log(result+" "+err.msg+" "+err.extra);
  }
});
```

## <h2 id='2'>常见问题</h3>

#### 问题一: H5 页面微信公众号支付调用 Ping++ 提示失败 (来源：工单)

返回结果: `get_brand_wcpay_request: fail`

- 报错原因：微信授权目录填写错误。
- 解决方案：详见[帮助中心](https://help.pingxx.com/article/123339)

#### 问题二：微信内调用支付宝没出现引导界面，只有复制链接到浏览器

- 报错原因：pay.htm 路径出错
- 解决方案：
    1. 默认情况下，访问该文件的 URL 需要与你的支付页面时同级的。例：  
        支付页面 URL：http://localhost/project/payment?a=b&c=d  
        该文件 URL：http://localhost/project/pay.htm
    2. 你也可以调用 `setAPURL` 方法来自定义该文件 URL。

        ``` js
        pingpp.setAPURL('http://localhost/your/custom/url');
        ```

        该文件([pay.htm](/alipay_in_weixin/pay.htm))内的 `CURRENT_PAGE_URL` 变量也设置为相同的值。

#### 问题三：调不起支付，返回报错信息 json_decode_fail

- 报错原因：传入的参数不是正确的 JSON 字符串或者 JSON 对象
- 解决方案：客户端调用 SDK 时，确认服务端输出到客户端时，数据的正确性。

---
_Source: https://npm.io/package/pingpp-js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._