1、 即时到账 接口集成 教程 服务名称 :create_direct_pay_by_user 版本号: 1.2 支付宝 (中 国) 网络 技术 有限公 司 版权 所有 即 时到账 接口集成 教程 支付宝(中国)网络技术有限公司 版权所有 | 版本号: 1.2 第 2 页 需要做的 集成 图 集成规 范点 列表 1 、 合作者 身份ID (partner ) 、 交易安 全校 验码 (key ) 需 要登录,点 击“商 家服 务”栏目, 在该界面中获 得。此查询 操作需要签约 的支付宝账 号、登录密码 、 支付密 码。 2 、 配置即时到 账 接 口。 需要 配置的 文件 有( 详细 可见 2 集
2、 ): 成 需要配置的文件 alipay_config 文件 alipayto 文件 return_url 文件 notify_url 文件 表 需要配 置的 文件 列表 测试 1 、 单独测 试即时到 账 接口( 详细可 见 3 测试); 2 、 结合商 户的 完整 业务 逻辑 测试整 个流 程: 登录 购买 下单 使 用支 付宝即时到 账 接口 付款 订单处 理完 成。 集成即时到 账 接口 获得合 作者 身份 ID(partner) 、交 易安 全校 验码(key) 【免费申请即可获得 】 即 时到账 接口集成 教程 支付宝(中国)网络技术有限公司 版权所有 | 版本号: 1.2 第 3
3、 页 目录 需要做的 2 集成 2 测试 2 目录 . 3 1 准备工作 . 5 1.1 确认工作 5 1.2 准备工作 5 2 集成 . 6 2.1 基础信息配 置 6 2.2 数据传输配 置 6 2.3 返回数据处 理 7 3 测试 . 8 3.1 步骤 . 8 3.2 支付 . 8 3.3 页面跳转同 步通知 9 3.4 服务器异步 通知 10 3.5 日志记录 10 4 常见问题 . 11 4.1 调试错误 11 4.2 订单更新异 常 15 即 时到账 接口集成 教程 支付宝(中国)网络技术有限公司 版权所有 | 版本号: 1.2 第 4 页 4.3 关掉了跳转 页面订 单未 更新
4、17 5 技术服务 . 18 即 时到账 接口集成 教程 支付宝(中国)网络技术有限公司 版权所有 | 版本号: 1.2 第 5 页 1 准备工作 1.1 确认工 作 1.1.1 确认商家网站 的基本信息 确认合 同是 否包 含即时到 账 接口 功能 。 合同查 询 , 用 签约的 支付 宝账号 , 登录 支付宝 官方 网站 , 点击 “商家 服务 ” “我的 产 品”。 确认网 站的 开发 语言 是什么 开 发语 言是 用指定 的一 种语 言来 开发 网站。 支付 宝提 供的 开发 语言代 码示 例目 前包 含 ASP 、PHP、A S P. N E T 、JAVA 四种 。 确认网 站编
5、码格 式是 GBK (GB2312)还 是 UTF-8 的 查询 网站使用的 是何种编码格 式,可通过 在网站网页上 右键,找到 “编码” ,打开 扩展 箭头后 查看 ,默 认选 中的 编码即 为网 站的 编码 格式 。 1.1.2 确认拿到的接 口资料 确认拿 到的 是接 口资 料是 即时到 账的接口 资料 确认选 择要 使用 的代 码示 例包是 与商 户网 站的 开发 语言及 编码 格式 都一 致的 代码 示例包 。 1.2 准备工 作 1.2.1 准备调试环境 本机电 脑的 调试 环境 开发工 具: Dreamweaver 、 Zend Studio 、 NetBeans 、 Micro
6、soft Visual Studio 、 Myeclipse 等; 编辑工 具:EditPlus、NotePad+ 、 电脑 自带 的“ 记事 本”等 环境配 置: 使用 ASP 和 A S P. N E T 开发 需要 配有 IIS 服务 ; 使用 PHP 开发 需要 xampp 或 PHP 环境包;使 用 JAVA 开发 需要 JAVA 的环 境配 置。 使 用 其他语 言开 发需 要配 置相 对该语 言 的环境 。 服务器 的调 试环 境 1 、 服务 器需 要支 持 各开发 语言对 应的 环境 ,如 :支 持 ASP 开发语 言的 IIS 服务 即 时到账 接口集成 教程 支付宝(中国
7、)网络技术有限公司 版权所有 | 版本号: 1.2 第 6 页 2 、 能够 把本 地文 件上 传到 服务器 上的 通道 与权 限, 如:FTP ,SFTP 传输 。 1.2.2 确认接口放置 位置 商户根 据业 务情 况, 需要确认支 付宝 的接 口是 用于 什么样 的场 景, 及确认 所属业务 流程 中的第 几个 步骤 ,如 :要 把支付 宝的 接口 功能 放置 在哪个 页面 里。 2 集成 2.1 基础信 息配置 打开 alipay_config 文件, 把所有 信息 全部 填写 完全 。 partner 、key 需要用签约支付宝账号登录支付宝官方网站,在“商家服务”的页面中查 询,h
8、ttps:/ 。 seller_email 收款支 付宝 账号 ,一 般为 签约的 支付 宝账 号。 notify_url 、return_url 它们需 要根据 notify_url 、return_url 这 两个页 面文 件 所在服 务器的 http:/ 格式的完整 路 径来设 定。 input_charset 商家网 站可 根据 网站 的编 码(UTF-8 或 GBK/GB2312 )下载 对应 编码 的接 口代 码示例 包。 input_charset 参 数的 值是 不需要 去修 改的 , 若 想修 改建议 直接 下载 另一 个编 码格式 的接 口代码 示例 包。 2.2 数据传输
9、 配置 打开 alipayto (A S P. N E T 中是 default)文件 , 在注释 “请求 参数 ”这部分 中需 要按照 注 释要求 配置 数据 。 这些数 据的 获得 方式 是 用户在 完成 一次 购买 的下 单流程 后 , 这 笔订 单便 已 经记录 到商 户的 订单 数据 中, 支付 宝 需要商 户提 供的 数据 正是 商户的 一部 分订 单数 据, 如: 订 单号 (out_trade_no)、 订 单名 称(subject ) 、订单描述(body ) 、订单总金额(total_fee )等。 商户只需要把 这笔要付 即 时到账 接口集成 教程 支付宝(中国)网络技术
10、有限公司 版权所有 | 版本号: 1.2 第 7 页 款的订 单的 数据 赋值 给 支 付宝指 定的 参数 ,就 能完 成数据 传输 的配 置, 如: out_trade_no = “ 商 户网 站的 唯一 订单号“ subject = “该笔订 单的 名称“ body = “ 该 笔订 单的 备注 或描述“ total_fee = “该笔订 单应 付总 额“ 引号中 的内 容 便是需 要商 户 放置 的订单 数据 。 2.3 返回数 据处理 打开 return_url (页 面跳 转 同步通 知) 文件 和 notify_url(服 务器 异步 通知 ) 文件,分 别 在代码 示例 中注 释
11、指 定位 置 增加 商家 网站 自己 的订 单处理 业务 程序 代码 ,即 “/验证成 功”这 个判 断中 。 第一步: 获得支 付宝 的处 理结 果数 据 获取众多返回数据中最重要的数据,如:订单号(参数 out_trade_no ) 、订单名称( 参 数 subject ) 、订单描述( 参数 body ) 、订单总金额 (参数 total_fee ) 、交易 状态(参数 trade_status) 、支 付宝 交易 号(参数 trade_no )等 , 更多参 数请 参考 页面 跳转 同步参 数 说明 、服 务器 异步 通知 参数 说明 (见 “ 即时 到账 交易接 口(create_d
12、irect_pay_by_user).pdf” ) 。 第二步: 判断该 笔订 单是 否在 商户 网站中 已经 做过 处理 判断该 笔订 单是 否有 被处 理过 。 由 于同 步通 知和 异 步通知 都会 返回 该笔 订单 的交易 状态 信息 , 那么该 笔订 单记 录就有可 能被 重复 刷新 。 因此, 根据 收到 通知 的这 笔 交易的 订单 号找到 商户 网站 订单 数据 库中这 笔订 单详 细信 息 , 把这次 收到 的支 付宝 的交 易状态 或退 款状态 与商 户网 站订 单数 据库中 这笔 订单 的交 易状 态或退 款状 态做 对比 。 如 果这笔 订单 没有做 过处 理则 刷新
13、该条 记录; 如果 已经 处理 过该 笔订单 则不 做处 理。 第三步: 业务逻 辑处 理 编写业 务订 单业 务流 程处 理程序 代码 。 一般 是在 这 里通过 订单 号 , 在 订单 数 据库中 更改 该笔订 单的 相关 数据 , 如 订单状 态从 “ 未付款 ” 改 变成 “已 付款 ” 等 , 并 在 订单数 据库 中存储 此次 订单 对应 的支 付宝交 易号 是什 么、 买家 账号是 什么 、处 理时 间是 什么等 。 注意: 1. 由于能够根据订单号(out_trade_no )SQL 语句查询 得到商家订单数据库得到 会员 的相关 信息或 存储 了会员 的相关 信息的 自定 义
14、参数 (extra_common_param ) ,所以 不需要 再在 返回 文件 return_url.asp 做 登录 验证 等处 理。 2. session 、cookie 在这两份 文件中 会失 效, 因此 不要 使用。 3. notify_url 文件不 能跳 转到 其他页 面 ,因此 请不 要写 页面自动跳 转的 程序 即 时到账 接口集成 教程 支付宝(中国)网络技术有限公司 版权所有 | 版本号: 1.2 第 8 页 4. 各开发 语言 代码 示例 中, “/验证 成功 ” 的判断 语句 里的所有 代码 仅为 样例 代码 , 商 户需要 根据 自身 的业 务情 况来修 改或 重
15、写 。 3 测试 3.1 步骤 第一步: 仅仅把接口配置好,不要放在网站项目中。在本机单独对这个接口进行调试。调试内 容包括 支付 、页 面跳 转同 步通知 ; 第二步: 本机调试没有问题后,再放入服务器中调试。调试内容包括:支付、页面跳转同步通 知、服务器 异步 通知 ; 第三步: 把调试 好的 接口 与网 站项 目的下 单流 程进 行衔 接和 融合; 第四步: 在本机 调试 衔接 到网 站项 目后的 接口 。调 试内 容包 括:支 付、 页面 跳转 同步 通知; 第五步: 本机调试没有问题后,再放入服务器中调试。调试内容包括:支付、页面跳转同步通 知、服务器 异步 通知 ; 3.2 支付
16、第一步: 保证订 单号 (out_trade_no )的唯 一性 ,不 要有 重复 的订单 号出 现。 第二步: 若包含 下单 流程 , 须 购买 一件商 品, 商品 设定 的金 额 0.01 元, 下单 完成 。 订 单总额 用 0.01 元做支 付测 试。 第三步: 访问 index 文件( 如: 本机路径 是 http:/localhost/ 接口文 件夹 名/index.asp;服务器 上 路径 是 http:/ 网站 域名/ 接 口文件 夹名/index.asp)即 :进入 确认 订单 页面 。 第四步: 点击支 付宝 付款 的按 钮, 页面会 跳转 至支 付宝 收银 台; 即 时到
17、账 接口集成 教程 支付宝(中国)网络技术有限公司 版权所有 | 版本号: 1.2 第 9 页 图 3.1 支付 宝 收银台 界面 第五步: 在支付 宝的 收银 台里 ,点 击“确 认无 误, 付款 ” , 完 成支付 宝里 的付 款操 作。 一般情 况下 ,页 面能 成功 到达支 付宝 收银 台, 没有 出错、 没有 乱码 ,那 么就 不会有 什么 问题 。 3.3 页面跳 转同步 通知 第一步: 在支付 宝收 银台 里, 完成 付款操 作, 支付 宝页 面显 示付款 成功 ,如 图: 图 3.2 支付 宝 付款成 功 界面 第二步: 等待几 秒, 页面 自动 跳转 到返回 页面 (参 数
18、return_url 对应 的路 径地 址) ,查 看返回 的 页面是 否打 印出 返回 的数 据,根 据返 回的 数据 来判 定是验 证失 败还 是成 功。 即 时到账 接口集成 教程 支付宝(中国)网络技术有限公司 版权所有 | 版本号: 1.2 第 10 页 第三步: 断点调 试或 用写 日志 函数 logResult()记录 数据 库程 序 代码段 的执 行情 况。 3.4 服务器 异步通 知 第一步: 必须把 接口 放置 在服 务器 里做调 试; 第二步: notify_url 的路径 互联 网上 可以访 问得 到, 且只 显示 fail 或无 通知 参数 。其 他如 空白或 是程序
19、 错误 提示 等内 容, 均属程 序执 行出 错; 第三步: 付款完 成一 次 1 分钱的 交易; 第四步: 用写日 志函 数 logResult() 记录 验证 是否 通过 , 记录这 验证的两 个判 断 中 三个 参数 的数 据。 各开发 语言 验证 的代码位 置 ASP : classalipay_notify.asp 文件 的 VerifyNotify()函数中的 if mysign = request.Form(“sign“) and responseTxt = “true“ then,三 个参 数是 mysign 、sign 、responseTxt 。 PHP : libalip
20、ay_notify.class.php 文件的 verifyNotify() 函数中的 if (preg_match(“/true$/i“,$responseTxt) ASP :response.write “success“ PHP:echo “success“; JAVA :out.println(“success“); G 、notify_url 页面中 不要 有 seesion 或 cookies,不 要做页 面自 动跳 转 第二步: 检查服 务器 配置 (以 下为 参考检 查方 向) A、服 务器 是否 开启 写入 权限 B 、DNS 解析 , 是否能 够解 析支付 宝 IP 。 支
21、付 宝 IP 范 围是: 121.0.26.0/23 (IP 范围 :121.0.26.1-121.0.27.254 ) 110.75.128.0/19 (IP 范围 :110.75.128.1110.75.159.254 ) 115.124.16.0/24 (IP 范围 :115.124.16.1115.124.16.254 ) C、防 火墙 是否 有拦 截 D、端 口 443 或 80 是 否有 开启, 且不 是假 死状 态, 也没有 被占 用 E 、 服务器 的 IP 地址是 否有 做过更换 ,如 果有 做过 更换 ,则请 把 notify_url 页面文 件重 命名, 参数 notif
22、y_url 的值 也一并 更新 。 第三步: 调试 A、 检查 程序 运行 到 alipay_notify 文件的 return_verify() 、 notify_verify()函数中 , 在 mysign 与 sign 是否 相等 的判 断与 responseTxt 是否为 true (PHP 代码 : $veryfy_result ) 的判断 这 即 时到账 接口集成 教程 支付宝(中国)网络技术有限公司 版权所有 | 版本号: 1.2 第 17 页 两个判 断上 是哪 个判 断验 证未通 过。 sign 与 mysign 不等的情况 有: 安全校验码 (参 数key )设 置有错 误
23、、 参数 格式 设置 错误与 编码 乱码 (见 第一 步 ) responseTxt 不是 true 的情 况有: 合 作身份 者ID (参 数partner )设置 有错 误、服 务器配置 (见 第 二步 ) 、页 面跳转返 回的 地址栏 里的 链接 超过 1 分钟的有 效时 间 B 、在 调试 notify_url 页面 时,必 须把 接口 放置 在服 务器里 做调 试 C 、 检查程序运行到商户 网站自己编 写的业务逻辑处理程序代 码段时,断点调试或使 用 写日志 函数 (函 数名 :logResult)逐行 检查 代码 ,监 控各个 参数 变量 注意: 商户网 站中 对这 笔交 易做
24、了多次 处理 (如 付了 一次 钱, 却 反复 充值 多次) 这 类情况 , 按 照 解决 方法 修正了 商户 网站 的程 序或 服务器 后, 请务 必在 页面 跳转同 步通 知页 面文 件 (return_url ) 与服务器 异步通知 页面 文件 (notify_url ) 中, 在商户 的业 务逻 辑处理的 程 序代码 执行 之前 , 一定 要 先判断 该次 处理 是否 已经 被做过 相同 的处 理 (即 , 该笔交 易在 已经 付过款后, 商户网站里的 订单是否已 经做过订单更新 ) ,如 :是否已经 为会员 充值 过一次 。没 有做 过相 同的 处理, 才执行下 面的 程序 。 (见
25、2.3 返回 数据 处理 第二步 ) 4.3 关掉了 跳转页 面订单未 更新 买家支 付完 成后 ,当 前界 面会停 留在 支付 宝的 交易 付款成 功的 提示 界面 上, 如: 图 4.2 支付 宝交 易成 功提 示界面 该页面 有短 暂的 停留 时间 , 买家看 到这 个提 示信 息 后有可 能会 把当 前页 面关 掉, 导致 页 面没有 自动 跳转 回商 户网 站 (return_url ) 使得 商户 的业务 数据 没有 被处 理 ( 如: 订单 没 即 时到账 接口集成 教程 支付宝(中国)网络技术有限公司 版权所有 | 版本号: 1.2 第 18 页 有更 新) 。出 现这种情况
26、的原因 是:商户网 站的支付宝接 口并没有利 用服务器异步 通知 页面文 件(notify_url )或 是该页 面在 订单 执行 过程 中也出 现异 常。 解决方法: 打开return_url 页 面文 件, 找到已 经编 写好 的业 务逻 辑处理 程序 代码 段 , 对 其 增加防 止该 笔交易 被重 复处 理判 断 。 打开notify_url 页 面文 件, 找到可 插入 商户 的业 务逻 辑处理 程序 代码的 地方 , 编写 与return_url 页面文 件 中相类 似的 程序, 也需 要包 含防 止该 笔交易被 重 复处理 的判 断。 如果是 因为notify_url 页面 文件
27、 更新 异常导 致订 单没 有更 新 , 其解决 方法 请参考4.2 订单更 新异 常 。 修改完成后效果: 当买家 关掉 自动 跳转 回商 户网站 的返 回页 面( 参数 return_url 对应的 return_url 返回 文 件)时 ,商 户的 业务 处理 依旧被 notify_url 页面 文 件所执 行, 因此 就不 会发 生业务 没有 同步的 现象 出现 (如 :订 单没有 被更 新) 5 技术服务 在开发 或使 用支 付宝 接口 时, 产生 疑问 或出 现问 题, 可点击 下面 的链 接填 写表单 , 提交 技术问 题, 支付 宝技 术支 持人员 会主 动联 系并 及时 处理。 https:/ 支付宝 论坛 接口 集成 专区 :http:/ 在论坛 中可 以下 载接 口资 料,查 找解 决方 案来 自主 解决问 题, 或是 发帖 寻求 帮助。 支付宝 商户 客服 热线 :0571-88158090