微工卡接入流程

本文档提供微工卡（Payroll Card）的完整接入流程，帮助客户快速理解并完成对接。

📖 前置阅读：
签名生成详细规则 - 所有接口都需要签名
错误码文档 - 了解错误码处理

📋 业务流程总览

🚀 快速接入（推荐方式）

方式一：核身预下单（一步完成授权 + 核身）

适用场景：用户首次使用微工卡，需要同时完成开通、授权和核身验证。

步骤：

步骤	接口	说明
①	`POST /api/v1/payroll-card/face/preorder/official`	核身预下单，获取 token
②	-	使用 token 拉起微工卡小程序
③	-	用户在小程序完成人脸核身
④	`GET /api/v1/payroll-card/face/result`	查询核身结果
⑤	-	核身成功后即可发起转账

方式二：分步授权 + 转账

适用场景：用户已授权，仅需发起转账；或需要精细控制授权流程。

步骤：

步骤	接口	说明
①	`POST /api/v1/payroll-card/token`	生成授权 token
②	`POST /api/v1/payroll-card/launch/use`	获取拉起链接
③	-	用户在小程序完成授权
④	`GET /api/v1/payroll-card/auth/status`	查询授权状态
⑤	`POST /api/v1/payroll-card/transfer/batch/create`	发起批量转账

📝 详细接入步骤

第一步：用户授权

1.1 生成授权 Token

响应：

{
  "success": true,
  "code": "SUCCESS",
  "data": {
    "openid": "oXXXXX",
    "mchid": "1900000001",
    "subMchid": "1900000109",
    "token": "abcdefghijklmn",
    "expiresIn": 1800
  }
}

1.2 拉起微工卡小程序

使用返回的 token 拉起微信微工卡小程序：
微信官方文档

💡 推荐：使用 POST /api/v1/payroll-card/launch/use 接口，可一步获取完整的拉起链接。

1.3 查询授权状态

响应：

{
  "success": true,
  "code": "SUCCESS",
  "data": {
    "openid": "oXXXXX",
    "subMchid": "1900000109",
    "authorizeState": "AUTHORIZED",    // UNAUTHORIZED / AUTHORIZED / DEAUTHORIZED
    "authorizeTime": "2025-01-08T10:30:00+08:00",
    "registerState": "REGISTERED",     // UNREGISTERED / REGISTERED / CLOSED
    "registerTime": "2025-01-08T10:30:00+08:00"
  }
}

授权状态说明：

状态	含义	后续操作
`UNAUTHORIZED`	未授权	需要拉起小程序让用户授权
`AUTHORIZED`	已授权	可以发起转账
`DEAUTHORIZED`	已取消授权	需要重新授权

第二步：核身验证（可选）

如果业务场景需要核身（如签到打卡、投保等），使用核身预下单接口：

2.1 核身预下单

响应：

{
  "success": true,
  "code": "SUCCESS",
  "data": {
    "authenticateNumber": "AUTH20250108001",
    "openid": "oXXXXX",
    "mchid": "1900000001",
    "subMchid": "1900000109",
    "token": "abcdefghijklmn",
    "expiresIn": 300
  }
}

2.2 查询核身结果

响应：

{
  "success": true,
  "code": "SUCCESS",
  "data": {
    "authenticateNumber": "AUTH20250108001",
    "openid": "oXXXXX",
    "authenticateState": "AUTHENTICATE_SUCCESS",
    "authenticateTime": "2025-01-08T10:35:00+08:00",
    "authenticateScene": "FROM_MINI_APP",
    "projectName": "XX物流项目",
    "employerName": "XX物流有限公司"
  }
}

核身状态说明：

状态	含义
`AUTHENTICATE_PROCESSING`	核身进行中
`AUTHENTICATE_SUCCESS`	核身成功
`AUTHENTICATE_FAILED`	核身失败

第三步：批量转账

3.1 发起批量转账

响应：

{
  "success": true,
  "code": "SUCCESS",
  "data": {
    "outBatchNo": "BATCH20250108001",
    "batchId": "1030000071100999991182020050700019480001",
    "createTime": "2025-01-08T10:40:00+08:00"
  }
}

3.2 查询批次状态

响应：

{
  "success": true,
  "code": "SUCCESS",
  "data": {
    "outBatchNo": "BATCH20250108001",
    "batchId": "1030000071100999991182020050700019480001",
    "batchStatus": "FINISHED",
    "totalAmount": 100000,
    "totalNum": 2,
    "successNum": 2,
    "failNum": 0
  }
}

批次状态说明：

状态	含义	处理建议
`ACCEPTED`	已受理	等待处理，定时轮询
`PROCESSING`	转账中	正在处理，继续轮询
`FINISHED`	已完成	查看明细确认结果
`CLOSED`	已关闭	查看关闭原因

3.3 查询转账明细

第四步：电子回单（可选）

4.1 申请电子回单

4.2 查询回单状态

4.3 下载回单

⚠️ 重要注意事项

1. 幂等性

批次号唯一：相同的 outBatchNo 视为同一批次（幂等）

遇错不换号：调用失败时，不要更换批次号重试，使用原批次号重试

明细号唯一：outDetailNo 在批次内必须唯一

2. 用工类型一致性

用户首次授权时设置的 employmentType 会被记录

后续核身/转账时的 employmentType 必须与授权时一致

不一致会返回错误：下单用工类型与授权用工类型不匹配

3. 金额单位

所有金额字段单位为"分"

totalAmount 必须等于 transferDetailList 中所有 transferAmount 之和

totalNum 必须等于 transferDetailList 的数量

4. 敏感字段

userName、idCardNumber 等敏感字段由平台自动加密

客户直接传明文即可，无需自行加密

5. 限流

接口类型	限流
创建批次	5 QPS/商户
查询接口	50 QPS/商户

🔄 回调通知

如果创建批次时传入了 callbackUrl，当批次状态变更（进入终态）时，平台会向该 URL 发送通知：

{
  "outBatchNo": "BATCH20250108001",
  "batchId": "1030000071100999991182020050700019480001",
  "batchStatus": "FINISHED",
  "successNum": 2,
  "failNum": 0,
  "updateTime": "2025-01-08T10:45:00+08:00"
}

📚 接口清单速查

功能	方法	路径
生成授权 token	POST	`/api/v1/payroll-card/token`
查询授权状态	GET	`/api/v1/payroll-card/auth/status`
拉起（授权并使用）	POST	`/api/v1/payroll-card/launch/use`
拉起（查看微工卡）	POST	`/api/v1/payroll-card/launch/view`
核身预下单	POST	`/api/v1/payroll-card/face/preorder/official`
查询核身结果	GET	`/api/v1/payroll-card/face/result`
发起批量转账	POST	`/api/v1/payroll-card/transfer/batch/create`
查询批次状态	GET	`/api/v1/payroll-card/transfer/batch/status`
查询批次明细	GET	`/api/v1/payroll-card/transfer/batch/details`
申请电子回单	POST	`/api/v1/payroll-card/transfer/batch/receipt/apply`
查询回单状态	GET	`/api/v1/payroll-card/transfer/batch/receipt/status`
下载回单	GET	`/api/v1/payroll-card/transfer/batch/receipt/download`

🆘 常见问题

Q1: 用户授权后多久可以转账？

授权完成后即可立即发起转账。建议在拉起小程序后，通过轮询 auth/status 接口确认授权状态。

Q2: 批量转账最多支持多少笔？

单批次最多支持 1000 笔转账。

Q3: 转账失败的明细可以重试吗？

可以。需要使用新的批次号和明细号重新发起转账（仅包含失败的明细）。

Q4: 核身预下单和普通授权有什么区别？

核身预下单（face/preorder/official）：一步完成授权 + 人脸核身，适合需要核身验证的场景

普通授权（token）：仅完成授权，不进行核身验证

Q5: 如何处理"用工类型不匹配"错误？

用户首次授权时的 employmentType 会被记录。后续请求必须使用相同的用工类型，否则需要用户重新授权。

📖 更多详情请参考各接口的详细文档。

📋 业务流程总览#

🚀 快速接入（推荐方式）#

方式一：核身预下单（一步完成授权 + 核身）#

方式二：分步授权 + 转账#

📝 详细接入步骤#

第一步：用户授权#

1.1 生成授权 Token#

1.2 拉起微工卡小程序#

1.3 查询授权状态#

第二步：核身验证（可选）#

2.1 核身预下单#

2.2 查询核身结果#

第三步：批量转账#

3.1 发起批量转账#

3.2 查询批次状态#

3.3 查询转账明细#

第四步：电子回单（可选）#

4.1 申请电子回单#

4.2 查询回单状态#

4.3 下载回单#

⚠️ 重要注意事项#

1. 幂等性#

2. 用工类型一致性#

3. 金额单位#

4. 敏感字段#

5. 限流#

🔄 回调通知#

📚 接口清单速查#

🆘 常见问题#

Q1: 用户授权后多久可以转账？#

Q2: 批量转账最多支持多少笔？#

Q3: 转账失败的明细可以重试吗？#

Q4: 核身预下单和普通授权有什么区别？#

Q5: 如何处理"用工类型不匹配"错误？#