1、 批量代发接口文档共 34 页 第 页商家与支付宝接口商家与支付宝接口 :批量代发批量代发浙江支付宝网络科技有限公司产品技术及用户体验部2007 年 12 月批量代发接口说明书共 34 页 第 页目目 录录商家与支付宝接口 :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.
2、通知参数 132.3.3. 通知验证接口 143. 上传付款文件 173.1. 接口类型 173.2. 请求参数表 173.3. 返回结果 193.4. 付款文件描述 193.4.1. 文件名格式 193.4.2. 文件内容格式 193.5. 支付宝直连银行 213.6. 付款文件银行信息填写规则 22批量代发接口说明书共 34 页 第 页4. 下载付款结果文件 234.1. 接口类型 234.1.1. 请求参数表 234.2. 批次处理结果文件 244.2.1. 文件名格式 244.2.2. 文件内容格式 244.3. 付款结果文件描述 274.3.1. 文件名格式 274.3.2. 文件内
3、容格式 285. 下载退票结果文件 305.1. 接口类型 305.1.1. 请求参数表 305.2. 退票文件 315.2.1. 文件名格式 315.2.2. 文件内容格式 316. 各银行错误描述附录。 34批量代发接口说明书共 34 页 第 页1. 总述本文描述商户与支付宝接口的相关协议阅读对象：商户网站的技术开发人员批量代发接口说明书共 34 页 第 页2. 支付宝对外接口技术2.1. 支付宝对外接口概述支付宝对外接口分为两种，一种是接受外部请求的接口，我们统称为外部服务接口。一种是主动通知外部系统的接口，我们统称为外部通知接口。外部服务接口的主要目的是让外部商户主动使用我们的服务，如
4、：创建交易等。外部通知接口的主要目的是为外部商户提供数据同步服务（如：交易状态同步）以及异步处理结果返回服务（有些业务的处理是无法做到即时返回的） 。2.2. 支付宝外部接入接口2.2.1. 接入 URLhttps:/ 接入方式POST/GET 方式2.2.3. 接入类型 系统调用顾名思义，这类接口是为商户系统获得支付宝系统信息提供服务的，是一种系统间的调用接口。批量代发接口说明书共 34 页 第 页系统调用示意图 页面跳转顾名思义，这类接口都是一些有页面操作的接口。通常是用户在商户页面执行部分操作，然后跳转到支付宝页面完成整个操作。有的甚至可能最后还要再跳回到商户的下一个页面，继续完成整个操
5、作。根据处理结果的返回方式，又分为： 立即返回处理结果，即用户在支付宝页面完成操作后，支付宝将处理结果立即返回给商户的下一步操作页面，让用户继续完成整个操作流程。所以，调用这类接口时，必须传递参数 return_url（即商户的下一个操作页面） 。立即返回（页面跳转）示意图批量代发接口说明书共 34 页 第 页 异步返回处理结果，即用户从商户页面跳转到支付宝页面后，在支付宝完成最后操作，用户不用再回到合作作伙伴页面。这类接口通常是通过通知接口异步获得处理结果。如果需要异步返回结果，那么必须传递 notify_url 参数，以指定通知返回的地址。如果不需要异步返回结果，那么可以不用传递 noti
6、fy_url 参数。页面跳转（通过通知接口返回结果）示意图2.2.4. 接入参数接入参数由协议参数和业务参数共同组成，业务接口中会介绍每个业务接口的输入/输出参数。2.2.4.1. 协议参数协议参数字段名称 变量名 说明接口名称 service 外部接口名称商户 ID partner 商户在支付宝的用户 ID通知 URL notify_url 通知返回 URL,仅适用于异步返回处理结果的接口。有批量代发接口说明书共 34 页 第 页些服务是无法立即返回处理结果的，那么需要通过这个 URL 将处理结果异步返回给商户。 （见外部通知接口概述）返回 URL return_url 结果返回 URL，仅
7、适用于立即返回处理结果的接口。支付宝处理完请求后，立即将处理结果返回给这个URL。代理商 ID agent 如果一些交易网站的交易，有一定的“代理”所属关系，代理商可以在交易中传递该参数，来表明代理的身份。这里传送的值，请使用代理商所属支付宝账户的 PartnerID。文件摘要 digest_上传文件名用于标识上传文件的摘要值;多个文件对应会有多个参数；如请求参数中存在 digest_upload_file 参数时、表示存在一个上传文件、其在请求中的参数名是upload_file、其摘要值是参数 digest_upload_file 的值文件摘要算法 file_digest_type支持 MD
8、5 和 SHA 建议使用 MD5签名类型 sign_type 见签名方式参数编码字符集_input_charset 商户系统与支付宝系统之间交互信息时使用的编码字符集。商户可以通过该参数指定使用何种字符集对传递参数进行编码。同时，支付宝系统也会使用该字符批量代发接口说明书共 34 页 第 页集对返回参数或通知参数进行编码。业务参数（见后续章节）参数编码字符集参数使用事例：POST 请求： GET 请求：https:/ 参数签名机制为了确保数据传输过程中的数据真实性和完整性，我们需要对数据进行签名校验。HTTP 请求中传递的所有参数 (除 sign 和 sign_type 以外)按照参数名称字符
9、升序的顺序串联起来（如：p1=v1&p2=v2&p3=v3） ，构成待签名数据。按照 sign_type 指定的方式对待签名数据进行签名。例如：调用某接口需要以下参数：service=user_querypartner=2088006300000000email=批量代发接口说明书共 34 页 第 页那么待签名数据就是：email=&partner=2088006300000000&service=user_query。签名注意事项： 没有值的参数无需传递，也无需包含到待签名数据中。 签名时将字符转变成字节流时指定的字符集要与_input_charset 保持一致。 如果传递了_input_c
10、harset 参数，那么这个参数也应该包含在待签名数据中。 根据 HTTP 协议要求，传递参数的值中如果存在特殊字符（如：&、等） ，那么该值需要做 URL Encoding，这样请求接受方才能接受到正确的参数值。这种情况下，请注意做签名时使用的应该是原生值而不是 encoding 之后的值。例如：会员 查询接口示例中待签名数据是email=&partner=2088006300000000&service=test，而不是 email=test%&partner=2088006300000000&service=test。批量代发接口说明书共 34 页 第 页2.2.6. 签名方式说明MD5
11、 待签名数据 + securityCode 值（支付宝为商户颁发的安全校验码）的 MD5 摘要作为签名。例如：安全校验码是 mysecurityCode，那么前面会员查询接口示例的待签名数据就是：email=&partner=2088006300000000&service=user_querymysecurityCode。DSA 商户发送请求时，使用自己的密钥对待签名数据进行 DSA 签名，支付宝使用商户的公钥进行校验；支付宝返回数据时，使用支付宝的密钥对待签名数据进行 DSA签名，商户使用支付宝的公钥进行校验。DSA 公私钥可以使用 OpenSSL 生成，如下：1. 生成 DSA 参数op
12、enssl 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.pem批量代发接口说明书共 34 页 第 页2.3. 支付宝外部通知接口2.3.1. 服务器通知服务器通知是支付宝系统提供的一套基于 HTTP 协议的主动向商户发送有关用户、交易等状态同步通知的基础服务。其工作流程如下图所示：通知系统交互时序图通知系统交互流程说
13、明：1. 支付宝系统向外部系统发出通知，即访问商户提供的通知接收 URL。2. 外部系统接到通知请求，通过 notify_id 询问支付宝这个通知的真实性，见通知验证接口。3. 支付宝系统判断通知是否是自己发送，如果是返回 true，否则返回 false。4. 商户系统得到支付宝系统的确认后，对通知进行处理。处理完毕后，返回结果给支付宝系统。批量代发接口说明书共 34 页 第 页5. 支付宝系统处理商户系统返回的处理结果。2.3.2. 通知参数接入参数由协议参数和业务参数共同组成，业务接口中会介绍每个业务接口的输入/输出参数。字段名称 变量名 类型 说明 可否为空协议参数通知类型 notify
14、_type String 通知类型，如：trade_status_sync，表示交易状态同步通知。境外收单取值为：forex_trade_status_syncN通知 ID notify_id String 支付宝通知流水号，商户可以用这个流水号询问支付宝该条通知的合法性N通知时间 notify_time Timestamp 通知时间（支付宝时间） ，格式：YYYY-MM-DD hh:mm:ssN签名 sign String 见 HTTP 参数签名机制 N批量代发接口说明书共 34 页 第 页签名方式 sign_type String 见签名方式 N业务参数（见后续章节）2.3.3. 通知验证
15、接口为了确保通知内容是由支付宝系统发出的，我们提供了通知验证接口。2.3.3.1. HTTPS 通知验证接口接入 URL：https:/ 程序在使用时需按以上要求发起一个 HTTPS 请求，获取该请求的结果即可，所有可能出现的结果见以下的输出参数表。ASP 可以使用 XMLHTTP，PHP 可以使用 fopen 或 fsockopen 函数，JAVA 可以使用 httpClient 或 .HttpURLConnection。字段名称 变量名 类型 说明 可否为空接口名称 service String notify_verify N商户 ID partner String(16) 商户在支付宝的
16、用户 ID N批量代发接口说明书共 34 页 第 页通知 ID notify_id String 支付宝发送的通知 ID N特别提醒：上述接口是用来校验支付宝所发出通知的真实性，需要网站支持 HTTPS 访问。若网站不支持 https 的访问，可以采用如下接口：2.3.3.2. HTTP 通知验证接口 接入 URL：http:/ 一个完整的验证请求例子：http:/ HTTP 请求，获取该请求的结果即可，所有可能出现的结果见以下的输出参数表。ASP 可以使用 XMLHTTP，PHP 可以使用 fopen 或 fsockopen 函数，JAVA 可以使用 httpClient 或 .HttpUR
17、LConnection。字段名称 变量名 类型 说明 可否为空商户 ID partner String(16) 商户在支付宝的用户 ID N通知 ID notify_id String 支付宝发送的通知 ID N批量代发接口说明书共 34 页 第 页2.3.3.3. 通知验证接口输出参数输出内容 说明invalid 传入的参数无效true 验证通过false 验证失败提醒 1：为了保证该接口被合法利用，商户系统只能查找 1 分钟之内（目前为 1 分钟，以后若有调整，恕不另行通知）的通知。提醒 2：从系统健康性角度考虑，在接收到支付宝系统通知以后，使用上述的通知验证接口验证支付宝系统通知的正确性
18、（合法性）是非常有必要的。支付宝强烈建议您在系统中加入上述的应用。批量代发接口说明书共 34 页 第 页3. 上传付款文件3.1. 接口类型系统调用3.2. 请求参数表特别注意：请按照支付宝外部请求接口概述中要求的签名方式，对输入参数进行签名，该接口请求才能够被支付宝系统接收。字段名 变量名 类型 说明 可空协议参数接口名称 service String(32) 文件类型操作、值为bptb_pay_fileN商户 ID partner String(16) 商户在支付宝的用户IDN文件摘要 digest_bptb_pay_fileString(64) 上传付款文件的摘要值N文件摘要算法file
19、_digest_type String MD5 或 SHA N签名 sign String(64) 签名串 N批量代发接口说明书共 34 页 第 页签名方式 sign_type String MD5 N业务类型 biz_type String 值为 d_sale N字符集 _input_charset String 默认为 gb2312 Y业务类型bussiness_type String 当bussiness_type 为“T0”的时候表示要使用 T+0 服务，为其他值，或者没有该字段的时候表示T+1 服务。Y付款文件作为附件上传、在请求参数中的名字为 bptb_pay_file、文件不纳入
20、支付宝的接入签名校验参数。该接口目前只支持一个上传文件。注意文件名是大小写不敏感的，例如a.zip 和 A.zip 认为是同一个文件名。提示 : HTTP 协议中表单的属性 enctype 应该设置为 multipart/form-data 才能把文件上传到服务器端、同时请用 post 的方式来提交表单。为了防止批量付款文件在传输过程中被篡改，建议对批量付款文件进行文件摘要，文件摘要算法支持 MD5 和 SHA。参与摘要的文件要和上传的文件一致，将文件的摘要值赋给 digest_bptb_pay_file，并设置文件摘要算法类型 file_digest_type。批量代发接口说明书共 34 页
21、 第 页3.3. 返回结果返回结果 结果说明ILLEGAL_SERVICE service 参数不正确HAS_NO_PRIVILEGE 没有访问权限ILLEGAL_SIGN 签名不正确ILLEGAL_DIGEST 文件摘要不正确上传成功 上传成功上传失败 : 文件名格式不正确上传失败：重复上传相同的文件上传失败：超过当天上传次数3.4. 付款文件描述3.4.1.文件名格式上传的文件请按照标准的 zip 压缩算法打包成 ZIP 文件、文件名中不能有包含中文zip 文件中只能有一个 csv 类型的付款文件、该付款文件的名字同样不能包含中文.请确保 csv 付款文件的名称不重复csv 的相关标准可以
22、查看 RFC 标准http:/tools.ietf.org/html/rfc4180、请根据该标准来生成文件3.4.2.文件内容格式付款文件中包括两部分信息、一个是汇总信息、一个是明细信息、具体的字段描述如下汇总信息批量代发接口说明书共 34 页 第 页明细信息序号 域名 类型 可空 备注1. 日期 String(8) 付款日期 格式为YYYYMMDD2. 总金额Number(15) 以元为单位、精确到两位小数3. 总笔数 String(8) 一个批次最多 3000 条4. 支付宝账户 String(32) 商户的支付宝账户(email)序号 域名 类型 可空 备注1 商户流水号 String
23、(20) Y 商户的付款流水号、唯一2 收款银行户名 String(32) N 收款银行户名3 收款银行帐号 String(32) N 收款银行帐号4 收款开户银行 String(32) Y 收款开户银行5 收款银行所在省份String(32) Y收款银行所在省份 收款银行所在市 String(32) Y 收款银行所在市 收款支行名称 String(32) Y 收款支行名称 金额 Number(15) N 付款金额，以元为单位、精确到小数两位批量代发接口说明书共 34 页 第 页示例文件 20080708002.csv3.5. 支付宝直连银行 中国建设银行 中国农业银行 中国民生银行 交通银行
24、 上海浦东发展银行 兴业银行 深圳发展银行 中国工商银行 招商银行 广东发展银行其中支持的省（直辖市）的名称只能是下面省（要完全匹配，否则文件校验不通过）“安徽省“ ，“北京市 “， “重庆市“ ，“ 福建省“， “广东省“， “广西自治区“，贵州省“， “海南省“， “河北省“， “黑龙江省“， ”河南省“， “湖北省“ ，“湖南省“ ， “江西省“， “江苏省“， “吉林省“， “辽宁省“， “内蒙古自治区“， ”宁夏自治区“， ”青海省“ ，“ 山东省“， “上海市“， “山西省“， “陕西省“， “四川省“ ， “天津市“， “新疆自治区“， ”三峡“， “云南省“， “浙江省“ ，
25、“大连市“， “宁波市“， “青岛市“， “深圳市“， “厦门市”， ”甘肃省”， ”西藏自治区”。其中支持英文户名的银行有兴业银行、交通银行、中国农业银行、中国民生银行、上海浦东发展银行、深圳发展银行、招商银行、广东发展银行3.6. 付款文件银行信息填写规则主要指：银行名称、开户行所在省份、城市、支行名称四列； 对公对私标志 String(1) 对公-1、对私-2 备注 String(256) Y 记录一些备注信息批量代发接口说明书共 34 页 第 页对私：1、中国建设银行、上海浦东发展银行、交通银行、深圳发展银行、兴业银行、中国民生银行：只需填写银行名称；2、中国工商银行：开户行所在的省份
26、、城市；3、广东发展银行（1）单笔金额在 5 万以下（不含 5 万）：如果未填省市名称，系统会默认填入浙江省和杭州；（2）单笔金额超过 5 万（含 5 万）：银行名称+开户行所在的省份、城市+支行名称；4、招商银行：（1）单笔（当日累计）金额在 50 万以下（不含 50 万）：只需填写银行名称；（2）单笔（当日累计）金额超过 50 万（含 50 万）：银行名称+开户行所在的省份、城市+支行名称；5、中国农业银行：（1） （不含存折）单笔金额在 5 万以下（不含 5 万）：只需填写银行名称；（2） （不含存折）单笔金额超过 5 万（含 5 万）：银行名称+开户行所在的省份、城市+支行名称；（3）
27、存折：银行名称+开户行所在的省份、城市+开户支行名称；6、中国邮政储蓄银行、中国银行：银行名称+开户行所在的省份、城市+支行名称；对公：无论金额多少，需要全部填写（银行名称、开户行所在省份、所在城市、支行名称）请严格按照上述规则填写你的付款文件批量代发接口说明书共 34 页 第 页4. 下载付款结果文件4.1. 接口类型系统调用4.1.1. 请求参数表特别注意：请按照支付宝外部请求接口概述中要求的签名方式，对输入参数进行签名，该接口请求才能够被支付宝系统接收字段名 变量名 类型 说明 可空协议参数接口名称 service String(32)文件类型操作、值为bptb_result_fileN
28、商户 ID partner String（16）商户在支付宝的用户IDN签名 sign String(64)签名串 N签名方式 sign_type String MD5 N字符集 _input_charset String 默认为 gb2312 Y批量代发接口说明书共 34 页 第 页业务参数文件名 file_name String（32）付款文件的文件名 Y查询日期 date String(8)付款文件提交的日期、格式为 YYYYMMDDY业务代号 biz_type String 值为 d_sale Nfile_name 和 date 不能同时为空、 file_name 的查询优先级高根据
29、file_name 查询、如果已经处理则返回对应的付款结果文件、zip 文件根据 date 查询时返回的是一个 zip 压缩文件、文件中包含一个批次处理结果文件以及多个已经处理的付款结果文件4.2. 批次处理结果文件4.2.1.文件名格式文件名格式为 ALIPAY_RESULT. csv4.2.2.文件内容格式汇总信息序号 域名 类型 可空 备注1. 付款日期 String(8) 商户请求的付款日期，格式为 YYYYMMDD批量代发接口说明书共 34 页 第 页明细信息2. 批次数 String(8) 本次查询批次个数3. 已处理批次个数String(8) N支付宝已经处理的批次个数4. 处理
30、中批次个数 String(8) 支付宝处理中的批次个数序号 域名 类型 可空 备注1. 批次名称 String(64) 和上传的付款文件名称一致2. 处理状态String(1) 处理成功、处理失败、处理中 3. 总笔数 String(8) N 本批次总笔数4. 总金额 String(8) Y 总金额5. 处理成功笔数 String(8) Y 处理成功的笔数6. 处理失败笔数 String(8) Y 处理失败的笔数7. 成功付款总金额Number(15) Y成功处理笔数的总金额，以元为单位8. 失败付款总金额Number(15) Y失败处理笔数的总金额，以元为单位9. 处理日期 String(8
31、) Y 付款文件的处理日期10. 支付宝账户String(32) Y商户的支付宝账户批量代发接口说明书共 34 页 第 页示例文件 ALIPAY_RESULT.csv处理结果代码列表如下0000：处理成功1001：批量代发文件格式不正确1002：批量代发文件批次号不存在1003：批量代发文件不存在1004：批量代发文件流水笔数总数和总比数不匹配1005：批量代发文件流水笔数金额与总金额不匹配1006：批量代发文件中 EMAIL 和用户 EMAIL 不匹配1007：解析批量代发文件错误1009: 批量代发文件商户号不存在1010: 文件日期格式不正确（email）11. 备注String(256
32、) Y备注、对于已经处理、但是是失败的情况下可以描述失败原因、比如账户余额不足、文件格式不对。备注前 4 位是结果代码，然后用冒号分割，接着是中文描述。批量代发接口说明书共 34 页 第 页1011: 文件金额格式不正确1012: 批量代发文件日期格式错误1013: 文件中记录条数超过限制1015: 批量代发文件流水信息不正确2001:批量代发文件流水中银行卡省份不符合要求2002:银行卡号长度超过限制2003:银行卡格式不规范3000:支付 宝打款帐户余额不足,请用户在 15 日内给帐户充值,以便支付宝进行批量代发3001:收费帐户不存在3002：支付 宝 收费帐户余额不足,请用户在 15
33、日内给帐户 充值,以便支付宝进行批量代发4000:批量代发流水收费失败4001:批量代发流水解冻收费金额失败4002:等待解冻批量代发流水收费金额5000:申请提现成功5001:申请提现失败6001:批量代发文件状态不正确6002:批量代发文件流水不存在6003:批量代发文件流水状态不正确7000:生成结果文件失败4.3. 付款结果文件描述批量代发接口说明书共 34 页 第 页4.3.1.文件名格式文件名为 ALIPAY_原付款文件名.csv4.3.2.文件内容格式汇总信息明细信息序号 域名 类型 可空 备注1. 付款日期 String(8) 付款日期 格式为YYYYMMDD2. 处理日期St
34、ring(8) 支付宝处理付款的日期，格式为 YYYYMMDD3. 总笔数 String(8) N 本批次总笔数4. 处理成功笔数 String(8) 处理成功的笔数5. 处理失败笔数 String(8) N 处理失败的笔数6. 成功付款总金额Number(15) N总金额，以元为单位，精确到两位小数7. 失败付款总金额Number(15) N失败处理的总金额、以元为单位8. 支付宝账户 String(32) 商户的支付宝账户(email)批量代发接口说明书共 34 页 第 页示例文件ALIPAY_pabx_20080519_s72.csv序号 域名 类型 可空 备注1 商户流水号 Strin
35、g(32) Y 商户的付款流水号、保证唯一2 收款银行户名 String(32) N 总金额3 收款银行帐号 String(32) N 收款银行帐号4 收款开户银行 String(32) N 收款开户银行5 收款银行所在省份String(32) Y收款银行所在省份 收款银行所在市 String(32) Y 请填写正确的市 收款支行名称 String(32) Y 收款支行名称 金额 Number(15) N 付款金额，以元为单位、精确到两位小数 对公对私标志 String(1) 对公-1、对私-210 成功失败标志 String(1) N 成功-S、失败-F11 提现流水号 String(32)
36、 N 支付宝的提现流水号12 是否退票 String(1) N 退票 1，不退票 013 备注 String(256) 记录处理流水信息14 原备注 String(256) Y 商户原文件中的备注批量代发接口说明书共 34 页 第 页5. 下载退票结果文件5.1. 接口类型系统调用5.1.1. 请求参数表特别注意：请按照支付宝外部请求接口概述中要求的签名方式，对输入参数进行签名，该接口请求才能够被支付宝系统接收字段名 变量名 类型 说明 可空协议参数接口名称 service String(32) 文件类型操作、值为bptb_refund_fileN商户 ID partner String(16) 商户在支付宝的用户IDN签名 sign String(64) 签名串 N签名方式 sign_type String MD5 N字符集 _input_charset String 默认为 gb2312 Y业务参数
