淘宝开放平台

登录
文档中心 > 开放平台

开放平台

生活缴费快速接入

更新时间：2017/06/08 访问次数：38223

第一步：创建应用

要在您的应用中使用支付宝开放产品的接口能力，您需要先去蚂蚁金服开放平台（open.alipay.com），在开发者中心中创建登记您的应用，并提交审核，审核通过后会为您生成应用唯一标识（APPID），并且可以申请开通开放产品使用权限，通过APPID您的应用才能调用开放产品的接口能力。需要详细了解开放平台创建应用步骤请参考《开放平台应用创建指南》。

第二步：配置密钥

开发者调用接口前需要先生成RSA密钥，RSA密钥包含应用私钥(APP_PRIVATE_KEY)、应用公钥(APP_PUBLIC_KEY）。生成密钥后在开放平台开发者中心进行密钥配置，配置完成后可以获取支付宝公钥(ALIPAY_PUBLIC_KEY)。详情请参考《配置应用环境》。

第三步：搭建和配置开发环境

1. 下载服务端SDK

为了帮助开发者调用开放接口，我们提供了开放平台服务端SDK，包含JAVA、PHP和.NET三个语言版本，封装了签名&验签、HTTP接口请求等基础功能。请先下载对应语言版本的SDK并引入您的开发工程。

各语言版本服务端SDK详细使用说明，请参考《服务端SDK说明》。

2. 接口调用配置

在SDK调用前需要进行初始化，以Java代码为示例如下：

AlipayClient alipayClient = new DefaultAlipayClient(URL, APP_ID, APP_PRIVATE_KEY, FORMAT, CHARSET, ALIPAY_PUBLIC_KEY, SIGN_TYPE);

关键参数说明:

配置参数 示例值解释 获取方式/示例值
URL 支付宝网关（固定） https://openapi.alipay.com/gateway.do
APPID APPID 即创建应用后生成 获取见上面创建应用并获取APPID
APP_PRIVATE_KEY 开发者私钥，由开发者自己生成 获取详见上面配置密钥
FORMAT 参数返回格式，只支持json json（固定）
CHARSET 编码集，支持GBK/UTF-8 开发者根据实际工程编码配置
ALIPAY_PUBLIC_KEY 支付宝公钥，由支付宝生成 获取详见上面配置密钥
SIGN_TYPE 商户生成签名字符串所使用的签名算法类型，目前支持RSA2和RSA，推荐使用RSA2 RSA2

第四步：调用接口

账单缴费

接口英文名称 接口中文名称 接口描述

alipay.ebpp.bill.add

创建账单

创建缴费账单

alipay.ebpp.bill.get

查询账单

查询账单状态

使用账单缴费接口您需要使用到如下开放产品：

  • 网页账户授权，或无线账户授权（scope需要使用auth_puc_charge）
  • 服务窗快捷支付（需要设置参数：bizType:"trade",bizSubType:"puc_charge"）

创建账单

以下为创建机构账单示例代码，因为每个机构约定的账单格式会不同，开发者如果需要对接，可以通过接入流程了解如何接入，以下设置的机构参数，开发者可以在沙箱进行接口调试体验，确定正式的账单格式后，可以在线上环境进行调整。

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
AlipayEbppBillAddRequest alipayRequest = new AlipayEbppBillAddRequest();
alipayRequest.setMerchantOrderNo("201507250000001"); //外部订单号，需要唯一
alipayRequest.setOrderType("JF"); //缴费类型
alipayRequest.setSubOrderType("GAS"); //缴费子类型
alipayRequest.setChargeInst("WHSTRQ2150"); //机构代码
alipayRequest.setBillKey("2015072001"); //户号
alipayRequest.setOwnerName("张三"); //户主姓名
alipayRequest.setPayAmount("91.00"); //账单金额
alipayRequest.setServiceAmount("9.00"); //服务费
alipayRequest.setBillDate("201607"); //账单日期
alipayRequest.setMobile("139XXXXXXXX"); //手机号码
alipayRequest.setBankBillNo("20160712"); //银行单号
alipayRequest.setExtendField("{\"channel\":\"EXTERNAL_BANGDAO\"}"); //机构扩展属性
AlipayEbppBillAddResponse alipayResponse = alipayClient.execute(alipayRequest);
//处理接口返回消息alipayResponse，具体返回参数可以参考API列表文档

查询账单

账单创建好之后，等待用户支付，商户可以使用商户外部订单号，通过查询账单接口查询账单状态，示例代码如下：

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
AlipayEbppBillGetRequest alipayRequest = new AlipayEbppBillGetRequest();
alipayRequest.setOrderType("JF");
alipayRequest.setMerchantOrderNo("201507250000001");
AlipayEbppBillGetResponse alipayResponse = alipayClient.execute(alipayRequest);
//处理接口返回消息alipayResponse，具体返回参数可以参考API列表文档

账单代扣

接口英文名称 接口中文名称 接口描述

alipay.ebpp.pdeduct.sign.add

代扣签约

缴费代扣用户签约

alipay.ebpp.pdeduct.sign.query

代扣协议查询

用户签约合约状态查询

alipay.ebpp.pdeduct.sign.cancel

代扣解约

用户代扣解约

alipay.ebpp.pdeduct.pay

代扣支付

代扣账单支付

alipay.ebpp.pdeduct.bill.pay.status

代扣支付状态查询

代扣支付交易状态查询

使用账单缴费接口您需要使用到如下开放产品：

  • 网页账户授权，或无线账户授权
  • 获取会员信息接口
TIPS：代扣签约需要使用代扣签约定制的支付密码鉴权页面，https://ebppprod.alipay.com/deduct/enterMobileicPayPassword.htm?cb=[鉴权码回调地址]，鉴权码将会以token或&token形式作为参数传给回调地址，该页面必须在支付宝已经登录的情况下才能正常访问，否则将报错，建议在服务窗中使用。

代扣签约

以下为代扣签约示例代码，因为每个机构约定的账单格式会不同，开发者如果需要对接，可以通过接入流程了解如何接入，以下设置的机构参数，开发者可以在沙箱进行接口调试体验，确定正式的账单格式后，可以在线上环境进行调整。

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
AlipayEbppPdeductSignAddRequest alipayRequest = new AlipayEbppPdeductSignAddRequest();
alipayRequest.setPayPasswordToken(PASSWORD_TOKEN); //通过支付鉴权拿到的token
alipayRequest.setUserId(USER_ID); //通过获取会员信息接口中拿到的，alipay_user_id
alipayRequest.setBizType("JF"); //业务类型
alipayRequest.setSubBizType("ELECTRIC"); //子业务类型
alipayRequest.setBillKey("2015072601"); //户号
alipayRequest.setOwnerName("张三");
alipayRequest.setPid("2088102123187816"); // 缴费机构商户UID（PID），沙箱固定值
alipayRequest.setChargeInst("CQCENTERELECTRIC"); // 机构号
alipayRequest.setOutAgreementId("123456"); // 外部协议号
alipayRequest.setDeductType("direct_sign_deduct"); // 协议扣款类型
alipayRequest.setAgentChannel("PUBLICPLATFORM"); // 签约代理渠道
alipayRequest.setAgentCode("123456"); // 签约代理渠道代码
AlipayEbppPdeductSignAddResponse alipayResponse = alipayClient.execute(alipayRequest);
//处理接口返回消息alipayResponse，具体返回参数可以参考API列表文档

代扣查询

根据返回的代扣agreement_id和user_id，可以通过代扣查询接口查询协议，示例代码如下：

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
AlipayEbppPdeductSignQueryRequest alipayRequest = new AlipayEbppPdeductSignQueryRequest();
alipayRequest.setBizContent("{" +
    "    \"agreement_id\":\"20160726000089404558\"," +
    "    \"user_id\":\"2088102168514583\"" + 
    //user_id为通过获取会员信息接口中拿到的，alipay_user_id
    "  }"
    );
AlipayEbppPdeductSignQueryResponse alipayResponse = alipayClient.execute(alipayRequest);
//处理接口返回消息alipayResponse，具体返回参数可以参考API列表文档

代扣解约

当用户希望解除代扣协议的话，可以调用代扣解约接口，示例如下：

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
AlipayEbppPdeductSignCancelRequest alipayRequest = new AlipayEbppPdeductSignCancelRequest();
alipayRequest.setUserId(USER_ID);//通过获取会员信息接口中拿到的，alipay_user_id
alipayRequest.setAgreementId("20160726000700130000580400000106");
alipayRequest.setAgentChannel("PUBLICPLATFORM");
alipayRequest.setAgentCode("123456");
alipayRequest.setPayPasswordToken(PASSWORD_TOKEN); //通过支付鉴权拿到的token
AlipayEbppPdeductSignCancelResponse alipayResponse = alipayClient.execute(alipayRequest);
//处理接口返回消息alipayResponse，具体返回参数可以参考API列表文档

代扣支付

用户完成代扣签约后，机构商户可以通过代扣支付接口，对用户的缴费账单进行扣款支付，示例代码如下：

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
AlipayEbppPdeductPayRequest alipayRequest = new AlipayEbppPdeductPayRequest();
alipayRequest.setAgreementId("20160726000700130000580400000106");//设置协议ID
alipayRequest.setUserId(USER_ID);//通过获取会员信息接口中拿到的，alipay_user_id
alipayRequest.setBillKey("2015072004"); //户号
alipayRequest.setPid("2088102123187816"); // 缴费机构商户UID（PID），沙箱固定值
alipayRequest.setOutOrderNo("20150720030102"); //商户订单号
alipayRequest.setPayAmount("23.00"); //设置支付金额
alipayRequest.setFineAmount("2.00"); //设置滞纳金
alipayRequest.setBillDate("201607"); //设置账期
alipayRequest.setAgentChannel("PUBLICPLATFORM"); //设置渠道
alipayRequest.setAgentCode("123456"); //设置二级渠道码
alipayRequest.setMemo("memo"); //设置描述
AlipayEbppPdeductPayResponse alipayResponse = alipayClient.execute(alipayRequest);
//处理接口返回消息alipayResponse，具体返回参数可以参考API列表文档

代扣支付状态查询

发起代扣支付后，机构商户可以通过代扣支付状态查询，查询支付状态和结果，示例如下：

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
AlipayEbppPdeductBillPayStatusRequest alipayRequest = new AlipayEbppPdeductBillPayStatusRequest();
alipayRequest.setAgreementId(USER_ID); //注意，此处需要用USER_ID，为通过获取会员信息接口中拿到的，alipay_user_id
alipayRequest.setOutOrderNo("20150720030102");
AlipayEbppPdeductBillPayStatusResponse alipayResponse = alipayClient.execute(alipayRequest);
//处理接口返回消息alipayResponse，具体返回参数可以参考API列表文档

接口调用返回错误码说明

      获取接口处理结果代码示例

System.out.println(alipayResponse.getCode()); // 获取接口结果码
System.out.println(alipayResponse.getSubCode()); // 当接口调用失败后，获取子错误码
System.out.println(alipayResponse.getMsg()); // 获取子错误描述
System.out.println(alipayResponse.getBody()); // 获取完整的返回报文
同步返回结果码 含义 说明

40001～40006

业务处理失败

具体失败原因请参考公共错误码。其它请参考API文档。

20000

业务出现未知错误或者系统异常

业务出现未知错误或者系统异常（请一定要在确定本次调用结果后，再发起重试），可调用查询接口发起查询确定结果。

关于沙箱

如何接入沙箱

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

生活缴费沙箱接入注意点

      1、生活缴费支持沙箱接入；在沙箱调通接口后，必须在线上进行测试与验收，所有返回码及业务逻辑以线上为准；
      2、因生活缴费业务较复杂，并且与机构关联较大，因此沙箱中，请根据上文快速接入中的参数进行调试；

FAQ

关于此文档暂时还没有FAQ
有用(18) 我要提问
返回
顶部