中国联通沃付互联网支付接口文档（V2.0） 中国联通支付有限公司 2012 年 9 月 中国联通沃付互联网支付接口文档 V2.0 版本 修订信息 版本 完成日期 起草人及修改人 发布日期 变更说明 V2.-9-21 互联网收单组 2012-9-21 新建文档 中国联通支付有限公司 第 2 页 共 28 页 中国联通沃付互联网支付接口文档 V2.0 目录 1文档描述 41.1功能描述 41.2阅读目标 41.3业务术语 42 商户技术开发准备 52.1技术资料获取与准备 52.1.1确认商户系统信息 52.1.2确认开发包 52.1.3确认请求资源 52.2环境搭建 53 订单支付接口调用流程 64 订单支付接口参数说明 94.1请求参数 94.1.1参数列表 94.1.2 示例 144.2 页面跳转回调参数 154.2.1 参数列表 154.3 服务端异步通知参数 194.3.1 参数列表 195 签名机制 205.1 商户签名密钥 205.2 等待签名串生成规则 205.3 请求时签名 215.4 商户得到支付平台响应后验证签名 226 常见问题及注意事项 236.1 商户签名密钥有什么用 236.2 商户开发测试环境资源 236.3 支付掉落 246.4 响应机制 246.5 通知重发机制 256.6 什么是支付工具 256.7 如果发起消费等前端交易，多久后可以调用查询接口 267 附录 267.1 交易响应码 267.2 银行列表 277.3 支付工具类型 277.4 支付产品类型 287.5 支付产品类型与支付工具类型转换 28 中国联通支付有限公司 第 3 页 / 共 28 联通沃支付互联网支付接口文档 V2.01 文档说明 1.1 功能描述 本文档从技术角度描述了商户平台如何接入联通沃支付互联网收银台完成订单支付，进而指导商户的开发与对接。

1.2 阅读对象 本文档适用于具有一定网站开发能力，了解ASP、PHP、JAVA、ASP.NET(C#)等其中一种开发语言的商户系统建设者、维护者和管理人员。 1.3 业务术语 术语解释 中国联通沃支付平台 中国联通沃支付平台（以下简称“联通沃支付”）是中国联通面向商户和个人用户提供的支付平台，主要由互联网收银台、移动互联网收银台、商户后台等系统组成。 互联网收银台沃支付是针对商户推出的互联网支付服务平台，平台集成了沃支付账户余额、快捷支付、网银网关等支付工具。用户通过网页浏览器在商户消费时，可使用沃支付的支付工具完成支付。 页面跳转通知 通过页面重定向的方式将支付结果返回给请求方的过程。 服务器后端异步通知通过服务器间点对点接口主动将支付结果通知给请求方。 统一支付网关标准网银网关支付接口，是指外部商户通过此接口创建订单并提交，用户由商户页面跳转至沃付宝收银台，消费者在沃付宝收银台选择网银网关支付并选择银行，再跳转至所选银行，消费者在银行完成交易。直接网银网关直接网银网关支付接口，是指在商户页面选择银行，外部商户创建订单时，包含用户选择的银行信息，通过此接口提交，用户无需在沃付宝收银台选择银行，而是通过沃付宝直接跳转至银行，消费者在银行完成交易。

中国联通支付有限公司 第 4 页 / 共 28 页 中国联通沃付互联网支付接口文档 V2.02 商户技术开发准备 2.1 技术资料获取与准备 2.1.1 确认商户系统信息  根据合同确认需要开发的接口功能；  确认网站的开发语言。开发语言是指定用来开发网站的语言，目前联通沃付提供的开发语言代码示例有 ASP、PHP、JAVA、ASP.NET（C#）。  确认网站的编码格式是 GBK() 还是 UTF-8。查看网站使用的是什么编码格式，可以在网站页面右键，找到“”，打开展开箭头查看，默认选择的编码就是网站的编码格式。 2.1.2 确认要使用的开发包 确认接口信息及原理图代码无遗漏地获取。 确认选择使用的代码示例包是与商户网站开发语言、编码格式一致的代码示例包。 2.1.3 确认申请的资源 确认申请的商户编号、运营商登录编号、运营商登录密码、商户签名密钥。 2.2 环境设置  本地电脑调试环境 开发工具：、Zend、、、等； 编辑工具：、++、电脑自带的“记事本”等。 环境配置：ASP开发需要IIS服务；PHP开发需要中国联通支付有限公司第 5 页 / 共 28 页 中国联通沃支付互联网支付接口文档V2.0或PHP环境包；JAVA开发需要JAVA环境配置。

使用其他语言开发需要配置该语言对应的环境。  服务器调试环境硬件方面： 由于网上支付平台提供的软件和商户系统结合紧密，通常不需要额外的硬件投入。 软件方面：Java语言JDK1.4以上版本，操作系统不限，服务器需支持各开发语言对应的环境，如：支持ASP开发语言的IIS服务。 3 订单支付接口调用流程 sd 订单支付数据交互 商户联通支付平台 1.构造请求数据() 2.浏览器post表单提交方法提交请求() 3.处理请求() 4.1.浏览器页面跳转同步通知() 4.2.服务器点对点异步通知() 5.处理相应数据() （1）构造请求数据 商户根据客户支付行为生成订单，包括对商户号、订单号、金额等关键数据进行数字签名，并根据联通沃支付平台订单支付接口规则完成数据组装请求。 中国联通支付有限公司 第 6 页 / 共 28 页 中国联通沃支付互联网支付接口文档 V2.0 （2）发送请求数据 构造好的数据集通过页面表单提交（POST）传递给联通沃支付平台，采用的协议是，提交地址为： 生产环境：/pay//e.htm 测试环境：6:8085/pay//e.htm 注意：商户需要根据自己网站采用的编码格式，将编码格式作为参数放在 URL 后面。 例如GBK编码的网站提交方式为： /pay//e.htm?=GBK 或者 6:8085/pay//e.htm?=GBK UTF-8编码的网站提交方式为： /pay //e.htm?=UTF-8 或者 6:8085/pay//e.htm?=UTF-8 （3）联通沃支付平台对请求数据的处理 联通沃支付平台在获取到这些集合之后，会先进行数据格式、签名等安全验证，一系列验证通过之后，才会处理本次发送的数据请求。

然后重定向浏览器，引导用户进行支付，用户支付完成后，订单才会被处理。 （4）返回处理的结果数据。对于已完成的交易，联通沃支付平台提供两种方式将数据反馈给机构（商户）网站。 1：浏览器页面跳转同步通知交易后，自动重构URL地址链接，在用户当前页面请求时自动跳转回机构（商户）设置的页面路径地址（参数）。 2：服务器点对点异步通知 服务器主动发起通知，调用机构（商户）请求时设置的后台通知地址路径（参数）。 注意：重发机制：对于支持服务器点对点异步通知的商户，在收到通知后，必须返回一个以“ ”开头的不区分大小写的字符串给联通沃支付平台，否则联通沃支付平台将启动重发机制，发送后台交易通知。 具体做法是每2(i-1)分钟发送一次后台交易结果通知，在重发通知过程中，如果商户响应一次，则中断重发策略。其中i为重发次数，i∈[1,10]。注意：商户收到交易通知后，应立即确认已收到，并丢弃重复的交易结果通知。

（5）商户对返回的结果数据进行处理。商户收到浏览器页面跳转同步通知（参数指定地址）或服务器点对点异步通知（参数指定地址）返回的结果数据后，可结合自身网站业务逻辑对数据进行处理（如：订单更新、为用户发货等）。注意：商户收到联通沃支付平台返回的结果数据后，应在向联通沃支付平台请求时对返回结果中的支付金额字段值进行校验，确认此金额与订单金额是否一致，以保证支付交易的安全性。 中国联通支付有限公司 第 8 页 / 共 28 页 中国联通沃支付互联网支付接口文档V2.04 订单支付接口参数说明 4.1 请求参数 4.1.1 参数列表 参数 参数名称 类型 长度 参数说明 可否为空 示例 消息 (7) 接口版本号，暂时固定不能为空 接口类型字符串 (5) 统一支付网关：不能为空 固定为直销网银网关：固定为银行代码字符串 “接口类型（ ）为” 可为空 (16) 必填项，银行清单见附录。

支付工具字符串“接口类型（ ）可以为空YE|B2类型（100）是”很有用，通过这个CWY|参数，在统一支付网关中为用户动态展示对应的支付工具。支付工具代码见“11.3支付工具类型”。多个支付工具之间用管道符“|”隔开，选择的支付工具必须是商户在联通沃支付平台开通的支付工具，否则即使传递过来也不会显示。例如参数：“YE||”表示在统一支付网关中可以显示的支付工具有：联通账户支付、B2C网银支付、联通快捷支付。如果该参数为空，则默认在统一支付网关中显示商户开通的所有支付工具。 （注：v1.1版本与v1.2版本存在差异，建议v1.1版本用户更新至v1.2版本参数，对比见11.5） 商户字符串 唯一标识商户的字符串，由商户申请注册时由联通（15）沃支付平台统一分配 商品名称 唯一标识用户购买商品的字符串，若长度超出限制，支付系统会自动截取前64个字节。

无线激光2.4G鼠标 产品描述字符串 产品的描述。若超出原价（200）长度，支付系统将自动截取399元的前200个字节。 惠普原装正品无线激光2.4G鼠标，特价68元，数量有限！售完即止。 联通支付有限公司 第10页 / 共28页 联通沃支付互联网支付接口文档V2.0。 商户订单字符串 (8)商户订单日期为非空日期格式 21 商户订单字符串 同一日期内，商户交易成功的订单号必须唯一（即交易成功后不能重复交易），交易失败可以重复下单。必须是字母（大写或小写）或数字或二者的组合。字母区分大小写。 订单金额 订单金额，单位：分，非空 2000 金额为大于0的正整数，如：2000，代表20.00元 商品id 商品在商户系统中的id NULL (64) 商户用户 购物者在商户网站上的用户id NULL 用户id (32) 扩展字段 原样返回给商户 NULL (100) =100|=text 买家姓名 付款用户姓名 NULL 张大千e (20) 买家手机字符串 付款用户的手机号码 NULL (20) ai 买家邮箱字符串 付款用户的邮箱地址 NULL l (30) 买家身份字符串 付款用户的身份证件 NULL 中国联通支付有限公司第11页/共28页 中国联通沃支付互联网支付接口文档V2.0证书 (20) 20 字符集字符串 字符集编码。

-8 不可为空 GBK (10) 必须和请求URL中的字符集一致 交易方式字符串 (4) 固定值为0001:立即支付 不可为空 0001 订单次字符串定义交易的超时时间，可以为空 1d1c表示当天，m表示分钟，支付超时时间 (10) h表示小时，d表示天数 时间参数有（1c，200m，3h，1d，3d，7d，15d等） 最大值15d 默认2h 关闭交易订单请求字符串格式为 不可为空时间 (14) 请求IP字符串 用户购物时的IP地址，如果为空 122.132 (20) 如果商家开启了防钓鱼功能，.13.2该字段为必填项（讨论） 响应机制字符串 (1) 固定值：不可为空 11.双向确认响应。 支付成功后，支付平台会给商户系统做两次回调通知：一次页面跳转通知、一次服务器点对点通知。商户系统在收到支付系统服务器的点对点支付成功通知时，必须回写一个以“”开头的字符串（不区分大小写）。即使商户平台在收到成功通知时发现订单已经处理，也必须正确回写“”，否则支付系统会认为你的系统没有收到通知，从而启动重发机制。

2.双向非确认响应。支付平台依然发送两次支付成功回调通知，无论商户系统是否正确响应回调通知，支付系统均不启动重发机制。 3.只发送页面重定向回调通知。 页面重定向字符串 用户支付成功后，联通沃不能为空要回调(255) 支付平台会组织结果通知ww..cURL数据通过浏览器重定向到URL om/path，以便商户收到支付结果。 .do 服务器不同字符串服务器点对点回调，用于通知商户系统支付结果。 ww..c 地址 “响应机制()” om/path为1或2。必填 /.do 签名方法字符串(8) MD5、SHA-1两种方法不能为空 MD5商户签名字符串见签名机制不能为空(40) (此参数不参与签名) 注意所有参数都区分大小写。 中国联通支付有限公司 第13页/共28页 中国联通沃支付互联网支付接口文档V2.04.1.2样例表单提交示例：!html-//W3C//DTD HTML 4.01//中国联通沃支付工具订单支付功能测试// name= =post=/pay//e.htm?= type= name= = type= name= = type= name= = type= name= = type= name= =原装正品惠普无线激光2.4G鼠标type= name= =惠普原装正品无线激光2.4G鼠标，原价399元，现仅售68元，数量有限，售完即止。

type= name= type= name= =ut type= name= = type= name= = type= name= = type= name= ==100|= type= name= =赵大宝type= name= type= name= =@ type= name= = type= name= = type= name= =0001 中国联通支付有限公司 第 14 页 / 共 28 页 中国联通沃支付互联网支付接口文档 V2. type= name= = type= name= = type= name= === =/path/.== =/path/. type= name= = type= name= === =; /p/form/body/.2 页面重定向回调参数 4.2.1 参数列表 参数 参数名称 类型 长度 参数说明 选填 样例消息 版本 (7) 接口版本号，暂不可选 固定为 商户 (15) 商户注册申请时，联通沃支付平台分配的统一标识，唯一标识一个商户 不可选 产品ID (64) 商户系统中的产品ID 不可选 产品名称 (64) 用户购买的产品名称 不可选 原装正品 联通支付有限公司 第15页/共28页 联通沃支付互联网支付接口文档V2.0 惠普原装正品无线激光2.4G鼠标 产品描述 产品描述 不可选 原价399元（200只）的惠普原装正品无线激光2.4G鼠标，现优惠68元，数量有限，售完即止

商户订单字符串(50) 同一日期内，商户交易成功的订单号必须唯一（即不能重复交易成功），交易失败时订单号可以重复，必须是字母（大写或小写）或者数字或者二者的组合，字母区分大小写。 支付金额 订单金额，单位：分，不能为空 2000 金额为大于0的正整数 商户用户字符串(32) 商户网站上的购物者用户。空 买家手机字符串(20) 付款用户的手机号。空 中国联通支付有限公司 第16页 / 共28页 中国联通沃支付互联网支付接口文档V2. 商户订单日期字符串(8) 商户订单日期不能为空 格式1 扩展字段字符串按原样返回给商户。空 =(100) 用户 100|=kao 字符集字符串(10) 字符集编码。 非空或UTF-8 订单请求字符串(14)格式为 非空 1 交易结果字符串(1) 固定值：1 成功 非空 1 描述：支付成功时支付平台才会回调 结果信息描述字符串 结果信息描述 可以为空 支付成功描述(100) 支付系统交易字符串(20) 支付成功时，联通沃支付 可以为空 易支付平台支付流程97流程 联通沃支付字符串(14)格式为 可以为空 平台支付完成时间 联通沃支付字符串(8)格式为， 可以为空 平台记账日期，用于对账结算 2 清算日期 支付金额详情字符串 支付时，各个子账户 可以为空 02:2000，03:3000 分隔符','(英文逗号)用于分隔各个子账户的信息。 子账户使用‘账户类型:金额’，02表示个人现金账户，03表示个人卡充值联通支付有限公司第17页/共28页联通沃支付互联网支付接口文档V2.0账户。

该键值对格式用于表示某一个账户的金额，格式如下：02:2000,03:3000表示从现金账户中扣除2000积分，从一张卡中充值3000积分。通知方式字符串（1）为“1”：页面重定向，可选1个回调；“2”：服务器异步通知。支付工具类型字符串（50）为可选YE:5000|用户完成支付所使用的类型支付工具以及对应的:1000和工具金额。返回结果格式为：产品码:金额|产品码:金额。产品码与金额以英文冒号“:”分隔，多个支付工具组合支付时以竖线“|”分隔。金额单位为美分。支付工具码见“11.3支付工具类型”。 例如“YE:5000|:1000”表示：使用联通沃付账户支付金额为5000积分，使用B2C网银支付金额为1000积分。中国联通支付有限公司第18页/共28页中国联通沃付互联网支付接口文档V2.支付银行编码字符串