拼多多开放平台：前端解密接入风控验证码 原文标题：拼多多 开放平台
内容概要总结
拼多多开放平台官方文档，说明 ISV（服务商）系统在查看商家订单、调用平台解密接口（/pdd/control/decrypt/… 系列）时如何接入拼多多的风控验证码与插件检测。背景是平台风控系统会分析商家的解密行为并拦截可疑操作，可能误触，故需让商家能自助解除风控。文档给出前置条件（解密必须走开平规定的接口路径，且已对接 oplb 解密）、B/S 与 C/S 两种架构的验证流程、风控响应格式（触发风控时 error_code 为 54001，响应体新增 risk_info.verify_auth_token）、风控验证码页的地址与入参（mall_id、client_id、verifyAuthToken、redirect_url）、verifyAuthToken 的保存与使用（放在请求 Header 的 X-PDD-VerifyAuthToken 字段，且需按 client_id + mall_id 分别保存）。此外还说明了插件检测接入：页面实时获取页面 code 初始化检测 SDK（https://pfile.pddpic.com/galerie-go/open_sdk/pc.js 的 PDD_OPEN_init），SDK 会周期上报插件检测结果；并提供调试用 Header X-PDD-MustVerify: True 以强制触发风控。
原文内容（原文即中文）
前端解密接入风控验证码
更新时间：2026-06-24 16:00:12
背景
目前商家通过 ISV 的系统查看订单主要走符合平台规范的解密接口(/pdd/control/decrypt/…系列接口)。平台风控系统，会分析商家的解密行为，判定一些商家可疑的解密，予以操作拦截。
这当中可能存在误触的情况，为了让误触发了风控的商家可以及时解除风控，需要 ISV 对接拼多多风控体系的验证码和插件检测。
前置条件
应用必须已经进行过以下改造：
（1）商家查看订单的解密行为通过以下开平规定的接口路径进行调用：
/pdd/control/decrypt/v1/address
/pdd/control/decrypt/v1/cardname
/pdd/control/decrypt/v1/cardnum
/pdd/control/decrypt/v1/receiverAddress
/pdd/control/decrypt/v1/receiverName
/pdd/control/decrypt/v1/receiverPhone
/pdd/control/decrypt/v1/street
/pdd/control/decrypt/v1/trackingNumber
（2）已经对接过 oplb 解密，即：实现以上接口时只需要返回符合格式的密文，开平的 oplb 会自动解密。
验证码接入
验证流程（B/S 架构）
[验证流程图，原页面为图片]
验证流程如上图所示，其中：
（1）步骤 6 和步骤 8：需要 ISV 的页面根据开平 SLB 的响应体来判断是否被风控，如果返回的是风控响应(步骤 8), 则进入被风控的流程。具体判断方式见下文风控响应部分。
（2）步骤 9：跳转开平风控页，并通过页面参数带入 client_id, mall_id, verify_auth_token, redirect_url。
（3）步骤 11 和步骤 12：验证通过后开平风控页会再次跳转步骤 9 里传入的 redirectUrl，并追加页面参数 verifyAuthToken。
（4）步骤 14：再次点击解密时，页面需要把 verifyAuthToken 加入到请求 Header 中，SLB 会根据这个字段做风控校验。
验证流程（C/S 架构）
C/S 架构的总体验证框架和 B/S 相同，验证仍然通过打开开平风控页完成。整体流程图如下：
[验证流程图，原页面为图片]
与 B/S 架构的区别主要在以下几个步骤
（1）步骤 9~10：ISV 客户端从 ISV 服务获取一个临时校验码。临时校验码的生成可以使用随机字符串，每次触发风控都生成新的。
（2）步骤 11：打开风控页时, 把临时校验码作为参数拼装到 redirect_url 参数里。例如：example.com/callback?client_code=${临时校验码}。再次注意 redirect_url 需要进行 url 编码。
（3）步骤 14：开平风控页验证通过后，会通过 GET 请求访问步骤 11 里的 redirect_url。 ISV服务可以在这个地址获取验证通过的 verify_auth_token。注意这个步骤需要 ISV 服务通过临时校验码对风控页的回调鉴权。
（4）步骤 15：客户端打开风控页之后，就可以开始轮询服务器获取校验结果和校验通过的 verify_auth_token，获取到 verify_auth_token 之后保存到本地存储中。后续发送请求带上 verify_auth_token
风控响应
URL
/pdd/control/decrypt/v1/address
/pdd/control/decrypt/v1/cardname
/pdd/control/decrypt/v1/cardnum
/pdd/control/decrypt/v1/receiverAddress
/pdd/control/decrypt/v1/receiverName
/pdd/control/decrypt/v1/receiverPhone
/pdd/control/decrypt/v1/street
/pdd/control/decrypt/v1/trackingNumber
示例响应
{
“error_code”: 54001, // 触发风控后，error_code为54001
“client_id”: “example of client id”,
“mall_id”: 1,
// 触发风控后, 开平 SLB 会在响应体里新增 risk_info 信息，内有 verify_auth_token
“risk_info”: {
“verify_auth_token”: “example of verify_auth_token”
}
… 其他无关字段
}对接调试：
为了让服务商对接时可以调试风控验证码功能，我们提供了一个特殊的请求 Header：X-PDD-MustVerify: True, 如果解密请求包含此 Header，则必定触发风控。需要进行开发调试的 isv，可以使用此方式触发风控的报错响应。
风控验证码页
触发风控后需要商家在风控验证码页解除风控，风控验证码页地址和页面入参如下：
URL
页面参数说明
| 参数名 | 是否必填 | 说明 |
|---|---|---|
| redirect_url | 是 | 验证码校验通过后的页面跳转地址, 注意进行 url 编码。ISV 需要在这个地址接收验证通过的 verifyAuthToken。（C/S 架构也可以只是一个接口，获取到返回的 verifyAuthToken，然后由客户端拿到这个 verifyAuthToken 用于验证） |
| mall_id | 是 | 触发风控的 mall_id。通过风控响应获取。 |
| client_id | 是 | 触发风控的 client_id。通过风控响应获取 |
| verifyAuthToken | 是 | 风控响应里的 verify_auth_token |
示例
以下地址:
fuwu.pinduoduo.com/service-market/are-you-robot?redirect_url=example.com%2fcallback&client_id=abcdefg&mall_id=1&verifyAuthToken=abcdefghi
表示：
mallId 为 1 的商家在 clientId 为 abcdefg 的应用上触发了解密风控，验证 Token 是 abcdefghi，风控页验证通过后需要跳转回 example.com/callback?verifyAuthToken=abcdefghi
保存和使用 verifyAuthToken
风控验证码页验证通过后会跳转 ISV 传入的 redirectUrl，并附带页面参数 verifyAuthToken，ISV 需要接收这个参数，并保存到 cookie 内（C/S 架构保存在客户端）。注意：verifyAuthToken 和 client_id + mall_id 相关，如果一个账号绑定了多个拼多多商家，每个 client_id + mall_id 的 verifyAuthToken 必须分别保存，根据解密时的订单属于的商家来选择 verifyAuthToken。
当 cookie 里存在 verifyAuthToken 时，前端发送解密请求时需要把 verify_auth_token 放在 Header 里。以电话号码为例，http 请求示例如下，注意其中 Header 里新增的 X-PDD-VerifyAuthToken 字段:
URL
/pdd/control/decrypt/v1/receiverPhone
请求
Header
X-PDD-VerifyAuthToken: “example of verify auth token”
Body
{
"decrypt_set": {
"sub_msg": "",
"sub_code": ""
},
"request_id": "",
"page_table_id": "",
"order_sn": ""
}插件检测接入
检测流程
[检测流程图，原页面为图片]
检测过程如上图所示：
（1）步骤 2：当商家登录系统并访问订单列表页、详情页等包含订单信息的页面时, 页面需要调用 ISV 服务端获取一个开平页面 code，注意这个 code 不能缓存, 每次实时获取。
（2）步骤 6：使用获取到的 code 初始化检测 SDK。之后检测 SDK 会自动周期上报检测结果到拼多多开放平台，不需要 ISV 做其他配置。
前端 SDK 使用
使用如下代码引用和初始化 SDK, 示例代码如下，其中 code 是通过后端服务调用开放平台接口拿到的。
初始化完成后，SDK 会周期上报检测的插件结果。
<script src="https://pfile.pddpic.com/galerie-go/open_sdk/pc.js"></script>
<script type="text/javascript">
PDD_OPEN_init({
code: 'example of sdk code' // 从开平接口拿到的页面code
})
</script>页面 Code 接口
初始化 SDK 时，必须先获取页面 Code，页面 Code 接口的文档:
https://open.pinduoduo.com/application/document/api?id=pdd.cloud.isv.page.code