alipay.js.org

支付宝 OpenAPI SDK

Yet Another Alipay OpenAPI Smart Development Kit

主要功能

OOP风格化的，可弹性扩容的，支付宝OpenAPI SDK
低依赖，目前仅依赖 Axios
使用Node原生代码实现支付宝OpenAPI的AES(aes-128-cbc)加/解密功能
使用Node原生代码实现支付宝OpenAPI的RSA(sha1WithRSAEncryption)及RSA2(sha256WithRSAEncryption)签名、验签功能
异步通知消息验签
命令行网关交互工具

SDK约定

使用 method({请求参数}[, {公共请求参数}[, {特殊头参数}]]) 作为HTTP接口驱动，释义如下：
- 接口定义中公共请求参数的 method，即作为本SDK标准方法链，弹性扩容，示例使用方法如下，详细审查见文末
- 接口定义中的请求参数，以 Object 对象作为第一个入参
- 接口定义中的公共请求参数，以 Object 对象作为第二个入参
- 特别的，对于图片/视频上传，需要定义 multipart/form-data 头信息，以 Object 对象作为第三个入参，见如下示例
- 特别的，对于页面表单提交型，即所谓的page类接口，第三参数须定义为 Formatter.page，返回结果可直接作为页面/接口输出，说明用法见如下示例
请求数据签名以及返回数据验签均自动完成，开发者仅需关注业务代码即可；特别地，对于验签结果有依赖的情况，可以从返回值的头部获取：
- headers[x-alipay-verified] 为验签结果，值可能为 ok, undefined
- headers[x-alipay-signature] 为源返回数据签名值，值可能为 undefined
- headers[x-alipay-responder] 为源返回值字段名转译，值可能为 undefined, error 或者实际请求的 method 值

使用手册

whatsCli 命令行工具

以命令行的形式，与OpenAPI网关交互，play the OpenAPI requests over command line.

$ ./node_modules/.bin/whatsCli -h (click to toggle display)

``` Usage: cli.js [options] Options: -k, --privateKey The privateKey pem file path [required] -p, --publicCert The publicCert pem file path [required] -m, --method The method, eg: alipay.trade.query [required] -s, --search The search parameters, eg: search.app_id=2088 [required] -b, --biz The biz_content, eg: biz.out_trade_no=abcd1234 [required] -d, --log Turn on the request trace log [boolean] -u, --baseURL The OpenAPI gateway, eg: https://openapi.alipaydev.com/gateway.do -h, --help Show help [boolean] -V, --version Show version number [boolean] Examples: cli.js -k merchant.key -p alipay.pub -m alipay.trade.pay The Face2Face barCode scenario -s.app_id=2088 -b.subject=HelloKitty -b.out_trade_no=Kitty0001 -b.scene=bar_code -b.total_amount=0.01 -b.auth_code= cli.js -k merchant.key -p alipay.pub -m alipay.trade.refund The trade refund scenario -s.app_id=2088 -b.refund_amount=0.01 -b.refund_currency=CNY -b.out_trade_no=Kitty0001 cli.js -d -u https://openapi.alipaydev.com/gateway.do -k The trade query scenario over the sandbox environment merchant.key -p alipay.pub -m alipay.trade.query with trace logging -s.app_id=2088 -b.out_trade_no=Kitty0001 ```

certHelper 命令行工具

$ ./node_modules/.bin/certHelper -h (click to toggle display)

``` Usage: cert.js [command] [options] Commands: cert.js SN Get the certificatie(s) `SN` [default] cert.js extract Extract the chained certificate(s) Options: -f, --file The certificate(s) file path [required] -p, --pattern The algo prefix or suffix, dot(.) for all -h, --help Show help [boolean] -V, --version Show version number [boolean] Examples: cert.js SN -f alipayRootCert.crt get the `sha256`(default) certificate `SN` cert.js SN -f alipayRootCert.crt -p ec get the signatureAlgorithm whose contains `ec` words certificate `SN` cert.js SN -f alipayRootCert.crt -p . get all chained certificate(s) `SN` cert.js extract -f alipayRootCert.crt extract the `sha256`(default) certificate cert.js extract -f alipayRootCert.crt -p sha1 extract the `sha1` certificate cert.js extract -f alipayRootCert.crt -p . extract all chained certificate(s) cert.js extract -f alipayRootCert.crt -p sha1 | openssl x509 piped openssl x509 command -noout -text cert.js extract -f alipayRootCert.crt -p sha1 > tmp.pem save to a file ```

此命令行工具，主要是用来计算并获取 公钥证书模式 所需的应用公钥证书SN(app_cert_sn)及支付宝公钥证书SN(alipay_root_cert_sn)。

./bin/cert.js SN -f /path/your/app_cert.crt

./bin/cert.js SN -f /path/your/alipay_root_cert.crt -p RSAEncryption

而SN 命令是 Helpers.SN 的语法糖，可从如下API文档查看更详细用法

初始化

const {readFileSync} = require('fs')
const {Alipay} = require('whats-alipay')

//应用app_id
const app_id = '2014072300007148'

//商户私钥证书，须完整格式，同时支持 `PKCS#1` `PKCS#8` 格式
const privateKey = readFileSync('/your/openapi/private_key.pem')

//支付宝公钥证书，须完整格式，同时支持 `PKCS#1` `PKCS#8` 格式
const publicCert = readFileSync('/the/alipay/public_cert.pem')

const whats = new Alipay({ privateKey, publicCert, params: { app_id, } })

证书完整格式 是指：包含 -----BEGIN 及 -----END，内容是列宽64的base64-encoded字符串，可直接用 openssl 命令行工具进行验证格式。

统一收单线下交易查询

whats
  .alipay.trade.query({out_trade_no})
  .then(({headers,data}) => ({headers,data}))
  .catch(({response: {data}}) => data)
  .then(console.log)

$ console.log sample result (click to toggle display)

```javascript { headers: { server: 'Tengine/2.1.0', date: 'Fri, 25 Sep 2020 03:27:32 GMT', 'content-type': 'text/html;charset=utf-8', 'content-length': '829', connection: 'close', 'set-cookie': [ 'JSESSIONID=6FF6F65BB1EC785992117C95EA7C27BB; Path=/; HttpOnly', 'spanner=ubOmkyHGnYLtouOsffShT4n70pJgSji6Xt2T4qEYgj0=;path=/;secure;' ], via: 'spanner-internet-5396.sa127[200]', 'x-alipay-responder': 'alipay.trade.query', 'x-alipay-signature': 'gALtsKSWEWRG4wSx8f1aPcLXYrro3ZLGplxNWerZkIAGR4qNz3fP4JCjdRx2M4uFfLfL1uIQ/L1Rt/oZD+NVKn46rLj7YLXWz2jTEnPPofgXywhwHIZ/MfrRc1DjL0xAh00OI6Gur2lileXmn7zaOG0RQoc0mXkSO5AwLWbiO0EnSoh3897TgQFp1hRDpTpXjnxvKSSFiUgr4EDCklfJbc6B3I1i3BvHtzB+lXtHPABukAvzJD/QtjjglIyOeZZ03699cCEl2JmJYGdA1Du+bBjsycLogCNXBLCmdOi5ntRVEo/Tlvl0QYTRleC7dGuCCn1ousZXLy09VUzJ1m85Fw==', 'x-alipay-verified': 'ok' }, data: { code: '10000', msg: 'Success', buyer_logon_id: '134******38', buyer_pay_amount: '183.00', buyer_user_id: '2088101117955611', fund_bill_list: [ { amount: '183.00', fund_channel: 'ALIPAYACCOUNT' } ], invoice_amount: '183.00', out_trade_no: '6823789339978248', point_amount: '0.00', receipt_amount: '183.00', send_pay_date: '2020-09-19 17:00:28', total_amount: '183.00', trade_no: '2013112011001004330000121536', trade_status: 'TRADE_SUCCESS' } } ```

统一收单交易支付接口

whats
  .alipay.trade.pay({
    out_trade_no,
    scene,
    auth_code,
    product_code,
    subject,
    total_amount,
  })
  .then(({data}) => data)
  .catch(({response: {data}}) => data)
  .then(console.log)

统一收单线下交易预创建

whats
  .alipay.trade.precreate({
    out_trade_no,
    subject,
    total_amount,
  })
  .then(({data}) => data)
  .catch(({response: {data}}) => data)
  .then(console.log)

手机网站支付接口2.0

whats
  .alipay.trade.wap.pay({
    out_trade_no,
    subject,
    total_amount,
    product_code,
    quit_url,
  }, {}, Formatter.page)
  .then(res => res)
  .then(console.log)

注: 特别地 res 结构做了优化，直接支持 literal(独立服务模式: ${res}) 或者 JSON.stringify (二次接口模式: JSON.stringify(res))

统一收单下单并支付页面接口

whats
  .alipay.trade.page.pay({
    out_trade_no,
    subject,
    total_amount,
    product_code,
  }, {return_url}, Formatter.page)
  .then(res => res)
  .then(console.log)

注: 特别地 res 结构做了优化，直接支持 literal(独立服务模式: ${res}) 或者 JSON.stringify (二次接口模式: JSON.stringify(res))

订单咨询服务

whats
  .alipay.trade.advance.consult({/*文档上的参数就好*/})
  .then(({data}) => data)
  .catch(({response: {data}}) => data)
  .then(console.log)

口碑营销活动列表查询

whats
  .koubei.marketing.campaign.activity.batchquery(/*文档上的参数就好*/})
  .then(({data}) => data)
  .catch(({response: {data}}) => data)
  .then(console.log)

支付API > 图片上传

const {Form} = require('whats-alipay')
const payload = new Form()
payload.append('image_content', require('fs').readFileSync('/path/for/uploading.jpg'), 'uploading.jpg')

whats
  .ant.merchant.expand.indirect.image.upload(
    payload.getBuffer(),
    {image_type: 'jpg'},
    {...payload.getHeaders()}
  )
  .then(({data}) => data)
  .catch(({response: {data}}) => data)
  .then(console.log)

店铺API > 上传门店照片和视频接口

const {Form} = require('whats-alipay')
const payload = new Form()
payload.append('image_content', require('fs').readFileSync('/path/for/uploading.jpg'), 'uploading.jpg')

whats
  .alipay.offline.material.image.upload(
    payload.getBuffer(),
    {image_type: 'jpg', image_name: 'uploading.jpg'},
    {...payload.getHeaders()}
  )
  .then(({data}) => data)
  .catch(({response: {data}}) => data)
  .then(console.log)

芝麻信用API > 授权查询

whats
  .zhima.auth.info.authquery(/*文档上的参数就好*/})
  .then(({data}) => data)
  .catch(({response: {data}}) => data)
  .then(console.log)

车主服务API > 车辆驶入接口

whats
  .alipay.eco.mycar.parking.enterinfo.sync(/*文档上的参数就好*/})
  .then(({data}) => data)
  .catch(({response: {data}}) => data)
  .then(console.log)

资金API > 单笔转账接口

whats
  .alipay.fund.trans.uni.transfer(/*文档上的参数就好*/})
  .then(({data}) => data)
  .catch(({response: {data}}) => data)
  .then(console.log)

何以弹性扩容

whats 上绑定多少 method，即扩容至多少，以上示例打印如下：

$ console.info sample result (click to toggle display)

```javascript console.info(whats) [Function (anonymous)] { ant: [Function: ant] { merchant: [Function: ant.merchant] { expand: [Function: ant.merchant.expand] { indirect: [Function: ant.merchant.expand.indirect] { image: [Function: ant.merchant.expand.indirect.image] { upload: [Function: ant.merchant.expand.indirect.image.upload] } } } } }, alipay: [Function: alipay] { trade: [Function: alipay.trade] { query: [Function: alipay.trade.query], precreate: [Function: alipay.trade.precreate], advance: [Function: alipay.trade.advance] { consult: [Function: alipay.trade.advance.consult] }, page: [Function: alipay.trade.page] { pay: [Function: alipay.trade.page.pay] }, wap: [Function: alipay.trade.wap] { pay: [Function: alipay.trade.wap.pay] } }, fund: [Function: alipay.fund] { trans: [Function: alipay.fund.trans] { uni: [Function: alipay.fund.trans.uni] { transfer: [Function: alipay.fund.trans.uni.transfer] } } }, eco: [Function: alipay.eco] { mycar: [Function: alipay.eco.mycar] { parking: [Function: alipay.eco.mycar.parking] { enterinfo: [Function: alipay.eco.mycar.parking.enterinfo] { sync: [Function: alipay.eco.mycar.parking.enterinfo.sync] } } } }, offline: [Function: alipay.offline] { material: [Function: alipay.offline.material] { image: [Function: alipay.offline.material.image] { upload: [Function: alipay.offline.material.image.upload] } } } }, zhima: [Function: zhima] { auth: [Function: zhima.auth] { info: [Function: zhima.auth.info] { authquery: [Function: zhima.auth.info.authquery] } } }, koubei: [Function: koubei] { marketing: [Function: koubei.marketing] { campaign: [Function: koubei.marketing.campaign] { activity: [Function: koubei.marketing.campaign.activity] { batchquery: [Function: koubei.marketing.campaign.activity.batchquery] } } } } } ```

Alipay 类实例链如下:

$ console.info sample result (click to toggle display)

```javascript console.info(Alipay) <ref *1> [class Alipay] { default: [Circular *1], Alipay: [Circular *1], Rsa: <ref *2> [class Rsa] { default: [Circular *2] }, Aes: <ref *3> [class Aes] { default: [Circular *3], AesCbc: [class AesCbc extends Aes] }, AesCbc: [class AesCbc extends Aes], Form: <ref *4> [class Form] { default: [Circular *4] }, Formatter: <ref *5> [class Formatter] { default: [Circular *5] }, Decorator: <ref *6> [class Decorator] { default: [Circular *6], [Symbol(PRIVATE_KEY)]: <Buffer 2d 2d 2d 2d 2d 42 45 47 49 4e 20 50 52 49 56 41 54 45 20 4b 45 59 2d 2d 2d 2d 2d 0a 4d 49 49 45 76 67 49 42 41 44 41 4e 42 67 6b 71 68 6b 69 47 39 77 ... 1653 more bytes>, [Symbol(PUBLIC_CERT)]: <Buffer 2d 2d 2d 2d 2d 42 45 47 49 4e 20 50 55 42 4c 49 43 20 4b 45 59 2d 2d 2d 2d 2d 0a 4d 49 49 42 49 6a 41 4e 42 67 6b 71 68 6b 69 47 39 77 30 42 41 51 45 ... 400 more bytes>, [Symbol(CLIENT)]: [Function: wrap] { request: [Function: wrap], getUri: [Function: wrap], delete: [Function: wrap], get: [Function: wrap], head: [Function: wrap], options: [Function: wrap], post: [Function: wrap], put: [Function: wrap], patch: [Function: wrap], defaults: { method: 'post', headers: { common: { Accept: 'application/json, text/plain, */*' }, delete: {}, get: {}, head: {}, post: { 'Content-Type': 'application/x-www-form-urlencoded' }, put: { 'Content-Type': 'application/x-www-form-urlencoded' }, patch: { 'Content-Type': 'application/x-www-form-urlencoded' }, 'User-Agent': 'WhatsAlipay/0.0.9 Node/14.5.0 darwin/x64' }, params: { app_id: '2014072300007148', format: 'JSON', charset: 'utf-8', sign_type: 'RSA2', version: '1.0' }, baseURL: 'https://openapi.alipay.com/gateway.do', transformRequest: [ [Function: transformRequest] ], transformResponse: [ [Function: verifier], [Function: transformResponse] ], timeout: 0, adapter: [Function: httpAdapter], xsrfCookieName: 'XSRF-TOKEN', xsrfHeaderName: 'X-XSRF-TOKEN', maxContentLength: -1, maxBodyLength: -1, validateStatus: [Function: validateStatus] }, interceptors: { request: InterceptorManager { handlers: [ { fulfilled: [Function: signer], rejected: undefined } ] }, response: InterceptorManager { handlers: [] } } } } } ```

异步通知消息验签

通知消息验签，依赖相关 webserver 提供的 POST 数据解析能力，以下函数在 http.createServer 上做过验证，仅供参考。

function notificationValidator(things, publicCert, withoutSignType = true) {
  const {groups: {sign}} = (typeof things === 'string' ? things : '').match(/\bsign=(?<sign>[^&]+)/) || {groups: {}}
  const source = [...new URLSearchParams(things)].reduce((des, [key, value]) => (des[key] = value, des), {})
  const signType = source['sign_type']
  const signature = (source.sign || '').replace(/ /g, '+').replace(/_/g, '/')
  // The signature with `sign_type` is only for the notifications whose come from `alipay.open.public.*` APIs.
  if (withoutSignType) {
      delete source['sign_type']
  }

  return Rsa.verify(Formatter.queryStringLike(Formatter.ksort(source)), sign || signature, publicCert, signType)
}

API(s)

Manually generated by for f in lib/*.js; do ./node_modules/.bin/jsdoc2md -d 3 $f; done

Classes

Aes: Aes - Advanced Encryption Standard
AesCbc: AesCbc

Aes

Aes - Advanced Encryption Standard

Kind: global class

Aes
- new Aes()
- .hex
- .utf8
- .base64
- .BLOCK_SIZE
- .MODE_CBC
- .detector(cipherkey, [mode]) ⇒ array

new Aes()

To prevent new operation, works only as static class.

Aes.hex

Kind: static property of Aes Properties

Name	Type	Description
hex	`string`	Alias of `hex` string

Aes.utf8

Kind: static property of Aes Properties

Name	Type	Description
utf8	`string`	Alias of `utf8` string

Aes.base64

Kind: static property of Aes Properties

Name	Type	Description
base64	`string`	Alias of `base64` string

Aes.BLOCK_SIZE

Kind: static property of Aes Properties

Name	Type	Description
BLOCK_SIZE	`integer`	The `aes` block size

Aes.MODE_CBC

Kind: static property of Aes Properties

Name	Type	Description
MODE_CBC	`string`	The `cbc` mode string

Aes.detector(cipherkey, [mode]) ⇒ `array`

Detect the algo with given cipherkey length and mode.

Kind: static method of Aes Returns: array - - [algorithm, key] pairs

Param	Type	Description
cipherkey	`string`	Based64 encoded key string.
[mode]	`string`	The `mode` string, default is `this.MODE_CBC`.

AesCbc

Kind: global class

AesCbc
- .encrypt(plaintext, cipherkey, [iv]) ⇒ string
- .decrypt(ciphertext, cipherkey, [iv]) ⇒ string

AesCbc.encrypt(plaintext, cipherkey, [iv]) ⇒ `string`

Encrypts plaintext.

Kind: static method of AesCbc Returns: string - Base64-encoded ciphertext.

Param	Type	Description
plaintext	`string`	Text to encode.
cipherkey	`string`	The secret key, base64 encoded string.
[iv]	`string` \| `buffer`	The initialization vector, 16 bytes string or buffer, default is `0{16}` buffer.

AesCbc.decrypt(ciphertext, cipherkey, [iv]) ⇒ `string`

Decrypts ciphertext.

Kind: static method of AesCbc Returns: string - Utf-8 plaintext.

Param	Type	Description
ciphertext	`string`	Base64-encoded ciphertext.
cipherkey	`string`	The secret key, base64 encoded string.
[iv]	`string` \| `buffer`	The initialization vector, 16 bytes string or buffer, default is `0{16}` buffer.

Classes

Alipay: Whats Alipay Core

Functions

get(target, property) ⇒ object

Alipay

Whats Alipay Core

Kind: global class

Alipay
- new Alipay(config)
- .handler
- .compose([prefix], [suffix]) ⇒ Proxy
- .chain(method) ⇒ function

new Alipay(config)

To compose the method chain.

Param	Type	Description
config	`object`	The configuration passed in `Decorator`.
config.privateKey	`string` \| `Buffer`	The merchant’s RSA’s private key.
config.publicCert	`string` \| `Buffer`	The alipay’s RSA’s pubkey or certificate(recommend).
[config.params]	`object`	The general parameters.
[config.params.app_id]	`string` \| `number`	The merchant’s application id.
[config.params.app_auth_token]	`string`	The merchant’s authorization token.
[config.params.app_cert_sn]	`string`	The merchant’s RSA’s certificate SN.
[config.params.alipay_root_cert_sn]	`string`	The alipay’s RSA’s certificate SN.

Alipay.handler

Kind: static property of Alipay Properties

Name	Type	Description
handler	`object`	A `Getter` handler object

Alipay.compose([prefix], [suffix]) ⇒ `Proxy`

Compose a named function with prefix and suffix whose joined by a dot(.)

Kind: static method of Alipay Returns: Proxy - - With a special Getter Function.

Param	Type	Description
[prefix]	`string`	The prefix string.
[suffix]	`string`	The suffix string.

Alipay.chain(method) ⇒ `function`

Chain the input method

Kind: static method of Alipay Returns: function - - Named as given method function

Param	Type	Description
method	`string`	The naming string.

get(target, property) ⇒ `object`

Kind: global function Returns: object - - An object or object’s property

Param	Type	Description
target	`object`	The object
property	`string`	The property

Properties

Name	Type	Description
get	`function`	Object’s `getter` handler

Decorator

Decorate the Axios instance

Kind: global class

Decorator
- new Decorator(config)
- .client
- .privateKey
- .publicCert
- .requestInterceptor
- .responseVerifier
- .defaults
- .request(config) ⇒ PromiseLike
- .withDefaults(config) ⇒ object