爱贝服务端接入指南

1、深圳市爱贝信息技术有限公司 爱贝服务端接入指南目录简介及注意事项21. 简介22. API接口列表简介23. 接口说明34. 通用参数定义3API接口列表51.登录令牌认证51.1 功能说明51.2 请求URL51.3 请求格式示例51.4业务参数说明51.5示例代码72.下单72.1功能说明72.2 请求URL82.3 请求格式示例82.4 业务参数说明92.5 示例代码103.交易结果回调通知113.1功能说明113.2 请求URL113.3 请求格式示例113.4 业务参数说明113.5 示例代码124.交易结果主动查询134.1 功能说明134.2 请求URL134.3 请求格式示例1

2、34.4 业务参数说明134.5 示例代码155. 契约查询155.1 功能说明155.2 请求URL155.3 请求格式示例155.4 业务参数说明165.5 示例代码186. 契约鉴权186.1 功能说明186.2 请求URL186.3 请求格式示例186.4 业务参数说明196.5 示例代码207. 契约退订207.1功能说明207.2 请求URL217.3 请求格式示例217.4 业务参数说明217.5 示例代码23简介及注意事项1. 简介本文档主要描述计费平台服务端为商户提供的API接口，用于指导商户接入并使用计费平台的相关能力。2. API接口列表简介 登录令牌认证：商户使用计费平

3、台账号作为用户的应用登录账号时，应用客户端调用计费平台sdk登录接口会拿到登录令牌，然后再调用本接口获取用户的账号信息。 下单：商户调用计费平台sdk支付接口之前需要先调用本接口进行下单获取transid。 支付结果通知：支付完成后计费平台通过本接口向商户后台发送支付结果通知。 支付结果查询：商户在发起支付请求后可以调用本接口查询支付结果。 契约查询：商户可以调用本接口查询托管在计费平台的契约数据。 契约鉴权：用户在使用商户的业务时，商户可以通过本接口进行使用鉴权。 契约退订：商户可以调用本接口将用户的契约进行退订。3. 接口说明 接口均采用http协议，POST方法。 数据传输的时候参数值需

4、要进行urlencode，urlencode规则使用application/x-www-form-urlencoded方式，即空格” ”会被编码成加号”+”。进行urlencode编码时，中文字符采用UTF-8编码。 请求和应答参数均为transdata、sign、signtype。transdata为具体业务参数，数据格式为json格式；sign为transdata的签名数据；signtype为签名算法类型，目前只支持RSA算法。具体呈现方式为transdata=xxxx&sign=yyyy&signtype=RSA，其中yyyy就是对xxxx的签名数据，采用RSA MD5数字签名算法，私钥

5、签名、公钥验签。和Java里面的MD5WithRSA算法一致。 商户需要以应用私钥对请求数据进行签名、使用平台公钥对应答数据进行验签。错误应答无须验签。4. 通用参数定义feetype定义feetype表示商品采用的计费方式，目前定义如下：0消费型_应用传入价格2 消费型_平台设置价格3 订阅型_按时长4 订阅型_自动续费5 非消费型6 订阅型_按次数因为业务拓展，计费方式定义可能会扩展，建议商户不要做严格校验paytype定义paytype表示用户采用的支付方式，目前定义如下：1 充值卡2 游戏点卡4 银行卡401 支付宝402 财付通501 支付宝网页502 - 财付通网页403 - 微信

6、支付5 - 爱贝币6 - 爱贝一键支付16 - 百度钱包30 - 移动话费31 - 联通话费32 - 电信话费因为业务拓展，支付方式定义可能会扩展，建议商户不要做严格校验code定义code表示计费平台处理请求失败时返回的错误代码，目前定义如下：1001应用发起的请求签名验证失败1002请求参数错误2001登录令牌已过期2002登录令牌认证失败3001商户订单号已存在3002商品数据异常3003支付金额为0，不需要支付3004用户存在有效契约，不需要支付4001订单正在处理5001用户不存在有效契约5002用户契约已过期5003用户契约已过完9999系统繁忙，请稍后再试API接口列表1.登录令

7、牌认证1.1 功能说明商户使用计费平台账号作为用户的应用登录账号时，应用客户端调用计费平台sdk登录接口会拿到登录令牌，然后再调用本接口获取用户的账号信息。接口采用http协议，POST方法。1.2 请求URL:9999/payapi/tokencheck1.3 请求格式示例urlencode前内容：transdata=appid:123,logintoken:3213213&sign=xxxxxx&signtype=RSA1.4业务参数说明参数名称参数含义数据类型是否可选参数说明appid应用编号String(20)必填平台分配的应用编号logintoken登录令牌String(32)必填商

8、户调用计费平台sdk登录接口得到的登录令牌Sign对transdata的签名数据必填对transdata的签名数据Signtype签名算法类型必填签名算法类型，目前仅支持RSA返回参数及格式成功应答数据样例（urlencode前内容）：transdata=loginname:testuser,userid:1234567890&sign=xxxxxx&signtype=RSA成功应答参数说明：参数名称参数含义数据类型是否可选参数说明loginname账号的登录名String(32)必填账号登录名userid账号的唯一标识String(20)必填账号编号Sign对transdata的签名数据必填

9、对transdata的签名数据Signtype签名算法类型必填签名算法类型，目前仅支持RSA失败应答数据样例（urlencode前内容）：transdata=code:1001,errmsg:签名验证失败失败应答参数列表：参数名称参数含义数据类型是否可选参数说明code错误代码String(4)必填请求失败时，返回的错误代码。具体定义参见简介及注意事项errmsg错误信息描述String(64)必填错误原因描述Sign对transdata的签名数据必填对transdata的签名数据Signtype签名算法类型必填签名算法类型，目前仅支持RSA1.5示例代码2.下单2.1功能说明用户购买商户的商

10、品时，商户先通过本接口进行下单，下单成功计费平台会返回交易流水号，商户再通过交易流水号调用计费平台sdk的支付接口。接口采用http协议，POST方法。2.2 请求URL:9999/payapi/order2.3 请求格式示例urlencode前内容：transdata=appid:123,waresid:1,cporderid:22222,price:1.00,currency:RMB,appuserid:test,notifyurl:2.4 业务参数说明参数名称参数含义数据类型是否可选参数说明appid应用编号String(20)必填平台分配的应用编号waresid商品编号Integer必

11、填应用中的商品编号waresname商品名称String(32)可选商品名称，对于消费型_应用传入价格的计费方式有效，如果不传则展示后台设置的商品名称cporderid商户订单号String(64)必填商户生成的订单号，需要保证系统唯一price支付金额Float(6,2)可选支付金额，对于消费型_应用传入价格的计费方式有效，其它计费方式不需要传入本参数currency货币类型String(32)必填货币类型以及单位：RMB 人民币（单位：元）appuserid用户在商户应用的唯一标识String(32)必填用户在商户应用的唯一标识，建议为用户帐号。对于游戏，需要区分到不同区服，#号分隔；比如

12、游戏帐号abc在01区，则传入“abc#01”cpprivateinfo商户私有信息String(64)可选商户私有信息，支付完成后发送支付结果通知时会透传给商户notifyurl支付结果通知地址String(128)可选商户服务端接收支付结果通知的地址Sign对transdata的签名数据必填对transdata的签名数据Signtype签名算法类型必填签名算法类型，目前仅支持RSA返回参数及格式成功应答数据样例（urlencode前内容）：transdata=transid:11111&sign=xxxxxx&signtype=RSA成功应答参数说明：参数名称参数含义数据类型是否可选参数说

13、明transid交易流水号String(32)必填计费支付平台的交易流水号Sign对transdata的签名数据必填对transdata的签名数据Signtype签名算法类型必填签名算法类型，目前仅支持RSA失败应答数据样例（urlencode前内容）：transdata=code:1001,errmsg:签名验证失败失败应答参数列表：参数名称参数含义数据类型是否可选参数说明code错误代码String(4)必填请求失败时，返回的错误代码。具体定义参见简介及注意事项errmsg错误信息描述String(64)必填错误原因描述Sign对transdata的签名数据必填对transdata的签名数

14、据Signtype签名算法类型必填签名算法类型，目前仅支持RSA2.5 示例代码3.交易结果回调通知3.1功能说明用户在计费平台完成支付或契约退订后，如果商户在下单接口有传入notifyurl，则交易平台会主动向商户发送支付结果通知。平台在没有收到商户应答或收到错误应答的情况下，会定时重发。重发超过一定次数后，将不再进行重发。接口采用http协议，POST方法。3.2 请求URL商户在后台设置的接收通知地址或下单接口传入的notifyurl。若都有配置以接口传入的为准。3.3 请求格式示例urlencode前内容：transdata=transtype:0,cporderid:1,transi

15、d:2,appuserid:test,appid:3,waresid:31,feetype:4,money:5.00,currency:RMB,result:0,transtime:2012-12-12 12:11:10,cpprivate:test,paytype:1&sign=xxxxxx&signtype=RSA3.4 业务参数说明参数名称参数含义数据类型是否可选参数说明transtype交易类型integer必填交易类型：0支付交易；1支付冲正（暂未启用）；2契约退订3自动续费cporderid商户订单号String(64)必填商户订单号transid交易流水号String(32)必填

16、计费支付平台的交易流水号appuserid用户在商户应用的唯一标识String(32)必填用户在商户应用的唯一标识appid游戏idString(20)必填平台为商户应用分配的唯一代码waresid商品编码integer必填平台为应用内需计费商品分配的编码feetype计费方式integer必填计费方式，具体定义见简介及注意事项money交易金额Float(6,2)必填本次交易的金额currency货币类型String(32)必填货币类型以及单位：RMB 人民币（单位：元）result交易结果integer必填交易结果：0交易成功1交易失败transtime交易完成时间String(20)必填

17、交易时间格式：yyyy-mm-dd hh24:mi:sscpprivate商户私有信息String(64)可选商户私有信息paytype支付方式integer可选支付方式，具体定义见简介及注意事项Sign对transdata的签名数据必填对transdata的签名数据Signtype签名算法类型必填签名算法类型，目前仅支持RSA返回参数及格式商户成功接收到支付结果通知之后，返回http包体数据为SUCCESS。若返回数据非SUCCESS，则视为失败。3.5 示例代码4.交易结果主动查询4.1 功能说明本接口适用于在支付交易完成后，CP可主动向支付平台服务端发起交易结果查询。接口采用http协议

18、，POST方法。4.2 请求URL:9999/payapi/queryresult4.3 请求格式示例urlencode前内容：transdata=appid:123456,cporderid:3213213&sign=xxxxxx&signtype=RSA4.4 业务参数说明参数名称参数含义数据类型是否可选参数说明appid应用代码String(20)必须商户在支付平台的应用代码cporderid外部订单号String(64)必须支付时传入的商户订单号Sign对transdata的签名数据必填对transdata的签名数据Signtype签名算法类型必填签名算法类型，目前仅支持RSA返回参数

19、及格式成功应答数据样例（urlencode前内容）：transdata=cporderid:3213213,transid:2,appuserid:test,appid:123456,waresid:31,feetype:4,money:5.00,currency:RMB, result:0, transtime:2012-12-12 12:11:10,cpprivate:test,paytype:1&sign=xxxxxx&signtype=RSA成功应答参数说明：参数名称参数含义数据类型是否可选参数说明cporderid商户订单号String(64)必填商户订单号transid交易流水号S

20、tring(32)必填计费支付平台的交易流水号appuserid用户在商户应用的唯一标识String(32)必填用户在商户应用的唯一标识appid游戏idString(20)必填平台为商户应用分配的唯一代码waresid商品编码integer必填平台为应用内需计费商品分配的编码feetype计费方式integer必填计费方式，具体定义见简介及注意事项money交易金额Float(6,2)必填本次交易的金额currency货币类型String(32)必填货币类型以及单位：RMB 人民币（单位：元）result交易结果integer必填交易结果：0交易成功；2待支付transtime交易完成时间S

21、tring(20)必填交易时间格式：yyyy-mm-dd hh24:mi:sscpprivate商户私有信息String(64)可选商户私有信息paytype支付方式integer可选支付方式，具体定义见简介及注意事项Sign对transdata的签名数据必填对transdata的签名数据Signtype签名算法类型必填签名算法类型，目前仅支持RSA失败应答数据样例（urlencode前内容）：transdata=code:1001,errmsg:签名验证失败失败应答参数列表：参数名称参数含义数据类型是否可选参数说明code错误代码String(4)必填请求失败时，返回的错误代码。具体定义参见

22、简介及注意事项errmsg错误信息描述String(64)必填错误原因描述Sign对transdata的签名数据必填对transdata的签名数据Signtype签名算法类型必填签名算法类型，目前仅支持RSA4.5 示例代码5. 契约查询5.1 功能说明对于提供契约型商品的应用，应用可以在用户进入商城时预先通过本接口查询契约状态，再给用户展示商品状态。接口采用http协议，POST方法。5.2 请求URL:9999/payapi/subsquery5.3 请求格式示例urlencode前内容：transdata=appuserid:username,appid:3213213,waresid:

23、1&sign=xxxxxx&signtype=RSA5.4 业务参数说明参数名称参数含义数据类型是否可选参数说明appuserid用户的应用账号String(32)必填用户在商户应用的唯一标识appid应用编号String(20)必填平台分配的应用编号waresid商品编号integer可选应用中的商品编号，如果本字段为空表示查询该用户购买的该应用中的所有契约Sign对transdata的签名数据必填对transdata的签名数据Signtype签名算法类型必填签名算法类型，目前仅支持RSA返回参数及格式成功应答数据样例（urlencode前内容）：transdata=subsnum:1,su

24、bslist:waresid:1,feetype:6,leftcount:1,subsstatus :0&sign=xxxxxx&signtype=RSA成功应答参数说明：参数名称参数含义数据类型是否可选参数说明subsnum契约数目integer必填用户订购的契约数目subslist契约列表subs_schema必填契约列表Sign对transdata的签名数据必填对transdata的签名数据Signtype签名算法类型必填签名算法类型，目前仅支持RSAsubs_schema定义：参数名称参数含义数据类型是否可选参数说明waresid商品编号integer必填应用中的商品编号feetype

25、计费方式integer必填计费方式，具体定义见附录leftcount剩余次数integer可选剩余次数，对于包次数类契约有效endtime截止时间String(20)可选契约的有效截止时间，格式为“HHHH-MM-DD HH24:MI:SS”subsstatus契约状态integer必填契约状态：0 正常1 退订2 暂停失败应答数据样例（urlencode前内容）：transdata=code:1001,errmsg:签名验证失败失败应答参数列表：参数名称参数含义数据类型是否可选参数说明code错误代码String(4)必填请求失败时，返回的错误代码。具体定义参见简介及注意事项errmsg错误

26、信息描述String(64)必填错误原因描述Sign对transdata的签名数据必填对transdata的签名数据Signtype签名算法类型必填签名算法类型，目前仅支持RSA5.5 示例代码6. 契约鉴权6.1 功能说明对于提供契约型商品的应用，应用可以在用户使用商品时调用本接口进行契约的鉴权。对于包时长类型的契约，鉴权成功会返回契约的有效截止时间；鉴权失败则返回错误码。对于包次数类型的契约，鉴权成功会将剩余次数减一，同时返回契约的剩余次数；鉴权失败则返回错误码。接口采用http协议，POST方法。6.2 请求URL:9999/payapi/subsauth6.3 请求格式示例urlenc

27、ode前内容：transdata=appuserid:username,appid:3213213,waresid:1&sign=xxxxxx&signtype=RSA6.4 业务参数说明参数名称参数含义数据类型是否可选参数说明appuserid用户的应用账号String(32)必填用户在商户应用的唯一标识appid应用编号String(20)必填平台分配的应用编号waresid商品编号integer必填应用中的商品编号Sign对transdata的签名数据必填对transdata的签名数据Signtype签名算法类型必填签名算法类型，目前仅支持RSA返回参数及格式成功应答数据样例（urlen

28、code前内容）：transdata=feetype:6,leftcount:2,subsstatus:0&sign=xxxxxx&signtype=RSA成功应答参数说明：参数名称参数含义数据类型是否可选参数说明feetype计费类型integer必填计费类型，具体定义见附录leftcount剩余次数integer可选剩余次数，对于包次数类契约有效endtime截止时间String(20)可选契约的有效截止时间，格式为“HHHH-MM-DD HH24:MI:SS”subsstatus契约状态integer必填契约状态：0 正常1 退订2 暂停Sign对transdata的签名数据必填对tra

29、nsdata的签名数据Signtype签名算法类型必填签名算法类型，目前仅支持RSA失败应答数据样例（urlencode前内容）：transdata=code:1001,errmsg:签名验证失败失败应答参数列表：参数名称参数含义数据类型是否可选参数说明code错误代码String(4)必填请求失败时，返回的错误代码。具体定义参见简介及注意事项errmsg错误信息描述String(64)必填错误原因描述Sign对transdata的签名数据必填对transdata的签名数据Signtype签名算法类型必填签名算法类型，目前仅支持RSA6.5 示例代码7. 契约退订7.1功能说明用户可以对已经完成购买的契约进行退订，退订时会将契约置为退订状态，在该状态下用户仍然可以使用该商品，直到契