外观
三方支付
约 2357 字大约 7 分钟
会员办理接口三方支付
2026-4-02
提示
三方支付产品与运营商产品的订购逻辑类似,最大的区别在于 三方支付产品需要用户提供姓名、证件号、卡号等信息申请签约验证(收验证码),然后提交签约完成产品订购。
页面要求
- 页面上需要用户手动勾选支付协议,协议内容见附件。
- 渠道方需按照要求设计页面,并提供链接进行页面报备。
对接流程
接口列表
签约申请(收验证码)
接口地址: /wy-cel-open/api/member/handle/send-sms
请求方式: POST
请求数据类型: application/json
接口描述: 与运营商产品的发验证码类似,该环节需要提供个人信息进行签约申请,调用成功后会发送验证码到预留手机号,下一步签约验证时提供验证码等信息。
请求参数:
| 参数名称 | 参数说明 | 是否必须 | 数据类型 | 说明 |
|---|---|---|---|---|
| appId | 系统标识 | true | string | |
| sign | 签名 | true | string | |
| data | 会员办理发短信入参 | true | object | SendSmsReq |
| phone | 号码 | true | string | |
| productId | 产品编码 | true | string | 分配的推广编码 |
| pan | 银行卡号 | true | string | 如:6222001234567890 |
| cardHolderName | 持卡人姓名(与银行预留一致) | true | string | 如:张三 |
| cardHolderId | 身份证号 | true | string | 如:110101199001011234 |
| phoneNo | 银行预留手机号 | true | string | 通常与办理手机号一致 |
| expiredDate | 卡有效期(MMYY 格式,信用卡必填) | false | string | 如:1225 |
| cvv2 | 卡校验码/CVV2(信用卡背面签名栏后 3 位数字) | false | string | 如:123 |
响应参数:
| 参数名称 | 参数说明 | 类型 | 说明 |
|---|---|---|---|
| code | 状态码 | integer | |
| message | 描述 | string | |
| data | object | SmsResp | |
| smsKey | 短信key 有返回则提交时必须带上 | string | |
| success | 状态 | boolean | |
| msg | 原因 | string |
请求示例:
{
"appId": "",
"sign": "",
"data": {
"phone": "1234567890",
"productId": "1752994995226415200",
"pan": "6222001234567890",
"cardHolderName": "张三",
"cardHolderId": "110101199001011234",
"phoneNo": "1234567890",
"expiredDate": "1225",
"cvv2": "123"
}
}响应示例:
// 接口调用异常
{
"code": 500,
"message": "签名失败"
}
// 短信发送失败
{
"code": 0,
"message": "",
"data": {
"smsKey": "",
"success": false,
"msg": "用户无权限办理"
}
}
// 短信发送成功
{
"code": 0,
"message": "",
"data": {
"smsKey": "",
"success": true
}
}签约申请(跳转签约)
接口地址: /wy-cel-open/api/member/handle/fast-bind
请求方式: POST
请求数据类型: application/json
接口描述: 提供个人信息进行一键绑卡申请,调用成功后会返回跳转地址,前端需要通过form表单进行跳转。
请求参数:
| 参数名称 | 参数说明 | 是否必须 | 数据类型 | 说明 |
|---|---|---|---|---|
| appId | 系统标识 | true | string | |
| sign | 签名 | true | string | |
| data | 一键绑卡签约入参 | true | object | ComboFastBindParam |
| phone | 号码 | true | string | |
| productId | 产品编码 | true | string | 分配的推广编码 |
| cardHolderName | 持卡人姓名(与银行预留一致) | true | string | 如:张三 |
| cardType | 银行卡类型: 0001信用卡 0002借记卡 | true | string | 默认0001 |
| bankId | 银行代码 | true | string | |
| idType | 证件类型 | false | string | 默认身份证 |
| cardHolderId | 身份证号 | true | string | 如:110101199001011234 |
| phoneNo | 银行预留手机号 | true | string | 通常与办理手机号一致 |
| clbckUrl | 绑卡回跳地址 | true | string | 绑卡成功后跳回的页面地址 |
| tr3Url | 异步通知地址 | true | string | 接收签约结果的通知地址,成功时才会通知 |
| sourceIp | 客户端 IP 地址 | false | string | 如:192.168.1.1 |
| appName | 交易发起应用名称 | false | string | 如:某某理财APP |
| reMark | 备注信息 | false | string |
证件类型
| 证件类型 | 编码 |
|---|---|
| 身份证类型 | 0 |
| 护照类型 | 1 |
| 军官证 | 2 |
| 士兵证 | 3 |
| 港澳台通行证 | 4 |
| 临时身份证 | 5 |
| 户口本 | 6 |
| 其他类型证件 | 7 |
| 警官证 | 9 |
| 外国人居留证 | 12 |
| 回乡证 | 15 |
| 企业营业执照 | 16 |
| 法人代码证 | 17 |
| 台胞证 | 18 |
| 外国人永久居留身份证 | 19 |
借记卡
| 银行名称 | 编码 |
|---|---|
| 农业银行 | ABC |
| 中国银行 | BOC |
| 邮储银行 | PSBC |
| 浦发银行 | SPDB |
| 平安银行 | PAB |
| 广发银行 | GDB |
| 华夏银行 | HXB |
| 民生银行 | CMBC |
信用卡
| 银行名称 | 编码 |
|---|---|
| 农业银行 | ABC |
| 邮储银行 | PSBC |
| 浦发银行 | SPDB |
| 平安银行 | PAB |
| 广发银行 | GDB |
| 华夏银行 | HXB |
| 中信银行 | CITIC |
响应参数:
| 参数名称 | 参数说明 | 类型 | 说明 |
|---|---|---|---|
| code | 状态码 | integer | |
| message | 描述 | string | |
| data | object | SmsResp | |
| success | 状态 | boolean | |
| msg | 失败原因 | string | |
| rdrctUrl | 用于跳转银行界面地址 | string | |
| signMsg | 一键绑卡秘钥 | string | 用于请求银行跳转地址赋值参数名epccGwMsg, 将参数名通过form表单POST提交至rdrctUrl地址 |
| status | 状态: 0-未处理 1-处理中 2-成功 3-失败 | string | |
| bindId | 一键绑卡标识 | string | 办理时传入 |
请求示例:
{
"appId": "",
"sign": "",
"data": {
"phone": "1234567890",
"productId": "1752994995226415200",
"cardHolderName": "张三",
"idType": "0",
"cardHolderId": "110101199001011234",
"phoneNo": "1234567890",
"cardType": "0002",
"bankId": "ABC",
"clbckUrl": "http://localhost:9985/oeh/mall/clb",
"tr3Url": "http://localhost:8080/api/callback/fast-bind-card",
"sourceIp": "192.168.1.1",
"appName": "某某理财 APP",
"reMark": "签约备注"
}
}响应示例:
// 接口调用异常
{
"code": 500,
"message": "签名失败"
}
// 申请签约失败
{
"code": 0,
"message": "",
"data": {
"success": false,
"msg": "失败原因",
"rdrctUrl": "http://localhost:9985/oeh/mall/clb?fid=12345",
"signMsg": "xx",
"bindId": ""
}
}
// 申请签约成功
{
"code": 0,
"message": "",
"data": {
"success": true,
"msg": "",
"rdrctUrl": "http://localhost:9985/oeh/mall/clb?fid=12345",
"signMsg": "xx",
"bindId": "12345"
}
}注意
我方会在传入的clbckUrl上追加fid=${bindId},以便调用方能够在从银行签约页面跳转回来的页面上,通过链接中的参数获取到bindId并轮询签约结果。
前端跳转银行签约页面示例代码参考:
// 前端参考以下代码通过form表单方式带参epccGwMsg(值取自signMsg)post请求rdrctUrl
let jumpBtn = $("#jumpToBankBtn")
if (jumpBtn.css("display") === "none") {
jumpBtn.css("display", "inline-block")
}
// 回跳地址
let rdrctUrl = jsonCode["responseBody"]["rdrctUrl"]
let signMsg = jsonCode["responseBody"]["signMsg"]
console.log("rdrctUrl:" + rdrctUrl)
console.log("signMsg:" + signMsg)
if (isEmpty(rdrctUrl) || isEmpty(signMsg)) {
console.log("disablew")
// 跳转按钮disabled
jumpBtn.attr("disabled", true)
} else {
jumpBtn.attr("disabled", false)
$("#jumpToBankForm").attr("action", rdrctUrl)
$("#epccGwMsg").attr("value", signMsg)
}
function jumpPageToBank() {
$("#jumpToBankForm").submit()
}
<form id="jumpToBankForm" target="_blank" method="post" style="display: none" action="">
<label>
<input type="text" id="epccGwMsg" name="epccGwMsg" value="">
</label>
</form>签约查询(轮询结果)
接口地址: /wy-cel-open/api/member/handle/query-fast-bind
请求方式: POST
请求数据类型: application/json
接口描述: 查询用户跳转到银行页面一键绑卡后的结果,看用户是否绑定完成以便进行下一步操作。
请求参数:
| 参数名称 | 参数说明 | 是否必须 | 数据类型 | 说明 |
|---|---|---|---|---|
| appId | 系统标识 | true | string | |
| sign | 签名 | true | string | |
| data | 一键绑卡状态查询入参 | true | object | ComboFastBindQueryParam |
| phone | 号码 | true | string | |
| productId | 产品编码 | true | string | 分配的推广编码 |
| bindId | 一键绑卡标识 | true | string | 如:12345 |
响应参数:
| 参数名称 | 参数说明 | 类型 | 说明 |
|---|---|---|---|
| code | 状态码 | integer | |
| message | 描述 | string | |
| data | object | SmsResp | |
| status | 绑卡状态: 0-未处理 1-处理中 2-成功 3-失败(一键绑卡) | boolean |
请求示例:
{
"appId": "",
"sign": "",
"data": {
"phone": "1234567890",
"productId": "1752994995226415200",
"bindId": "FS12345"
}
}响应示例:
// 接口调用异常
{
"code": 500,
"message": "签名失败"
}
// 一键绑卡失败
{
"code": 0,
"message": "",
"data": {
"status": 3
}
}
// 一键绑卡处理中
{
"code": 0,
"message": "",
"data": {
"status": 1
}
}
// 一键绑卡成功
{
"code": 0,
"message": "",
"data": {
"status": 2
}
}签约验证(提交办理)
接口还是走 办理接口,只是smsKey传值的时需要对值做一下处理:
- 普通绑卡:
smsKey的值设置为签约申请(收验证码)返回的smsKey,smsCode为用户收到的真实验证码。 - 一键绑卡:
smsKey的值设置为签约申请(跳转签约)返回的bindId,smsCode固定填000000不为空即可。
警告
提交办理的时候,务必传入notifyUrl接收通知,来确定用户是否办理完成。
签约通知(tr3Url)
接口地址: 接入方提供
请求方式: POST
请求数据类型: application/json
接口描述: 签约申请(跳转签约)时传入的tr3Url会在用户确定签约后发起通知。
请求参数:
| 参数名称 | 参数说明 | 是否必须 | 数据类型 | 说明 |
|---|---|---|---|---|
| status | 绑卡状态: 0-未处理 1-处理中 2-成功 3-失败(一键绑卡) | boolean | ||
| bindId | 一键绑卡标识 | true | string | 如:12345 |
响应参数: 字符串的ok或error
请求示例:
{
"status": 1,
"bindId": "12345"
}响应示例:
// 成功
ok
// 失败
error