支付宝商户接口及技术文档-V1.7.doc

商家与支付宝接口::批量代发浙江支付宝网络科技有限公司产品技术及用户体验部2007年12月目 录商家与支付宝接口:: 1批量代发 1目 录 21. 总述 42. 支付宝对外接口技术 52.1. 支付宝对外接口概述 52.2. 支付宝外部接入接口 52.2.1. 接入URL 52.2.2. 接入方式 52.2.3. 接入类型 52.2.4. 接入参数 72.2.5. 参数签名机制 92.2.6. 签名方式 112.3. 支付宝外部通知接口 122.3.1. 服务器通知 122.3.2. 通知参数 132.3.3. 通知验证接口 143. 上传付款文件 173.1. 接口类型 173.2. 请求参数表 173.3. 返回结果 193.4. 付款文件描述 193.4.1. 文件名格式 193.4.2. 文件内容格式 193.5. 支付宝直连银行 213.6. 付款文件银行信息填写规则 224. 下载付款结果文件 234.1. 接口类型 234.1.1. 请求参数表 234.2. 批次处理结果文件 244.2.1. 文件名格式 244.2.2. 文件内容格式 244.3. 付款结果文件描述 274.3.1. 文件名格式 274.3.2. 文件内容格式 285. 下载退票结果文件 305.1. 接口类型 305.1.1. 请求参数表 305.2. 退票文件 315.2.1. 文件名格式 315.2.2. 文件内容格式 316. 各银行错误描述附录。

341. 总述本文描述商户与支付宝接口的相关协议阅读对象：商户网站的技术开发人员2. 支付宝对外接口技术2.1. 支付宝对外接口概述支付宝对外接口分为两种，一种是接受外部请求的接口，我们统称为外部服务接口一种是主动通知外部系统的接口，我们统称为外部通知接口外部服务接口的主要目的是让外部商户主动使用我们的服务，如：创建交易等外部通知接口的主要目的是为外部商户提供数据同步服务（如：交易状态同步）以及异步处理结果返回服务（有些业务的处理是无法做到即时返回的）2.2. 支付宝外部接入接口2.2.1. 接入URL2.2.2. 接入方式POST/GET方式2.2.3. 接入类型l 系统调用顾名思义，这类接口是为商户系统获得支付宝系统信息提供服务的，是一种系统间的调用接口 系统调用示意图l 页面跳转顾名思义，这类接口都是一些有页面操作的接口通常是用户在商户页面执行部分操作，然后跳转到支付宝页面完成整个操作有的甚至可能最后还要再跳回到商户的下一个页面，继续完成整个操作根据处理结果的返回方式，又分为：n 立即返回处理结果，即用户在支付宝页面完成操作后，支付宝将处理结果立即返回给商户的下一步操作页面，让用户继续完成整个操作流程。

所以，调用这类接口时，必须传递参数return_url（即商户的下一个操作页面） 立即返回（页面跳转）示意图n 异步返回处理结果，即用户从商户页面跳转到支付宝页面后，在支付宝完成最后操作，用户不用再回到合作作伙伴页面这类接口通常是通过通知接口异步获得处理结果如果需要异步返回结果，那么必须传递notify_url参数，以指定通知返回的地址如果不需要异步返回结果，那么可以不用传递notify_url参数 页面跳转（通过通知接口返回结果）示意图2.2.4. 接入参数接入参数由协议参数和业务参数共同组成，业务接口中会介绍每个业务接口的输入/输出参数2.2.4.1. 协议参数协议参数字段名称变量名说明接口名称service外部接口名称商户IDpartner商户在支付宝的用户ID通知URLnotify_url通知返回URL,仅适用于异步返回处理结果的接口有些服务是无法立即返回处理结果的，那么需要通过这个URL将处理结果异步返回给商户见外部通知接口概述）返回URLreturn_url结果返回URL，仅适用于立即返回处理结果的接口支付宝处理完请求后，立即将处理结果返回给这个URL。

代理商IDagent如果一些交易网站的交易，有一定的“代理”所属关系，代理商可以在交易中传递该参数，来表明代理的身份这里传送的值，请使用代理商所属支付宝账户的PartnerID文件摘要digest_上传文件名用于标识上传文件的摘要值;多个文件对应会有多个参数；如请求参数中存在digest_upload_file参数时、表示存在一个上传文件、其在请求中的参数名是upload_file、其摘要值是参数digest_upload_file的值文件摘要算法file_digest_type支持MD5和SHA 建议使用MD5签名类型sign_type见签名方式参数编码字符集_input_charset商户系统与支付宝系统之间交互信息时使用的编码字符集商户可以通过该参数指定使用何种字符集对传递参数进行编码同时，支付宝系统也会使用该字符集对返回参数或通知参数进行编码业务参数（见后续章节）……参数编码字符集参数使用事例：POST请求：

HTTP请求中传递的所有参数(除sign和sign_type以外)按照参数名称字符升序的顺序串联起来（如：p1=v1&p2=v2&p3=v3），构成待签名数据按照sign_type指定的方式对待签名数据进行签名例如：调用某接口需要以下参数：service=user_querypartner=2088006300000000email=test@那么待签名数据就是：email=test@&partner=2088006300000000&service=user_query签名注意事项：n 没有值的参数无需传递，也无需包含到待签名数据中n 签名时将字符转变成字节流时指定的字符集要与_input_charset保持一致n 如果传递了_input_charset参数，那么这个参数也应该包含在待签名数据中n 根据HTTP协议要求，传递参数的值中如果存在特殊字符（如：&、@等），那么该值需要做URL Encoding，这样请求接受方才能接受到正确的参数值这种情况下，请注意做签名时使用的应该是原生值而不是encoding之后的值例如：会员 查询接口示例中待签名数据是email=test@&partner=2088006300000000&service=test，而不是email=test%&partner=2088006300000000&service=test。

2.2.6. 签名方式说明MD5待签名数据 + securityCode值（支付宝为商户颁发的安全校验码）的MD5摘要作为签名例如：安全校验码是mysecurityCode，那么前面会员查询接口示例的待签名数据就是：email=test@&partner=2088006300000000&service=user_querymysecurityCodeDSA商户发送请求时，使用自己的密钥对待签名数据进行DSA签名，支付宝使用商户的公钥进行校验；支付宝返回数据时，使用支付宝的密钥对待签名数据进行DSA签名，商户使用支付宝的公钥进行校验DSA公私钥可以使用OpenSSL生成，如下：1. 生成DSA参数openssl dsaparam -out dsa_param.pem 10242. 生成私钥openssl gendsa -out dsa_private_key.pem dsa_param.pem3. 生成公钥openssl dsa -in dsa_private_key.pem -pubout -out dsa_public_key.pem2.3. 支付宝外部通知接口2.3.1. 服务器通知服务器通知是支付宝系统提供的一套基于HTTP协议的主动向商户发送有关用户、交易等状态同步通知的基础服务。

其工作流程如下图所示：通知系统交互时序图通知系统交互流程说明：1. 支付宝系统向外部系统发出通知，即访问商户提供的通知接收URL2. 外部系统接到通知请求，通过notify_id询问支付宝这个通知的真实性，见通知验证接口3. 支付宝系统判断通知是否是自己发送，如果是返回true，否则返回false4. 商户系统得到支付宝系统的确认后，对通知进行处理处理完毕后，返回结果给支付宝系统5. 支付宝系统处理商户系统返回的处理结果2.3.2. 通知参数接入参数由协议参数和业务参数共同组成，业务接口中会介绍每个业务接口的输入/输出参数字段名称变量名类型说明可否为空协议参数通知类型notify_typeString通知类型，如：trade_status_sync，表示交易状态同步通知境外收单取值为：forex_trade_status_syncN通知IDnotify_idString支付宝通知流水号，商户可以用这个流水号询问支付宝该条通知的合法性N通知时间notify_timeTimestamp通知时间（支付宝时间），格式：YYYY-MM-DD hh:mm:ssN签名signString见HTTP参数签名机制N签名方式sign_typeString见签名方式N业务参数（见后续章节）……2.3.3. 通知验证接口为了确保通知内容是由支付宝系统发出的，我们提供了通知验证接口。

2.3.3.1. HTTPS通知验证接口接入URL：一个完整的验证请求例子： 程序在使用时需按以上要求发起一个HTTPS请求，获取该请求的结果即可，所有可能出现的结果见以下的输出参数表ASP可以使用XMLHTTP，PHP可以使用fopen或fsockopen函数，JAVA可以使用httpClient或.HttpURLConnection字段名称变量名类型说明可否为空接口名称serviceStringn。