PayTrigger 手机锁接口整理

本文按当前接入链路整理：查机型、预录入 IMEI、查状态、回调、还款解锁、移除锁、临时解锁。

1. 接入说明

1.1 环境地址

非印度正式环境：

text

https://paytrigger.transsion-os.com/PayTrigger

印度正式环境：

text

https://ind-paytrigger.transsion-os.com/PayTrigger

1.2 通用请求头

http

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

1.3 签名规则

将请求 body 中非空参数按参数名 ASCII 升序排列。
按 k1=v1&k2=v2 格式拼接签名明文。
使用 HmacSHA256，以 apiKey 作为 key 计算摘要。
将摘要转为大写 hex string。
对大写 hex string 做 Base64，放入请求头 sign。

示例：

json

{
  "apiKey": "8qXIGKndpecSDmlLF1HaQ0fN6AREjvs4",
  "imeiInfo": "[{\"expiration\":1662136801,\"imei\":\"359581820772412\",\"model\":\"infinix SMART 6\",\"ram\":\"2\",\"rom\":\"32\"}]",
  "preLockFlag": "false"
}

签名明文：

text

apiKey=8qXIGKndpecSDmlLF1HaQ0fN6AREjvs4&imeiInfo=[{"expiration":1662136801,"imei":"359581820772412","model":"infinix SMART 6","ram":"2","rom":"32"}]&preLockFlag=false

注意：

imeiInfo 要传“字符串形式的数组”，不是直接传 JSON 数组。
true/false 建议统一使用固定格式，否则不同语言序列化后可能导致签名不一致。

2. 设备状态说明

设备生命周期：

text

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

状态值：

值	含义
`0`	unregistered，未注册
`500`	pre_enroll / enrolled，预录入
`1000`	registered，已注册
`2000`	ready_to_activate，待激活
`3000`	active，已激活
`5000`	removable，可移除/已移除

锁定状态：

值	含义
`1000`	locked，已锁定
`2000`	unlock，未锁定

关键理解：

imei/input 只是预录入 IMEI，不代表手机已经锁机。
真正激活和锁机依赖手机端已有 PayTrigger/设备锁组件联网同步。
文档没有提供“让手机下载 APK”的接口。若设备没有内置/支持锁控组件，仅调用服务端接口不能让手机自动下载 APK 并锁机。

3. 查询机型

通过 IMEI 查询传音制造/出厂信息。建议在预录入前调用，用来确认该 IMEI 是否存在于传音制造数据中。

http

POST /api/partner/model/v1/get

入参

字段	类型	必填	说明
`apiKey`	String	是	商户 API Key
`imei`	String	是	设备 IMEI
`sign`	Header	是	请求头签名

请求示例

json

{
  "apiKey": "siRBMLw6H2kCvN8uId5qlcmr1KGQ4WZ3",
  "imei": "355818617005570"
}

成功返回示例

json

{
  "code": 200,
  "message": "Success",
  "data": {
    "imei": "351997122657705",
    "brandName": "TECNO",
    "modelLabelName": "KL5",
    "modelMarketName": "TECNO SPARK 30C",
    "rom": 128,
    "ram": 4,
    "imei1": "351997122657705",
    "imei2": "351997129428365",
    "color": "MAGIC SKIN GREEN",
    "dpmActDate": "2024-08-24",
    "senderCountryCode": "PK",
    "senderCountryName": "Pakistan"
  }
}

常见失败返回

json

{
  "code": 40005,
  "message": "No matching manufacturing data",
  "data": null
}

含义：传音后台按该 IMEI 未找到匹配的制造/出厂数据。

常见原因：

IMEI 写错，或双卡手机需要换另一个 IMEI 查询。
当前接口环境没有该设备制造数据，例如测试环境/正式环境不一致。
该设备不是 PayTrigger 支持批次。
当前商户未开通该机型/国家/版本权限。
设备的 apkVersion / frameworkVersion 未加入运营白名单。

4. 预录入 IMEI

把单个或批量 IMEI 预录入 PayTrigger。预录入成功后，设备进入 Enrolled 链路。

http

POST /api/partner/lock/v1/imei/input

入参

字段	类型	必填	说明
`apiKey`	String	是	商户 API Key
`imeiInfo`	String	是	字符串形式的数组，最多 2000 个不重复 IMEI
`preLockFlag`	Boolean/String	是	激活后是否立即锁定
`sign`	Header	是	请求头签名

imeiInfo 内部字段：

字段	类型	必填	说明
`imei`	String	是	设备 IMEI
`model`	String	否	机型，激活时会校验
`ram`	String	否	运行内存，不带单位
`rom`	String	否	存储内存，不带单位
`cycleType`	Integer	否	还款周期：`0` 无，`1000` Day，`2000` Week，`3000` Month
`expiration`	Long	条件必填	到期时间戳。`preLockFlag=false` 时必填
`orderNum`	String	否	商户订单号
`deeplink`	String	否	商户跳转链接
`deeplinkPkg`	String	否	deeplink 对应 App 包名
`ruleNum`	Integer	否	锁策略规则编号
`nfcFlag`	Boolean	否	手机是否支持 NFC，激活时会校验
`planGaid`	String	否	plan gaid，激活时会校验
`nextRepaymentTimeSwitch`	Boolean	否	是否展示下次还款时间

preLockFlag 说明：

值	含义
`true`	激活后立即下发预录入锁
`false`	激活后不立即锁，到期后按锁策略上锁

请求示例

json

{
  "imeiInfo": "[{\"cycleType\":3000,\"expiration\":1621468800,\"imei\":\"555555512223\",\"model\":\"infinix CT6\",\"orderNum\":\"PT202207181233\",\"ram\":\"4\",\"rom\":\"256\",\"deeplink\":\"https://www.pay.url\",\"deeplinkPkg\":\"com.android.chrome\",\"nfcFlag\":true,\"ruleNum\":0,\"planGaid\":\"gew4536543\"}]",
  "preLockFlag": false,
  "apiKey": "9j4S7Ob0sT5h6DVwAez2cPxUKMqBvf8d"
}

成功返回示例

json

{
  "code": 200,
  "message": "Success",
  "data": []
}

部分失败返回示例

json

{
  "code": 50021,
  "message": "Some IMEI entry failed",
  "data": [
    {
      "imei": "123123123000431x",
      "message": "Expiration is null",
      "errCode": 50022
    },
    {
      "imei": "123123123000429",
      "message": "This IMEI has been enrolled or activated and cannot be enrolled again.",
      "errCode": 50015
    }
  ]
}

5. 取消预录入

设备未激活前，可取消 IMEI 预录入，释放 enroll 额度，并让手机不走分期锁机流程。

http

POST /api/partner/lock/v1/imei/cancel

入参

字段	类型	必填	说明
`apiKey`	String	是	商户 API Key
`imeiInfo`	String	否	IMEI，多个用英文逗号分隔
`sign`	Header	是	请求头签名

请求示例

json

{
  "apiKey": "3w1mZa2pK79Wye0k5UfLCHPVbiodNv4F",
  "imeiInfo": "112233445566,4532546547777"
}

返回示例

json

{
  "code": 200,
  "message": "Success",
  "data": []
}

6. 查询设备锁状态

查询单个设备锁信息，是排查“是否激活、是否锁定、端侧是否联网”的核心接口。

http

POST /api/partner/lock/v1/findLockState

入参

字段	类型	必填	说明
`apiKey`	String	是	商户 API Key
`deviceTag`	String	条件必填	设备标签，`deviceTag` 与 `imei` 必传一个
`imei`	String	条件必填	设备 IMEI，`deviceTag` 与 `imei` 必传一个
`orderNum`	String	否	商户订单号，可查询已移除设备
`sign`	Header	是	请求头签名

请求示例

json

{
  "deviceTag": "QYMDX4KN",
  "imei": "1587105425960",
  "orderNum": "D1587105425960",
  "apiKey": "8qXIGKndpecSDmlLF1HaQ0fN6AREjvs4"
}

成功返回示例

json

{
  "code": 200,
  "data": {
    "lockState": 2000,
    "serverState": 2000,
    "orderNum": "11111111",
    "mobileStatus": 1000,
    "serverLockStatus": 1000,
    "activeTime": 1596698973,
    "lastConnectTime": 1596698973,
    "lockRuleNum": 0,
    "lockTypeSwitch": "[{\"lockFlag\":false,\"lockType\":\"WATERMARK_LOCK\"},{\"lockFlag\":false,\"lockType\":\"CALL_LOCK\"},{\"lockFlag\":false,\"lockType\":\"SMS_LOCK\"}]",
    "serverLockTypeSwitch": "[{\"lockFlag\":false,\"lockType\":\"WATERMARK_LOCK\"}]",
    "imei": "4326546576888",
    "frameworkVersion": "1.2.0.0",
    "apkVersion": "1.2.0.0",
    "serverAntiTheftFunction": true,
    "clientAntiTheftFunction": false,
    "model": "TECNO AC8",
    "partnersPkgState": "TYPE_ABNORMAL",
    "ram": 8,
    "rom": 256,
    "buildNumber": "BF6-SE668SABCDE-SGo-OP-230320V442",
    "antiCrackingVer": "P1"
  },
  "message": "Success"
}

关键返回字段

字段	说明
`lockState`	客户端实际生命周期状态
`serverState`	服务端下发生命周期状态
`mobileStatus`	客户端实际锁定状态，`1000=locked`，`2000=unlock`
`serverLockStatus`	服务端下发锁定状态
`activeTime`	激活时间戳
`lastConnectTime`	设备上次联网同步时间戳
`lockTypeSwitch`	客户端执行成功的锁策略
`serverLockTypeSwitch`	服务端生成/下发的锁策略
`frameworkVersion`	设备锁控 framework 版本
`apkVersion`	设备锁控 APK 版本
`partnersPkgState`	商户 App 状态

partnersPkgState 枚举：

值	含义
`TYPE_NORMAL`	正常
`TYPE_ABNORMAL`	应用异常
`TYPE_PKG_NULL`	未配置
`TYPE_UNINSTALLED`	未安装

7. 通过 IMEI 查询 DeviceTag

通过 IMEI 查询设备 tag 及第三方订单号。

http

POST /api/partner/lock/v1/getDevice

入参

字段	类型	必填	说明
`apiKey`	String	是	商户 API Key
`imei`	String	否	设备 IMEI
`sign`	Header	是	请求头签名

请求示例

json

{
  "apiKey": "3w1mZa2pK79Wye0k5UfLCHPVbiodNv4F",
  "imei": "112233445566"
}

返回示例

json

{
  "code": 200,
  "message": "Success",
  "data": {
    "deviceTag": "6EABQDC8",
    "lockState": 2000,
    "serverState": 2000,
    "orderNum": "1642052225550"
  }
}

8. 设备状态变化回调

当设备端实际已激活、更新、锁定、解锁、移除时，PayTrigger 会通知合作方回调地址。

http

POST https://xxx/callbackUrl

回调入参

字段	类型	必填	说明
`productModel`	String	是	设备型号
`deviceTag`	String	是	设备 tag
`imei`	String	是	设备 IMEI
`orderNum`	String	是	商户订单号
`expiration`	Long	是	过期时间戳
`activeTime`	Long	是	激活时间戳
`state`	Integer	是	客户端当前生命周期状态
`mobileStatus`	Integer	是	客户端锁定状态
`serverState`	Integer	是	服务端当前生命周期状态
`clientRemoveTime`	Long	否	客户端实际移除时间戳
`serverRemoveTime`	Long	否	服务端下发移除时间戳
`notifyType`	Integer	是	通知类型
`tip`	String	否	强限制超限提示
`sign`	Header	是	请求头签名

notifyType：

值	含义
`1000`	客户端激活状态回调
`2000`	客户端移除状态回调
`4000`	设备锁指令因强限制超限回调

回调示例

json

{
  "productModel": "TECNO",
  "mobileStatus": 1000,
  "serverState": 1000,
  "orderNum": "1111111",
  "activeTime": 1572969600,
  "deviceTag": "IST3PDUZ",
  "imei": "111111111111",
  "expiration": 1572969600,
  "state": 1000,
  "clientRemoveTime": 1572969600,
  "serverRemoveTime": 1572969600,
  "notifyType": 1000
}

强限制超限回调示例：

json

{
  "notifyType": 4000,
  "deviceTag": "3WGHPKCJ",
  "orderNum": "LOAN1000074720201203071002",
  "imei": "",
  "tip": "The strong restriction order issued by the equipment did not take effect due to control."
}

合作方回调响应

合作方必须返回以下格式，否则 PayTrigger 认为处理失败，并可能重试通知。

json

{
  "code": 200,
  "message": "Success"
}

9. 还款状态变更/实际解锁

客户每次还款后调用，用于解锁、延长到期时间，并产生解锁指令。

http

POST /api/partner/lock/v1/updateRepayInfo

入参

字段	类型	必填	说明
`deviceTag`	String	条件必填	设备标签，`deviceTag` 与 `imei` 必传一个
`imei`	String	条件必填	设备 IMEI，`deviceTag` 与 `imei` 必传一个
`repayedAmt`	BigDecimal	否	已还金额，两位小数
`totalAmt`	BigDecimal	否	总金额，两位小数
`nextRepayTime`	Long	是	下期还款时间戳，需大于当前时间
`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 对应包名
`ruleNum`	Integer	否	锁策略规则，0-5，不传则不更新
`sign`	Header	是	请求头签名

请求示例

json

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

返回示例

json

{
  "code": 200,
  "message": "Success"
}

10. 移除设备锁

客户全部还款完成后，调用该接口移除设备锁，解除设备限制。

http

POST /api/partner/lock/v1/removeLock

入参

字段	类型	必填	说明
`apiKey`	String	是	商户 API Key
`deviceTag`	String	条件必填	设备标签，`deviceTag` 与 `imei` 必传一个
`imei`	String	条件必填	设备 IMEI，`deviceTag` 与 `imei` 必传一个
`sign`	Header	是	请求头签名

请求示例

json

{
  "deviceTag": "QYMDX4KN",
  "imei": "111111111111",
  "apiKey": "8qXIGKndpecSDmlLF1HaQ0fN6AREjvs4"
}

返回示例

json

{
  "code": 200,
  "message": "Success"
}

11. 临时解除设备锁

用户已被锁机时，临时允许设备解锁一段时间。

http

POST /api/partner/unlock/v1/tempUnlock

入参

字段	类型	必填	说明
`apiKey`	String	是	商户 API Key
`deviceTag`	String	条件必填	设备标签，`deviceTag` 与 `imei` 必传一个
`imei`	String	条件必填	设备 IMEI，`deviceTag` 与 `imei` 必传一个
`tempLockTime`	Integer	否	临时解锁时间。默认 24 小时
`timeUnit`	String	否	时间单位：`HOURS` 或 `MINUTES`。默认 `HOURS`
`sign`	Header	是	请求头签名

时间范围：

单位	范围
`MINUTES`	1-1440
`HOURS`	1-720

请求示例

json

{
  "deviceTag": "QYMDX4KN",
  "imei": "1587105425960",
  "apiKey": "8qXIGKndpecSDmlLF1HaQ0fN6AREjvs4",
  "tempLockTime": 72,
  "timeUnit": "HOURS"
}

返回示例

json

{
  "code": 200,
  "message": "Success"
}

12. 单个设备锁策略配置

针对不同用户等级设置不同锁策略和提示文案。

http

POST /api/partner/lockRule/v1/setLockRule

入参

字段	类型	必填	说明
`apiKey`	String	是	商户 API Key
`deviceTag`	String	条件必填	设备标签，`deviceTag` 与 `imei` 必传一个
`imei`	String	条件必填	设备 IMEI，`deviceTag` 与 `imei` 必传一个
`ruleNum`	Integer	是	锁策略编号，0-5，默认 0
`deviceTips`	String	否	锁主界面/屏幕锁展示提示，400 字符内
`deeplink`	String	否	商户 deeplink
`deeplinkPkg`	String	否	deeplink 对应包名。与 `deeplink` 要么都传，要么都不传
`deviceTitle`	String	否	自定义锁屏标题
`callInPhoneNum`	String	否	允许呼入电话列表
`CallOutPhoneNum`	String	否	允许呼出电话列表
`sign`	Header	是	请求头签名

请求示例

json

{
  "deviceTag": "FLTZWA7V",
  "imei": "1587105425960",
  "apiKey": "UIFqXasP68LhblnR41iz92ADKcO73mGQ",
  "ruleNum": 0,
  "deviceTips": "please repay as soon as possible",
  "deeplink": "app://repay",
  "deeplinkPkg": "com.example.app",
  "deviceTitle": "Notice",
  "callInPhoneNum": "110,120",
  "CallOutPhoneNum": "110,120"
}

返回示例

json

{
  "code": 200,
  "message": "Success"
}

13. PIN 离线解锁

用户逾期锁机后，可通过离线方式从金融方获取离线解锁 PIN，在 PayTrigger 界面输入后解锁。

http

POST /api/partner/unlock/v1/verifyCode

入参

字段	类型	必填	说明
`apiKey`	String	是	商户 API Key
`imei`	String	否	设备 IMEI
`deviceTag`	String	否	设备 tag
`captcha`	String	否	4 位随机数
`sign`	Header	是	请求头签名

请求示例

json

{
  "apiKey": "3w1mZa2pK79Wye0k5UfLCHPVbiodNv4F",
  "imei": "112233445566",
  "captcha": "1234",
  "deviceTag": "A23DFTP8"
}

返回示例

json

{
  "code": 200,
  "message": "Success",
  "data": {
    "verifyCode": "123456789"
  }
}

14. 推荐接入流程

14.1 放款/售机前

调用 model/v1/get 查询 IMEI 制造数据。
若返回 40005 No matching manufacturing data，先找传音确认设备、环境、白名单，不建议继续预录入。
调用 imei/input 预录入设备。
保存业务订单号、IMEI、后续回调中的 deviceTag。

14.2 手机激活后

接收传音回调，关注 notifyType=1000。
调用 findLockState 复核：
- serverState
- lockState
- mobileStatus
- lastConnectTime
- apkVersion
- frameworkVersion

14.3 还款后

调用 updateRepayInfo 更新还款状态和下期到期时间。
查询 findLockState 确认锁状态是否同步。

14.4 逾期后

到期后设备端按锁策略执行锁定。
通过 findLockState 查询 mobileStatus=1000 是否已锁。
如需临时解锁，调用 tempUnlock。

14.5 全部还清后

调用 removeLock。
等待回调或调用 findLockState 确认状态进入 Removable。

15. 当前问题判断

当前调用：

json

{
  "apiKey": "siRBMLw6H2kCvN8uId5qlcmr1KGQ4WZ3",
  "imei": "355818617005570"
}

json

{
  "code": 40005,
  "message": "No matching manufacturing data",
  "data": null
}

判断：

请求字段符合文档要求。
问题大概率不是入参格式，而是传音后台未找到该 IMEI 的制造数据。
需要传音确认该 IMEI 是否存在于当前环境、是否属于 PayTrigger 支持批次、是否需要换 IMEI1 查询、商户是否开通该机型/国家/版本权限。

附录：全量接口补充

本附录补齐 PDF 中未在前文详细展开的接口，确保 1-28 个接口都能在本文档中查到。前文已经详细展开的接口包括：预录入 IMEI、取消预录入、查询机型、查询锁状态、DeviceTag 查询、状态回调、还款解锁、移除锁、临时解锁、单设备锁策略、PIN 离线解锁。

A1. 合作方推送消息

http

POST /api/partner/push/v1/sendPushInfo

用途：针对单个设备发送定制化推送消息、弹窗消息、模拟来电或 Promise Pay 信息。

入参：

字段	类型	必填	说明
`apiKey`	String	是	商户 API Key
`deviceTag`	String	条件必填	设备标签，`deviceTag` 与 `imei` 必传一个
`imei`	String	条件必填	设备 IMEI，`deviceTag` 与 `imei` 必传一个
`content`	String	是	推送内容，500 字符内；`pushType=3` 时传录音文件编号 `0-3`
`title`	String	是	推送标题，80 字符内；`pushType=3` 时传模拟来电显示号码
`pushType`	Integer	是	`1` 弹窗，`2` 推送，`3` 模拟来电，`4` Promise Pay
`deeplink`	String	否	点击消息后的 deeplink，仅支持 `pushType=1/2`
`deeplinkPkg`	String	条件必填	deeplink 对应包名；传 `deeplink` 时必填
`h5link`	String	否	H5 链接，仅支持 `pushType=1/2`
`imgUrl`	String	否	`pushType=1` 时弹窗展示图片
`sign`	Header	是	请求头签名

请求示例：

json

{
  "deviceTag": "QYMDX4KN",
  "imei": "",
  "apiKey": "8qXIGKndpecSDmlLF1HaQ0fN6AREjvs4",
  "content": "12434",
  "title": "12223",
  "pushType": 1,
  "h5link": "www.baidu.com",
  "imgUrl": "https://xxxx.jpg",
  "deeplink": "halacredit://credit/order?id=123664",
  "deeplinkPkg": "com.hala.fintech.coihub"
}

返回示例：

json

{
  "code": 200,
  "message": "Success"
}

A2. 合作方批量推送消息

http

POST /api/partner/push/v1/sendBatchPushInfo

用途：针对多个设备批量发送推送、弹窗、模拟来电或 Promise Pay 信息。

入参：

字段	类型	必填	说明
`apiKey`	String	是	商户 API Key
`pushType`	Integer	是	消息类型，同单设备推送
`pushInfo`	String	是	字符串形式的数组；每次最多 100 个设备
`sign`	Header	是	请求头签名

请求示例：

json

{
  "pushInfo": "[{\"content\":\"12434\",\"deviceTag\":\"QYMDX4KN\",\"imei\":\"1111\",\"title\":\"12223\",\"h5link\":\"www.baidu.com\",\"imgUrl\":\"https://xxxx.jpg\",\"deeplink\":\"halacredit://credit/order?id=123664\",\"deeplinkPkg\":\"com.hala.fintech.coihub\"}]",
  "apiKey": "8qXIGKndpecSDmlLF1HaQ0fN6AREjvs4",
  "pushType": 1
}

返回示例：

json

{
  "code": 200,
  "data": [
    {
      "code": 30020,
      "deviceTag": "QYMDX4KN",
      "imei": "11111",
      "message": "ClientId is null"
    }
  ],
  "message": "Success"
}

A3. 查询商户 Web 配置信息

http

POST /api/partner/company/v1/queryCompanyConfigInfo

用途：查询商户后台设置的默认配置，例如电话白名单、应用白名单、锁机文案等。

入参：

字段	类型	必填	说明
`apiKey`	String	是	商户 API Key
`sign`	Header	是	请求头签名

请求示例：

json

{"apiKey":"8qXIGKndpecSDmlLF1HaQ0fN6AREjvs4"}

返回示例：

json

{
  "code": 200,
  "message": "Success",
  "data": {
    "whitelistPhoneNum": "222555661112223",
    "whitelistCallInPhoneNum": "222,4555,3",
    "customerServiceNum": "24222227772223,24222227772223",
    "whitelistAppContent": "[{\"execTime\":\"0\",\"execContent\":\"com.ksmobile.launcher\"}]",
    "watermarkTime": "[{\"execTime\":\"0\",\"execContent\":\"watermark\"}]",
    "smsBlockedTime": "172800",
    "callsBlockedTime": "0",
    "appBlockedContent": "[{\"execTime\":\"0\",\"execContent\":\"\",\"blockAllApp\":true}]",
    "autoPopupContent": "[{\"execTime\":\"0\",\"title\":\"title\",\"execContent\":\"content\"}]",
    "callsInTime": "0",
    "activeWatermarkContent": "active watermark",
    "screenBlockedContent": "{\"execContent\":\"Dear Customer, Your loan has been overdue.\",\"execTime\":\"0\",\"title\":\"Notice of repayment\"}",
    "operatorBlockedContent": "{\"execContent\":\"content\",\"title\":\"title\",\"allowList\":\"46000\"}",
    "fullScreenContent": "{\"fullScreenMsg\":\"msg\",\"fullScreenTitle\":\"title\",\"fullScreenName\":\"\",\"fullScreenLink\":\"\"}"
  }
}

A4. 批量查询设备锁状态

http

POST /api/partner/lock/v1/batchFindLockState

用途：批量查询设备锁信息，最多 100 个不重复设备标识。

入参：

字段	类型	必填	说明
`apiKey`	String	是	商户 API Key
`deviceTag`	String	条件必填	多个 deviceTag 用英文逗号分隔，最多 100 个
`imei`	String	条件必填	多个 IMEI 用英文逗号分隔，最多 100 个
`orderNum`	String	否	多个订单号用英文逗号分隔，最多 100 个
`sign`	Header	是	请求头签名

请求示例：

json

{
  "deviceTag": "QYMDX4KN,UBK4F8XN,XNAYPCJL",
  "imei": "1587105425960,1587105425960",
  "orderNum": "D1587105425960,D1587105425960",
  "apiKey": "8qXIGKndpecSDmlLF1HaQ0fN6AREjvs4"
}

返回示例：

json

{
  "code": 200,
  "message": "Success",
  "data": [
    {
      "deviceTag": "FLTZWA7V",
      "orderNum": null,
      "lockState": 5000,
      "mobileStatus": 2000,
      "serverState": 5000,
      "activeTime": null,
      "lastConnectTime": 1575896686,
      "expiration": 1576322185,
      "serverLockStatus": 2000,
      "lockRuleNum": 0,
      "imei": "1111111111111111111",
      "frameworkVersion": "1.2.0.0",
      "apkVersion": "1.2.0.0",
      "partnersPkgState": "TYPE_ABNORMAL"
    }
  ]
}

A5. 查询商户 License 信息

http

POST /api/partner/company/v1/checkLicense

用途：查询商户激活额度。

入参：apiKey、请求头 sign。

请求示例：

json

{"apiKey":"8qXIGKndpecSDmlLF1HaQ0fN6AREjvs4"}

返回示例：

json

{
  "code": 200,
  "message": "Success",
  "data": {
    "totalAmountOfLicense": 20000,
    "amountUsedOfLicense": 0,
    "remainingAmountOfLicense": 20000
  }
}

A6. 更新公司分步锁设置

http

POST /api/partner/company/v1/lock-rule/update

用途：更新公司层面的分步锁策略配置。

主要入参：

字段	类型	必填	说明
`apiKey`	String	是	商户 API Key
`ruleNum`	Integer	是	分步锁策略编号，0-5
`strategyDesc`	String	否	分步锁备注
`watermarkSwitch`	Boolean	否	是否开启水印锁
`watermarkContent`	JSONArray/String	否	水印锁内容
`callsOutSwitch`	Boolean	否	是否开启呼出锁
`callsOutContent`	JSONObject/String	否	呼出锁内容
`callsInSwitch`	Boolean	否	是否开启呼入锁
`callsInContent`	JSONObject/String	否	呼入锁内容
`smsBlockedSwitch`	Boolean	否	是否开启短信锁
`smsBlockedContent`	JSONObject/String	否	短信锁内容
`appBlockedSwitch`	Boolean	否	是否开启 APP 锁
`appBlockedContent`	JSONArray/String	否	APP 锁内容
`screenBlockedSwitch`	Boolean	否	是否开启全屏锁
`screenBlockedContent`	JSONArray/Object/String	否	全屏锁内容
`simBlockedSwitch`	Boolean	否	是否开启 SIM 卡锁
`simBlockedContent`	JSONObject/String	否	SIM 卡锁内容
`sign`	Header	是	请求头签名

请求示例：

json

{
  "apiKey": "8qXIGKndpecSDmlLF1HaQ0fN6AREjvs4",
  "ruleNum": 0,
  "appBlockedSwitch": true,
  "appBlockedContent": "[{\"blockAllApp\":false,\"execContent\":\"com.test\",\"execTime\":\"0\"}]",
  "autoPopupSwitch": true,
  "autoPopupContent": "[{\"execContent\":\"for test content\",\"execTime\":\"259200\",\"title\":\"for test title\"}]",
  "callsInSwitch": true,
  "callsInContent": "{\"execTime\":\"259200\"}",
  "callsOutSwitch": true,
  "callsOutContent": "{\"execTime\":\"259200\"}",
  "screenBlockedSwitch": true,
  "screenBlockedContent": "{\"execContent\":\"for test content\",\"execTime\":\"259200\",\"title\":\"for test title\"}",
  "simBlockedSwitch": false,
  "simBlockedContent": "{\"execContent\":\"for test content\"}",
  "smsBlockedSwitch": true,
  "smsBlockedContent": "{\"execTime\":\"259200\"}",
  "watermarkSwitch": true,
  "watermarkContent": "[{\"execContent\":\"ABC\",\"execTime\":\"259200\",\"fontColor\":\"#E41111\",\"fontSize\":14}]"
}

返回示例：

json

{"code":200,"message":"Success"}

A7. 更新公司定制设置

http

POST /api/partner/company/v1/customize/update

用途：更新公司名称、Logo、客服电话、呼入/呼出白名单等。

入参：

字段	类型	必填	说明
`apiKey`	String	是	商户 API Key
`callInPhoneNum`	String	否	呼入白名单电话
`callOutPhoneNum`	String	否	呼出白名单电话
`companyName`	String	否	公司名称
`logoUrl`	String	否	Logo 地址
`customerServiceNumList`	String	否	客服电话列表字符串
`sign`	Header	是	请求头签名

请求示例：

json

{
  "apiKey": "8qXIGKndpecSDmlLF1HaQ0fN6AREjvs4",
  "callInPhoneNum": "10086",
  "callOutPhoneNum": "10086",
  "companyName": "test",
  "logoUrl": "https://127.0.0.1/1.png",
  "customerServiceNumList": "[{\"countryName\":\"cn\",\"number\":\"10087\"}]"
}

返回示例：

json

{"code":200,"message":"Success"}

A8. 查询客户反馈信息

http

POST /api/partner/feedback/v1/query

用途：分页查询设备客户反馈。

入参：

字段	类型	必填	说明
`apiKey`	String	是	商户 API Key
`deviceTag`	String	否	设备标签
`imei`	String	否	设备 IMEI
`feedbackType`	String	否	反馈类型
`pageNum`	Integer	是	页码
`pageSize`	Integer	是	页大小
`startTime`	String	是	开始时间，UTC0
`endTime`	String	是	结束时间，UTC
`sign`	Header	是	请求头签名

请求示例：

json

{
  "apiKey": "8qXIGKndpecSDmlLF1HaQ0fN6AREjvs4",
  "deviceTag": "2H8DAUNM",
  "endTime": "2024-01-20",
  "imei": "855512222222226",
  "feedbackType": "Complaint",
  "pageNum": 1,
  "pageSize": 100,
  "startTime": "2024-01-01"
}

返回示例：

json

{
  "code": 200,
  "message": "Success",
  "data": {
    "count": 1,
    "list": [
      {
        "imei": "855512222222226",
        "deviceTag": "2H8DAUNM",
        "problemDesc": "test",
        "phoneNum": "",
        "email": "",
        "feedbackType": "Complaint",
        "fileUrl": null,
        "orderNum": null,
        "ct": "2024-01-16 10:05:44"
      }
    ]
  }
}

A9. 手机找回 - 提交

http

POST /api/partner/anti-theft/v1/submit

用途：开启或提交手机找回信息。

入参：apiKey 必填，contactInformation 必填，deviceTag/imei 设备标识，Header sign 必填。

请求示例：

json

{
  "apiKey": "NYBqesV7CROwx5yzH2cE3TvP0bLJ9hnd",
  "contactInformation": "2-20",
  "deviceTag": "LXNVTUPZ",
  "imei": "359076369133688"
}

返回示例：

json

{"code":200,"message":"Success","data":null}

A10. 手机找回 - 关闭

http

POST /api/partner/anti-theft/v1/close

用途：关闭手机找回。

入参：apiKey 必填，deviceTag/imei 设备标识，Header sign 必填。

请求示例：

json

{
  "apiKey": "NYBqesV7CROwx5yzH2cE3TvP0bLJ9hnd",
  "deviceTag": "LXNVTUPZ",
  "imei": "359076369133688"
}

返回示例：

json

{"code":200,"message":"Success","data":null}

A11. 手机找回 - 状态查询

http

POST /api/partner/anti-theft/v1/status

用途：查询手机找回端侧状态和操作状态。

入参：apiKey 必填，deviceTag/imei 设备标识，Header sign 必填。

请求示例：

json

{
  "apiKey": "NYBqesV7CROwx5yzH2cE3TvP0bLJ9hnd",
  "deviceTag": "LXNVTUPZ",
  "imei": "359076369133688"
}

返回示例：

json

{
  "code": 200,
  "message": "Success",
  "data": {
    "apkStatus": "Invalid",
    "operationStatus": "OFF",
    "contactInformation": "2-20"
  }
}

A12. 批量更新还款状态

http

POST /api/partner/lock/v1/batchUpdateRepayInfo

用途：批量更新还款状态，作用与单笔 updateRepayInfo 类似。

入参：

字段	类型	必填	说明
`apiKey`	String	是	商户 API Key
`updateInfo`	String	是	字符串形式的数组
`sign`	Header	是	请求头签名

updateInfo 内部字段同单笔还款状态变更。

请求示例：

json

{
  "apiKey": "NYBqesV7CROwx5yzH2cE3TvP0bLJ9hnd",
  "updateInfo": "[{\"repayedAmt\":1000,\"totalAmt\":3000,\"deviceTag\":\"PL9DU4CR\",\"nextRepayTime\":1778490281,\"nextRepayAmt\":1000,\"currencyType\":\"$\",\"currentTerm\":1,\"totalTerm\":3,\"description\":\"repay record update\",\"phoneNum\":\"1388188888\",\"imei\":\"358491280012251\"}]"
}

成功返回示例：

json

{
  "code": 200,
  "data": [
    {"deviceTag":"PL9DU4CR","reason":"Success","status":"200"}
  ],
  "message": "Success"
}

失败返回示例：

json

{
  "code": 400,
  "data": [
    {"deviceTag":"PL9DU4CR","reason":"DeviceTag or imei does not exist, or the two do not match","status":"20001"}
  ],
  "message": "Failed"
}

A13. 批量移除设备锁

http

POST /api/partner/lock/v1/batchRemoveLock

用途：批量移除设备锁。

入参：

字段	类型	必填	说明
`apiKey`	String	是	商户 API Key
`removeInfo`	String	是	字符串形式的数组
`deviceTag`	String	条件必填	`removeInfo` 内部字段，`deviceTag` 与 `imei` 二选一
`imei`	String	条件必填	`removeInfo` 内部字段，`deviceTag` 与 `imei` 二选一
`sign`	Header	是	请求头签名

请求示例：

json

{
  "apiKey": "BS52jGm1nuZ7DVcURY6bJqhCpkvXraTH",
  "removeInfo": "[{\"deviceTag\":\"XZV4MYG2\"},{\"deviceTag\":\"PL9DU4CR\"}]"
}

返回示例：

json

{
  "code": 200,
  "data": [
    {"deviceTag":"XZV4MYG2","reason":"Success","status":"200"}
  ],
  "message": "Success"
}

A14. 查询 Promise Pay 列表

http

POST /api/partner/promise-pay/v1/list

用途：分页查询 Promise Pay 列表。

入参：apiKey、pageNum、pageSize 必填；deviceTag、imei 选填；Header sign 必填。

请求示例：

json

{
  "apiKey": "Zq3j9Xt7ReadyicYPV4HAJTrvp1xbOsN",
  "pageNum": 1,
  "pageSize": 100,
  "deviceTag": "RTHK8DS4"
}

返回示例：

json

{
  "code": 200,
  "message": "Success",
  "data": {
    "list": [
      {
        "id": 93,
        "deviceTag": "RTHK8DS4",
        "imei": "357818601111127",
        "title": "111",
        "content": "222",
        "expirationTime": 1769529600,
        "status": "EXPIRED",
        "createTime": 1774332449000,
        "updateTime": 1774333371000,
        "responseTime": null,
        "ptpTime": 1773479242000,
        "delayReason": null,
        "messageId": "935173969914576896"
      }
    ],
    "total": 1,
    "pages": 1,
    "pageNum": 1,
    "pageSize": 100
  }
}

状态枚举：NOT_REGISTERED 未注册、EXPIRED 已过期、TO_REPAY 去还款、TERMINATED 已终止、REPAID 已还款。

A15. simLock Reset

http

POST /api/partner/sim-lock/v1/reset

用途：重置设备 simLock。

入参：apiKey、deviceTag、Header sign 必填。

请求示例：

json

{
  "apiKey": "Zq3j9Xt7ReadyicYPV4HAJTrvp1xbOsN",
  "deviceTag": "RTHK8DS4"
}

返回示例：

json

{"code":200,"message":"Success","data":null}

A16. 单笔设备锁有效期延期

http

POST /api/partner/active-expire-renewal/v1/renewal

用途：对单个设备锁有效期延期。

入参：apiKey 必填；deviceTag 与 imei 只允许填一个；Header sign 必填。

请求示例：

json

{
  "deviceTag": "M3BGYDF4",
  "apiKey": "BS52jGm1nuZ7DVcURY6bJqhCpkvXraTH"
}

返回示例：

json

{
  "code": 200,
  "message": "Success",
  "data": {
    "deviceTag": "M3BGYDF4",
    "imei": "356779620009562",
    "beforeActiveExpireTime": "2028-06-14T08:36:06.000+00:00",
    "afterActiveExpireTime": "2028-07-14T08:36:06.000+00:00",
    "remainingRenewalLicense": 110
  }
}

A17. 批量设备锁有效期延期

http

POST /api/partner/active-expire-renewal/v1/batchRenewal

用途：批量设备锁有效期延期，最大 1000 条。

入参：apiKey、renewalInfo、Header sign 必填。renewalInfo 为字符串形式的数组，每项可传 deviceTag 或 imei。

请求示例：

json

{
  "renewalInfo": "[{\"deviceTag\":\"M3BGYDF4\"},{\"deviceTag\":\"M3BGYDF3\"},{\"imei\":\"356779620009562\"}]",
  "apiKey": "Zq3j9Xt7ReadyicYPV4HAJTrvp1xbOsN"
}

返回示例：

json

{
  "code": 400,
  "message": "Failed",
  "data": {
    "successCount": 0,
    "failCount": 3,
    "remainingRenewalLicense": 108,
    "details": [
      {
        "deviceTag": "M3BGYDF4",
        "imei": null,
        "success": false,
        "errorCode": 40009,
        "errorMessage": "Device has been renewed in the last 24 hours",
        "beforeActiveExpireTime": null,
        "afterActiveExpireTime": null,
        "remainingRenewalLicense": null
      },
      {
        "deviceTag": "M3BGYDF3",
        "imei": null,
        "success": false,
        "errorCode": 50071,
        "errorMessage": "The device-lock not exist",
        "beforeActiveExpireTime": null,
        "afterActiveExpireTime": null,
        "remainingRenewalLicense": null
      }
    ]
  }
}

附录：接口总览（通用 28 + 微额贷款新增）

微额贷款（Microfinancing）变体额外提供 initializeLock 入口与全量错误码 / 限频 / 跨语言签名参考，详见 PayTrigger 微额贷款 Microfinancing 接入。

通用设备锁接口（1–28）

编号	接口	路径
1	预录入 IMEI	`/api/partner/lock/v1/imei/input`
2	取消预录入	`/api/partner/lock/v1/imei/cancel`
3	还款状态变更/实际解锁	`/api/partner/lock/v1/updateRepayInfo`
4	移除设备锁	`/api/partner/lock/v1/removeLock`
5	设备状态变化回调	合作方回调地址
6	合作方推送消息	`/api/partner/push/v1/sendPushInfo`
7	合作方批量推送消息	`/api/partner/push/v1/sendBatchPushInfo`
8	查询商户 Web 配置信息	`/api/partner/company/v1/queryCompanyConfigInfo`
9	临时解除设备锁	`/api/partner/unlock/v1/tempUnlock`
10	单个设备配置/锁策略	`/api/partner/lockRule/v1/setLockRule`
11	查询设备锁状态	`/api/partner/lock/v1/findLockState`
12	批量查询设备锁状态	`/api/partner/lock/v1/batchFindLockState`
13	通过 IMEI 查询 DeviceTag	`/api/partner/lock/v1/getDevice`
14	PIN 离线解锁	`/api/partner/unlock/v1/verifyCode`
15	查询商户 License	`/api/partner/company/v1/checkLicense`
16	查询机型	`/api/partner/model/v1/get`
17	更新公司分步锁设置	`/api/partner/company/v1/lock-rule/update`
18	更新公司定制设置	`/api/partner/company/v1/customize/update`
19	查询客户反馈信息	`/api/partner/feedback/v1/query`
20	手机找回 - 提交	`/api/partner/anti-theft/v1/submit`
21	手机找回 - 关闭	`/api/partner/anti-theft/v1/close`
22	手机找回 - 状态查询	`/api/partner/anti-theft/v1/status`
23	批量更新还款状态	`/api/partner/lock/v1/batchUpdateRepayInfo`
24	批量移除设备锁	`/api/partner/lock/v1/batchRemoveLock`
25	查询 Promise Pay 列表	`/api/partner/promise-pay/v1/list`
26	simLock Reset	`/api/partner/sim-lock/v1/reset`
27	单笔设备锁有效期延期	`/api/partner/active-expire-renewal/v1/renewal`
28	批量设备锁有效期延期	`/api/partner/active-expire-renewal/v1/batchRenewal`

PayTrigger 手机锁接口整理 ​

1. 接入说明 ​

1.1 环境地址 ​

1.2 通用请求头 ​

1.3 签名规则 ​

2. 设备状态说明 ​

3. 查询机型 ​

入参 ​

请求示例 ​

成功返回示例 ​

常见失败返回 ​

4. 预录入 IMEI ​

入参 ​

请求示例 ​

成功返回示例 ​

部分失败返回示例 ​

5. 取消预录入 ​

入参 ​

请求示例 ​

返回示例 ​

6. 查询设备锁状态 ​

入参 ​

请求示例 ​

成功返回示例 ​

关键返回字段 ​

7. 通过 IMEI 查询 DeviceTag ​

入参 ​

请求示例 ​

返回示例 ​

8. 设备状态变化回调 ​

回调入参 ​

回调示例 ​

合作方回调响应 ​

9. 还款状态变更/实际解锁 ​

入参 ​

请求示例 ​

返回示例 ​

10. 移除设备锁 ​

入参 ​

请求示例 ​

返回示例 ​

11. 临时解除设备锁 ​

入参 ​

请求示例 ​

返回示例 ​

12. 单个设备锁策略配置 ​

入参 ​

请求示例 ​

返回示例 ​

13. PIN 离线解锁 ​

入参 ​

请求示例 ​

返回示例 ​

14. 推荐接入流程 ​

14.1 放款/售机前 ​

14.2 手机激活后 ​

14.3 还款后 ​

14.4 逾期后 ​

14.5 全部还清后 ​

15. 当前问题判断 ​

附录：全量接口补充 ​

A1. 合作方推送消息 ​

A2. 合作方批量推送消息 ​

A3. 查询商户 Web 配置信息 ​

A4. 批量查询设备锁状态 ​

A5. 查询商户 License 信息 ​

A6. 更新公司分步锁设置 ​

A7. 更新公司定制设置 ​

A8. 查询客户反馈信息 ​

A9. 手机找回 - 提交 ​

A10. 手机找回 - 关闭 ​

A11. 手机找回 - 状态查询 ​

A12. 批量更新还款状态 ​

A13. 批量移除设备锁 ​

A14. 查询 Promise Pay 列表 ​

A15. simLock Reset ​

A16. 单笔设备锁有效期延期 ​

A17. 批量设备锁有效期延期 ​

附录：接口总览（通用 28 + 微额贷款新增） ​

通用设备锁接口（1–28） ​

PayTrigger 手机锁接口整理

1. 接入说明

1.1 环境地址

1.2 通用请求头

1.3 签名规则

2. 设备状态说明

3. 查询机型

入参

请求示例

成功返回示例

常见失败返回

4. 预录入 IMEI

入参

请求示例

成功返回示例

部分失败返回示例

5. 取消预录入

入参

请求示例

返回示例

6. 查询设备锁状态

入参

请求示例

成功返回示例

关键返回字段

7. 通过 IMEI 查询 DeviceTag

入参

请求示例

返回示例

8. 设备状态变化回调

回调入参

回调示例

合作方回调响应

9. 还款状态变更/实际解锁

入参

请求示例

返回示例

10. 移除设备锁

入参

请求示例

返回示例

11. 临时解除设备锁

入参

请求示例

返回示例

12. 单个设备锁策略配置

入参

请求示例

返回示例

13. PIN 离线解锁

入参

请求示例

返回示例

14. 推荐接入流程

14.1 放款/售机前

14.2 手机激活后

14.3 还款后

14.4 逾期后

14.5 全部还清后

15. 当前问题判断

附录：全量接口补充

A1. 合作方推送消息

A2. 合作方批量推送消息

A3. 查询商户 Web 配置信息

A4. 批量查询设备锁状态

A5. 查询商户 License 信息

A6. 更新公司分步锁设置

A7. 更新公司定制设置

A8. 查询客户反馈信息

A9. 手机找回 - 提交

A10. 手机找回 - 关闭

A11. 手机找回 - 状态查询

A12. 批量更新还款状态

A13. 批量移除设备锁

A14. 查询 Promise Pay 列表

A15. simLock Reset

A16. 单笔设备锁有效期延期

A17. 批量设备锁有效期延期

附录：接口总览（通用 28 + 微额贷款新增）

通用设备锁接口（1–28）