payment常见问题我要提意见
Payment模块管理支付功能,用于提供网页安全支付能力,支持通过Web接口进行支付操作。通过plus.payment可获取支付管理对象。
支付接口可使得网页开发人员能获取浏览器支持的支付渠道进行支付操作,而不需要安装额外的浏览器支付插件。 规范不定义支付渠道安全认证及支付操作通讯协议,由运行环境的支付模块根据支付服务器接入规范实现。
方法:
- getChannels: 获取支付通道
- request: 请求支付操作
对象:
- PaymentChannel: 支付通道对象
- OrderStatementIAP: IAP订单数据对象
- PaymentResult: 支付操作结果对象
- IAPProduct: IAP商品对象
- IAPProductInfo: 购买IAP商品对象
- IAPTransaction: 购买IAP商品交易信息对象
- GooglePayOptions: 判断谷歌支付是否可用参数对象
回调方法:
- ChannelsSuccessCallback: 获取支付通道成功回调
- IapRequestOrderSuccessCallback: 请求支付商品列表回调方法
- IapRestoreComplateRequestCallback: 请求已经购买的非消耗性商品和订阅商品回调方法
- IapPaymentSuccessCallback: IAP支付操作成功回调
- PaymentSuccessCallback: 支付操作成功回调
- PaymentErrorCallback: 支付操作失败回调
权限:
permissions
{
// ...
"permissions":{
// ...
"Payment": {
"description": "支付"
}
}
}
getChannels
获取支付通道
void plus.payment.getChannels(successCB, errorCB);
说明:
在进行支付操作前需获取终端支持的支付通道列表,用于提示用户进行选择。 获取支付通道成功后通过successCB回调返回支持的所有通道列表,获取支付通道列表失败则通过errorCB回调返回。
参数:
- successCB:
(
ChannelsSuccessCallback
)
必选 获取支付通道成功回调函数
获取支付通道列表成功时的回调函数,用于返回终端支持的支付通道列表。
- errorCB:
(
PaymentErrorCallback
)
可选 获取支付通道失败回调函数
获取支付通道列表失败时的回调函数,用于返回错误信息。
返回值:
void : 无平台支持:
- Android - 2.2+ (支持)
- iOS - 5.0+ (支持)
示例:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>Payment Example</title>
<script type="text/javascript">
var channels=null;
// 监听plusready事件
document.addEventListener("plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.payment.getChannels( function(s){
channels = s;
}, function(e){
alert( "获取支付通道列表失败:"+e.message );
});
}, false );
</script>
</head>
<body>
</body>
</html>
request
请求支付操作
void plus.payment.request(channel, statement, successCB, errorCB);
说明:
调用指定的支付通道进行支付操作,其中statement包含支付操作的相关信息,支付模块将弹出支付界面供用户进行支付信息的输入确认操作。 用户支付操作成功后通过successCB回调返回支付操作结果,支付操作失败则通过errorCB回调返回。
参数:
- channel:
(
PaymentChannel
)
必选 支付通道
指定支付操作的通道,通过getChannels接口获取。
- statement:
(
String
|
JSON
|
OrderStatementIAP
)
必选 支付订单信息
支付订单信息,由支付通道定义的数据格式,通常是由业务服务器生成或向支付服务器获取,是经过加密的字符串信息。
- successCB:
(
PaymentSuccessCallback
|
IapPaymentSuccessCallback
)
可选 请求支付成功回调函数
请求支付成功时触发,用于返回支付结果。
- errorCB:
(
PaymentErrorCallback
)
可选 请求支付失败回调函数
请求支付失败时触发,用于返回错误信息。
返回值:
void : 无平台支持:
- Android - 2.2+ (支持)
- iOS - 5.0+ (支持)
示例:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>Payment Example</title>
<script type="text/javascript">
var channels=null;
// 监听plusready事件
document.addEventListener("plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.payment.getChannels(function(s){
channels = s;
}, function(e){
alert("获取支付通道列表失败:"+e.message);
});
}, false );
// 请求支付操作
function requestPay(c){
// 必须从业务服务器获取支付信息
var statement = "...";
plus.payment.request(c, statement, function(){
alert("支付操作成功!");
}, function(e){
alert("支付失败:"+e.message);
} );
}
</script>
</head>
<body>
<button onclick="requestPay(channels)">请求支付</button>
</body>
</html>
PaymentChannel
支付通道对象
interface plus.payment.PaymentChannel{
attribute String id;
attribute String description;
attribute Boolean serviceReady;
function void installService();
// iOS iAP
function void requestOrder(ids, successCB, errorCB);
function void restoreComplateRequest(options, successCB);
function void finishTransaction(transaction, successCB, errorCB);
// Google Pay
function void isReadyToPay(options, successCB, errorCB);
}
说明:
PaymentChannel对象表示特定的支付通道,用于向系统请求支付操作。
属性:
- id: 支付通道标识
- description: 支付通道描述
- serviceReady: 支付通道服务是否安装
方法:
- installService: 安装支付通道依赖的服务
- requestOrder: 向IAP服务器请求支付订单
- restoreComplateRequest: 向IAP服务器请求已经购买的非消耗性商品和订阅商品
- finishTransaction: 向IAP服务器请求关闭订单
- isReadyToPay: 判断当前设备是否支持谷歌支付(Google Pay)
id
支付通道标识
说明:
String 类型 只读属性
用于标识支付通道: "alipay" - 表示支付宝; "wxpay" - 表示微信支付; "appleiap" - 表示苹果应用内支付; "qhpay" - 表示360聚合支付(仅360手助流应用环境下支持)。
平台支持:
- Android - 2.2+ (支持)
- iOS - 5.0+ (支持)
description
支付通道描述
说明:
String 类型 只读属性
支付通道的描述信息,如“支付宝”、“微信”、“In-App Purchase”。
平台支持:
- Android - 2.2+ (支持)
- iOS - 5.0+ (支持)
serviceReady
支付通道服务是否安装
说明:
Boolean 类型 只读属性
通常特定的支付通道依赖系统安装相关的服务,此属性用于标识其服务是否安装,如果没有安装则为false,否则为true。 若系统环境中没有安装相关的服务,则可能导致调用支付操作失败,这时可以调用installService方法进行安装。 注意:如果支付通道不需要依赖系统安装服务,则永远返回true。例如支付宝,如果设备上未安装支付宝客户端则调用Wap页面进行支付,因此值固定返回true; 而微信支付则依赖微信客户端,如果设备上未安装微信客户端则serviceReady值为false,此时应该提示用户安装微信客户端才能进行支付操作。
平台支持:
- Android - 2.2+ (支持)
- iOS - 5.0+ (支持)
installService
安装支付通道依赖的服务
void pay.installService();
说明:
对于某些支付通道,通常特定的支付通道依赖系统安装相关的服务,调用此方法将安装其依赖的支付服务。 如支付宝,则在系统中安装支付宝客户端程序。
参数:
无
返回值:
void : 无平台支持:
- Android
- 2.2+
(支持)
:
支付宝:支付操作可不依赖系统环境服务,此方法不做任何操作。 当调用plus.payment.request请求支付操作时如果系统环境中已经安装“支付宝钱包”则会调用支付宝钱包进行支付,否则调用Webview窗口进行支付。
- iOS
- 5.0+
(支持)
:
支付宝:支付操作可不依赖系统环境服务,此方法不做任何操作。 当调用plus.payment.request请求支付操作时如果系统环境中已经安装“支付宝钱包”则会调用支付宝钱包进行支付,否则调用Webview窗口进行支付。
示例:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>Payment Example</title>
<script type="text/javascript">
var channels=null;
// 监听plusready事件
document.addEventListener("plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.payment.getChannels(function(s){
channels = s;
}, function(e){
alert("获取支付通道列表失败:"+e.message);
});
}, false);
// 请求支付操作
function requestPay(c){
// 必须从业务服务器获取支付信息
var statement = "...";
if(!c.serviceReady){
c.installService();
}
plus.payment.request(c, statement, function(){
alert("支付操作成功!");
}, function(e){
alert("支付失败:"+e.message);
} );
}
</script>
</head>
<body>
</body>
</html>
requestOrder
向IAP服务器请求支付订单
void pay.requestOrder(ids, successCB, errorCB);
说明:
IAP支付在调用plus.payment.request方法支付前须先向服务器请求获取商品的详细信息,否则会支付失败。
参数:
- ids:
(
Array[String]
)
必选 请求商品的标识
- successCB:
(
IapRequestOrderSuccessCallback
)
必选 请求成功回调
- errorCB:
(
PaymentErrorCallback
)
必选 请求失败回调
返回值:
void : 无平台支持:
- Android - 2.2+ (不支持)
- iOS
- 5.0+
(支持)
:
仅苹果应用内支付(IAP)支持:需在itunesconnect上添加商品并配置好才能请求成功。
示例:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>In-App Purchase</title>
<script type="text/javascript" src="../js/common.js"></script>
<script type="text/javascript">
var iap=null;
var ids=['donation','donation6'];//应用内购项目
function plusReady(){
// 获取支付通道
plus.payment.getChannels(function(channels){
for(var i in channels){
var channel=channels[i];
if(channel.id==='appleiap'){
iap=channel;
}
}
requestOrder();
},function(e){
console.log("获取支付通道失败:"+e.message);
});
}
document.addEventListener('plusready',plusReady,false);
// 获取订单
function requestOrder(){
plus.nativeUI.showWaiting('检测支付环境...');
iap.requestOrder(ids,function(e){
plus.nativeUI.closeWaiting();
console.log('requestOrder success: '+JSON.stringify(e));
},function(e){
console.log('requestOrder failed: '+JSON.stringify(e));
plus.nativeUI.closeWaiting();
plus.nativeUI.confirm("错误信息:"+JSON.stringify(e), function(e){
if(e.index==0){
requestOrder();
}else{
back();
}
}, '重新请求支付',['确定','取消']);
});
}
// 支付
function pay(id){
plus.nativeUI.showWaiting('', {style:"black",background:"rgba(0,0,0,0)"});
plus.payment.request(iap, {productid:id}, function(result){
plus.nativeUI.closeWaiting();
plus.nativeUI.alert("支付成功:感谢你的支持,我们会继续努力完善产品。", function(){
back();
}, "捐赠");
},function(e){
plus.nativeUI.closeWaiting();
plus.nativeUI.alert("错误信息:"+e.message,null,"支付失败:"+e.code);
});
}
</script>
<link rel="stylesheet" href="../css/common.css" type="text/css" charset="utf-8"/>
</head>
<body>
<header id="header">
<div class="nvbt iback" onclick="back()"></div>
<div class="nvtt">In-App Purchase</div>
</header>
<div id="content" class="content">
<br/><br/>
<p class="des" style="font-size:16px;line-height:30px;margin: 0px .5em;">
DCloud 是W3C会员、中国HTML5产业联盟发起单位,致力于推进HTML5发展,构建HTML5生态。
</p>
<br/>
<strong>
支持HTML5开发工具HBuilder
</strong>
<div class="button" onclick="pay(ids[0])">
捐赠1元
</div>
<div class="button" onclick="pay(ids[1])">
捐赠6元
</div>
</div>
</body>
<script type="text/javascript" src="../js/immersed.js" ></script>
</html>
restoreComplateRequest
向IAP服务器请求已经购买的非消耗性商品和订阅商品
void pay.restoreComplateRequest(options, successCB);
说明:
注意:不能获取已购买的消耗性商品。
参数:
- options:
(
Object
)
必选 请求参数
支持属性:
- "username" - 用户名称,可选项,请求支付时设置的username值
- "manualFinishTransaction" - Boolean类型,可选项,是否需要主动调用"finishTransaction"关闭订单,默认值为false。
- successCB:
(
IapRestoreComplateRequestCallback
)
必选 请求成功回调
返回值:
void : 无平台支持:
- Android - 2.2+ (不支持)
- iOS
- 5.0+
(支持)
:
仅苹果应用内支付(IAP)支持。
示例:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>In-App Purchase</title>
<script type="text/javascript">
var iap=null;
function plusReady(){
// 获取支付通道
plus.payment.getChannels(function(channels){
for(var i in channels){
var channel=channels[i];
if(channel.id==='appleiap'){
iap=channel;
}
}
},function(e){
console.log("获取支付通道失败:"+e.message);
});
}
document.addEventListener('plusready',plusReady,false);
// 获取已购买商品(非消耗性商品和订阅商品)
function restoreComplateRequest(){
plus.nativeUI.showWaiting('',{style:"black",background:"rgba(0,0,0,0)"});
iap.restoreComplateRequest({},function(results){
plus.nativeUI.closeWaiting();
for(var i in results){
alert('restoreComplateRequest['+i+']: '+JSON.stringify(results[i]));
}
});
}
</script>
</head>
<body>
<button onclick="restoreComplateRequest()">获取已购买商品</button>
</body>
</html>
finishTransaction
向IAP服务器请求关闭订单
void pay.finishTransaction(transaction, successCB, errorCB);
说明:
IAP支付在调用plus.payment.request方法支付后须先向服务器请求关闭订单,否则会无法再次购买。
调用restoreComplateRequest方法请求已经购买的非消耗性商品和订阅商品时如果设置manualFinishTransaction为true时,
需调用此方法关闭订单。
HBuilderX3.5.1+版本新增支持。
参数:
- transaction:
(
IAPTransaction
)
必选 要关闭的订单信息
- successCB:
(
PaymentSuccessCallback
)
必选 关闭订单成功回调
无回调参数
- errorCB:
(
PaymentErrorCallback
)
必选 关闭订单失败回调
可能失败的原因:
- 1.传入错误的 transaction 订单信息不正确
- 2.调用restoreComplateRequest方法请求已经购买的非消耗性商品和订阅商品时设置manualFinishTransaction参数为false
返回值:
void : 无平台支持:
- Android - 4.4+ (不支持)
- iOS - 9.0+ (支持)
isReadyToPay
判断当前设备是否支持谷歌支付(Google Pay)
void isReadyToPay(options, successCB, errorCB);
说明:
在使用谷歌支付前,探测谷歌支付是否可用(支付请求是否被支持)。 HBuilderX3.4.2+版本支持。
参数:
- options:
(
GooglePayOptions
)
必选 判断谷歌支付的参数
- successCB:
(
PaymentSuccessCallback
)
必选 支持谷歌支付则触发成功回调
- errorCB:
(
PaymentErrorCallback
)
必选 不支持谷歌支付则触发失败回调
返回值:
void : 无平台支持:
- Android - 4.3+ (支持)
- iOS - 5.0+ (不支持)
OrderStatementIAP
IAP订单数据对象
interface plus.payment.OrderStatementIAP {
attribute String productid;
attribute String username;
attribute Number quantity;
}
说明:
描述IAP商品订单信息,如标识、数量等。
属性:
- productid: (String
类型
)商品的标识
- username: (String
类型
)购买用户名称
- quantity: (Number
类型
)商品数量
PaymentResult
支付操作结果对象
interface plus.payment.PaymentResult {
attribute PaymentChannel channel;
attribute String tradeno;
attribute String description;
attribute String url;
attribute String signature;
attribute String rawdata;
}
说明:
PaymentResult对象表示支付操作返回结果,用于确认支付操作成功。
属性:
- channel: (PaymentChannel
类型
)支付通道对象
用于发起支付操作的支付通道对象。
平台支持
- Android - 2.2+ (支持)
- iOS - 5.0+ (支持)
- tradeno: (String
类型
)交易编号信息
如果支付平台不支持此数据则返回undefined。
- description: (Boolean
类型
)交易描述信息
如果支付平台不支持此数据则返回undefined。
- url: (Boolean
类型
)查找支付交易信息地址
用于向支付平台查询交易信息,如果支付平台不支持此数据则返回undefined。
- signature: (String
类型
)支付操作指纹信息
用于向支付平台查询支付订单信息,如果支付平台不支持此数据则返回undefined。
- rawdata: (String
类型
)支付平台返回的原始数据
如果支付平台返回key-value类型字符串,则组合成符合JSON格式的字符串。
IAPProduct
IAP商品对象
interface plus.payment.IAPProduct {
attribute String productid;
attribute String price;
attribute String title;
attribute String description;
}
说明:
描述IAP商品详细信息,如标识、价格、标题、描述信息等。
属性:
- productid: (String
类型
)商品的标识
- price: (String
类型
)商品的价格
- title: (String
类型
)商品标题
- description: (String
类型
)商品的描述信息
IAPProductInfo
购买IAP商品对象
interface plus.payment.IAPProductInfo {
attribute String productIdentifier;
attribute String quantity;
}
说明:
描述购买的IAP商品详细信息,如标识、数量等。
属性:
- productIdentifier: (String
类型
)商品的标识
- quantity: (String
类型
)商品的数量
IAPTransaction
购买IAP商品交易信息对象
interface plus.payment.IAPTransaction {
attribute IAPProductInfo payment;
attribute String transactionDate;
attribute String transactionIdentifier;
attribute String transactionReceipt;
attribute String transactionState;
}
说明:
描述购买的IAP商品交易详细信息,如购买商品信息、交易日期、订单标识等。
属性:
- payment: (String
类型
)购买商品的信息
- transactionDate: (String
类型
)购买商品的交易日期
- transactionIdentifier: (String
类型
)购买商品的交易订单标识
- transactionReceipt: (String
类型
)购买商品的交易收据
base64编码格式字符串数据。
- transactionState: (String
类型
)购买商品的交易状态
可取值:"0"为正在支付;"1"为支付成功;"2"为支付失败;"3"为支付已恢复。
GooglePayOptions
判断谷歌支付是否可用参数对象
interface plus.payment.GooglePayOptions {
attribute Number environment;
attribute String paymentMethodType;
attribute String merchantId;
attribute Array<String> allowedAuthMethods;
attribute Array<String> allowedCardNetworks;
attribute Boolean billingAddressRequired;
attribute String billingAddressParametersFormat;
}
说明:
判断谷歌支付方式相关参数。
属性:
- environment: (Number
类型
)支付环境类型
取值范围: 1表示生产环境; 3表示测试环境 。
- paymentMethodType: (String
类型
)支付方式
取值范围: "CARD"表示使用信用卡支付; "PAYPAL"表示使用paypal支付 。
- merchantId: (String
类型
)商户id
仅在 paymentMethodType为"PAYPAL"时需要此字段。
- allowedAuthMethods: (Array[String]
类型
)支付认证方式
取值范围: "PAN_ONLY"、"CRYPTOGRAM_3DS" 。
- allowedCardNetworks: (Array[String]
类型
)卡网络类型
取值范围: "AMEX"、"DISCOVER"、"JCB"、"MASTERCARD"、"VISA" 。
- billingAddressRequired: (Boolean
类型
)是否需要账单地址
- billingAddressParametersFormat: (String
类型
)账单地址参数格式
取值范围: "FULL"、"MIN" 。
ChannelsSuccessCallback
获取支付通道成功回调
void ChannelsSuccessCallback( channels ) {
// Get payment channels success code
}
说明:
当获取支付通道列表成功时的回调函数,用于返回终端支持的支付通道列表。
参数:
- channels:
(
Array[PaymentChannel]
)
必选 数组,系统支持的支付通道PaymentChannel列表
返回值:
void : 无平台支持:
- Android - 2.2+ (支持)
- iOS - 5.0+ (支持)
IapRequestOrderSuccessCallback
请求支付商品列表回调方法
void onsuccess( results ) {
// Payment success code
}
说明:
获取IAP商品列表信息成功时的回调函数,返回商品详细信息。
参数:
- results:
(
Array[IAPProduct]
)
必选 商品信息数据
返回值:
void : 无平台支持:
- Android - 2.2+ (不支持)
- iOS - 5.0+ (支持)
IapRestoreComplateRequestCallback
请求已经购买的非消耗性商品和订阅商品回调方法
void onsuccess( results ) {
// Payment success code
}
说明:
获取IAP商品列表信息成功时的回调函数,返回商品详细信息。
参数:
- results:
(
Array[IAPTransaction]
)
必选 已购买的非消耗性商品和订阅商品交易信息
返回值:
void : 无平台支持:
- Android - 2.2+ (不支持)
- iOS - 5.0+ (支持)
IapPaymentSuccessCallback
IAP支付操作成功回调
void PaymentSuccessCallback ( result ) {
// Payment success code
}
说明:
当支付操作成功时的回调函数,用于返回支付操作的成功信息。
参数:
- result :
(
IAPTransaction
)
必选 支付操作成功的信息
苹果IAP支付返回的数据,类型为IAPTransaction。
返回值:
void : 无平台支持:
- Android - 2.2+ (不支持)
- iOS - 5.0+ (支持)
PaymentSuccessCallback
支付操作成功回调
void PaymentSuccessCallback ( result ) {
// Payment success code
}
说明:
当支付操作成功时的回调函数,用于返回支付操作的成功信息。
参数:
- result :
(
PaymentResult
)
必选 支付操作成功的信息
支付返回的数据,类型为PaymentResult。
返回值:
void : 无平台支持:
- Android - 2.2+ (支持)
- iOS - 5.0+ (支持)
PaymentErrorCallback
支付操作失败回调
void PaymentErrorCallback(error){
// Payment error code
}
说明:
当支付操作失败时的回调函数,用于返回支付操作失败的错误信息。
参数:
- error:
(
Exception
)
必选 支付操作失败错误信息,可通过error.code获取错误代码,具体错误码有各支付通道定义
支付宝支付错误代码如下: 62000,客户端未安装支付通道依赖的服务; 62001,用户取消支付操作; 62002,此设备不支持支付; 62003,数据格式错误; 62004,支付账号状态错误; 62005,订单信息错误; 62006,支付操作内部错误; 62007,支付服务器错误; 62008,网络问题引起的错误; 62009,其它未定义的错误。 微信支付错误代码如下: -1,一般错误; -2,用户取消; -3,发送失败; -4,认证被否决; -5,不支持错误。
返回值:
void : 无平台支持:
- Android - 2.2+ (支持)
- iOS - 5.0+ (支持)