alipay-serverless-sdk

Alipay Serverless SDK

支付宝小程序端Serverless配套SDK，让您享受极简编程体验的同时，快速集成支付宝、阿里云等阿里经济体开放的各项核心能力。

Installation 安装

npm install alipay-serverless-sdk --save
npm install @alicloud/mpserverless-sdk --save

alipay-serverless-sdk 依赖 @alicloud/mpserverless-sdk，使用时需要传入 mpserverless-sdk 实例进行初始化

Usage 快速示例

// 1. 引入必要的 sdk
import MPServerless from '@alicloud/mpserverless-sdk';
import cloud from 'alipay-serverless-sdk';

// 2. 在 app.js 中对 sdk 进行初始化
// 2.1 初始化 MPServerless
my.serverless = my.serverless || new MPServerless({
  uploadFile: my.uploadFile,
  request: my.request,
  getAuthCode: my.getAuthCode,
}, {
  // 2.2 参数能在小程序云服务空间详情中获取
  appId: '',
  spaceId: '',
  clientSecret: '',
  endpoint: ''
});
// 2.3 初始化 alipay-serverless-sdk
cloud.init(my.serverless);

// 3. 在想要使用的页面导入 alipay-serverless-sdk 即可使用
// 比如在 page.js
import cloud from 'alipay-serverless-sdk';

cloud.base.qrcode.create(urlParam, queryParam, describe);

API Doc

将API Doc中API的上两级标题中的英文（转首字符小写驼峰格式），用点号拼接在一起作为前缀，就是这个API的完整引用路径。Alipay Serverless SDK致力于保持良好的API命名，以符合开发者的编程直觉。

下面是几个典型的例子。

import cloud from 'alipay-serverless-sdk';

//调用基础能力-用户授权-获取授权访问令牌API
cloud.base.oauth.getToken

//调用营销能力-小程序模板消息-发送模板消息API
cloud.marketing.templateMessage.send

//调用营销能力-兑换券使用
cloud.marketing.exchangevoucher.use

//调用会员能力-支付宝身份认证-生成认证链接API
cloud.member.identification.certify

//调用支付能力-花呗分期-创建花呗分期交易API
cloud.payment.huabei.create

// 调用资金能力-无密转账到支付宝账户-单笔转账API
cloud.fund.transferAccount.transfer

// 调用资金能力-B2C现金红包-发放现金红包
cloud.fund.b2cRedPacket.send

//调用安全能力-文本风险识别-检测内容风险API
cloud.security.textRisk.detect

//调用阿里云能力-短信-发送API
cloud.aliyun.shortMessage.send

基础能力 Base

用户授权 OAuth

获取授权访问令牌

• API声明

getToken(code: string)

• 入参说明

字段名	类型	必填	说明
code	string	是	授权码，用户对应用授权后得到

• 出参说明

可前往alipay.system.oauth.token查看更加详细的参数说明。

刷新授权访问令牌

• API声明

refreshToken(refreshToken: string)

• 入参说明

字段名	类型	必填	说明
refreshToken	string	是	刷新令牌，上次换取访问令牌时得到，见出参的refresh_token字段

• 出参说明

可前往alipay.system.oauth.token查看更加详细的参数说明。

---

小程序二维码 Qrcode

创建小程序二维码

• API声明

create(urlParam: string, queryParam: string, describe: string)

• 入参说明

字段名	类型	必填	说明
urlParam	string	是	小程序中能访问到的页面路径，例如：page/component/component-pages/view/view
queryParam	string	是	小程序的启动参数，打开小程序的query ，在小程序 onLaunch的方法中获取
describe	string	是	二维码描述

• 出参说明

可前往alipay.open.app.qrcode.create查看更加详细的参数说明。

---

营销能力 Marketing

小程序模板消息 TemplateMessage

发送模板消息

• API声明

send(toUserId: string, formId: string, userTemplateId: string, page: string, data: string)

• 入参说明

字段名	类型	必填	说明
toUserId	string	是	发送消息的支付宝账号
formId	string	是	用户发生的交易行为的交易号，或者用户在小程序产生表单提交的表单号，用于信息发送的校验
userTemplateId	string	是	用户申请的模板id号，固定的模板id会发送固定的消息
page	string	是	小程序的跳转页面，用于消息中心用户点击之后详细跳转的小程序页面，例如：page/component/index
data	string	是	开发者需要发送模板消息中的自定义部分来替换模板的占位符，例如：{"keyword1": {"value" : "12:00"},"keyword2": {"value" : "20180808"},"keyword3": {"value" : "支付宝"}}

• 出参说明

可前往alipay.open.app.mini.templatemessage.send查看更加详细的参数说明。

---

兑换券 Exchangevoucher

创建兑换券模板

• API声明

create(outBizNo: string, brandName: string, voucherName: string, quantity: number, publishStartTime: string, publishEndTime: string, validPeriod: string, availableTime: string, description: string, extensionInfo: string)

• 入参说明

字段名	类型	必填	说明
outBizNo	string	是	外部业务单号。用作幂等控制。同一个pid下相同的外部业务单号作唯一键。
brandName	string	是	品牌名。用于在卡包中展示，长度不能超过12个字符。
voucherName	string	是	券名称。用于在卡包中展示，长度不能超过20个字符。展示的实际名称为：券名称+兑换券。如，voucher_name为咖啡。则，卡包展示名称为：咖啡兑换券。
quantity	number	是	拟发行券的数量。单位为张。该数值必须是大于0的整数。
publishStartTime	string	是	发放开始时间，早于该时间不能发券。发放开始时间不能大于当前时间15天。格式为：yyyy-MM-dd HH:mm:ss
publishEndTime	string	是	发放结束时间，晚于该时间不能发券。券的发放结束时间和发放开始时间跨度不能大于90天。发放结束时间必须晚于发放开始时间。格式为：yyyy-MM-dd HH:mm:ss
validPeriod	string	是	券有效期。具体取值规则可前往alipay.marketing.exchangevoucher.template.create查看更加详细的参数说明。
availableTime	string	是	券可用时段。具体取值规则可前往alipay.marketing.exchangevoucher.template.create查看更加详细的参数说明。
description	string	是	券使用说明。JSON数组字符串，最多可以有10条，每条最多50字。不采用时输入"[]"
extensionInfo	string	是	扩展字段，JSON字符串。具体取值规则可前往alipay.marketing.exchangevoucher.template.create查看更加详细的参数说明。

• 出参说明

可前往alipay.marketing.exchangevoucher.template.create查看更加详细的参数说明。

发放兑换券

• API声明

send(templateId: string, userId: string, outBizNo: string)

• 入参说明

字段名	类型	必填	说明
templateId	string	是	券模板ID。
userId	string	是	支付宝用户ID 。
outBizNo	string	是	外部业务订单号，用于幂等控制，相同template_id和out_biz_no认为是同一次业务。

• 出参说明

可前往alipay.marketing.voucher.send查看更加详细的参数说明。

使用兑换券

• API声明

use(voucherId: string, userId: string, outBizNo: string)

• 入参说明

字段名	类型	必填	说明
voucherId	string	是	待使用的券id ，来自发券接口alipay.marketing.voucher.send
userId	string	是	支付宝用户ID ，必须保证待使用的券ID归属于该支付宝用户ID。
outBizNo	string	是	外部业务号，用户幂等控制。相同voucher_id和out_biz_no被认为是同一次核销。

• 出参说明

可前往alipay.marketing.exchangevoucher.use查看更加详细的参数说明。

查询兑换券

• API声明

query(voucherId: string)

• 入参说明

字段名	类型	必填	说明
voucherId	string	是	券ID(券唯一标识, 发券接口返回参数) 。

• 出参说明

可前往alipay.marketing.voucher.query查看更加详细的参数说明。

---

会员能力 Member

支付宝身份认证 Identification

身份认证初始化

• API声明

init(outerOrderNo: string, bizCode: string, identityParam: IdentityParam, merchantConfig: MerchantConfig)

• 入参说明

字段名	类型	必填	说明
outerOrderNo	string	是	商户请求的唯一标识，商户要保证其唯一性，值为32位长度的字母数字组合，建议前面几位字符是商户自定义的简称，中间可以使用一段时间，后段可以使用一个随机或递增序列
bizCode	string	是	认证场景码，入参支持的认证场景码和商户签约的认证场景相关，可选值有如下，FACE：多因子人脸认证；CERT_PHOTO：多因子证照认证；CERT_PHOTO_FACE：多因子证照和人脸认证；SMART_FACE：多因子快捷认证
identityParam	IdentityParam	是	需要验证的身份信息参数
merchantConfig	MerchantConfig	是	商户个性化配置

IdentityParam对象说明

字段名	类型	必填	说明
identityType	string	是	身份信息参数类型，必须传入CERT_INFO
certType	string	是	证件类型，当前支持身份证，必须传入IDENTITY_CARD
certName	string	是	真实姓名
certNo	string	是	证件号码

MerchantConfig对象说明

字段名	类型	必填	说明
returnUrl	string	是	需要回跳的目标URL地址，一般指定为商户业务页面

• 出参说明

可前往alipay.user.certify.open.initialize查看更加详细的参数说明。

生成认证链接

• API声明

certify(certifyId: string)

• 入参说明

字段名	类型	必填	说明
certifyId	string	是	本次申请操作的唯一标识，由身份认证初始化接口调用后生成，后续的操作都需要用到

• 出参说明

可前往alipay.user.certify.open.certify查看更加详细的参数说明。

身份认证记录查询

• API声明

query(certifyId: string)

• 入参说明

字段名	类型	必填	说明
certifyId	string	是	身份认证操作的唯一标识，由身份认证初始化接口调用后生成

• 出参说明

可前往alipay.user.certify.open.query查看更加详细的参数说明。

---

支付能力 Payment

通用接口 Common

创建交易

• API声明

create(subject: string, outTradeNo: string, totalAmount: string, buyerId: string)

• 入参说明

字段名	类型	必填	说明
subject	string	是	订单标题
outTradeNo	string	是	商户订单号，64个字符以内，可包含字母、数字、下划线，需保证在商户端不重复
totalAmount	string	是	订单总金额，单位为元，精确到小数点后两位，取值范围[0.01,100000000]
buyerId	string	是	买家的支付宝用户ID，如果为空，会从传入的码值信息中获取买家ID

• 出参说明

可前往alipay.trade.create查看更加详细的参数说明。

查询交易

• API声明

query(outTradeNo: string)

• 入参说明

字段名	类型	必填	说明
outTradeNo	string	是	交易创建时传入的商户订单号

• 出参说明

可前往alipay.trade.query查看更加详细的参数说明。

交易退款

• API声明

refund(outTradeNo: string, refundAmount: string)

• 入参说明

字段名	类型	必填	说明
outTradeNo	string	是	交易创建时传入的商户订单号
refundAmount	string	是	需要退款的金额，该金额不能大于订单金额，单位为元，支持两位小数

• 出参说明

可前往alipay.trade.refund查看更加详细的参数说明。

关闭交易

• API声明

close(outTradeNo: string)

• 入参说明

字段名	类型	必填	说明
outTradeNo	string	是	交易创建时传入的商户订单号

• 出参说明

可前往alipay.trade.close查看更加详细的参数说明。

撤销交易

• API声明

cancel(outTradeNo: string)

• 入参说明

字段名	类型	必填	说明
outTradeNo	string	是	交易创建时传入的商户订单号

• 出参说明

可前往alipay.trade.cancel查看更加详细的参数说明。

---

花呗分期 Huabei

创建花呗分期交易

• API声明

create(subject: string, outTradeNo: string, totalAmount: string, buyerId: string, extendParams: HuabeiConfig)

• 入参说明

字段名	类型	必填	说明
subject	string	是	订单标题
outTradeNo	string	是	商户订单号，64个字符以内，可包含字母、数字、下划线，需保证在商户端不重复
totalAmount	string	是	订单总金额，单位为元，精确到小数点后两位，取值范围[0.01,100000000]
buyerId	string	是	买家的支付宝用户ID，如果为空，会从传入的码值信息中获取买家ID
extendParams	HuabeiConfig	是	花呗交易扩展参数

HuabeiConfig对象说明

字段名	类型	必填	说明
hbFqNum	string	是	花呗分期数，仅支持传入3、6、12
hbFqSellerPercent	string	是	代表卖家承担收费比例，商家承担手续费传入100，用户承担手续费传入0，仅支持传入100、0两种

• 出参说明

可前往alipay.trade.create查看更加详细的参数说明。

---

当面付 FaceToFace

当面付交易付款

• API声明

pay(subject: string, outTradeNo: string, totalAmount: string, authCode: string)

• 入参说明

字段名	类型	必填	说明
subject	string	是	订单标题
outTradeNo	string	是	交易创建时传入的商户订单号
totalAmount	string	是	订单总金额，单位为元，精确到小数点后两位，取值范围[0.01,100000000]
authCode	string	是	支付授权码，2530开头的长度为1624位的数字，实际字符串长度以开发者获取的付款码长度为准

• 出参说明

可前往alipay.trade.pay查看更加详细的参数说明。

---

资金能力 Fund

无密转账到支付宝账户 TransferAccount

单笔转账

• API声明

transfer(outBizNo: string, transAmount: string, payee: object, orderTitle: string)

• 入参说明

字段名	类型	必填	说明
outBizNo	string	是	商户端的唯一订单号，对于同一笔转账请求，商户需保证该订单号唯一。
transAmount	string	是	订单总金额，单位为元，精确到小数点后两位，取值范围[0.1,100000000]。
+ payee	object	是	收款方信息。
└ identity	string	是	参与方的唯一标识。
└ identity_type	string	是	参与方的标识类型，目前支持如下类型：1、ALIPAY_USER_ID 支付宝的会员ID 2、ALIPAY_LOGON_ID：支付宝登录号，支持邮箱和手机号格式。
└ name	string	否	参与方真实姓名，如果非空，将校验收款支付宝账号姓名一致性。当identity_type=ALIPAY_LOGON_ID时，本字段必填。
orderTitle	string	是	转账业务的标题，用于在支付宝用户的账单里显示。

• 出参说明

可前往alipay.fund.trans.uni.transfer查看更加详细的参数说明。

查询转账单据

• API声明

query(payFundOrderId: string)

• 入参说明

字段名	类型	必填	说明
payFundOrderId	string	是	支付宝支付资金流水号。

• 出参说明

可前往alipay.fund.trans.common.query查看更加详细的参数说明。

---

无密转账到银行卡 TransferBankcard

单笔转账

• API声明

transfer(outBizNo: string, transAmount: string, payee: object, orderTitle: string)

• 入参说明

字段名	类型	必填	说明
outBizNo	string	是	商户端的唯一订单号，对于同一笔转账请求，商户需保证该订单号唯一。
transAmount	string	是	订单总金额，单位为元，精确到小数点后两位，取值范围[0.1,100000000]。
+ payee	object	是	收款方信息。
└ identity	string	是	参与方的唯一标识。
└ identity_type	string	是	参与方的标识类型，目前支持如下类型：1、ALIPAY_USER_ID 支付宝的会员ID 2、ALIPAY_LOGON_ID：支付宝登录号，支持邮箱和手机号格式。
└ name	string	否	参与方真实姓名，如果非空，将校验收款支付宝账号姓名一致性。当identity_type=ALIPAY_LOGON_ID时，本字段必填。
orderTitle	string	是	转账业务的标题，用于在支付宝用户的账单里显示。

• 出参说明

可前往alipay.fund.trans.uni.transfer查看更加详细的参数说明。

查询转账单据

• API声明

query(payFundOrderId: string)

• 入参说明

字段名	类型	必填	说明
payFundOrderId	string	是	支付宝支付资金流水号。

• 出参说明

可前往alipay.fund.trans.common.query查看更加详细的参数说明。

---

B2C现金红包 B2cRedPacket

发放现金红包

• API声明

send(outBizNo: string, transAmount: string, payee: object, orderTitle: string)

• 入参说明

字段名	类型	必填	说明
outBizNo	string	是	商户端的唯一订单号，对于同一笔转账请求，商户需保证该订单号唯一。
transAmount	string	是	订单总金额，单位为元，精确到小数点后两位，取值范围[0.01,100000000]。
+ payee	object	是	收款方信息。
└ identity	string	是	参与方的唯一标识。
└ identity_type	string	是	参与方的标识类型，目前支持如下类型：1、ALIPAY_USER_ID 支付宝的会员ID 2、ALIPAY_LOGON_ID：支付宝登录号，支持邮箱和手机号格式。
└ name	string	否	参与方真实姓名，如果非空，将校验收款支付宝账号姓名一致性。当identity_type=ALIPAY_LOGON_ID时，本字段必填。
orderTitle	string	是	转账业务的标题，用于在支付宝用户的账单里显示。

• 出参说明

可前往alipay.fund.trans.uni.transfer查看更加详细的参数说明。

查询转账单据

• API声明

query(payFundOrderId: string)

• 入参说明

字段名	类型	必填	说明
payFundOrderId	string	是	支付宝支付资金流水号。

• 出参说明

可前往alipay.fund.trans.common.query查看更加详细的参数说明。

---

安全能力 Security

文本风险识别 TextRisk

检测内容风险

• API声明

detect(content: string)

• 入参说明

字段名	类型	必填	说明
content	string	是	待检测的文本内容

• 出参说明

可前往alipay.security.risk.content.detect查看更加详细的参数说明。

阿里云能力 Aliyun

短信 ShortMessage

发送

• API声明

send(phoneNumbers: string, signName: string, templateCode: string, templateParam: string)

• 入参说明

字段名	类型	必填	说明
phoneNumbers	string	是	短信接收号码,支持以逗号分隔的形式进行批量调用，批量上限为1000个手机号码,批量调用相对于单条调用及时性稍有延迟，验证码类型的短信推荐使用单条调用的方式；发送国际/港澳台消息时，接收号码格式为：国际区号+号码，如“85200000000”
signName	string	是	短信签名
templateCode	string	是	短信模板ID，发送国际/港澳台消息时，请使用国际/港澳台短信模版
templateParam	string	否	短信模板变量替换JSON串，例如：{"code":"1234","product":"ytx"}

• 出参说明

可前往SendSms查看更加详细的参数说明。

批量发送

• API声明

batchSend(phoneNumberJson: object, signNameJson: object, templateCode: string, templateParamJson: string)

• 入参说明

字段名	类型	必填	说明
phoneNumberJson	string	是	短信接收号码,JSON格式，批量上限为100个手机号码，批量调用相对于单条调用及时性稍有延迟，验证码类型的短信推荐使用单条调用的方式
signNameJson	string	是	JOSN格式短信签名，例如：[“云通信”,”云通信”]
templateCode	string	是	短信模板ID，发送国际/港澳台消息时，请使用国际/港澳台短信模版
templateParamJson	string	是	短信模板变量替换JSON串，例如：[{"code":"1234","product":"ytx1"},{"code":"5678","product":"ytx2"}]

• 出参说明

可前往SendBatchSms查看更加详细的参数说明。

查询

• API声明

query(phoneNumber: string, sendDate: string, pageSize: number, currentPage: number)

• 入参说明

字段名	类型	必填	说明
phoneNumber	string	是	短信接收号码,如果需要查询国际短信,号码前需要带上对应国家的区号,区号的获取详见国际短信支持国家信息查询API接口
sendDate	string	是	短信发送日期格式yyyyMMdd,支持最近30天记录查询，例如：20170525
pageSize	number	是	页大小，最大不超过50
currentPage	number	是	当前页码

• 出参说明

可前往QuerySendDetails查看更加详细的参数说明。

精准查询

• API声明

preciseQuery(phoneNumber: string, sendDate: string, pageSize: number, currentPage: number, bizId: string)

• 入参说明

字段名	类型	必填	说明
phoneNumber	string	是	短信接收号码,如果需要查询国际短信,号码前需要带上对应国家的区号,区号的获取详见国际短信支持国家信息查询API接口
sendDate	string	是	短信发送日期格式yyyyMMdd,支持最近30天记录查询，例如：20170525
pageSize	number	是	页大小，最大不超过50
currentPage	number	是	当前页码
bizId	string	是	发送流水号,从调用发送接口返回值中获取

• 出参说明

可前往QuerySendDetails查看更加详细的参数说明。

辅助工具 Util

通用 Generic

通用接口

• API声明

execute(method: string, params: object)

• 入参说明

字段名	类型	必填	说明
method	string	是	API接口名称，例如：alipay.trade.create
params	object	是	被包装在biz_content下的请求参数集合，例如：{ url_param: 'pages/cloud/cloud', query_param: 'key=value', describe: '我是二维码描述'}

• 出参说明

字段名	类型	必填	说明
code	string	是	网关返回码
msg	string	是	网关返回码描述
subCode	string	否	业务返回码，参见具体的API接口文档
subMsg	string	否	业务返回码描述，参见具体的API接口文档