uexApplePay查看3.0文档

• 1、简介
• 2、API概览
• 3、术语表
• 4、FAQ常见问题
• 5、接入指引
• 6、更新历史

  1、简介

  Apple Pay 支付插件

  1.1、说明

  该插件实现了iPhone手机的Apple Pay 支付功能.

  本文的目的是为了开发能够更好更快地将API集成到自己的项目中，在使用前最好先使用好我们提供的demo并对照文档运行看看效果。
  这里可以【参考教程】下载AppCan IDE为开发者工具开发，然后集成到自己的项目上。

1.2、UI展示

1.3、开源源码

插件测试用例与源码下载:点击 插件中心至插件详情页 (插件测试用例与插件源码已经提供)

1.4、平台版本支持

本插件的所有API默认支持仅iOS9.2+操作系统,不支持Android.
有特殊版本要求的API会在文档中额外说明.

1.5、接口有效性

本插件所有API默认在插件版本4.0.0+可用.
在后续版本中新添加的接口会在文档中额外说明.

2、API概览

在进行插件调试之前,请先阅读接入指引并按其步骤进行接入操作,否则无法进行支付操作.

2.1、方法

canMakePayment //检测能否进行AppplePay支付

uexApplePay.canMakePayment(params)

说明:

• 检测能否进行ApplePay

参数:

var params = {
    networks:[]
};

各字段含义如下:

返回值:

Number类型,检测结果,是一个UexAppleCanMakePaymentStatus,详见术语表-UexAppleCanMakePaymentStatus

示例:

var params = {
    networks:["ChinaUnionPay"]
};
var data = JSON.stringify(params);
var result = uexApplePay.canMakePayment(data);
if (result != 0){
    alert ("不能进行ApplePay支付!")
}

startChinaUnionPay //调起银联ApplePay支付

uexApplePay.startChinaUnionPay(params)

说明:

• 调用银联封装的ApplePay方法.
• 开发者需注册成为银联的商户并开通ApplePay支付功能，通过银联后台得到交易流水号，再调用此接口。
• 和StartPay方法相比,此方法集成更加简单,但可定制化程度低,并且只支持中国银联支付.
• 调用此接口前,请先调用uexApplePay.canMakePayment接口并限定支付网络为"ChinaUnionPay"来检测是否可以进行支付

参数:

var params = {
    orderInfo:,
    mode:,
    merchantIdentifier:
};

各字段含义如下:

返回值:

Number类型,检测结果,是一个UexApplePayStartPayResult,详见术语表-UexApplePayStartPayResult

示例:

var params = {
    merchantIdentifier:"merchant.com.zywx.devTest",
    orderInfo:"201603011028451152878",
    mode:"01"
};
var data = JSON.stringify(params);
var result = uexApplePay.startChinaUnionPay(JSON.stringify(data));
if (result != 0 ){
    alert("调起支付失败");
}

注:从http://101.231.114.216:1725/sim/getacptn可以获取测试用的orderInfo.

startPay //调起Apple Pay支付

uexApplePay.startPay(params)

说明:

• 调用iOS原生的ApplePay方法.
• 和startChinaUnionPay方法相比,此方法集成较复杂,但可定制化程度高,支持所有ApplePay支持的支付渠道
• 调用此接口前,请先调用uexApplePay.canMakePayment接口并限定支付网络为你的后台支持的支付网络来检测是否可以进行支付.

参数:

var params = {
    merchantIdentifier:,
    merchantCapability:,
    networks:,
    currencyCode:,
    countryCode:,
    payment{
        payee:,
        totalPrice:,
        items:[
            {
                label:,
                price:,
            }
        ]
    },
    billingContactRequiredFlag:,
    shippingContactRequiredFlag:,
    shippingType:,
    shippingMethods:[
            {
                label:,
                identifier:,
                price:,
                detail:
            }
        ]
};

各字段含义如下:

Payment Object表示这个订单中的账单信息,其各字段含义如下

说明:对于totalPrice

• 不传此参数时,插件会自动将传入的所有items中的价格相加作为totalPrice.
• 若items参数不传,则此参数必传,否则支付会报错.
• 若传入此参数,则不会进行items价格计算,以传入的参数为准.

Item Object 表示账单中的一个项目,各字段含义如下

注:价格未确定的项目在计算totalPrice时,按0处理.

ShippingMethod Object表示一种物流方式,各字段含义如下

返回值:

Number类型,打开支付页面的结果,是一个UexApplePayStartPayResult,详见术语表-UexApplePayStartPayResult

示例:

var params = {
    merchantIdentifier:"merchant.com.zywx.devTest",
    merchantCapability:4,
     networks:["AMEX","ChinaUnionPay","VISA"],
     currencyCode:"CNY",
     countryCode:"CN",
     billingContactRequiredFlag:4,
     payment:{
         payee:"AppCan",
         items:[
               {
                label:"item1",
                price:5
            },
            {
                label:"item2",
                price:8.5
            },
            {
                label:"discount",
                price:-1.2
            },
            ]
         },
     shippingContactRequiredFlag:2,
     shippingType:3,
     shippingMethods:[
          {
            label:"shippingMethod1",
            price:1,
            detail:"detail1",
            identifier:"method1",

        },
        {
            label:"shippingMethod2",
            price:2,
            detail:"detail2",
            identifier:"method2",

        }
     ],
     applicationData:"applicationData",
 };
var data = JSON.stringify(params);
var result = uexApplePay.startPay(JSON.stringify(data));
if (result != 0 ){
    alert("调起支付失败");
}

commitPaymentMethodChange //确认支付方式变化

uexApplePay.commitPaymentMethodChange(params)

说明:

• 在onPaymentMethodChange 监听触发之后必须调用此方法,否则支付无法正常进行下去
• 可以在此方法中更新此次订单的账单,实现诸如信用卡具有额外折扣等功能

参数:

var params = {
    payment:
};

各字段含义如下:

返回值:

Boolean类型,调用接口结果.若为false,一般为参数错误或者不完整引起,必须重新调用此接口

示例:

var params = {
    payment:{
         payee:"AppCan",
         items:[
               {
                label:"item1",
                price:5
            },
            {
                label:"item2",
                price:8.5
            },
            {
                label:"discount",
                price:-1.2
            },
            {
                label:"信用卡打折",
                price:-3
            },
       ]
    }
}
var result = uexApplePay.commitPaymentMethodChange(JSON.stringify(params));
if(!result){
    alert("传入参数错误");
    //此时应该重新调用uexApplePay.commitPaymentMethodChange方法
}

commitShippingMethodChange //确认物流方式变化

uexApplePay.commitShippingMethodChange(params)

说明:

• 在onShippingMethodChange 监听触发之后必须调用此方法,否则支付无法正常进行下去
• 可以在此方法中更新此次订单的账单,实现诸如对不同的物流方式有不同的总价格等功能

参数:

var params = {
    payment:
};

各字段含义如下:

返回值:

Boolean类型,调用接口结果.若为false,一般为参数错误或者不完整引起,必须重新调用此接口

示例:

var params = {
    payment:{
         payee:"AppCan",
         items:[
               {
                label:"item1",
                price:5
            },
            {
                label:"item2",
                price:8.5
            },
            {
                label:"discount",
                price:-1.2
            },
            {
                label:"运费",
                price:5
            },
       ]
    }
}
var result = uexApplePay.commitShippingMethodChange(JSON.stringify(params));
if(!result){
    alert("传入参数错误");
    //此时应该重新调用uexApplePay.commitShippingMethodChange方法
}

commitShippingContactChange //确认物流信息变化

uexApplePay.commitShippingContactChange(params)

说明:

• 在onShippingContactChange 监听触发之后必须调用此方法,否则支付无法正常进行下去
• 可以在此方法中更新此次订单的账单和物流方式,实现诸如对不同的地点提供不同的物流方式等功能

参数:

var params = {
    payment:,
    shippingMethods,
    isPostalAddressInvalid:
};

各字段含义如下:

返回值:

Boolean,调用接口结果.若为false,一般为参数错误或者不完整引起,必须重新调用此接口

示例:

var params = {
    isPostalAddressInvalid:false,
    shippingMethods:[
          {
            label:"shippingMethod1",
            price:10,
            detail:"detail1",
            identifier:"method1",

        },
        {
            label:"shippingMethod2",
            price:5,
            detail:"detail2",
            identifier:"method2",

        }
     ]
}
var result = uexApplePay.commitShippingContactChange(JSON.stringify(params));
if(!result){
    alert("传入参数错误");
    //此时应该重新调用uexApplePay.commitShippingContactChange方法
}

commitAuthorizedResult //确认订单支付结果

uexApplePay.commitAuthorizedResult(params)

说明:

• 在onPaymentAuthorized 监听触发之后必须调用此方法,告知系统订单支付结果,否则支付无法完成.

参数:

var params = {
    result:
};

各字段含义如下:

返回值:

Boolean,调用接口结果.若为false,一般为参数错误或者不完整引起,必须重新调用此接口

示例:

var params = {
    result:true
}
var result = uexApplePay.onPaymentAuthorized(JSON.stringify(params));
if(!result){
    alert("传入参数错误");
    //此时应该重新调用uexApplePay.onPaymentAuthorized方法
}

addButton //添加ApplePay按钮

uexApplePay.addButton(params)

说明:

• 提供一个符合Apple的ApplePay设计规范的支付按钮
• 注意,Apple的ApplePay设计规范指出此类按钮必须用于ApplePay支付,用于其他用途会导致你的App被Apple Store拒绝.

参数:

var params = {
    id:,
    x:,
    y:,
    width:,
    height:,
    type:,
    style:,
    scrollWithWeb:,
};

各字段含义如下:

返回值:

Boolean类型,是否添加按钮成功.若为false,一般为参数错误或者不完整引起

示例:

var data = {
    x : 200,
    y : 170,
     width : 180,
     height : 60,
     id : "button",
     scrollWithWeb : false,
     type:0,
     style:1,
}
var suc = uexApplePay.addButton(JSON.stringify(data));
alert(suc)

removeButton //移除ApplePay按钮

uexApplePay.removeButton(params)

说明:

• 移除由addButton接口添加的ApplePay按钮

参数:

var params = {
    id:,
};

各字段含义如下:

返回值:

Boolean类型,是否删除按钮成功.若为false,一般为参数错误或者不完整引起

示例:

var data = {
     id : "button",
}
var suc = uexApplePay.removeButton(JSON.stringify(data));
alert(suc)

2.2、监听方法

onChinaUnionPayFinish //银联ApplePay支付结束的监听方法

uexApplePay.onChinaUnionPayFinish(params)

说明:

• 在调用uexApplePay.startChinaUnionPay接口后,通过此接口来监听支付结果

参数:

var params = {
    result:,
    errorInfo:,
    otherInfo:,
};

各字段含义如下:

示例:

uexApplePay.onChinaUnionPayFinish = function(info){
    alert(info);
}

onPaymentMethodChange //支付方式变化的监听方法

uexApplePay.onPaymentMethodChange(params)

说明:

• 在调用uexApplePay.startPay接口后,当用户选择或者更改支付方式时,会触发此监听
• 触发此监听之后,必须调用commitPaymentMethodChange来确认支付方式变化

参数:

params是一个PaymentMethod Object转换而成的JSON字符串.

PaymentMethod Object结构如下

var paymentMethod = {
    type:,
    displayName:,
    network:,
};

各字段含义如下:

示例:

uexApplePay.onPaymentMethodChange = function(info){
    alert(info);
}

onShippingContactChange //物流联系人变化的监听方法

uexApplePay.onShippingContactChange(params)

说明:

• 在调用uexApplePay.startPay接口后,当用户选择或者更改物流联系人时,会触发此监听
• 触发此监听之后,必须调用commitShippingContactChange来确认物流联系人变化

参数:

params是一个Contact Object序列化得到的JSON字符串,Contact Object结构如下

var contact = {
    addressInfo:{//联系人地址
        country:,//国家
        ISOCounrtyCode:,//ISO国家编码
        state:,//省/州名
        city:,//城市
        street:,//街道
        postalCode:,//邮编
    }
    phoneNumber:,//电话号码
    emailAddress:,//电子邮件地址
    nameInfo:{//电子邮件信息
        nameSuffix:,//姓名后缀
        namePrefix:,//姓名前缀
        middleName:,//中间名
        givenName:,//名
        familyName:,//姓
        nickName:,//昵称
    }
};

注:

• 以上4个主参数分别对应了UexApplePayContactRequiredFlag的4个枚举值
• 以上参数均为可选参数,具体参数是否存在,取决于用户是否填入相应的信息.

示例:

uexApplePay.onShippingContactChange = function(info){
    alert(info);
}

onShippingMethodChange //物流方式变化的监听方法

uexApplePay.onShippingMethodChange(params)

说明:

• 在调用uexApplePay.startPay接口后,当用户选择或者更改物流方式时,会触发此监听
• 触发此监听之后,必须调用commitShippingMethodChange来确认物流方式变化

参数:

params是一个ShippingMethod Object序列化得到的JSON字符串,字段介绍详见startPay接口中的ShippingMethod Object参数介绍

var param = {
     label:,
     identifier:,
     price:,
     detail:
}

示例:

uexApplePay.onShippingMethodChange = function(info){
    alert(info);
}

onPaymentAuthorized //用户进行支付的监听方法

uexApplePay.onPaymentAuthorized(params)

说明:

• 在调用uexApplePay.startPay接口后,当用户确认进行支付时,会触发此监听
• 触发此监听之后,必须调用commitAuthorizedResult来确认支付结果

参数:

var param = {
     shippingMethod:,//可选,一个ShippingMethod Object,描述了用户最终选择的物流方式
     billingContact:,//可选,一个Contact Object(字段可参考onShippingContactChange方法中的介绍),描述了账单接收人的联系人信息
     shippingContact:,//可选,一个Contact Object(字段可参考onShippingContactChange方法中的介绍),描述了货物接收人的联系人信息
     paymentInfo:{//必选,支付信息
         paymentMethod:,//必选,一个PaymentMethod Object(字段可参考onPaymentMethodChange方法中的介绍),描述了支付方式信息
         transactionIdentifier:,//必选,苹果ApplePay模块生成的订单标识符
         token:{//支付Token,
                  data:,//加密过的支付信息
                  signature:,//签名信息,用于校验此token是否有效
                  version:,//解密key的二次加密方式,为"EC_v1"或者"RSA_v1"之一
                 header:{//加密Header,
                     applicationData:,//调用startPay接口时传入的applicationData的SHA256 Hash,用Base64编码得到的字符串
                     transactionId:,//支付卡ID,根据支付的银行卡由设备的ApplePay模块唯一生成
                     wrappedKey:,//RSA加密过的解密Key,用于解密data,仅version为"RSA_v1"时存在
                     ephemeralPublicKey:,//Ephemeral公钥 仅version为"EC_v1"时存在
                     publicKeyHash:,//二次加密key所用到的公钥的SHA256 Hash,用Base64编码得到的字符串
                  },
             }
         }
     }
}

• 支付Token的具体解密方法请参考苹果官方的解密文档
• 除非测试,否则绝对不要在前端进行解密工作!
• 正常的操作流程应该是
  • 前端发送paymentInfo到后台
  • 后台校验加密内容是否有效
  • 进行解密工作.
  • 根据解密后的信息调用相应的支付网关进行支付操作
  • 后台得到支付结果 返回给前端
  • 前端调用commitAuthorizedResult告诉插件支付结果,并展示给用户

示例:

uexApplePay.onPaymentAuthorized = function(info){
    alert(info);
}

onCommitError //支付提交变化发生错误的监听方法

uexApplePay.onCommitError(params)

说明:

• 在调用uexApplePay.commitShippingMethodChange、uexApplePay.commitShippingContactChange、uexApplePay.commitPaymentMethodChange、uexApplePay.commitAuthorizedResult这4个接口后,若提交失败,会触发此方法
• 提交失败的原因多为必要参数缺失/参数格式错误/参数内容不合法引起

参数:

var param = {
     type:,//触发这个监听的方法类型 0 - uexApplePay.commitAuthorizedResult,1 - uexApplePay.commitShippingMethodChange,2 - uexApplePay.commitPaymentMethodChange ,3 - uexApplePay.commitShippingContactChange,
 }

示例:

uexApplePay.onCommitError = function(info){
    alert(info);
}

onPayFinish //支付结束的监听方法

uexApplePay.onPayFinish(params)

说明:

• 在调用uexApplePay.startPay接口后,完成支付或者用户取消支付时,会调用此方法

参数:

var param = {
     result:,//Number 必选 0-成功 1-失败 2-支付被取消
 }

示例:

uexApplePay.onPayFinish = function(info){
    alert("onPayFinish:" + info );
}

onButtonClick //支付按钮被点击的监听方法

uexApplePay.onButtonClick(params)

说明:

• 用户点击由uexApplePay.addButton设置的ApplePay按钮时,会触发此监听.

参数:

var params = {
    id://按钮的唯一标识符
};

示例:

uexApplePay.onButtonClick = function(info){
    alert(info);
}

3、 术语表

UexApplePayNetworkKey

UexApplePayNetworkKey 是一系列字符串,代表了各个银行卡发行商的支付网络

UexAppleCanMakePaymentStatus

• UexAppleCanMakePaymentStatus是一个Number类型的枚举值,表示检测是否支持ApplePay的结果,非0时均表示不能进行ApplePay支付

注1 : 目前支持ApplePay的设备型号有 ​

• iPhone : iPhone 6,iPhone 6 Plus,iPhone 6s,iPhone 6s Plus
• iPad : iPad Pro,iPad Air 2,iPad mini 3,iPad mini 4

注2 : 账号不支持包含但不限于以下几种情况

• 设备登录的苹果账号未在Wallet中绑定指定支付网络的银行卡
• 设备登录的苹果账号处于锁定状态,或者处于家长监控状态下

UexApplePayStartPayResult

• UexApplePayStartPayResult是一个Number类型的枚举值,表示调用开始支付接口的结果,非0时均表示打开支付界面失败

UexApplePayMerchantCapability

• UexApplePayMerchantCapability是一个Number类型的枚举值,表示支持的支付处理标准.
• 如果需要支持多种处理标准,请将需要支持的标准的值相加后作为最终结果传入. 比如,要同时支持3DS和EMV,请传3.

其中3DS和EMV均同时支持信用卡和借记卡.因此假设你需要限此订单只支持信用卡支付,传4可达到此效果.

UexApplePayContactRequiredFlag

• UexApplePayContactRequiredFlag是一个Number类型的枚举值,表示需要的联系人信息.
• 如果同时需要多种信息,请将需要信息的值相加后作为最终结果传入.比如,同时需要联系人的名称和电话号码,请传10.

UexApplePayShippingType

• UexApplePayShippingType是一个Number类型的枚举值,表示此订单货物的物流类型.

UexApplePayPaymentMethodType

• UexApplePayPaymentMethodType是一个Number类型的枚举值,表示此支付方式的类型.

4、 FAQ常见问题

startPay 和 startChinaUnionPay 这2个接口都能进行ApplePay支付,我该用哪个?

• 如果您需要快速实现ApplePay功能,并且只需要支持中国银联渠道,那么使的startChinaUnionPay接口
• 如果您的应用需要进行非中国银联渠道的ApplePay 支付,那么只能选择startPay接口
• 您应该视您的实际使用情况选择用哪个接口.它们的主要区别如下表所示

为什么我无法打开支付的界面?

• 请确认您在调用startPay或者startChinaUnionPay接口时传入的merchantIdentifier无误,并且此merchantIdentifier在comfig.xml中被正确配置

我能否不用插件提供的ApplePay按钮?

• 若您的App不需要考虑上架问题(比如企业内部的OA等App),那么完全可以用自己的UI
• 若您的App需要发布至AppStore，您可以用自己设计的UI,但必须要符合《Apple Pay 识别标志指南》，否则您的应用会无法通过审核

我的应用在启用ApplePay之后被拒了!为什么?

ApplePay有如下原因会导致您的应用审核被拒

• Apple Pay 页面的UI不符合《Apple Pay 识别标志指南》
• Apple Pay 按钮不是用于进行ApplePay支付
• 在不能进行ApplePay支付的设备上提示或者可以选择进行Apple Pay支付(正确的做法是先判断是否可以进行ApplePay支付,再展示ApplePay支付的UI)

5、 接入指引

开发者集成及使用此插件,需要到Apple开发者中心申请Merchant证书,并且在Config.xml中配置相关的MerchantIdentifier才能使用.以下是具体步骤.

一、注册商用ID标识

• 在Apple开发者中心登录后,选择"Certificates,Identifiers&Profiles"
• 在Identifiers下,选择Merchant IDs
• 在右上角点击"+"按钮
• 在Description栏、ID栏输入相应信息,点击"Continue".此处配置的ID,即为merchantIdentifier.
• 浏览下配置参数,点击"Register"
• 点击"Done"

二、为你的商用ID标识配置一个证书

• 在Apple开发者中心登录后,选择"Certificates,Identifiers&Profiles"
• 在Identifiers下,选择Merchant IDs
• 选择列表中的商用ID标识,点击Edit
• 点击"Create Certificate",按照指示获取或生成签名证书请求(CSR),点击"Continue"
• 点击"Choose File",选择你的CSR,点击"Generate"
• 关于CSR文件:
  • 有的的支付渠道(比如中国银联)可能会要求上传指定的.CSR文件才能使用其支付功能.
  • 但上传不适配的.CSR文件只影响最后支付的结果
  • 由于从支付渠道申请.CSR文件可以需要一定的时间,因此可以先上传自己生成的.CSR文件进行插件与前端页面调试,待正式的.CSR文件申请成功之后再进行替换,并测试前后端交互.

如果你需要为不同的支付项目配置不同的商用ID标识,步骤一、和二、会进行多次.

三、在你的APP中使用商用ID标识

• 在Apple开发者中心登录后,选择"Certificates,Identifiers&Profiles"
• 在Identifiers下,选择App IDs
• 选择你的App,点击Edit
• 在新打开的页面中启用 Apple Pay
• 点击 Apple Pay 选项栏中的Edit 并勾选你这个App需要使用的所有商用ID标识
• 完成编辑

注意:每当你编辑了你的App ID,你都需要重新下载mobileprovision文件并用新的mobileprovision文件去打包,否则你的更改将不会生效

四、在config.xml中配置商用ID标识

• 在config.xml中添加如下配置

<config desc="uexApplePay" type="ENTITLEMENTS">
    <entitlement type="merchant" value="merchantIdentifier1"/>
    <entitlement type="merchant" value="merchantIdentifier2"/>
</config>

• 其中<entitlement>节点数量取决于你的App中会用到的商用ID标识数量.你应该为每一个商用ID标识设置一个<entitlement>节点,并修改其中的value值为此商用ID标识的merchantIdentifier.(type值不要更改!)

6、更新历史

iOS

API版本: uexApplePay-4.0.0

最近更新时间:2016-3-2

Android

uexApplePay不支持Android