× 公告：在线文档访问域名已变更为 doc.payful.com，若原访问链接有问题可更换域名后重新访问。

📌 概述

Payful 提供集成所需API，集成商可使用POST方法向GEP系统发送HTTPS请求并接收对应的响应。
导航： 请求地址 / 请求报文 / 响应报文。

🔗 请求地址

格式：https:// {Host} / {Path}
示例：https://member-test-api.payful.com/api/user/account/queryUserBalanceAccount

属性说明：

属性 描述
Host 域名：请求指定环境的服务器域名
测试环境：https://member-test-api.payful.com
正式环境：https://api.payful.com
Path 请求路径：也即 API 访问路径，从具体 API 的 请求URL 模块获取
示例：/api/user/account/queryUserBalanceAccount

请求方式：POST

Content-Type：application/x-www-form-urlencoded（文件上传接口需使用：application/data-form）

⚠️默认返回中文错误信息，如需英文，请在请求头中设置：Accept-Language:en-US

安全性验证

安全维度 具体措施 实现方式与说明
1. 传输安全 协议与加密 1. 强制使用 HTTPS 协议。
2. 采用 TLSv1.2 及以上版本进行通道加密。
请求方法 统一使用 POST 方法提交请求，避免敏感参数出现在URL中。
2. 数据安全 业务数据加密 对业务字段使用 RSA 非对称加密 后传输，确保即使被截获也无法解密，防止信息泄露。
3. 访问控制 来源IP白名单 支持配置 请求来源IP白名单，只有列表内的服务器IP才能发起有效请求，从网络层面限制访问源。

📤 请求报文

✅ 公共请求参数

序号 域名 变量名 必填 字段类型 备注
01. 版本号 version M String(6) 固定值：1.0.0
02. 证书编号 certificateId M String(19) Payful 提供给商户的证书编号
03. 商户号 userNo M String(19) Payful 提供给商户的唯一编号
04. 数据类型 dataType M String(8) dataContent明文的组装方式，固定值：JSON
05. 加密数据 dataContent M String(2048) 1.先把 API 接口 加密数据dataContent规定参数组装JSON字符串
2. 然后对字符串做base64编码后再进行rsa私钥加密
加密方法可参考 加密说明 或 Demo
06. 文件 file C File 文件信息,只有 文件上传接口 需要,其他接口不需要
文件传输方式可参考Demo

📄 请求报文示例

{
  "certificateId": "2103031802000005106",
  "userNo": "5181200731000138828",
  "dataType": "JSON",
  "version": "1.0.0",
  "dataContent": "0a8036ad6115b321847d6495fc6f6291952da5c9dbd9c208bca2115afb1c6edec9c9b3f3fa97273eb032efce416669fe3b4aa45f066bf0003a0826d8278ad0a47f8e6c6189c42f8cbe5038fda1200139da7d6991c232df17f8da9aeed48380706b9ad35afc56a94a17935047e9505b8a7b6fdcb2dac06e6a67bf2595eb49d002"
}

📥 响应报文

✅ 公共响应参数

序号 域名 变量名 必填 字段类型 备注
01. 成功标识 success M String(8) true/false
02. 错误码 errorCode C String(64) 错误编码，目前只要VCC虚拟卡的API接口会返回errorCode，具体见对应接口附录错误码
03. 错误描述 errorMsg C String(512) success=false 时非空
04. 返回结果信息 result C String(2048) success为false时为空，其他时候不为空,结果信息参考个接口结果信息result说明
解密方法参考 解密说明 或DMEO
05. 商户编号 userNo M String(19) Payful提供给商户的唯一编号
06. 证书编号 certificateId M String(19) Payful提供给商户的证书编号

📄 响应报文示例

  • 成功示例

    {
"certificateId": "2103031802000005106",
"errorCode": "000000",
"errorMsg": "受理成功",
"result": "64bb2db0b9c495666274399698c1256f0c1679563a351c6071224ab7abea3164d281e525598d3b92f68461e4debb850f778d86065f6472847bf6f25b017a216d877cab3e8c0c5a8e0b95043020c390b1278e85082f6d058d701b62ff494adf7f1209cd889403fb8b9a66529b327ac6adff8462705ec4d2ef8150a3b278cc07d57d9b3e1a77b273f7e28b04b51dcfbcc2d6750df659fbf3c5601631651de9905a62e789e3588455924b33d7958cdc41844bf229dd2e5f73f373ec904f850aef3f24c5d628aa980802b37e48068d0d28307753ae91ca2cc7ed543b9ba905847397f88b384d307fab3ba0a12b44b1981b7b7aa3eb9f754386e75dc7a6c3e68216db7ab9e4b424e39538c61ede005e8207d18ba8dae5aeddda79b798b5258686f95ebc64b0a3e2e6924ebcdf41c6f614223e2c71afca58efc9c504c2aab57ee1cd7a2e71459e722d3c2a1b57ca033f228e6d954d71c4a2b5db3e562bc2110be05479a59c9f5e9d5c61fdebfdd07a3199cda62863516cc3ef4e3a5caadb82340cea80",
"success": true,
"userNo": "5181200731000138828"
}

  • 失败示例

    {
"certificateId": "2103031802000005106",
"errorMsg": "订单状态已更新,请刷新重试",
"success": false,
"userNo": "5181200731000138828"
}
作者：陈花枪  创建时间：2024-08-15 10:15
最后编辑：陈花枪  更新时间：2026-04-02 11:07