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

《支付宝商户接口及技术文档.doc》由会员分享，可在线阅读，更多相关《支付宝商户接口及技术文档.doc（34页珍藏版）》请在三一办公上搜索。

1、商家与支付宝接口:批量代发浙江支付宝网络科技有限公司产品技术及用户体验部2007年12月目 录商家与支付宝接口:1批量代发1目 录21.总述42.支付宝对外接口技术52.1.支付宝对外接口概述52.2.支付宝外部接入接口52.2.1.接入URL52.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.文件名格式1

2、93.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

3、.1. 支付宝对外接口概述支付宝对外接口分为两种，一种是接受外部请求的接口，我们统称为外部服务接口。一种是主动通知外部系统的接口，我们统称为外部通知接口。外部服务接口的主要目的是让外部商户主动使用我们的服务，如：创建交易等。外部通知接口的主要目的是为外部商户提供数据同步服务（如：交易状态同步）以及异步处理结果返回服务（有些业务的处理是无法做到即时返回的）。2.2. 支付宝外部接入接口2.2.1. 接入URL2.2.2. 接入方式POST/GET方式2.2.3. 接入类型l 系统调用顾名思义，这类接口是为商户系统获得支付宝系统信息提供服务的，是一种系统间的调用接口。 系统调用示意图l 页面跳转顾

4、名思义，这类接口都是一些有页面操作的接口。通常是用户在商户页面执行部分操作，然后跳转到支付宝页面完成整个操作。有的甚至可能最后还要再跳回到商户的下一个页面，继续完成整个操作。根据处理结果的返回方式，又分为：n 立即返回处理结果，即用户在支付宝页面完成操作后，支付宝将处理结果立即返回给商户的下一步操作页面，让用户继续完成整个操作流程。所以，调用这类接口时，必须传递参数return_url（即商户的下一个操作页面）。 立即返回（页面跳转）示意图n 异步返回处理结果，即用户从商户页面跳转到支付宝页面后，在支付宝完成最后操作，用户不用再回到合作作伙伴页面。这类接口通常是通过通知接口异步获得处理结果。如

5、果需要异步返回结果，那么必须传递notify_url参数，以指定通知返回的地址。如果不需要异步返回结果，那么可以不用传递notify_url参数。 页面跳转（通过通知接口返回结果）示意图2.2.4. 接入参数接入参数由协议参数和业务参数共同组成，业务接口中会介绍每个业务接口的输入/输出参数。2.2.4.1. 协议参数协议参数字段名称变量名说明接口名称service外部接口名称商户IDpartner商户在支付宝的用户ID通知URLnotify_url通知返回URL,仅适用于异步返回处理结果的接口。有些服务是无法立即返回处理结果的，那么需要通过这个URL将处理结果异步返回给商户。（见外部通知接口概

6、述）返回URLreturn_url结果返回URL，仅适用于立即返回处理结果的接口。支付宝处理完请求后，立即将处理结果返回给这个URL。代理商IDagent如果一些交易网站的交易，有一定的“代理”所属关系，代理商可以在交易中传递该参数，来表明代理的身份。这里传送的值，请使用代理商所属支付宝账户的PartnerID。文件摘要digest_上传文件名用于标识上传文件的摘要值;多个文件对应会有多个参数；如请求参数中存在digest_upload_file参数时、表示存在一个上传文件、其在请求中的参数名是upload_file、其摘要值是参数digest_upload_file的值文件摘要算法file_

7、digest_type支持MD5和SHA 建议使用MD5签名类型sign_type见签名方式参数编码字符集_input_charset商户系统与支付宝系统之间交互信息时使用的编码字符集。商户可以通过该参数指定使用何种字符集对传递参数进行编码。同时，支付宝系统也会使用该字符集对返回参数或通知参数进行编码。业务参数（见后续章节）参数编码字符集参数使用事例：POST请求：GET请求：2.2.5. 参数签名机制为了确保数据传输过程中的数据真实性和完整性，我们需要对数据进行签名校验。HTTP请求中传递的所有参数(除sign和sign_type以外)按照参数名称字符升序的顺序串联起来（如：p1=v1&p2

8、=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 根据

9、HTTP协议要求，传递参数的值中如果存在特殊字符（如：&、等），那么该值需要做URL Encoding，这样请求接受方才能接受到正确的参数值。这种情况下，请注意做签名时使用的应该是原生值而不是encoding之后的值。例如：会员 查询接口示例中待签名数据是email=test&partner=2088006300000000&service=test，而不是email=test%&partner=2088006300000000&service=test。2.2.6. 签名方式说明MD5待签名数据 + securityCode值（支付宝为商户颁发的安全校验码）的MD5摘要作为签名。例如：安全校

10、验码是mysecurityCode，那么前面会员查询接口示例的待签名数据就是：email=test&partner=2088006300000000&service=user_querymysecurityCode。DSA商户发送请求时，使用自己的密钥对待签名数据进行DSA签名，支付宝使用商户的公钥进行校验；支付宝返回数据时，使用支付宝的密钥对待签名数据进行DSA签名，商户使用支付宝的公钥进行校验。DSA公私钥可以使用OpenSSL生成，如下：1. 生成DSA参数openssl dsaparam -out dsa_param.pem 10242. 生成私钥openssl gendsa -out

11、 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. 支付宝系统向外部系统发出通知，即访问商户提供的通知接收URL。2. 外部系统接到通知请求，通过notify_id询问支付宝这个通知的真实性，见通知验证接口。3.

12、 支付宝系统判断通知是否是自己发送，如果是返回true，否则返回false。4. 商户系统得到支付宝系统的确认后，对通知进行处理。处理完毕后，返回结果给支付宝系统。5. 支付宝系统处理商户系统返回的处理结果。2.3.2. 通知参数接入参数由协议参数和业务参数共同组成，业务接口中会介绍每个业务接口的输入/输出参数。字段名称变量名类型说明可否为空协议参数通知类型notify_typeString通知类型，如：trade_status_sync，表示交易状态同步通知。境外收单取值为：forex_trade_status_syncN通知IDnotify_idString支付宝通知流水号，商户可以用这个

13、流水号询问支付宝该条通知的合法性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

14、或fsockopen函数，JAVA可以使用httpClient或.HttpURLConnection。字段名称变量名类型说明可否为空接口名称serviceStringnotify_verifyN商户IDpartnerString(16)商户在支付宝的用户IDN通知IDnotify_idString支付宝发送的通知IDN特别提醒：上述接口是用来校验支付宝所发出通知的真实性，需要网站支持HTTPS访问。若网站不支持https的访问，可以采用如下接口：2.3.3.2. HTTP通知验证接口 接入URL： 一个完整的验证请求例子：程序在使用时需按以上要求发起一个HTTP请求，获取该请求的结果即可，所有

15、可能出现的结果见以下的输出参数表。ASP可以使用XMLHTTP，PHP可以使用fopen或fsockopen函数，JAVA可以使用httpClient或.HttpURLConnection。字段名称变量名类型说明可否为空商户IDpartnerString(16)商户在支付宝的用户IDN通知IDnotify_idString支付宝发送的通知IDN2.3.3.3. 通知验证接口输出参数输出内容说明invalid传入的参数无效true验证通过false验证失败提醒1：为了保证该接口被合法利用，商户系统只能查找1分钟之内（目前为1分钟，以后若有调整，恕不另行通知）的通知。提醒2：从系统健康性角度考虑，

16、在接收到支付宝系统通知以后，使用上述的通知验证接口验证支付宝系统通知的正确性（合法性）是非常有必要的。支付宝强烈建议您在系统中加入上述的应用。3. 上传付款文件3.1. 接口类型系统调用3.2. 请求参数表特别注意：请按照支付宝外部请求接口概述中要求的签名方式，对输入参数进行签名，该接口请求才能够被支付宝系统接收。变量名类型说明可空协议参数接口名称serviceString(32)文件类型操作、值为bptb_pay_fileN商户IDpartnerString(16)商户在支付宝的用户IDN文件摘要digest_bptb_pay_fileString(64)上传付款文件的摘要值N文件摘要算法f

17、ile_digest_typeString MD5或SHAN签名signString(64)签名串N签名方式sign_typeStringMD5N业务类型biz_typeString值为d_saleN字符集_input_charsetString默认为gb2312Y业务类型 bussiness_typeString当bussiness_type为“T0”的时候表示要使用T+0服务，为其他值，或者没有该字段的时候表示T+1服务。Y付款文件作为附件上传、在请求参数中的名字为bptb_pay_file、文件不纳入支付宝的接入签名校验参数。该接口目前只支持一个上传文件。注意文件名是大小写不敏感的，例如

18、a.zip和A.zip认为是同一个文件名。提示 : HTTP协议中表单的属性enctype应该设置为multipart/form-data才能把文件上传到服务器端、同时请用post的方式来提交表单。为了防止批量付款文件在传输过程中被篡改，建议对批量付款文件进行文件摘要，文件摘要算法支持MD5和SHA。参与摘要的文件要和上传的文件一致，将文件的摘要值赋给digest_bptb_pay_file，并设置文件摘要算法类型file_digest_type。3.3. 返回结果返回结果结果说明ILLEGAL_SERVICEservice参数不正确HAS_NO_PRIVILEGE没有访问权限ILLEGAL_

19、SIGN签名不正确ILLEGAL_DIGEST文件摘要不正确上传成功上传成功上传失败 : 文件名格式不正确上传失败：重复上传相同的文件上传失败：超过当天上传次数3.4. 付款文件描述3.4.1. 文件名格式上传的文件请按照标准的zip压缩算法打包成ZIP文件、文件名中不能有包含中文zip文件中只能有一个csv类型的付款文件、该付款文件的名字同样不能包含中文.请确保csv付款文件的名称不重复csv的相关标准可以查看RFC标准http:/tools.ietf.org/html/rfc4180、请根据该标准来生成文件3.4.2. 文件内容格式付款文件中包括两部分信息、一个是汇总信息、一个是明细信息、

20、具体的字段描述如下汇总信息序号域名类型可空备注1.日期String(8)付款日期 格式为YYYYMMDD2.总金额Number(15)以元为单位、精确到两位小数3.总笔数String(8)一个批次最多3000条4.支付宝账户String(32)商户的支付宝账户(email)明细信息序号域名类型可空备注1商户流水号String(20)Y商户的付款流水号、唯一2收款银行户名String(32)N收款银行户名3收款银行帐号String(32)N收款银行帐号4收款开户银行String(32)Y收款开户银行5收款银行所在省份String(32)Y收款银行所在省份收款银行所在市String(32)Y收款银

21、行所在市收款支行名称String(32)Y收款支行名称金额Number(15)N付款金额，以元为单位、精确到小数两位对公对私标志String(1)对公-1、对私-2备注String(256)Y记录一些备注信息示例文件 3.5. 支付宝直连银行l 中国建设银行l 中国农业银行l 中国民生银行l 交通银行l 上海浦东发展银行l 兴业银行l 深圳发展银行l 中国工商银行l 招商银行l 广东发展银行其中支持的省（直辖市）的名称只能是下面省（要完全匹配，否则文件校验不通过）安徽省 ，北京市， 重庆市 ，福建省， 广东省， 广西自治区，贵州省， 海南省， 河北省， 黑龙江省，”河南省， 湖北省 ，湖南省，

22、 江西省， 江苏省， 吉林省， 辽宁省， 内蒙古自治区，”宁夏自治区，”青海省 ，山东省， 上海市， 山西省， 陕西省， 四川省， 天津市， 新疆自治区，”三峡， 云南省， 浙江省， 大连市， 宁波市， 青岛市， 深圳市， 厦门市”，”甘肃省”，”西藏自治区”。其中支持英文户名的银行有兴业银行、交通银行、中国农业银行、中国民生银行、上海浦东发展银行、深圳发展银行、招商银行、广东发展银行3.6. 付款文件银行信息填写规则主要指：银行名称、开户行所在省份、城市、支行名称四列；对私：1、中国建设银行、上海浦东发展银行、交通银行、深圳发展银行、兴业银行、中国民生银行：只需填写银行名称；2、中国工商银行

23、：开户行所在的省份、城市；3、广东发展银行（1）单笔金额在5万以下（不含5万）：如果未填省市名称，系统会默认填入浙江省和杭州；（2）单笔金额超过5万（含5万）：银行名称+开户行所在的省份、城市+支行名称；4、招商银行：（1）单笔（当日累计）金额在50万以下（不含50万）：只需填写银行名称；（2）单笔（当日累计）金额超过50万（含50万）：银行名称+开户行所在的省份、城市+支行名称；5、中国农业银行：（1）（不含存折）单笔金额在5万以下（不含5万）：只需填写银行名称；（2）（不含存折）单笔金额超过5万（含5万）：银行名称+开户行所在的省份、城市+支行名称；（3）存折：银行名称+开户行所在的省份、

24、城市+开户支行名称；6、中国邮政储蓄银行、中国银行：银行名称+开户行所在的省份、城市+支行名称；对公：无论金额多少，需要全部填写（银行名称、开户行所在省份、所在城市、支行名称）请严格按照上述规则填写你的付款文件4. 下载付款结果文件4.1. 接口类型系统调用4.1.1. 请求参数表特别注意：请按照支付宝外部请求接口概述中要求的签名方式，对输入参数进行签名，该接口请求才能够被支付宝系统接收字段名变量名类型说明可空协议参数接口名称serviceString(32)文件类型操作、值为bptb_result_fileN商户IDpartnerString（16）商户在支付宝的用户IDN签名signStr

25、ing(64)签名串N签名方式sign_typeStringMD5N字符集_input_charsetString默认为gb2312Y业务参数文件名file_name String（32）付款文件的文件名Y查询日期dateString(8)付款文件提交的日期、格式为YYYYMMDDY业务代号biz_typeString值为d_saleNfile_name和date不能同时为空、file_name的查询优先级高根据file_name查询、如果已经处理则返回对应的付款结果文件、zip文件根据date查询时返回的是一个zip压缩文件、文件中包含一个批次处理结果文件以及多个已经处理的付款结果文件4.2

26、. 批次处理结果文件4.2.1. 文件名格式文件名格式为ALIPAY_RESULT. csv4.2.2. 文件内容格式汇总信息序号域名类型可空备注1.付款日期String(8)商户请求的付款日期，格式为YYYYMMDD2.批次数String(8)本次查询批次个数3.已处理批次个数String(8)N支付宝已经处理的批次个数4.处理中批次个数String(8)支付宝处理中的批次个数 明细信息序号域名类型可空备注1.批次名称String(64)和上传的付款文件名称一致2.处理状态String(1)处理成功、处理失败、处理中 3.总笔数String(8)N本批次总笔数4.总金额String(8)Y总

27、金额5.处理成功笔数String(8)Y处理成功的笔数6.处理失败笔数String(8)Y处理失败的笔数7.成功付款总金额Number(15)Y成功处理笔数的总金额，以元为单位8.失败付款总金额Number(15)Y失败处理笔数的总金额，以元为单位9.处理日期String(8)Y付款文件的处理日期10.支付宝账户String(32)Y商户的支付宝账户（email）11.备注String(256)Y备注、对于已经处理、但是是失败的情况下可以描述失败原因、比如账户余额不足、文件格式不对。备注前4位是结果代码，然后用冒号分割，接着是中文描述。示例文件 处理结果代码列表如下0000：处理成功1001：

28、批量代发文件格式不正确1002：批量代发文件批次号不存在1003：批量代发文件不存在1004：批量代发文件流水笔数总数和总比数不匹配1005：批量代发文件流水笔数金额与总金额不匹配1006：批量代发文件中EMAIL和用户EMAIL不匹配1007：解析批量代发文件错误1009: 批量代发文件商户号不存在1010: 文件日期格式不正确1011: 文件金额格式不正确1012: 批量代发文件日期格式错误1013: 文件中记录条数超过限制1015: 批量代发文件流水信息不正确2001:批量代发文件流水中银行卡省份不符合要求2002:银行卡号长度超过限制2003:银行卡格式不规范3000:支付宝打款帐户余

29、额不足,请用户在15日内给帐户充值,以便支付宝进行批量代发3001:收费帐户不存在3002：支付宝收费帐户余额不足,请用户在15日内给帐户充值,以便支付宝进行批量代发4000:批量代发流水收费失败4001:批量代发流水解冻收费金额失败4002:等待解冻批量代发流水收费金额5000:申请提现成功5001:申请提现失败6001:批量代发文件状态不正确6002:批量代发文件流水不存在6003:批量代发文件流水状态不正确7000:生成结果文件失败4.3. 付款结果文件描述4.3.1. 文件名格式文件名为 ALIPAY_原付款文件名.csv4.3.2. 文件内容格式汇总信息序号域名类型可空备注1.付款日

30、期String(8)付款日期 格式为YYYYMMDD2.处理日期String(8)支付宝处理付款的日期，格式为YYYYMMDD3.总笔数String(8)N本批次总笔数4.处理成功笔数String(8)处理成功的笔数5.处理失败笔数String(8)N处理失败的笔数6.成功付款总金额Number(15)N总金额，以元为单位，精确到两位小数7.失败付款总金额Number(15)N失败处理的总金额、以元为单位8.支付宝账户String(32)商户的支付宝账户(email) 明细信息序号域名类型可空备注1商户流水号String(32)Y商户的付款流水号、保证唯一2收款银行户名String(32)N总

31、金额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) N支付宝的提现流水号12是否退票String(1) N退票1，不退票0 13备注String(256)记录处理流水信息14原备注String(2

32、56)Y商户原文件中的备注示例文件5. 下载退票结果文件5.1. 接口类型系统调用5.1.1. 请求参数表特别注意：请按照支付宝外部请求接口概述中要求的签名方式，对输入参数进行签名，该接口请求才能够被支付宝系统接收字段名变量名类型说明可空协议参数接口名称serviceString(32)文件类型操作、值为bptb_refund_fileN商户IDpartnerString(16)商户在支付宝的用户IDN签名signString(64)签名串N签名方式sign_typeStringMD5N字符集_input_charsetString默认为gb2312Y业务参数查询日期dateString(8)

33、付款文件提交的日期、格式为YYYYMMDDN业务代号biz_typeString固定值为d_saleN5.2. 退票文件5.2.1. 文件名格式文件名格式为ALIPAY_YYYYMMDD_R.csv5.2.2. 文件内容格式汇总信息序号域名类型可空备注1总金额Number(15)N退票总金额、以元为单位、精确到两位小数 2总笔数String（8）N退票总笔数、范围在3000笔内 3支付宝账户String（32）商户的支付宝账户(email) 明细信息序号域名类型可空备注1商户批次号String（32）N商户的上传付款文件的批次号2商户流水号String（32）N原付款文件中商户提供的流水号3收

34、款银行户名String(32)N收款银行户名4收款银行帐号String(32)N收款银行帐号5收款开户银行String(32)N收款开户银行6收款银行所在省份String(32)Y收款银行所在省份7收款银行所在市String(32)Y收款银行所在市8收款支行名称String(32)收款支行名称9金额Number(15)N付款金额，以元为单位、精确到两位小数10对公对私标志String(1)对公-1、对私-211备注String(256)Y备注12提现流水号String(32) N支付宝的提现流水号 13退票日期String(8)N退票日期、格式为YYYYMMDD 14退票原因String(256) Y 退票原因示例文件 退票文件的返回同样以zip的方式返回6. 各银行错误描述附录。 详情见附录。