接入说明

1.研发接入

开发者需要提供给连连以下信息

提供方	内容	是否必须	备注
商户	商户RSA公钥	必须	平台会基于公钥对商户发起的请求进行验签。可通过：https://www.toolhelper.cn/AsymmetricEncryption/RSA 获取
商户	服务器出口ip	必须	平台会校验商户请求来源ip
商户	商户通知地址	必须	用于接收平台发起的通知请求
商户	支付确认地址	可选	企业支付时若企业配置该地址，平台会发起同步确认，企业通过后才会完成交易动作
平台	连连公钥及demo	可选	SDK-Demo:https://github.com/LLPayiOSDev/EnterpriceWallet

根据商户申请的通讯协议接入算法，需要获取相应的证书，企业钱包系统提供相关的接入包。

由于商户与平台系统采用非对称加密算法，故商户和平台系统各自持有一对公私钥，
由于私钥信息唯一标识商户，请请妥善保管。

2.连连配置

测试环境网关地址:https://cwallet-openapi-ewtest.lianlianpay.com
生产环境网关地址:https://cwallet-openapi.lianlianpay.com

3.协议规则

传输方式	为保证交易安全性，接口全部采用HTTPS传输
提交方式	前台类交易通过用户APP/浏览器直接方式后台类交易采用POST方式提交
数据格式	提交和返回数据都为JSON格式
字符编码	统一采用utf-8字符编码

4.通讯安全

商户与平台系统之间的通讯采用HTTPS协议，SSL握手时验证服务器证书，加密算法128位以上。服务器证书采用DigiCert签发的服务器证书。SSL协议保证传输通道的安全，包括通讯数据加密、服务器身份认证。

5.日期规范

考虑商户订单系统主机时间和平台主机时间会有微小差别，并且考虑地区时区差别，允许商户订单日期和平台日期前后相差一天，但所有给商户的清算和对账数据都以平台的账务日期为准。

6.异步通知说明

平台系统对商户的交易请求处理完成后，会将交易结果通过服务器主动通知的方式通知给商户在交易申请接口请求时传入的异步通知地址。
异步通知特性：
l 如何获取通知信息：平台系统通过HTTP POST数据流的方式发送通知信息，商户开发者可参考如下方法获取通知内容：

java参考request.getInputStream()；
php参考file_get_contents("php://input")；
asp参考Request.InputStream。

l 商户接收通知地址的要求：通知地址公网可访问，端口不限；建议使用https协议，对于https地址，商户证书必须为认证机构颁发的证书，不可使用非授信组织颁发的测试证书，如不可使用自行颁发的证书。
l 处理通知后如何返回：如果商户系统处理业务成功，则直接返回ret_code=0000即可。否则返回其他信息、抛异常或者无返回，平台系统均会认为商户系统处理失败，并进行重复通知。
l 如何重复通知：当第一次通知失败后，重复通知目前频率2分钟，共30次；商户响应成功则通知停止，否则会重复发起；平台系统可能会根据内部系统需要调整支付结果通知的频率和次数。
关于通知无序性说明：由于互联网中存在拥塞、丢包、重发等现象，所以异步通知可能在极端情况下以未定义的顺序到达商户服务端，又或可能存在由于网络延时、丢包等原因，导致商户系统接收到交易成功通知后，接收到相同交易的重复通知，此时需要商户端对支付成功通知做且仅做一次成功业务的处理。商户系统必须具备接收重复通知处理的能力，若未进行处理，由于重复通知导致的重复入账等资金风险由商户自行承担。

6.1事件格式

事件以统一格式推送至应用系统。

字段	数据结构	描述
mch_id	String	商户唯一编号
topic	String	事件主题，每个事件都有唯一的主题
data	String	主题数据，不同主题事件拥有不同的消息体，具体内容参考对应事件接口

6.1.1示例

{
    "mch_id":"402308300000084103",
    "topic":"CARD_STATUS_CHANGED",
    "event_id":"202311160010808673",
    "data":"{\"account_no\":\"2023111515475488\",\"account_status\":\"NORMAL\",\"remark\":\"申请通过\",\"bank_card_no\":\"240117170710710267\"}"
}

6.2安全校验

6.2.1签名校验

这种校验方式相对复杂，但是安全性高，不需要解密和解析事件。校验方式如下：
平台发起HTTP请求时，在请求头内会带如下参数，应用通过平台颁发的平台公钥进行验签，确保请求时由平台发起，具体步骤可参考签名方法

自定义Header key	必须	描述
Signature-Type	是	签名方式：RSA
Signature-Data	是	签名值RSA签名，见安全签名机制 Signature-Data = Base64(RSA(MD5(完整JSON报文)))
mch_id	可选	商户在连连系统中的唯一标识
sp_no	可选	服务商编号，服务商接入模式下必须
timestamp	是	时间戳(yyyyMMddHHmmss) 例如20211110145022
nonce	是	随机字符串,至少为10位,有效期内防重复提交

6.3通知列表

6.3.1商务卡

商务卡	topic	描述
卡状态变更通知	card.v1.status.change	卡申请完成后，平台会把相关卡结果和卡号发送给企业，企业需要接收处理该消息，并返回应答。
卡申请结果通知	card.v1.apply.result	卡申请完成后，平台会把相关卡结果和卡号发送给企业，企业需要接收处理该消息，并返回应答。

6.3.2公司主体

公司主体	topic	描述
公司主体创建事件	enterprise.v1.create	创建公司主体后发出事件。
公司主体信息变更事件	enterprise.v1.update	公司主体信息变更后发出事件。
公司主体删除事件	enterprise.v1.delete	删除公司主体后发出事件。

6.3.3组织架构

组织架构	topic	描述
部门创建事件	department.v1.create	创建部门后发出事件。
部门删除事件	department.v1.update	删除部门后发出事件。
部门信息变更事件	department.v1.delete	部门信息变更后发出事件。
用户创建事件	user.v1.create	创建用户后发出事件。
用户变更事件	user.v1.update	用户信息变更后发出事件。
用户删除事件	user.v1.delete	删除用户后发出事件。

6.3.4企业码付

企业码	topic	描述
交易结果通知	order.v1.status	企业码被扫或主扫交易成功或失败，平台会通知该消息给到企业。
交易退款通知	order.v1.refund	企业码交易成功后一个自然日，商家发起退款会发送该通知给到企业。
交易撤销通知	order.v1.reverse	企业码交易成功后当日撤销时会发起该请求，通知企业撤销业务处理。

6.3.5VCC卡支付

VCC	topic	描述
交易创建通知	order.v1.preauth	仅当VCC商务卡发生交易时，将异步通知企业交易发生。
交易结果通知	order.v1.status	VCC交易成功或失败，平台会通知该消息给到企业。
交易退款通知	order.v1.refund	VCC交易成功后一个自然日，商家发起退款会发送该通知给到企业。
交易撤销通知	order.v1.reverse	VCC交易成功后当日撤销，系统处理异常时会发起该请求，通知企业撤销业务处理。
交易结算通知	order.v1.settle.success	此接口目前只支持VCC支付场景，用于接收已完成实际资金结算的交易通知。
3DS验证通知	vcc.v1.3ds	为了提供额外的欺诈保护，3DS 验证 (3DS) 会要求客户在付款时在发卡行那里完成额外的验证步骤。在这种场景下平台会发送3DS验证通知给到您，您需要将3DS验证码通过短信或者邮件的方式推送给用户。

7.报文解析

由于功能迭代，平台侧请求、响应报文内容可能会新增字段，或字段的顺序发生调整，调用需要兼容该情况，确保新增字段不会影响签名及报文解析

1.研发接入#

2.连连配置#

3.协议规则#

4.通讯安全#

5.日期规范#

6.异步通知说明#

6.1事件格式#

6.1.1示例#

6.2安全校验#

6.2.1签名校验#

6.3通知列表#

6.3.1商务卡#

6.3.2公司主体#

6.3.3组织架构#

6.3.4企业码付#

6.3.5VCC卡支付#

7.报文解析#