文档中心 > 开放平台

开放平台

在线物业缴费快速接入

更新时间：2017/03/30 访问次数：30195

流程综述

1、小区信息管理

场景

开发者通过接口调用在支付宝物业平台创建小区、变更小区信息、批量查询小区编号和查询单个小区信息；

创建小区是开发者与支付宝物业平台对接的第一步，创建的小区在经过支付测试和支付宝小二审核后，将会暴露给支付宝用户，因此务必要确保小区信息的真实性；

流程

接口说明

1）创建物业小区（alipay.eco.cplife.community.create）

请求参数特别说明

参数名称 参数说明
community_name 中文小区名用于展示、搜索等用途，建议传入业主熟知或地图平台上的小区名。
community_address 按城市内标准地址格式传入，省市区名可以不必传入。
district_code/city_code/province_code 6位县级市（区）、地级市、省/直辖市/自治区国标码，可按接口文档的说明地址下载或从官方渠道下载最新国标码清单。
community_locations 目前只接受小区所在的高德坐标系经纬度列表，若只有百度坐标系或没有坐标，可调用接口说明中的高德开放平台接口进行转换或获取；传入的小区地址和小区经纬度在高德地图上不能偏差过大。
associated_pois 小区对应的高德POI兴趣点列表，可选参数，详见接口说明。
hotline 物业服务热线，必填。
out_community_id 物业端系统有小区编号，可传入，用户支付后在交易通知会原样回传。

 响应参数特别说明

参数名称 参数说明
community_id 支付宝小区统一编号，开发者需保存，在后续接口中作为关键请求参数转入。
status 小区当前状态，默认为待上线状态。
next_action 提示开发者所创建的小区从当前状态到下一状态需完成的事件码。

提示：避免在支付宝线上环境上传测试数据，测试接口请通过沙箱环境。

SDK调用示例（以JAVA为例，更多语言示例参见接口文档）

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","UTF-8","alipay_public_key","RSA2");
AlipayEcoCplifeCommunityCreateRequest request = new AlipayEcoCplifeCommunityCreateRequest();
// 如果是开发者代物业公司账号调用接口，必须传入物业给开发者授权的令牌
request.putOtherTextParam("app_auth_token","请传入实际的第三方授权令牌值");
// 示例中通过string拼接json，实际项目建议用json库生成Json请求报文
request.setBizContent("{" +
"    \"community_name\":\"金海湾花园\"," +
"    \"community_address\":\"福荣路46号\"," +
"    \"district_code\":\"440304\"," +
"    \"city_code\":\"440300\"," +
"    \"province_code\":\"440000\"," +
"      \"community_locations\":[" +
"        \"114.032395|22.519725\",\"114.032469|22.519336\"" +
"      ]," +
"      \"associated_pois\":[" +
"        \"B02F37VVFP\",\"B0FFFQB4Y4\"" +
"      ]," +
"    \"hotline\":\"0571-87654321\"," +
"    \"out_community_id\":\"12345\"" +
"  }");
try {
    AlipayEcoCplifeCommunityCreateResponse response = alipayClient.execute(request);
    if(response.isSuccess()){
        //成功处理逻辑;
   } else {
        //失败处理逻辑;
   }
} catch(AlipayApiException e) {
    // 异常处理
}

2）变更物业小区信息（alipay.eco.cplife.community.modify）

请求参数特别说明

请求参数参照“创建物业小区”接口，根据小区所处的状态，小区参数变更规则如下：

小区接入状态 可修改的参数 具体变更规则
待上线 未上传房间 所有 通过系统校验后立即生效。 注意若变更city_code或province_code这两个参数，支付宝小区编号会变化，接口会返回新的community_id，请开发者同步更新后的支付宝小区编号。
待上线 已上传房间 除district_code、city_code和province_code以外的其余参数 通过系统校验后立即生效。
若需要变更行政区编码，请删除所有房间后重试。
已上线 / 除district_code、city_code和province_code以外的其余参数 通过系统校验后立即生效。

 SDK调用示例（以JAVA为例，更多语言示例参见接口文档）

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","UTF-8","alipay_public_key","RSA2");
AlipayEcoCplifeCommunityModifyRequest request = new AlipayEcoCplifeCommunityModifyRequest();
// 如果是开发者代物业公司账号调用接口，必须传入物业给开发者授权的令牌
request.putOtherTextParam("app_auth_token","请传入实际的第三方授权令牌值");

// 示例中通过string拼接json，实际项目建议用json库生成Json请求报文
request.setBizContent("{" +
"    \"community_id\":\"AJ5OFJC124403\"," +
"    \"community_name\":\"金海湾花园\"," +
"    \"community_address\":\"福荣路46号\"," +
"    \"district_code\":\"440304\"," +
"    \"city_code\":\"440300\"," +
"    \"province_code\":\"440000\"," +
"      \"community_locations\":[" +
"        \"114.032395|22.519725\",\"114.032469|22.519336\"" +
"      ]," +
"      \"associated_pois\":[" +
"        \"B02F37VVFP\",\"B0FFFQB4Y4\"" +
"      ]," +
"    \"hotline\":\"0571-87654321\"," +
"    \"out_community_id\":\"12345\"" +
"  }");
try {
    AlipayEcoCplifeCommunityModifyResponse response = alipayClient.execute(request);
    if(response.isSuccess()){
        //成功处理逻辑;
    } else {
        //失败处理逻辑;
    }
} catch (AlipayApiException e) {
    // 异常处理
}

3）批量查询支付宝小区编号（alipay.eco.cplife.community.batchquery）

调用说明

查询本开发者调用小区创建接口创建成功过的所有小区基本信息，若不传入物业授权令牌app_auth_token公共参数，则返回开发者代所有物业公司创建成功的小区信息，否则返回开发者帮助指定授权物业公司创建成功的小区。

响应参数特别说明

参数名称 参数说明
merchant_pid 每个小区所对应的物业公司支付宝账户PID。

SDK调用示例（以JAVA为例，更多语言示例参见接口文档）

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","UTF-8","alipay_public_key","RSA2");
AlipayEcoCplifeCommunityBatchqueryRequest request = new AlipayEcoCplifeCommunityBatchqueryRequest();

// 如果是开发者代物业公司账号调用接口，则传入物业给开发者授权的令牌，否则返回开发者所有创建过的小区
request.putOtherTextParam("app_auth_token","请传入实际的第三方授权令牌值");

// 示例中通过string拼接json，实际项目建议用json库生成Json请求报文
request.setBizContent("{" +
"    \"status\":\"ONLINE\"," +
"    \"page_num\":1," +
"    \"page_size\":300" +
"  }");
try {
    AlipayEcoCplifeCommunityBatchqueryResponse response = alipayClient.execute(request);
    if(response.isSuccess()){
        //成功处理逻辑;
    } else {
        //失败处理逻辑;
    }
} catch (AlipayApiException e) {
    // 异常处理
}

4）查询单个物业小区信息（alipay.eco.cplife.community.details.query）

响应参数特别说明

参数名称 参数说明
audit_status 若小区当前在审核流程，则返回当前审核状态。
community_services 返回小区已初始化的服务信息
community_services. qr_code_image
community_services. qr_code_type		 这两个参数在服务不同阶段返回不同的值：
在服务上线前返回短期有效的测试二维码，开发者可以通过支付宝客户端扫码进入服务上线前的测试验证入口。
服务上线后返回长期有效的正式二维码，可打印线下张贴引导用户进入服务入口。

SDK调用示例（以JAVA为例，更多语言示例参见接口文档）

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","UTF-8","alipay_public_key","RSA2");
AlipayEcoCplifeCommunityDetailsQueryRequest request = new AlipayEcoCplifeCommunityDetailsQueryRequest();

// 如果是开发者代物业公司账号调用接口，必须传入物业给开发者授权的令牌
request.putOtherTextParam("app_auth_token","请传入实际的第三方授权令牌值");

// 示例中通过string拼接json，实际项目建议用json库生成Json请求报文
request.setBizContent("{" +
"    \"community_id\":\"AJ5OFJC124403\"" +
"  }");
try {
    AlipayEcoCplifeCommunityDetailsQueryResponse response = alipayClient.execute(request);
    if(response.isSuccess()){
        //成功处理逻辑;
    } else {
        //失败处理逻辑;
    }
} catch (AlipayApiException e) {
    // 异常处理
}

2、开通小区基础服务

场景

开发者通过开通小区基础服务相关接口，设置小区的接入模式、小区对应的URL、结算模式、结算账号、服务期限等；

在正式环境验证环节，若开发者传入的结算账号是第一次在支付宝物业平台配置，则开发者在支付宝正式环境完成服务初始化、房间上传工作后，需调用单个小区查询（alipay.eco.cplife.community.details.query）接口获取测试二维码和有效期，当开发者上传至少一条账单（金额任意）后，在测试二维码失效前，通过正式版支付宝钱包扫码进入缴费查询页面，并成功支付至少一笔缴费，方可提交服务上线申请。

流程

接口说明

1）初始化小区基础服务信息（alipay.eco.cplife.basicservice.initialize）

请求参数特别说明

参数名称 参数说明
service_type 目前只支持一种服务类型：PROPERTY_PAY_BILL_MODE - 物业缴费账单上传模
external_invoke_address 对于PROPERTY_PAY_BILL_MODE服务类型，该参数用于传入用户缴费支付完成后开发者系统接收支付结果通知的完整回调URL。线上环境需要是HTTPS协议，并配置正规机构签发的OV级别及以上证书，不支持自签名证书；
account 可选参数，不指定则默认收款到物业授权支付宝物业平台时用的签约支付宝账号； 若需为小区另行指定物业缴费收款账号，可通过申请加入"在线物业缴费接入指南“最后的服务钉钉群 联系支付宝商务小二进行配置流程，确认完成配置后才能通过本接口传入，否则用户支付物业费时会报类似“该商户支付宝账户不支持收款”的错误信息。
account_type account的配套参数，指定物业缴费收款账号形式，支持支付宝用户号（UID，即合作伙伴Partner ID）和支付宝账号（登录名）两种形式。根据实际账号类型在接口中指定。
service_expires 若指定开发者与物业公司线下签约的服务有效期，则一旦过截止日期24点，小区物业缴费服务自动从支付宝下线；若不传该参数，服务长期有效，如服务合同有变化，开发者可通过修改服务接口重新指定服务有效期。

响应参数特别说明

参数名称 参数说明
bill_pay_auth_url 若接口响应的next_action为WAIT_AUTH_TO_PLATFORM - 等待物业授权给支付宝物业平台。开发者需引导物业商户访问该URL登录商户支付宝账号，授权支付宝物业平台代物业商户发起交易并支付到指定收款账号。
next_action 重要参数，提示开发者所初始化的服务从当前状态到下一状态需完成的事件码。开发者需根据事件码完成相应步骤，逐步推进直至小区上线。

SDK调用示例（以JAVA为例，更多语言示例参见接口文档）

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","UTF-8","alipay_public_key","RSA2");
AlipayEcoCplifeBasicserviceInitializeRequest request = new AlipayEcoCplifeBasicserviceInitializeRequest();

//如果是开发者代物业公司账号调用接口，必须传入物业给开发者授权的令牌
request.putOtherTextParam("app_auth_token","请传入实际的第三方授权令牌值");

// 示例中通过string拼接json，实际项目建议用json库生成Json请求报文
request.setBizContent("{" +
"    \"community_id\":\"AJ5OFJC124403\"," +
"    \"service_type\":\"PROPERTY_PAY_BILL_MODE\"," +
"    \"external_invoke_address\":\"https://example.com/gateway.do\"," +
"    \"account_type\":\"ALIPAY_PARTNER\"," +
"    \"account\":\"2088501624560333\"," +
"    \"service_expires\":\"2017-12-31 23:59:59\"" +
"  }");
try {
    AlipayEcoCplifeBasicserviceInitializeResponse response = alipayClient.execute(request);
    if(response.isSuccess()){
        //成功处理逻辑;
    } else {
        //失败处理逻辑;
    }
} catch (AlipayApiException e) {
    // 异常处理
}

2）修改小区物业基础服务信息（alipay.eco.cplife.basicservice.modify）

请求参数特别说明

参数名称 参数说明
status 开发者完成交易验证等相关工作后，需单独调用该接口并传入status: ONLINE发起服务/小区上线申请

SDK调用示例（以JAVA为例，更多语言示例参见接口文档）

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","UTF-8","alipay_public_key","RSA2");
AlipayEcoCplifeBasicserviceModifyRequest request = new AlipayEcoCplifeBasicserviceModifyRequest();

// 如果是开发者代物业公司账号调用接口，必须传入物业给开发者授权的令牌
request.putOtherTextParam("app_auth_token","请传入实际的第三方授权令牌值");

// 示例中通过string拼接json，实际项目建议用json库生成Json请求报文
request.setBizContent("{" +
"    \"community_id\":\"AJ5OFJC124403\"," +
"    \"service_type\":\"PROPERTY_PAY_BILL_MODE\"," +
"    \"status\":\"ONLINE\"" +
"  }");
try {
    AlipayEcoCplifeBasicserviceModifyResponse response = alipayClient.execute(request);
    if(response.isSuccess()){
        //成功处理逻辑;
    } else {
        //失败处理逻辑;
    }
} catch (AlipayApiException e) {
    // 异常处理
}

3、房屋信息管理

场景

开发者在创建小区并且完成小区基础服务初始化后，可以针对该小区上传房屋信息；上传成功后会返回支付宝系统的房屋唯一标识；

用户的账单是跟着房屋走的，因此通过“小区-房屋”的关联关系可以定位到账单；

开发者亦可以删除已经上传的房屋信息，查询已经上传的某个小区的所有房屋信息列表；如开发者已经针对房屋上传账单，且账单未支付，则开发者可以在删除账单后删除房屋信息；如账单已经被支付，则开发者在被支付账单当前账期内不可删除房屋信息；

流程

 

接口说明

1）上传物业小区内部房屋信息（alipay.eco.cplife.roominfo.upload）

请求参数特别说明

参数名称 参数说明
batch_id 每次新增一批房间需要传入不重复的批次号，防止重复提交
community_id 已入驻的支付宝小区ID，必须在同一个物业公司名下
room_info_set.out_room_id （重要，必传）在开发者系统中定义的每个房间编号，在该小区范围内（同一个community_id）必须唯一，在不同小区可以重复
room_info_set.address 每个房间在小区内的完整门牌地址，用于向用户展示，不必包含小区名称和地址
room_info_set.group和unit 如果该小区没有组团（小区内还有一期、二期，东区、西区子结构）和单元，不要传入。
TIPS：
  • 若一次上传的房间较多，调用上传接口时可能会返回系统繁忙的错误码，此时系统仍在后台处理，并不代表业务失败。请等候1分钟左右，调用alipay.eco.cplife.roominfo.query查询接口确认房间上传结果；
  • 上传是追加模式，不是覆盖模式，支付宝会根据小区+组团（若有）+楼栋+(单元)+房间的值组合或community_id+out_room_id的组合来判断是否重复；如需重新上传，需要事先删除所有房间；
  • 由于涉及到层级结构，小区房间不支持修改，如需修改，需要先删除指定房间再重新上传。

 SDK调用示例（以JAVA为例，更多语言示例参见接口文档）

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","UTF-8","alipay_public_key","RSA2");
AlipayEcoCplifeRoominfoUploadRequest request = new AlipayEcoCplifeRoominfoUploadRequest();

// 如果是开发者代物业公司账号调用接口，必须传入物业给开发者授权的令牌
request.putOtherTextParam("app_auth_token","请传入实际的第三方授权令牌值");

// 示例中通过string拼接json，实际项目建议用json库生成Json请求报文
request.setBizContent("{" +
"    \"batch_id\":\"201609201730123754\"," +
"    \"community_id\":\"AJ5OFJC443301\"," +
"      \"room_info_set\":[{" +
"        \"out_room_id\":\"20160427110001006778440713\"," +
"        \"group\":\"一期\"," +
"        \"building\":\"1栋\"," +
"        \"unit\":\"1单元\"," +
"        \"room\":\"1101室\"," +
"        \"address\":\"一期1栋2单元2202室\"" +
"        }]" +
"  }");
try {
    AlipayEcoCplifeRoominfoUploadResponse response = alipayClient.execute(request);
    if(response.isSuccess()){
        //成功处理逻辑;
    } else {
        //失败处理逻辑;
    }
} catch (AlipayApiException e) {
    // 异常处理
}

2）删除物业小区房屋信息（alipay.eco.cplife.roominfo.delete）

请求参数特别说明

参数名称 参数说明
out_room_id_set 参数格式为["开发者系统房屋ID 1", "开发者系统房屋ID 2", …, "开发者系统房屋ID 3"], 一次最多传200个房间；若需要一次清空小区所有已上传的房间，参数值设为["all"]
TIPS：
  • 只能删除房间，不支持删除组团、楼栋、单元这些中间结构（若需要删除整栋楼，需要把该栋所有房间删除，楼栋会自动删除。以此类推）。但支持一次删除小区下所有楼宇房间信息（请谨慎操作）；
  • 小区楼宇房间是缴费产品核心数据结构，上传前后请开发者仔细验证。特别在物业费账单上传后，必须将上传的物业费删除，才能删除房间。如果对应的房间已经有用户缴过费，则在物业账单当前账期内不允许删除该房间。

 SDK调用示例（以JAVA为例，更多语言示例参见接口文档）

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","UTF-8","alipay_public_key","RSA2");
AlipayEcoCplifeRoominfoDeleteRequest request = new AlipayEcoCplifeRoominfoDeleteRequest();

// 如果是开发者代物业公司账号调用接口，必须传入物业给开发者授权的令牌
request.putOtherTextParam("app_auth_token","请传入实际的第三方授权令牌值");

// 示例中通过string拼接json，实际项目建议用json库生成Json请求报文
request.setBizContent("{" +
"    \"batch_id\":\"201609201730123754\"," +
"    \"community_id\":\"AJ5OFJC443301\"," +
"      \"out_room_id_set\":[" +
"        \"201609201730123754\"" +
"      ]" +
"  }");

try {
    AlipayEcoCplifeRoominfoDeleteResponse response = alipayClient.execute(request);
    if(response.isSuccess()){
        //成功处理逻辑;
    } else {
        //失败处理逻辑;
    }
} catch (AlipayApiException e) {
    // 异常处理
}

3）查询小区房屋信息列表（alipay.eco.cplife.roominfo.query）

请求参数特别说明

参数名称 参数说明
community_id 传入已入驻的单个支付宝小区ID，该小区必须在同一个物业公司名下
page_size 有效取值范围为1~500，不传默认为200

SDK调用示例（以JAVA为例，更多语言示例参见接口文档）

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","UTF-9","alipay_public_key","RSA2");
AlipayEcoCplifeRoominfoQueryRequest request = new AlipayEcoCplifeRoominfoQueryRequest();

// 如果是开发者代物业公司账号调用接口，必须传入物业给开发者授权的令牌
request.putOtherTextParam("app_auth_token","请传入实际的第三方授权令牌值");

// 示例中通过string拼接json，实际项目建议用json库生成Json请求报文
request.setBizContent("{" +
"    \"community_id\":\"AJ5OFJC443301\"," +
"    \"page_num\":1," +
"    \"page_size\":100" +
"  }");
try {
    AlipayEcoCplifeRoominfoQueryResponse response = alipayClient.execute(request);
    if(response.isSuccess()){
        //成功处理逻辑;
    } else {
        //失败处理逻辑;
    }
} catch (AlipayApiException e) {
    // 异常处理
}

4、账单管理

场景

开发者在上传完楼宇房屋信息后，针对房屋上传账单；账单与楼宇房屋关联；

开发者亦可以针对已上传的账单进行修改、删除和查询操作；

流程

 

接口说明

1）批量上传代缴物业费账单（alipay.eco.cplife.bill.batch.upload）

请求参数特别说明

参数名称 参数说明
batch_id 防止重复提交，批次号不可重复；若所有业务参数完全相同，则支付宝作幂等处理；若批次号相同，其他业务参数不同，则报ITEM_UNIQUENESS_VIOLATION错误；
bill_set.bill_entry_id （重要）开发者定义每一条缴费明细项的唯一编号，用于后续变更、开发者系统中销账和对账中的费用项关联；在同一个小区内必须唯一。
bill_set.out_room_id （重要）开发者系统中的小区房屋唯一编号，必须事先通过房屋信息上传接口在支付宝上传对应的房屋；
bill_set.cost_type 物业定义的费用类型，例如物业管理费、二次供水费
bill_set.acct_period 由物业自定义展示给用户的账期，除字段长度外无限制；
bill_set.release_day 该项对应的账单出账日，格式为yyyyMMdd
bill_set.deadline 该项对应的缴费截止日期，格式 yyyyMMdd，不能早于请求接口时的系统时间；
bill_set.relate_id 缴费明细项关联ID，可选，由开发者自定义。若多笔明细的relate_id相同，则产品上约束用户必须同时支付关联的缴费明细项；
bill_set.remark_str 可选，由物业自定义，支付宝用户在查询到指定户的缴费明细，准备支付前，展示给用户的验证信息，预防用户错缴。
TIPS：
  • 物业账单数据上传接口处理时由于涉及资金敏感信息，任意一条处理失败，全部回滚，在接口响应中返回失败的bill_entry_id和错误码便于开发者定位问题；
  • 若一次上传的账单条目较多，调用上传接口时可能会返回系统繁忙的错误码，此时系统仍在后台处理，并不代表业务失败。请等候1分钟左右，调用alipay.eco.cplife.bill.batchquery查询接口确认账单上传结果；
  • 在线缴费产品允许用户一次合并支付多笔待缴费项目，由于系统限制，允许合并支付的项目笔数有上限，用户支付完成后，支付宝会通过异步支付通知将该笔支付对应的bill_entry_id发送给开发者系统，便于开发者进行销账。
  • 开发者可通过传入物业授权令牌，调用支付宝通用查询账单下载地址（ alipay.data.dataservice.bill.downloadurl.query）接口，定期获取物业收款账号的支付宝对账单，来完成业务对账，并提供缴费报表给到物业。 

SDK调用示例（以JAVA为例，更多语言示例参见接口文档）

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","UTF-8","alipay_public_key","RSA2");
AlipayEcoCplifeBillBatchUploadRequest request = new AlipayEcoCplifeBillBatchUploadRequest();

// 如果是开发者代物业公司账号调用接口，必须传入物业给开发者授权的令牌
request.putOtherTextParam("app_auth_token","请传入实际的第三方授权令牌值");

// 示例中通过string拼接json，实际项目建议用json库生成Json请求报文
request.setBizContent("{" +
"    \"batch_id\":\"201607192119100001\"," +
"    \"community_id\":\"AJ5OFJC124403\"," +
"      \"bill_set\":[{" +
"                \"bill_entry_id\":\"15000120160701\"," +
"        \"out_room_id\":\"453200086\"," +
"        \"room_address\":\"1号102室\"," +
"        \"cost_type\":\"物业管理费\"," +
"        \"bill_entry_amount\":\"200.00\"," +
"        \"acct_period\":\"2016年07月\"," +
"        \"release_day\":\"20160701\"," +
"        \"deadline\":\"20160831\"," +
"        \"relate_id\":\"1234\"," +
"        \"remark_str\":\"王*五\"" +
"        }]" +
"  }");
try {
    AlipayEcoCplifeBillBatchUploadResponse response = alipayClient.execute(request);
    if(response.isSuccess()){
        //成功处理逻辑;
    } else {
        //失败处理逻辑;
    }
} catch (AlipayApiException e) {
    // 异常处理
}

2）修改已上传的物业账单数据（alipay.eco.cplife.bill.modify）

响应参数特别说明

参数名称 参数说明
alive_bill_entry_list 若存在不允许修改的账单明细条目，响应参数会返回不允许修改的条目ID以及当前状态（支付中或支付完成）。

SDK调用示例（以JAVA为例，更多语言参见接口文档）

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","UTF-8","alipay_public_key","RSA2");
AlipayEcoCplifeBillModifyRequest request = new AlipayEcoCplifeBillModifyRequest();

// 如果是开发者代物业公司账号调用接口，必须传入物业给开发者授权的令牌
request.putOtherTextParam("app_auth_token","请传入实际的第三方授权令牌值");

// 示例中通过string拼接json，实际项目建议用json库生成Json请求报文
request.setBizContent("{" +
"    \"community_id\":\"AJ5OFJC124403\"," +
"      \"bill_entry_list\":[{" +
"                \"bill_entry_id\":\"15000120160701\"," +
"        \"room_address\":\"1号102室\"," +
"        \"cost_type\":\"物业管理费\"," +
"        \"bill_entry_amount\":\"200.00\"," +
"        \"acct_period\":\"2016年07月\"," +
"        \"release_day\":\"20160701\"," +
"        \"deadline\":\"20160831\"" +
"        }]" +
"  }");
try {
    AlipayEcoCplifeBillModifyResponse response = alipayClient.execute(request);
    if(response.isSuccess()){
        //成功处理逻辑;
    } else {
        //失败处理逻辑;
    }
} catch (AlipayApiException e) {
    // 异常处理
}

3）删除已上传的物业账单数据（alipay.eco.cplife.bill.delete）

响应参数特别说明

参数名称 参数说明
alive_bill_entry_list 若存在不允许删除的账单明细条目，响应参数会返回不允许删除的条目ID以及当前状态（支付中或支付完成）。 
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","UTF-8","alipay_public_key","RSA2");
AlipayEcoCplifeBillDeleteRequest request = new AlipayEcoCplifeBillDeleteRequest();

// 如果是开发者代物业公司账号调用接口，必须传入物业给开发者授权的令牌
request.putOtherTextParam("app_auth_token","请传入实际的第三方授权令牌值");

// 示例中通过string拼接json，实际项目建议用json库生成Json请求报文
request.setBizContent("{" +
"    \"community_id\":\"AJ5OFJC124403\"," +
"      \"bill_entry_id_list\":[" +
"        \"15000120160701\",\"15000120160702\",\"15000120160703\"" +
"      ]" +
"  }");
try {
    AlipayEcoCplifeBillDeleteResponse response = alipayClient.execute(request);
    if(response.isSuccess()){
        //成功处理逻辑;
    } else {
        //失败处理逻辑;
    }
} catch (AlipayApiException e) {
    // 异常处理
}

4）物业费账单数据批量查询（alipay.eco.cplife.bill.batchquery）

请求参数特别说明

支持多种查询过滤条件及组合，所有查询条件均不支持部分关键字模糊查询。

SDK调用示例（以JAVA为例，更多语言示例参见接口文档）

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","UTF-8","alipay_public_key","RSA2");
AlipayEcoCplifeBillBatchqueryRequest request = new AlipayEcoCplifeBillBatchqueryRequest();

// 如果是开发者代物业公司账号调用接口，必须传入物业给开发者授权的令牌
request.putOtherTextParam("app_auth_token","请传入实际的第三方授权令牌值");

// 示例中通过string拼接json，实际项目建议用json库生成Json请求报文
request.setBizContent("{" +
"    \"community_id\":\"AJ5OFJC124403\"," +
"    \"bill_status\":\"FINISH_PAYMENT\"," +
"    \"out_room_id\":\"453200086\"," +
"    \"cost_type\":\"物业管理费\"," +
"    \"acct_period\":\"2016年07月\"," +
"    \"release_day\":\"20160701\"," +
"    \"batch_id\":\"201607192119100001\"," +
"    \"page_num\":2," +
"    \"page_size\":300" +
"  }");
try {
    AlipayEcoCplifeBillBatchqueryResponse response = alipayClient.execute(request);
    if(response.isSuccess()){
        //成功处理逻辑;
    } else {
        //失败处理逻辑;
    }
} catch (AlipayApiException e) {
    // 异常处理
}

5、小区及账单上线

场景

开发者创建小区完成并且上传完账单后，通过“查询单个物业小区信息”接口，获取测试二维码，扫码针对测试账单进行支付测试。完成测试之后，小区具备上线条件，开发者可以调用“修改小区物业基础服务信息”接口为指定小区提出物业缴费服务上线申请，待支付宝小二审核后完成小区上线和生活缴费应用露出工作。一般周期为3-5个工作日，在此期间开发者可每天调用一次"查询单个物业小区信息"接口查询小区当前状态。

流程

支付成功异步通知

场景

用户通过物业缴费产生的交易，支付宝平台通过POST请求的形式将支付结果和该笔支付对应的部分缴费项业务信息组装成HTTP报文发送到开发者系统。为确保开发者能及时收到支付结果，支付宝在线缴费物业产品会按照15秒,30秒,1分钟,5分钟,10分钟,30分钟,15秒,30秒,1小时,15秒,30秒,2小时,4小时,8小时,16小时，16小时，16小时，16小时，16小时，16小时，16小时，16小时，16小时，16小时的间隔规则最多发送24次通知，重试期间若开发者系统收到支付通知并按如下约定格式响应成功报文则支付宝停止重发。

开发者需通过调用初始化小区基础服务信息（alipay.eco.cplife.basicservice.initialize）接口完成接收物业缴费完成异步消息回调URL的配置，通过调用修改小区物业基础服务信息（alipay.eco.cplife.basicservice.modify）接口完成回调URL的变更。

流程

关键通知参数

参数 类型 必传 描述 样例
notify_time Date 是 通知首次发送时间。格式为yyyy-MM-dd HH:mm:ss。 2016-08-11 12:12:12
sign_type String(10) 是 签名类型，由开发者在应用网关->加签方式中指定 RSA2
sign String(256) 是 支付宝生成的签名字符串  
trade_no String(64) 是 支付宝交易号 2013112011001004330000121536
buyer_user_id String(28) 否 买家支付宝账号对应的支付宝唯一用户号。以2088开头的纯16位数字 2088102146225130
buyer_logon_id String(100) 否 脱敏后的买家支付宝账号。 159****5620
seller_id String(30) 否 卖家支付宝用户号 2088102146225130
trade_status String(32) 是 交易目前所处的状态，见交易状态说明 TRADE_SUCCES
total_amount Number(9,2) 否 本次交易支付的订单金额，单位为人民币（元） 12.39
receipt_amount Number(9,2) 否 商家在交易中实际收到的款项，单位为元 10.23
refund_fee Number(9,2) 否 退款通知中，返回总退款金额，单位为元，支持两位小数 12.39
body String(128) 是 交易订单描述，在本产品中用于表示该笔缴费归属的小区编号和户号 支付宝房号|支付宝小区编号|物业户号
det_list String(320) 是 用于标识该笔缴费对应的缴费明细项外部编号，格式：:明细Id1|明细Id2|明细Id3 0001|0002|0003
gmt_create Date 否 交易创建时间 2014-11-27 15:45:56
gmt_payment Date 否 交易付款时间 2014-11-27 15:45:57
gmt_refund Date 否 交易退款时间 2014-11-27 15:45:57
gmt_close Date 否 交易结束时间 2014-11-27 15:45:57
fund_bill_list String 否 支付成功的各个渠道金额信息，详见资金明细信息说明  
└ fund_channel String 是 支付渠道，参见下面的“支付渠道说明”。 ALIPAYACCOUNT
└ amount Number(9,2) 是 对应支付渠道支付的金额，单位为元。 10

 通知触发条件

触发条件名 触发条件描述 触发条件默认值
TRADE_FINISHED 交易完成 false（不触发通知）
TRADE_SUCCESS 支付成功 true（触发通知）
WAIT_BUYER_PAY 交易创建 false（不触发通知）
TRADE_CLOSED 交易关闭 true（触发通知）

开发者对异步通知的处理

第一步： 对通知报文做验签

1、在接收到的通知HTTP报文参数中，将除sign以外的所有业务参数（包括sign_type， service和charset）的键-值对加入一个Map实例中。

2、使用《服务端SDK使用说明》中对于异步通知的验签方法AlipaySignature.rsaCheckV2。入参中：其中publicKey为开发者在应用配置阶段从蚂蚁金服开放平台开发者中心下载的支付宝公钥。

第二步：开发者响应异步通知，表示成功接受到通知。

响应格式要求必须是如下的XML格式报文，并且用开发者应用私钥加签。支付宝端接受到响应后若验签成功，则不再重复发送通知。

<alipay> 
      <response>{"econotify":"success"}</response>
      <sign>开发者动态生成</sign>
      <sign_type>RSA</sign_type>
</alipay>

第三步：开发者对通知数据做业务处理和销账。

1、判断total_amount是否确实为该订单包含的缴费明细项编号汇总（det_list字段）的实际金额。

2、校验通知中的seller_id 是否是实际物业收款账号。

在上述验证通过后开发者系统必须根据支付宝不同类型的业务通知，正确的进行不同的业务处理，并且过滤重复的通知结果数据。在支付宝的业务通知中，只有交易通知状态为TRADE_SUCCESS或TRADE_FINISHED时，支付宝才会认定为买家付款成功。

SDK调用示例（以JAVA为例，更多语言示例参见接口文档）

String bizContent = "";
Map<String, String> params = new HashMap<String, String>();
//将所有业务参数（包括sign，sign_type， service和charset）的键-值对加入一个Map实例中
params = putRequestParamsIntoMap();
   
try {
	//验签
	boolean checkResult =  AlipaySignature.rsaCheckV2(params, ALIPAY_PUBLIC_KEY, ALIPAY_CHARSET, SIGN_TYPE);	   
	if (checkResult) {//验签成功
		bizContent = "{\"econotify\":\"success\"}";
	} else {
		// 验签失败, 日志记录, 并反馈支付宝技术支持小二
		LOG.error("物业缴费异步通知验签失败");
	}
} catch (Exception e) {
	// 异常, 日志记录, 并反馈支付宝技术支持小二
	LOG.error("物业缴费异步通知处理失败", e);
}

// 不加密报文，加签后直接回送接收结果。
// 仅表明已成功接收通知,支付宝不再重复发送通知。
result = AlipaySignature.encryptAndSign(bizContent, ALIPAY_PUBLIC_KEY,ISV_PRIVATE_KEY,ALIPAY_CHARSET,false,true, SIGN_TYPE);
  
//注意：开发者后续自行异步处理销账逻辑，业务处理成功与否不要影响上面回传成功接收通知的报文。

支付结果异步通知特性

  • 只有在支付宝的交易管理中存在该笔交易，且发生了交易状态的改变，支付宝才会通过该方式发起服务器通知（ “等待买家付款”的状态默认是不会发送通知的）；
  • 开发者接收到支付宝异步交易通知，无论后续业务处理（比如物业系统销账等）结果如何，必须先同步返回包含 {\"econotify\":\"success\"}的XML报文。否则支付宝服务器会不断重发通知，直到超过24小时；
  • 程序执行完成后，该页面不能执行页面跳转。如果执行页面跳转，支付宝会收不到成功接受响应，会被支付宝服务器判定为该页面程序运行出现异常，而重发支付结果通知；
  • cookies、session等在此页面会失效，即无法获取这些数据；
  • 该方式的调试与运行必须在服务器上，即互联网上能访问；

注意：

  • 状态TRADE_SUCCESS的通知触发条件是物业商户签约的产品支持退款功能的前提下，买家付款成功；
  • 交易状态TRADE_FINISHED的通知触发条件是物业商户签约的产品不支持退款功能的前提下，买家付款成功；或者，商户签约的产品支持退款功能的前提下，交易已经成功并且已经超过可退款期限。

关于沙箱

沙箱环境是开放平台提供给开发者调试接口的环境，具体操作步骤见 沙箱接入指南。

物业缴费产品沙箱接入注意点

1、物业缴费产品支持沙箱接入；在沙箱调通接口后，必须在线上正式环境进行测试与验收，所有返回码及业务逻辑以线上为准；

2、沙箱环境下，开发者必须在联调初始化小区基础服务信息（alipay.eco.cplife.basicservice.initialize）接口前通过PC浏览器中访问以下沙箱授权链接，用沙箱商家账号授权支付宝获得代下单授权：

https://openauth.alipaydev.com/oauth2/appToAppAuth.htm?app_id=2016080100140559&redirect_uri=https%3a%2f%2falivemngsandbox.alipay-eco.com%2fcpmerchantmng-web-home%2fsecondauth%2fauthcode

3、物业缴费支付只支持余额支付，不支持银行卡、余额宝等其他支付方式；

4、请从蚂蚁开放平台-开发者中心-研发服务下载沙箱版钱包，并登录沙箱买家账号测试支付。

5、沙箱版钱包目前没有生活缴费应用入口，也不支持通知消息。开发者通过调用单个小区查询（alipay.eco.cplife.community.details.query）接口获取测试二维码和有效期，并通过沙箱版钱包扫一扫进入缴费查询页面，完成支付。沙箱联调通过后再通过线上环境完成真实数据对接和缴费服务上线申请。

FAQ

关于此文档暂时还没有FAQ
有用(11) 我要提问
返回
顶部
阿里巴巴集团 | 淘宝网 | 天猫 | 聚划算 | 全球速卖通 | 阿里巴巴国际交易市场 | 1688 | 阿里妈妈 | 阿里旅行·去啊 | 阿里云计算 | YunOS | 阿里通信 | 万网 | 高德 | 优视 | 友盟 | 酷盘 | 虾米 | 天天动听 | 来往 | 钉钉 | 11Main | 支付宝
关于淘宝 合作伙伴 营销中心 联系客服 开放平台 诚征英才 联系我们 网站地图 法律声明 © 2016 Taobao.com 版权所有
网络文化经营许可证：文网文[2010]040号 | 增值电信业务经营许可证：浙B2-20080224-1 | 信息网络传播视听节目许可证：1109364号