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 | 是 | 支付授权码，25~30开头的长度为16~24位的数字，实际字符串长度以开发者获取的付款码长度为准 |

• 出参说明

可前往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接口文档 |