SaaS交易平台委托代征API接口文档

一.产品介绍

        SaaS交易平台标准版是平台对旗下商户提供的一种多元化支付开放服务能力。 企业开发者在自己的业务系统中可以通过SaaS交易平台API标准版所提供的接口来解决签约、支付问题。流程参考下图：

二.适用场景

        支持在通过移动端、H5、PC端、微信公众号/小程序中进行文件在线签约。 企业开发者希望集成平台的签约和支付系统。

三.接入方式

        商户网站系统和支付系统之间通过 http 协议来进行通信，报文编码格式为 UTF-8，接口以URL的形式提供以 POST/GET的请求方式处理，接口说明中描述了请求参数。公钥（appKey）、白名单配置等请求配置信息，请与我们系统运营人员联系接洽。

四.对接前准备

4.1 环境区分

• 生产环境：api-merchant.leqinkeji.com

• 沙箱环境：leqin-merchant-test.youjiayun.com

4.2 公共请求头参数描述

4.3 公共响应参数

五.接口API

5.1 小程序/H5签约API

         进行签约时，需要进行姓名、身份证2要素校验，必须保证为同一人才可以签约，传入成功后将对灵工手机号发送通知短信，通过通知短信进入小程序完成注册/登录，确认无误后完成合同签署。建议签约前自行进行运营商三要素校验

业务背景

        因业务需求，企业的产品中需嵌入SaaS交易平台电子签约功能，确认C端用户先签约（成为合法兼职员工），形成服务合作关系，再提现（发薪）。

接口地址

        /merchant/exportApi/sign/sign

请求方式

        POST

请求头

        公共请求头

请求参数

响应参数

请求示例

POST https://api-merchant.leqinkeji.com/merchant/exportApi/sign/sign
{
    "name":"张三",
    "idCard":"4332238932828",
    "mobile":"132239022321"
}

响应示例

{
    "code":"200",    
    "msg":"请求成功",
    "data":{
        "contractId":"94736783463487",
        "signUrl":"http://sdfsfsfsfds.com/sdfsdfidsdi"
    }
}

5.2 静默签

       生成静默签合同。如果运营打开后置签约，商户可以无需对接此接口

业务背景

        无需用户交互签约。

接口地址

         /merchant/exportApi/sign/silence

请求方式

        POST

请求头

        公共请求头

请求参数

请求示例

POST 
https://api-merchant.leqinkeji.com/merchant/exportApi/sign/noSign
{ 
    "name":"张三",  
    "idCard":"4332238932828"
}

5.3 委托代征佣金发放

        对已签约/未签约的灵工进行银行卡/支付宝/微信方式佣金发放（发放）

接口地址

        /merchant/exportApi/pay/payApi

请求方式

        POST

请求头

        公共请求头

请求参数

PayDetailObj 明细对象

响应参数

请求示例

POST 
https://api-merchant.leqinkeji.com/merchant/exportApi/pay/payApi
{
    "bizOrderNo":"M1234567893456",  
    "totalCount":1,
    "totalAmount":"120.33",
    "bankType":1,
    "payMethod":1,
    "payDetailList":[{
        "userName":"范蠡",
        "idCard:"330429200515122653" ,
        "accountNo:"633565894365445" ,
        "phone:"15099835222" ,
        "amount:"120.33" ,
        "merchantRemark:"测试打款" ,
        "detailOrderNo:"M0000001" ,
        "payAccountType:"1" 
     }]
}

响应示例

{
    "code":"200",  
    "msg":"请求成功",
    "data":{
        "bizOrderNo":"M1234567893456",
        "platformOrderNo:"P211101019011915410" 
     }
}

异步通知规则

第一次失败后，5分钟后、15分钟后、30分钟后、1小时后、2小时后重试，最后还是没有成功，可自主查询结果。

5.4 发放异步通知

        调用委托代征方式发放佣金API，批次处理结束通知商户订单批次状态

接口地址

        商户自行提供给运营人员进行配置

请求方式

        POST

请求头

        公共请求头

请求参数

PayNotifyObj

响应参数

        返回success字符串表示成功，不在进行消息投递，否则会依据通知策略再次回调

响应示例

{
    "success"
}

ps:这个回调状态40是指批次处理完成状态，不是交易状态，交易状态需要调用查询明细获取，举例一批提交了1000笔，这个回调状态40是说1000笔全部交易完成，具体哪些成功失败哪些失败需要调用明细接口查询，里面可能有校验失败，有交易失败的和交易成功的,如果是50说明发放取消。

5.5 签约异步通知

        调用小程序签约，用户成功签约后，通知商户签约状态

接口地址

        商户自行提供给运营人员进行配置

请求方式

        POST

请求头

        公共请求头

请求参数

SignNotifyObj 签约通知对象

响应参数

           返回success字符串表示成功，不在进行消息投递，否则会依据通知策略再次回调

响应示例

{
    "success"
}

5.6 充值异步通知

        商户充值成功后，通知商户充值的账户信息

接口地址

        商户自行提供给运营人员进行配置

请求方式

        POST

请求头

        公共请求头

请求参数

ChargeNotifyObj 充值信息

响应参数

           返回success字符串表示成功，不在进行消息投递，否则会依据通知策略再次回调

响应示例

{
    "success"
}

5.7 退票异步通知

        打款成功后，可能会因为接收银行各种情境，发生的退票

接口地址

        商户自行提供给运营人员进行配置

请求方式

        POST

请求头

        公共请求头

请求参数

ReturnTicketObj 退票信息

响应参数

           返回success字符串表示成功，不在进行消息投递，否则会依据通知策略再次回调

响应示例

{
    "success"
}

5.8 任务审核异步通知

        创建任务后平台审核任务通知

接口地址

        商户自行提供给运营人员进行配置

请求方式

        POST

请求头

        公共请求头

请求参数

TaskInfoObj 退票信息

响应参数

        返回任意字符串，表示成功，返回error或者空，会5分钟后再次回调

响应示例

{
    "success"
}

5.9 余额查询

        商户可通过当前协议下的渠道类型来查余额明细

接口地址

        /merchant/exportApi/pay/getBalanceApi

请求方式

        GET

请求头

        公共请求头

请求参数

响应参数

5.10 订单分页查询

        根据商户打款批次订单号或平台批次号进行结果查询，建议接收到批次结果异步通知后进行查询

接口地址

        /merchant/exportApi/pay/getOrderListApi

请求方式

        GET

请求头

        公共请求头

请求参数

响应参数

PayDetailObj 打款明细

5.11 签署结果查询

        通过小程序签约接口返回的请求编号来查询合同签署状态

接口地址

        /merchant/exportApi/sign/getSignResult

请求方式

        GET

请求头

        公共请求头

请求参数

响应参数

响应示例

{
    "code": 200,
    "msg": "成功",
    "data": {
        "idCard": "156578190001015555",
        "userName": "用户名称",
        "userPhone": "13554567886",
        "status": 1
    }
}

5.12 任务列表查询

       查询创建的任务列表，详情及状态

接口地址

        /merchant/exportApi/task/selectTaskList

请求方式

        GET

请求头

        公共请求头

请求参数

响应参数

TaskInfoObj 任务对象

5.13 催签

        发起签约通知后，对未签约的用户进行催签，目前支持最大催签5次

接口地址

        /merchant/exportApi/sign/urgeSign

请求方式

        POST

请求头

        公共请求头

请求参数

响应参数

响应示例

{
    "code":200, 
    "msg":"成功", 
    "data":"true"
}

5.14 订单回单分页查询

        根据商户打款批次订单号或平台批次号进行结果及回单查询，回单需T+1生成

接口地址

        /merchant/exportApi/pay/getOrderReceiptList

请求方式

        GET

请求头

        公共请求头

请求参数

响应参数

OrderReceipt 打款明细

5.15 创建任务

        创建业务任务订单用于佣金发放

接口地址

        /merchant/exportApi/task/createTask

请求方式

        POST

请求头

        公共请求头

请求参数

响应参数

响应示例

{
    "code":200, 
    "msg":"成功", 
    "data":"T2022120815458435354""
}

对接demo地址

        https://common.leqinkeji.com/leqin-saas/api-demo.zip

ps：

        demo中的SignEncryUtil有两个加密生成签名方法，encrySignGet是为GET请求方式时使用，encrySignPost是为POST请求方式时使用

返回状态码

QA:

1、post与get签名不同，get参数放到url上拼接，参数key使用ascll,(密钥+bankType+bizOrderNo+payDetailList+payMethod+remarks+taskNo+totalAmount+totalCount)

1、佣金发放明细字段顺序，未用ascll排序需要按照文档排序(payAccountType+detailOrderNo+amount+phone+idCard+accountNo+userName+merchantRemark)，如

密钥对
appKey = "kWb7MeSATqYRb474u6pO0Sw9Es4SitjjRVXXLZ";  
serct = "Bwls4lu8EP9znjvvsPpklNK8ofLshIvB2xtoVQ";
请求传参数
{"headers":{"orderId":["fa359493-f735-40b4-91bb-1bd506b61063"],"agreementId":["30000089"],"sign":["dc65432ad3f35665f7ca7eb5d80caae6"],"appKey":["kWb7MeSATqYRb474u6pO0Sw9Es4SitjjRVXXLZ"],"Content-Type":["application/json"],"merchantNo":["10000232365"],"requireTime":["2023-02-01 09:54:46"]},"body":{"totalAmount":"1.00","payDetailList":[{"payAccountType":1,"detailOrderNo":"TS00000011","amount":"1.00","phone":"13188711522","idCard":"111429196605291811","accountNo":"62234258676607631","userName":"吴2阳1","merchantRemark":"给他钱"}],"bankType":1,"payMethod":1,"taskNo":"TK20221217001","totalCount":1,"remarks":"测试第一笔","bizOrderNo":"2022122815090728198"}} 
签名原文：
Bwls4lu8EP9znjvvsPpklNK8ofLshIvB2xtoVQ12022122815090728198[{"payAccountType":1,"detailOrderNo":"TS00000011","amount":"1.00","phone":"13188711522","idCard":"111429196605291811","accountNo":"62234258676607631","userName":"吴2阳1","merchantRemark":"给他钱"}]1测试第一笔TK202212170011.001

2、打款明细整体json_encode 后再拼接字符串，json_encode 要加 JSON_UNESCAPED_UNICODE，不能用unicode码

4.签名时数值采用字符串格式进行签名