拉卡拉第三方账单号支付接入接口文档

1、拉卡拉账单号支付接入规范副标题：技术标准版本 1.0.1修订历史版本号作者内容提要核准人发布日期1.0.1董复文赵铭2008-09-061.0.2李英杰目 录1、概述41.1、名词解释42、报文签名概述43.通讯报文编码44、账单号支付54.1、账单号支付-查询交易能否支付54.1.1、接口描述54.1.2、业务约束54.1.3、处理流程54.1.4、协作模式64.1.5、请求格式74.1.6、应答格式84.2、账单号支付-交易支付104.2.1、接口描述104.2.2、业务约束104.2.3、处理流程114.2.4、协作模式114.2.5、请求格式124.2.6、应答格式144.3 商户获取

2、拉卡拉账单对帐文件164.3.1、接口描述164.3.2、处理流程164.3.3、对帐文件格式174.3.4、文件内容174.4 Lakala的demo的使用介绍171、概述拉卡拉账单平台以安全、合规、标准、易用的方式，将拉卡拉的服务发布出来，连接外部合作伙伴，构建开放的价值网络。拉卡拉账单平台对外发布的服务遵循统一的接口规范。接口规范基于互联网开放标准，符合国家关于金融行业电子化方面的各种法律法规，以及拉卡拉公司对业务与系统风险进行控制的需要。拉卡拉账单平台接口规范对外部系统与拉卡拉账单平台协作中的交互模式、数据交换格式、安全机制、外部系统接入与管理方式等制定统一的标准。1.1、名词解释拉卡

3、拉账单平台是拉卡拉对外提供的一组标准的基础业务服务，使得拉卡拉的客户可以基于此服务安全、灵活的组装构成满足他们的需求，以实现协同、开放、繁荣的生态圈！2、报文签名概述报文中的签名使用的RSA公私钥技术时,发送报文方使用自己持有的私钥对报文进行签名,然后接收报文方使用公钥对签名进行验签.拉卡拉持有拉卡拉私钥和商户的公钥。商户持有商户自己的私钥和拉卡拉的公钥。拉卡拉将原文使用拉开拉私钥进行签名和原文传输给商户。商户接收之后，将原文按照报文说明中的顺序及方式组织。进行验签。商户将信息返回给拉卡拉系统时，将原文按照本文档说明的进行结构和顺序，进行签名，然后和原文一起回应给拉卡拉。拉卡拉系统进行验签。报

4、文中的签名使用的是MD5数字签名,双方约定mackey,报文中明文不传mackey,摘要原文按照接口拉卡拉提供商户的具体签名方法。针对不同的开发环境，拉卡拉提供响应的接口。和接口说明。具体的签名内容参见报文.3.通讯报文编码 通讯报文中采用key=value的形式，value,统一使用utf-8的编码格式。4、账单号支付4.1、账单号支付-查询交易能否支付 拉卡拉账单平台向合作伙伴系统发起查询交易能否支付请求4.1.1、接口描述合作伙伴用户到拉卡拉的下属网点申请合作伙伴支付业务、提供合作伙伴的交易号和支付金额。拉卡拉系统首先查询合作伙伴系统确认交易能否支付后再发送支付请求4.1.2、业务约束约

5、束：l 交易的状态为”等待买家付款”l 支付的金额和交易的金额需一致l 交易的买家状态必须合法4.1.3、处理流程流程如下图所示:1. 合作伙伴用户在拉卡拉的线下网点提供合作伙伴交易号和金额、通过口授或者填写网点的单子2. 拉卡拉网点核实合作伙伴交易号和金额、网点营业员需要提醒用户所提供正确的交易号和金额l 合作伙伴是一串16位的数字、不包含数字等其他类型的字符3. 拉卡拉网点营业员在其终端录入合作伙伴交易号和金额4. 拉卡拉终端系统向合作伙伴系统发起查询请求5. 拉卡拉系统根据需要处理自己的业务6. 拉卡拉系统向合作伙伴查询交易能否支付、请求中带有合作伙伴交易号和金额7. 合作伙伴系统查询交

6、易能否支付8. 合作伙伴返回交易能否支付结果9. 拉卡拉账单平台系统根据需要进行业务处理、并向其网点返回能否支付的信息10. 拉卡拉网点将能否支付结果告知合作伙伴用户11.合作伙伴用户核实本次查询结果4.1.4、协作模式请求/响应交互模式。使用紧凑型的参数格式。在业务流程第59步的交互过程如下图所示:4.1.5、请求格式查询账单能否支付请求参数字段名变量名类型/格式说明可空通用参数接口版本v1.1,商户响应原样返回N服务servicelakala.agency.tradePayConsultBalance 商户在响应报文中原样返回N拉卡拉商户号mer_id由合作伙伴提供(拉卡拉在合作伙伴的身份

7、) N安全号配置号sec_id由合作伙伴提供 暂提供sec_id=RSA,MD5N请求IDreq_id参见数据格式部分(拉卡拉产生的商户可以不关注,按照原值返回)N业务参数(agency_pay_consult_balance_req)账单号trade_noString(16)合作伙伴账单号(用户的帐号,或者合作伙伴平台的订单号)N金额amountNumber(8,2)以元为单位、范围为0，999999.99 N拉卡拉查询时间lakala_query_timeTimestamp拉卡拉的查询时间、格式为YYYYMMDDhhmmssN签名sign公私钥签名amount=50.00&lakala_q

8、uery_time=2010-04-15 23:14:30&mer_id=test&req_id=1004152314301&sec_id=RSA&service=lakala.agency.tradePayConsultBalance&trade_no=00001&v=1.1(拉卡拉使用拉卡拉私钥进行签名,签名方法因为合作伙伴平台使用的开发语言不同,所以具体不做举例,但是该接口的输入参数为原数据串和私钥,得到的结果为签名数据) NMD5数字签名amount=50.00&lakala_query_time=2010-04-15 23:14:30&mer_id=test&req_id=10041

9、52314301&sec_id=RSA&service=lakala.agency.tradePayConsultBalance&trade_no=00001&v=1.1mackey(mackey双方约定)例：v=1.1&service= lakala.agency.tradePayConsultBalance &mer_id=1234&sec_id=RSA&req_id=1234&trade_no=2008062302799024&amount=20.33&lakalar_query_time=20030515202233&sign =1234(注：“1234”为假定的字符串)4.1.6、应

10、答格式查询账单能否支付应答参数字段名变量名类型/格式说明可空通用参数接口版本v请求时传入的内容,原样返回则可N服务service请求时传入的内容,原样返回则可N拉卡拉商户号mer_id请求时传入的内容,原样返回则可N安全号配置号sec_id请求时传入的内容,原样返回则可N请求IDreq_id请求时传入的内容,原样返回则可N结果参数(agency_pay_consult_balance_res)可以支付can_payString(1)值为主y（y表示可以支付 n 表示账单号不存在，001 金额输入有误,002，账单号错误，003，支付金额小于交易金额，004 商品售罄）N合作伙伴系统流水号par

11、tner _bill_noString(16)合作伙伴流水号用于对帐标识（如果can_pay值为y，那么合作伙伴订单号不为空,合作伙伴订单号在合作伙伴系统内唯一）N金额amountNumber(8,2)以元为单位、范围为0.01，999999.99Y合作伙伴查询时间partner _query_timeTimestamp合作伙伴的查询时间、格式为YYYYMMDDhhmmssN附加信息partner_extendinfoString(60)附加信息（第三方为uid对应的用户名称）使用Base64编码,然后再用utf-8编码N签名sign公私钥签名amount=20.50&can_pay=y&me

12、r_id=1234&partner_bill_no=1111&partner_extendinfo=usernames&partner_query_time=2008417111135&req_id=1234&sec_id=1234&service=lakala.agency.tradePayConsultBalance&v=1.1NMD5数字签名amount=20.50&can_pay=y&mer_id=1234&partner_bill_no=1111&partner_extendinfo=usernames&partner_query_time=2008417111135&req_id=

13、1234&sec_id=1234&service=lakala.agency.tradePayConsultBalance&v=1.1mackey(mackey双方约定)例：v=1.1&service= lakala.agency.tradePayConsultBalance &mer_id=1234&sec_id=RSA&req_id=1234&can_pay=y&partner_bill_no=1234123412341234&amount=20.50&partner_query_time=2008417111135&partner_extendinfo=usernames&sign=12

14、344.2、账单号支付-交易支付 拉卡拉确认交易可支付后向合作伙伴发起交易支付请求4.2.1、接口描述拉卡拉网点在确认交易可以支付后、向合作伙伴系统发起真正的交易支付请求、拉卡拉账单系统与合作伙伴交互，完成交易的支付;请注意：拉卡拉系统必须通过查询订单能否支付接口确认订单可以支付，并且得到合作伙伴订单号后，向合作伙伴发起支付请求。4.2.2、业务约束约束：l 合作伙伴交易的状态必须合法交易才能被支付4.2.3、处理流程处理流程如下图所示:1. 合作伙伴用户在拉卡拉的线下网点提供合作伙伴交易号和金额、通过口授或者填写网点的单子2. 拉卡拉网点核实合作伙伴交易号和金额、网点营业员需要提醒用户提供正

15、确的交易号l 合作伙伴交易号是一串16位的数字、不包含数字等其他类型的字符3. 拉卡拉网点营业员在其终端录入合作伙伴交易号和金额4. 拉卡拉终端系统向拉卡拉账单系统发起支付请求5. 拉卡拉账单系统根据需要处理自己的业务6. 拉卡拉账单系统向合作伙伴发起支付请求、请求中带有合作伙伴交易号和金额、合作伙伴订单号、拉卡拉订单号7. 合作伙伴系统进行交易支付8. 合作伙伴系统返回支付结果9. 拉卡拉账单系统根据需要进行业务处理、并向其网点返回支付结果10. 合作伙伴网点将支付结果告知合作伙伴用户11. 合作伙伴用户核实本次支付结果4.2.4、协作模式请求/响应交互模式。使用紧凑型的参数格式。在业务流程

16、第59步的交互过程如下图所示:4.2.5、请求格式交易支付请求参数字段名变量名类型/格式说明可空通用参数接口版本v1.1N服务servicelakala.agency.tradePayBalanceN拉卡拉商户号mer_id由合作伙伴提供(拉卡拉在合作伙伴的身份)N安全号配置号sec_id由合作伙伴提供，sec_id=RSA,MD5N请求IDreq_id参见数据格式部分,拉卡拉随机生成N业务参数(agency_trade_pay_balance_req)账单号trade_noString(16)合作伙伴账单号N用户输入金额amountNumber(8,2)以元为单位、范围为0.01，99999

17、9.99 N支付金额amount_payNumber(8,2)以元为单位、范围为0.01，999999.99 N付款类型pay_typeString(2)付款类型（M:表示现金；D：表示借记卡；C：表示贷记卡、信用卡；O：表示其它方式。默认为M）N合作伙伴系统流水号partner_bill_noString(16)合作伙伴订单号用于对帐标识（合作伙伴订单号在合作伙伴系统内唯一，为拉卡拉查询交易能否支付，得到可以支付结果时，同时取得的合作伙伴订单号）N拉卡拉流水号lakala _bill_noString(16)拉卡拉流水号（确保在拉卡拉系统中唯一）、只能为数字和字母、推进用数字N货币代码cur

18、rencychar(3)见货币代码表（默认是人民币，代码：156）N拉卡拉支付时间lakala_pay_timeTimestamp拉卡拉的支付时间、格式为YYYYMMDDhhmmssN终端号terminalnoString(32)拉卡拉终端号格式为010460012220348956终端输入的手机号usermobilenoString(20)终端上输入的支付人 的手机。签名sign公私钥签名amount=99.90&amount_pay=99.90¤cy=2 &lakala_bill_no=99999999999& lakala_pay_time=20100415231058 &m

19、er_id=test &partner_bill_no=abcefg123 &pay_type=11 &req_id=1004152310581 &sec_id=RSA &service=lakala.agency.tradePayBalance &trade_no=00001 &v=1.1NMd5数字签名amount=99.90&amount_pay=99.90¤cy=2 &lakala_bill_no=99999999999& lakala_pay_time=20100415231058 &mer_id=test &partner_bill_no=abcefg123 &pay_

20、type=11 &req_id=1004152310581 &sec_id=RSA &service=lakala.agency.tradePayBalance &trade_no=00001 &v=1.1mackey(mackey双方约定)例：v=1.1&service= lakala.agency.tradePayBalance &mer_id=1234&sec_id=RSA&req_id=1234&trade_no=2008062302799024&amount=20.33&amount_pay=20.33&pay_type=M&partner_bill_no=1234123412341

21、234&lakala_bill_no=200805150001¤cy=156&lakala_pay_time=20030515202233&sign =1234 (注：“1234”为假定的字符串)4.2.6、应答格式字段名变量名类型/格式说明可空通用参数接口版本v请求时传入的内容N服务service请求时传入的内容,按照原样返回N拉卡拉商户号mer_id请求时传入的内容,按照原样返回N安全号配置号sec_id请求时传入的内容,按照原样返回N请求IDreq_id请求时传入的内容,按照原样返回N结果参数(agency_trade_pay_balance_res)支付结果is_succe

22、ssString(1)值为yN拉卡拉订单号lakala_bill_noString(16)拉卡拉订单号（确保在拉卡拉系统中唯一）、只能为数字和字母、推进用数字N合作伙伴订单号partner_bill_noString(16)合作伙伴订单号用于对帐标识（合作伙伴订单号在合作伙伴系统内唯一，为拉卡拉查询交易能否支付，得到可以支付结果时，同时取得的合作伙伴订单号）N合作伙伴支付时间partner_pay_timeTimestamp合作伙伴的支付时间、格式为YYYYMMDDhhmmssN签名sign公私钥签名is_success=y&lakala_bill_no=1111&mer_id=1234&pa

23、rtner_bill_no=22222&partner_pay_time=2008417111135&req_id=1234&sec_id=1234&service=lakala.agency.tradePayConsultBalance&v=1.1NMd5数字签名is_success=y&lakala_bill_no=1111&mer_id=1234&partner_bill_no=22222&partner_pay_time=2008417111135&req_id=1234&sec_id=1234&service=lakala.agency.tradePayConsultBalance&

24、v=1.1mackey(mackey双方约定)例：v=1.1&service= lakala.agency.tradePayBalance &mer_id=1234&sec_id=RSA&req_id=1234&is_success=y&lakala_bill_no=2009070611425682&partner_bill_no=2009070611425682&partner_pay_time=2008417111135&sign =1234说明：合作伙伴提供的”查询交易能否支付”以及”交易支付”这两个接口应该是配合使用的、拉卡拉账单系统发起”查询交易能否支付”请求、而后根据合作伙伴的返回结果决定是否需要发起”交易支付”请求。一个典型的应用是拉卡拉下接很多的终端、用户在终端提供交易号和金额后、终端向拉卡拉的服务器发起请求、拉卡拉账单系统先查询合作伙伴确认交易可以支付后马上返回终端告知其收取用户的钱、而后拉卡拉异步的调用合作伙伴来推进交易这里要说明的是当拉卡拉向合作伙伴发起”交易支付”请求时、只要合作伙伴找到对应的交易、则合作伙伴一定会对拉卡拉进行帐务记录，并且结交易的买家合作商户帐户中充值(也就是用户) 当然、拉卡拉在收取用户的钱后请确保向合作伙伴发起交易推进请求！在这种