签订支付协议（已安装招商银行APP）

1. 接口介绍

功能简述：

商户app唤起招行APP的方式来实现周期扣款的签约，或招行APP内场景商户直接进行APP周期扣款签约

应用场景：

1、 客户在招行侧未签订“周期扣款”支付协议，商户需调用该接口为客户签约。
2、 调用该接口成功后，客户即在招行侧签订协议，并成功开通招行周期扣款功能，商户侧收到“支付协议签订成功回调通知”。
3、 客户关闭支付协议的免密功能，可调用该接口重新开通，开通成功后，商户侧收到“支付协议签订成功回调通知”。

调用方式：

目前支持以下三种调用方式：
1、商户客户端集成招行SDK，通过SDK判断客户是否安装招行APP并发起签约。集成SDK方法请参考【SDK接口】，签约字段定义请参考本文档第3节jsonRequestData的参数定义。
2、商户客户端编写代码或采用其他方式，判断客户是否安装招行APP，未安装则参考本文档第2—3节内容进行调用。
3、商户不判断客户是否安装招行APP，仅对接H5签约流程，则参考本文档第2—3节内容进行调用。

约束条件：

1、秘钥，商户需通过配置管理，方便后续调整。
2、商户需要判断是否安装招行手机银行APP，已安装采用此方案。

正常流程：

1、商户APP唤起招行手机银行APP，或从招行APP内发起。
2、用户使用一网通登录后，信息校验通过后，正常签约成功。

异常流程:

1、用户信息校验不通过，界面报错，签约停止

2. 请求地址

1）招行App内的商户使用
var url = “http://cmbls/functionjump?action=gofuncid&funcid=0027024&clean=false&cmb_app_trans_parms_start=here&jsonRequestData=“ + encodeURIComponent($(“#jsonRequestData”).val());—-json组织同下方

2）在商户App内使用：
cmbmobilebank://CMBLS/FunctionJump?action=gofuncid&funcid=0027024&requesttype=post&cmb_app_trans_parms_start=here&jsonRequestData={“charset”:”UTF-8”,”sign”:”见签名处理章节”,”reqData”:{“agrNo”:”201606238888888”,”branchNo”:”0755”,”dateTime”:”20160623101430”,”lat”:”30.949505”,”lon”:”50.949506”,”merchantNo”:”123456”,”merchantSerialNo”:”2016062310143088”,”mobile”:”13888888888”,”noticePara”:””,”noticeUrl”:”http://www.xxx.com/xxx","userID":"2016062388888"}}

注意事项：jsonRequestData的值需要做urlEncode。

3. 请求报文

jsonRequestData参数定义

请求示例：

json报文组织：

{   
    "version":"1.0",   
    "charset":"UTF-8",   
    "sign":"见签名处理章节",   
    "signType":"SHA-256",   
    "reqData":{        
        "agrNo":"201707232442421234500",
        "branchNo":"0451",
        "dateTime":"20210413215632",
        "lat":"30.949505",
        "lon":"50.949506",
        "merchantNo":"000013",
        "merchantSerialNo":"20210413215632",
        "mobile":"13888888888",
        "returnUrl":"http://99.6.150.225:811/euserpayos/enterPage/SignJson.html",
        "noticeUrl":"http://www.merchant.com/path/WAPProcResult.dll",
        "userID":"0000000001",
        "noticePara":"",
        "merchantUserIdType":"",
        "merchantUserIdNo":"",
        "merchantUserName":"",
        "merchantCardType":"",
        "merchantCardNo":"",
        "merchantUserInfoEncryptType":"",
        "periodType":"M",
        "period":"1",
        "periodMaxAmt":"1000",
        "executeTime":"20210411",
        "periodTotalCnt":"12",
        "billType":"01"        
        }   
}

表单组织：

<form action="请求地址" method="post" >    
    <input type="hidden" name="jsonRequestData" value='以上json字符串' />
</form>

待签名字符串(未包含支付密钥)：

首先组成待签名字符串。待签名字符串组成规则为：对reqData所有请求参数按从a到z的顺序排列，如果首字母相同，按第二个字母排列，以此类推。排序完成后按将所有键值对以&符号拼接：

param1=value1&param2=value2&……

样例报文：

agrNo=201606238888888&branchNo=0755&dateTime=20160623101430&lat=30.949505&lon=50.949506&merchantNo=123456&merchantSerialNo=2016062310143088&mobile=13888888888&noticePara=&noticeUrl=http://www.xxx.com/xxx&userID=2016062388888

注意：
1、所有reqData中请求参数，即便其值为空，也加入签名字符串
2、签名时，按指定的字符集将字符串转换为字节流
3、根据HTTP协议要求，如果请求参数值中有特殊字符，如&、@等，需进行URLEncoding处理。待签名数据为原生值而非encoding后的值。

4. 响应报文

1、网页端直接展示签约成功或失败结果，无响应报文。
2、签约成功后有异步结果通知，失败无通知。详见【支付协议签订成功回调通知】。

5. 错误码

无

6. FAQ

参考【签订支付协议（未安装招商银行APP）】 FAQ

7. 商户APP调用招商银行APP签约功能样例

Android平台样例：

Private void callCMBApp() 
{     
    final String url = “cmbmobilebank://CMBLS/FunctionJump?
    action=gofuncid&funcid=0027013&requesttype=post&cmb_app_trans_parms_start=here &……”;     
    try     
    {         
        Intent intent = new Intent();         
        Uri data = Uri.parse(url);         
        intent.setData(data);         
        intent.setAction("android.intent.action.VIEW");         
        startActivity(intent);     
    }     
    catch(Exception e)     
    {         
        Log.d(TAG, "Exception", e);     
    } 
}

iOS平台样例：

(void)callCMBApp {    
    NSURL *url = [NSURL URLWithString: 
    @"cmbmobilebank://CMBLS/FunctionJump?
    action=gofuncid&funcid=0027013&requesttype=post&cmb_app_trans_parms_start=here&..."];    
    
    if (![[UIApplication sharedApplication] canOpenURL:url]) {        
        //没有安装手机银行或没有添加scheme"        
        return;     
    }   
    
    CGFloat systemVersion = [[[UIDevice currentDevice] systemVersion] floatValue];    
    if (systemVersion < 10.0f) {        
        BOOL success = [[UIApplication sharedApplication] openURL:url];        
        if (success) {            
            //跳转成功         
            }else {            
            //跳转失败         
            }     
    }else {         
        [[UIApplication sharedApplication] openURL:url                                            
                                           options:@{}                                  
                                 completionHandler:^(BOOL success) {              
             if (success) {                    
                 //跳转成功               
                 }else {                    
                 //跳转失败               
                 }         
         }];     
     } 
}