PayTrigger 微额贷款（Microfinancing）Partner API 接入

文档信息

原始文件：PayTrigger-Microfinancing-PartnerAPI_20251113.pdf
版本：v1.0（2025-11-13），Security Solution Service API Documentation
产品定位：面向「微额贷款 / 分期购机」场景的合作方接入文档。

与通用设备锁文档的关系

本文是 PayTrigger 文档族中的 微额贷款（Microfinancing）变体，与 PayTrigger 手机锁接口整理（通用设备锁，全量 28 接口）互补。三处关键差异：

维度	通用设备锁	微额贷款（本文）
入口接口	`imei/input` 预录入 → `updateRepayInfo`	`initializeLock` 一次性带入贷款计划初始化锁
生命周期	`Enrolled → Registered → Ready_to_active → Active → Removable`（5 态）	`Registered → Ready_to_active → Active → Removable`（4 态，无独立预录入）
贷款用途字段	无	`loanPurpose`（必填）

本文同时沉淀 PDF 中通用版未覆盖的 全量错误码、接口限频、跨语言签名实现（见附录），这些规则对所有 PayTrigger 接口通用。

1. 接入前置：鉴权与 apiKey

双重鉴权：IP 白名单 + apiKey。

项	说明
Dashboard（非印度）	`https://paytrigger.transsion-os.com/pay-trigger/#/login`
Dashboard（印度）	`https://ind-paytrigger.transsion-os.com/pay-trigger/#/login`
apiKey 获取 / IP 白名单	登录 Dashboard → `Developer Management` → `Customize IP` 配白名单、获取 apiKey
正式 API（非印度）	`https://paytrigger.transsion-os.com/PayTrigger`
正式 API（印度）	`https://ind-paytrigger.transsion-os.com/PayTrigger`

2. 通用签名规则

取请求 body 中非空参数。
参数名按 ASCII 升序 拼接为 k1=v1&k2=v2。
以 apiKey 作为 key，计算 HmacSHA256，结果转 大写 hex string。
对大写 hex string 做 Base64，放入请求头 sign。

请求头：

http

Content-Type: application/json; charset=UTF-8
sign: Base64(HMAC_SHA256(content))

注意事项：

imeiInfo / pushInfo 等数组字段需传「字符串形式的数组」，不是 JSON 数组。
布尔值跨语言序列化不一致是签名失败高发点，统一用字符串 "true" / "false"，详见附录 C。

3. 设备生命周期（微额贷款 4 态）

text

Registered --> Ready_to_active --> Active --> Removable

状态值复用通用版：0 unregistered / 1000 registered / 2000 ready_to_activate / 3000 active / 4000 active_and_lock / 5000 removable。
与通用版差异：通用版含 500 pre_enroll（Enrolled）预录入前置态；微额贷款通过 initializeLock 直接以贷款信息初始化，跳过独立预录入步骤。

4. 接口清单（微额贷款 Partner API）

PDF 共 12 个接口。除 initializeLock 为微额贷款核心入口外，其余与通用版共享，字段与示例见对应章节。

#	能力	路径	详见
1	初始化锁（微额贷款）	`POST /api/partner/lock/v1/initializeLock`	§5（本文重点）
2	更新还款信息	`POST /api/partner/lock/v1/updateRepayInfo`	通用版 §9
3	移除设备锁	`POST /api/partner/lock/v1/removeLock`	通用版 §10
4	查询锁状态	`POST /api/partner/lock/v1/findLockState`	通用版 §6
5	批量查询锁状态	`POST /api/partner/lock/v1/batchFindLockState`	通用版 A4
6	状态变更回调	`POST {callbackUrl}`	通用版 §8
7	单设备推送	`POST /api/partner/push/v1/sendPushInfo`	通用版 A1
8	批量推送	`POST /api/partner/push/v1/sendBatchPushInfo`	通用版 A2
9	临时解锁	`POST /api/partner/unlock/v1/tempUnlock`	通用版 §11
10	PIN 离线解锁	`POST /api/partner/unlock/v1/verifyCode`	通用版 §13
11	查询商户 License	`POST /api/partner/company/v1/checkLicense`	通用版 A5
12	查询客户反馈	`POST /api/partner/feedback/v1/query`	通用版 A8

5. initializeLock —— 微额贷款初始化锁

微额贷款 Partner API 的核心入口：一次性带入完整贷款与还款计划，初始化设备锁。

http

POST /api/partner/lock/v1/initializeLock
Content-Type: application/json; charset=UTF-8
sign: <Base64(HMAC_SHA256(content))>

入参

字段	类型	必填	说明
`deviceTag`	String	是	设备标签
`imei`	String	否	设备 IMEI；`deviceTag` 与 `imei` 二选一，优先 `deviceTag`
`repayedAmt`	BigDecimal	是	已还金额
`totalAmt`	BigDecimal	是	总金额
`nextRepayTime`	Long	是	下期还款时间戳，13 位毫秒
`nextRepayAmt`	BigDecimal	是	下期还款金额
`currencyType`	String	是	货币符号，例如 `$`
`currentTerm`	Integer	是	当前期数，1-1000
`totalTerm`	Integer	是	总期数，1-1000
`relatedMerchant`	String	是	关联商户 apiKey
`description`	String	否	备注
`phoneNum`	String	是	客户手机号
`orderNum`	String	是	商户订单号
`deeplink`	String	否	商户跳转 deeplink
`deeplinkPkg`	String	否	deeplink 对应 App 包名
`ruleNum`	Integer	否	锁策略规则编号 0-5，默认 0
`loanPurpose`	String	是	贷款用途（微额贷款新增字段）
`sign`	String（header）	是	请求头签名

请求示例

json

{
  "repayedAmt": 1000,
  "totalAmt": 3000,
  "deviceTag": "QYMDX4KN",
  "nextRepayTime": 1576322185,
  "nextRepayAmt": 1000,
  "currencyType": "$",
  "currentTerm": 1,
  "totalTerm": 3,
  "relatedMerchant": "8qXIGKndpecSDmlLF1HaQ0fN6AREjvs4",
  "description": "repay record update",
  "orderNum": "11111111",
  "phoneNum": "1388188888",
  "deeplink": "halacredit://credit/order?id=123664",
  "deeplinkPkg": "com.hala.fintech.coihub",
  "ruleNum": 1,
  "imei": "111124345435432",
  "loanPurpose": "test"
}

响应示例

json

{
  "code": 200,
  "data": {
    "orderNum": "11111111"
  },
  "message": "Success"
}

时间戳精度提醒：PDF 标注 nextRepayTime 为 13 位（毫秒），而通用版 updateRepayInfo 的同类字段为 10 位（秒）。两者精度可能不同，联调时务必以传音确认为准，避免到期计算与签名不一致。

6. 微额贷款推荐接入流程

6.1 放款 / 售机

（可选）model/v1/get 校验 IMEI 制造数据。
调用 initializeLock 一次性带入贷款计划初始化锁。
保存 orderNum / deviceTag / imei，等待激活回调。

6.2 手机激活后

接收回调，关注 notifyType=1000（激活）。
findLockState 复核 serverState / lockState / mobileStatus / lastConnectTime / apkVersion / frameworkVersion。

6.3 还款周期

每次还款调用 updateRepayInfo 更新 repayedAmt / currentTerm / nextRepayTime。
findLockState 确认锁状态同步。

6.4 逾期

到期端侧按 ruleNum 策略自动锁定。
sendPushInfo / 模拟来电触达；必要时 tempUnlock 临时放行。
网络不可达时 verifyCode 下发离线 PIN。

6.5 全部还清

调用 removeLock 移除设备锁。
等回调 notifyType=2000，或 findLockState 确认进入 Removable。

6.6 额度管理

定期调用 checkLicense 关注 remainingAmountOfLicense，额度不足会返回 Insufficient remaining available licenses（见附录 A）。

附录 A：全量错误码参考

来源：PDF §4。原表为中英双语三列，本表为重建版，按错误前缀分组。个别 code ↔ message 映射在原 PDF 表格中存在错行，已结合接口示例交叉校验；联调遇到歧义时以 Dashboard 错误字典为准。

A.1 系统 / 参数类

code	含义
`200`	Success
`400`	bad request（签名 / 入参错误）
`500`	Server Error
`510`	Frequent requests, try again later（限频，见附录 B）
`516`	argument invalid
`518`	sys_config error
`519`	process failure
`520`	encrypt data failure
`530`	decrypt data failure / data processing
`10011`	export data error, data empty
`10014`	error sign
`10036`	DeviceTag is null
`10042`	Expire time is null
`10045`	Imei format error
`20001`	DeviceTag or imei does not exist, or the two do not match（批量响应 per-item `status` 命名空间同值）
`20002`	DeviceTag quantities are out of range

A.2 账户 / 权限类

code	含义
`20003`	Apikey not exist or expired
`20005`	Error, the function is turned off
`30004`	Illegal state change
`30021`	Apikey has no permission
`40000`	This account does not have permission to activate the current country/model/A/S device
`40003`	Please configure whitelist ip / Request ip is not in whitelist
`50004`	ApiKey is null
`50023`	Partner not exist

A.3 设备 / 业务类

code	含义
`40009`	Device has been renewed in the last 24 hours（延期接口，见通用版 A16/A17）
`50008`	The number of calls to a single device exceeds the limit（推送限频，见附录 B）
`50013`	Repay / Lock state error，或 The device is not overdue
`50015`	This IMEI has been enrolled or activated and cannot be enrolled again
`50021`	Some IMEI entry failed（批量预录入部分失败，明细见 `data`）
`50022`	Expiration is null
`50024`	The imei length must be 12 to 20 digits
`50025`	The maximum number of batch operations is 2000
`50026`	The device does not support SMS unlocking
`50027`	The order num not exist
`50028`	The device is not in removable state
`50051`	The file address is incorrect or invalid
`50054`	The simulated incoming call num not exist
`50055`	Device unavailable
`50056`	Imei not exist
`50057`	IMEI is already in use
`50058`	Repeated activation is not allowed. Please change the device and try again
`50061`	Wrong time range or format
`50071`	The device-lock not exist（延期接口示例中出现）
`9900`	The order no exist
`9999`	deeplink、deeplinkPkg、h5link 三者不能同时存在，只能选一种 link

其余白名单 / 呼入呼出 / SIM 锁相关错误（50005–50012、50016–50017、50020、50029、50059–50063 等）属公司配置与分步锁策略边界，建议直接在 Dashboard 错误字典中按 code 查询。

附录 B：接口限频（QPS / 24h）

接口	维度	限额窗口	超限错误码
`findLockState`	单设备	100 次 / 24h	`510`
`batchFindLockState`	单设备	100 次 / 24h	`510`
`sendPushInfo`（`pushType=1` 弹窗）	单设备	3 次 / 24h	`50008`
`sendPushInfo`（`pushType=2` 推送）	单设备	3 次 / 24h	`50008`
`sendPushInfo`（`pushType=3` 模拟来电）	单设备	1 次 / 24h	`50008`

触发限频后：查询类返回 510 Frequent requests, try again later；推送类返回 50008 The number of calls to a single device exceeds the limit. Please try again after 24 hours.。催收触达调度需按此节流，避免单设备 24h 内重复推送被拒。

附录 C：跨语言签名实现

C.1 Python ↔ Java 布尔值陷阱

Python 的布尔字面量是首字母大写（True / False），Java 是全小写（true / false）。两者序列化后字符串不同，会导致签名明文不一致、验签失败。

对策：传输布尔值时 统一用字符串 "true" / "false"，保证签名明文跨语言一致。

text

# 推荐写法：布尔值统一用字符串 "false"，而非布尔 false
{
  "imeiInfo": "[{\"expiration\":1662136801,\"imei\":\"359581820772412\"}]",
  "preLockFlag": "false",
  "apiKey": "8qXIGKndpecSDmlLF1HaQ0fN6AREjvs4"
}

# 签名明文（参数名 ASCII 升序，preLockFlag 取字符串字面值）
apiKey=8qXIGKndpecSDmlLF1HaQ0fN6AREjvs4&imeiInfo=[{"expiration":1662136801,"imei":"359581820772412"}]&preLockFlag=false

C.2 HmacSHA256 参考实现

通用步骤：① 取 sha256 实例 → ② 用密钥初始化 → ③ 对明文计算 hash → ④ 转 16 进制输出 → ⑤ 大写后 Base64 放入 sign。

Golang 示例（来自 PDF §6）：

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
)

func main() {
	secret := "apiKey-value" // 以 apiKey 作为 HMAC key
	data := "k1=v1&k2=v2"    // ASCII 升序拼接的签名明文
	h := hmac.New(sha256.New, []byte(secret))
	h.Write([]byte(data))
	sha := hex.EncodeToString(h.Sum(nil)) // 转 hex
	fmt.Println("hex: " + sha)
	// 再将 sha 大写后 Base64，放入请求头 sign
}

PHP 思路（来自 PDF §6）：

php

// hash_hmac sha256 + 密钥，结果转 hex；再大写后 Base64
bin2hex(hash_hmac("sha256", $plaintext, $secret, true));

不同语言默认大小写、Base64 标准与否、密钥是否需 base64_decode 存在差异，接入时以 Dashboard「API Debugging」自带的签名验签工具对齐结果。

接入待确认

微额贷款 initializeLock 与通用版 imei/input 在同一商户下能否混用，是否共享 License 额度。
nextRepayTime 毫秒 / 秒精度以传音确认为准。
沙箱与正式环境 apiKey、IP 白名单、回调地址配置。
微额贷款场景的消费者保护合规边界：锁机提示文案、紧急通话白名单、临时解锁 SLA。
错误码字典以 Dashboard 为准，本页附录 A 仅作快速定位。

PayTrigger 微额贷款（Microfinancing）Partner API 接入 ​

文档信息 ​

与通用设备锁文档的关系 ​

1. 接入前置：鉴权与 apiKey ​

2. 通用签名规则 ​

3. 设备生命周期（微额贷款 4 态） ​

4. 接口清单（微额贷款 Partner API） ​

5. initializeLock —— 微额贷款初始化锁 ​

入参 ​

请求示例 ​

响应示例 ​

6. 微额贷款推荐接入流程 ​

6.1 放款 / 售机 ​

6.2 手机激活后 ​

6.3 还款周期 ​

6.4 逾期 ​

6.5 全部还清 ​

6.6 额度管理 ​

附录 A：全量错误码参考 ​

A.1 系统 / 参数类 ​

A.2 账户 / 权限类 ​

A.3 设备 / 业务类 ​

附录 B：接口限频（QPS / 24h） ​

附录 C：跨语言签名实现 ​

C.1 Python ↔ Java 布尔值陷阱 ​

C.2 HmacSHA256 参考实现 ​

接入待确认 ​