《AliPay支付宝标准快速付款接口文档(专用纯网关)V151.docx》由会员分享，可在线阅读，更多相关《AliPay支付宝标准快速付款接口文档(专用纯网关)V151.docx（25页珍藏版）》请在三一办公上搜索。
1、纯网关接口文档 副标题：网银直连修订历史版本号作者修订章节修订原因修订日期V1.0技术支持团队全版修改加强文档结构的合理性2008-11-17V1.1甘宁订正部分接口参数和描述信息，例如：即时支付支持错误通知地址（error_notify_url）更新签约接口内容接口升级、增加查询签约接口2009-8-2V1.2甘宁重新整理流程以及文档说明使文档阅读性更强2009-12-8V1.3甘宁增加“公用回传参数”满足用户自定义参数的要求2010-3-18V1.4甘宁通知中增加网银流水满足商户网银支付需求2010-3-29V1.5甘宁请求参数列表支持自定义超时可以使用时间区间2010-9-13V1.5.
2、1甘宁增加4.3.2的信用卡简码信用卡大额支付也支持纯网关2010-10-26说明：本接口将支付宝即时到帐接口用作纯网关的功能做详细介绍。在集成时处理机制和原有支付宝即时到帐一样，请求时必须增加默认支付方式（paymethod）和默认网银（defaultbank）2个参数目录1前言31.1概述31.2术语32接口功能及参数介绍32.1标准即时到账接口（适用于纯网银）32.1.1功能描述32.1.2交互流程42.1.3交互模式42.1.4接口详细说明42.1.5接口注意事项112.1.6接口错误代码列表113签名通用策略133.1安全方面CheckList133.2签名方面133.2.1签名机制
3、133.2.24.2.2签名方式133.3其他方面144附录144.1接口通用机制144.1.1系统调用144.1.2页面跳转144.1.3支付宝主动通知处理流程164.1.4通知验证174.2数字签名构造184.2.1请求参数构造184.3公用枚举表214.3.1通知返回结果枚举214.3.2通用交易状态枚举表214.3.1银行列表224.3.2信用卡大额银行列表234.3.3订单状态列表234.4FAQ（常见问题的的解答）241 前言1.1 概述本接口主要用在外部集成网银直连(纯网关)功能1.2 术语名称说明外部商户、合作伙伴、商户和支付宝进行业务合作的商户通知页参数名称Notify_ur
4、l，所指定的互联网HTTP地址，当代扣完成之后，支付宝发送信息到该页面去，即调用该页面，该页面中的程序自动运行，并判断请求与处理获取到的信息合作伙伴ID签约后，为商家自动分配的唯一编号。分润分润指将某一部分费用分给其它的帐户页面跳转执行操作后跳转到其它页面2 接口功能及参数介绍2.1 标准即时到账接口（适用于纯网银）2.1.1 功能描述调用此接口，根据用户传过来的参数创建交易，买家再付款。目前该接口的交易全部为即时到帐纯网银支付接口，即只要买家一付款，钱就会从买家银行卡转到卖家的支付宝账号。同时该接口还支持分润，商家传过来分润的账号和金额，系统会自动打款到该账号上。2.1.2 交互流程2.1.
5、3 交互模式请求/响应交互模式，页面跳转2.1.4 接口详细说明2.1.4.1 请求参数列表特别注意：a.) 此接口只支持https请求，支付宝是以https进行验证b.) 按照支付宝外部请求接口概述中要求的签名方式，对输入参数进行签名，该接口请求才能够被支付宝系统接收。c.) 本接口支持重复调用，但是提交数据必须一样才可以。d.) 在请求时必须增加默认支付方式和默认网银2个参数字段名变量名类型说明可空协议参数接口名称serviceStringcreate_direct_pay_by_userN合作伙伴IDpartnerString(16)合作伙伴在支付宝的用户ID与支付宝签约后自动生成N通知
6、URLnotify_urlURL（String(190)）针对该交易的交易状态同步通知接收URL。N返回URLreturn_urlURL结果返回URL，仅适用于立即返回处理结果的接口。支付宝处理完请求后，立即将处理结果返回给这个URL。N错误通知地址（需要支付宝功能人员开通）error_notify_urlURL（String(190)）如果在交易过程中出错（如签名错误等），则通过此URL将错误码返回给合作伙伴系统Y签名signString见签名机制，MD5加密算法后得出的结果N签名方式sign_typeString见签名方式，现今默认是MD5加密，无需更改该参数的值N参数编码字符集_inpu
7、t_charsetString（默认为GBK）合作伙伴系统与支付宝系统之间交互信息时使用的编码字符集。合作伙伴可以通过该参数指定使用何种字符集对传递参数进行编码。同时，支付宝系统也会使用该字符集对返回参数或通知参数进行编码。注：该参数必须在queryString中传递，不论使用的是POST还是GET方式发送请求。如：N业务参数商品展示网址show_urlString(400)点击商品链接后跳转的页面Y商品名称subjectString(256)商品的标题N商品描述bodyString(1000)商品的具体描述，如果是多种商品，请将商品描述字符串累加传给bodyY外部交易号out_trade_n
8、oString(64)合作伙伴交易号（确保在合作伙伴系统中唯一）N商品单价priceNumber(13,2)price:单位为RMB Yuan 0.01100000000.00total_fee:单位为RMB Yuan0.01100000000.00quantity:0quantity 0Y交易金额total_feeNumber(13,2)单位为RMB Yuan0.011000000.00Y是否调整总价is_total_fee_adjustString(1)该交易是否调整过价格Y交易创建时间gmt_createTimestamp该笔交易创建的时间Y交易付款时间gmt_paymentTimest
9、amp该交易买家的付款时间Y交易关闭时间gmt_closeTimestamp交易关闭时间Y退款时间gmt_refundTimestamp卖家退款的时间，退款通知时会发送Y公用回传参数extra_common_paramString用于商户回传参数,该值不能包含=&等特殊字符。如果用户请求时传递了该参数，则返回给商户时会回传该参数.Y网银流水号bank_seq_noString(20)开通了纯网关和伪网关的商户，在交易成功后可以返回网银流水。备注：需要支付宝技术支持人员开启Y交易状态信息：交易状态trade_statusString见交易状态枚举表Y退款状态refund_statusString
10、见交易状态枚举表Y买家卖家信息：卖家Emailseller_emailString(100)卖家EmailY卖家IDseller_idString(30)卖家IDY买家IDbuyer_idString(30)买家EmailY买家Emailbuyer_emailString(100)买家IDY是否使用红包use_couponString(1)买家是否在交易过程中使用了红包Y错误通知参数信息（需要在传入参数增加错误通知地址）：错误代码error_codeString(说明接口调用过程中的出错信息N2.1.5 接口注意事项l 您需使用HTTPS 协义, 支付宝是以HTTPS的形式进行通知l 请按照支
11、付宝外部请求接口概述中要求的签名方式，对输入参数进行签名，该接口请求才能够被支付宝系统接收l 该接口支持重复调用，即：一笔订单可以重新支付，但是前提是这笔订单的信息和原来信息一样，否则会报订单号重复l 处理支付宝的返回信息可以异步处理也可以同步处理，前提是防止订单重复接收l 提成数据集：1. 收款方Email_1金额备注|付款方Email收款方Email_2金额备注例如：gwl2510.02分润1|gwl251gwl0610.01分润22. 收款方Email_1金额备注|收款方Email_2金额备注例如：gwl2510.02分润1|gwl0610.01分润23.收款方Email_1金额备注|收
12、款方Email_1收款方Email_2金额备注例如：gwl2510.02分润1|gwl251gwl0610.01分润22.1.6 接口错误代码列表错误代码（error_code）说明ILLEGAL_SIGN签名验证出错ILLEGAL_ARGUMENT参数不正确HAS_NO_PRIVILEGE没有权限访问该服务ILLEGAL_SERVICEService参数不正确ILLEGAL_PARTNER商户ID不正确HAS_NO_PUBLICKEY没有上传公钥USER_NOT_EXIST会员不存在OUT_TRADE_NO_EXIST外部交易号已经存在TRADE_NOT_EXIST交易不存在ILLEGAL_
13、PAYMENT_TYPE无效支付类型，需要联系支付宝技术支持工程师处理BUYER_NOT_EXIST买家不存在SELLER_NOT_EXIST卖家不存在BUYER_SELLER_EQUAL买家、卖家是同一帐户ILLEGAL_SIGN_TYPE签名类型不正确COMMISION_ID_NOT_EXIST佣金收取帐户不存在COMMISION_SELLER_DUPLICATE收取佣金帐户和卖家是同一帐户COMMISION_FEE_OUT_OF_RANGE佣金金额超出范围ILLEGAL_LOGISTICS_FORMAT无效物流格式TOTAL_FEE_LESSEQUAL_ZERO交易总金额小于等于0TOT
14、AL_FEE_OUT_OF_RANGE交易总金额超出范围ILLEGAL_FEE_PARAM非法交易金额格式（参考单价、总价、数量三个组合规则）DONATE_GREATER_THAN_MAX小额捐赠总金额超出最大值限制DIRECT_PAY_AMOUNT_OUT_OF_RANGE快速付款交易总金额超出最大值限制DIGITAL_FEE_GREATER_THAN_MAX虚拟物品交易总金额超出最大值限制SELF_TIMEOUT_NOT_SUPPORT不支持自定义超时COMMISION_NOT_SUPPORT不支持佣金VIRTUAL_NOT_SUPPORT不支持虚拟发货方式ILLEGAL_CHARSET字
15、符集不合法ROYALTY_SELLER_ENABLE_STATUS_FORBID有提成情况下，卖家状态不正常ROYALTY_SELLER_NOT_CERTIFY有提成情况下，卖家未通过认证ROYALTY_FORAMT_ERROR提成信息错误，请检查后重新集成ROYALTY_TYPE_ERROR提成类型不支持，请检查后重新集成ROYALTY_PAY_EMAIL_NOT_EXIST提成付款帐户不存在ROYALTY_RECEIVE_EMAIL_NOT_EXIST提成收款帐户不存在DEFAULT_BANK_MUST_NOT_NULL默认网银不能为空LLEGAL_PAYMENT_TYPE错误的Payme
16、nt_type参数ILLEGAL_OUTTIME_ARGUMENT自定义超时参数错误CANT_CREDIT_PAY不能使用信用支付TRADE_NOT_ALLOWED_PAY交易不允许付款NAVIGATION_INCOME_OF_ROYALTY_ACCOUNT在提成情况下的多级分润，二次分润帐户次序问题或者分润时没有预留支付宝服务费3 签名通用策略3.1 安全方面CheckLista 从集成后的系统健壮性考虑，收到支付宝发出的通知后，合作伙伴系统须判断接收到的交易状态、交易金额是否与自己系统中的参数对应，并处理这些数据信息，使网站内的交易信息与支付宝内的交易信息保持一致，可防止掉单情况出现。如果
17、不判断，存在潜在的风险，合作伙伴自行承担因此而产生的所有损失。3.2 签名方面3.2.1 签名机制a 没有值的参数无需传递，也无需包含到待签名数据中。b 签名时将字符转变成字节流时指定的字符集要与_input_charset保持一致。c 如果传递了_input_charset参数，那么这个参数也应该包含在待签名数据中。d 根据HTTP协议要求，传递参数的值中如果存在特殊字符（如：&、等），那么该值需要做URL Encoding，这样请求接受方才能接受到正确的参数值。这种情况下，做签名时使用的应该是原生值而不是encoding之后的值。例如：会员查询接口示例中待签名数据是email=test&p
18、artner=2088006300000000&service=test，而不是email=test%&partner=2088006300000000&service=test。3.2.2 4.2.2签名方式按照sign_type参数指定的签名算法对待签名数据进行签名【参见：数字签名构造】3.3 其他方面1) 您必需使用HTTPS 协义, 支付宝是以HTTPS的形式进行通知2) 请按照支付宝外部请求接口概述中要求的签名方式，对输入参数进行签名，该接口请求才能够被支付宝系统接收3) 如果设置了notify_url，支付宝会发一条通知到notify_url对应的站点4) 通知URL不要如此设置：
19、4 附录4.1 接口通用机制4.1.1 系统调用顾名思义，这类接口是为合作伙伴系统获得支付宝系统信息提供服务的，是一种系统间的调用接口。 系统调用示意图4.1.2 页面跳转顾名思义，这类接口都是一些有页面操作的接口。通常是用户在合作伙伴页面执行部分操作，然后跳转到支付宝系统记录订单信息及时再转入网银系统页面完成整个操作。有的甚至可能最后还要再跳回到合作伙伴的下一个页面，继续完成整个操作。根据处理结果的返回方式，又分为：n 立即返回处理结果，即用户在网银系统页面完成操作后，支付宝将处理结果立即返回给合作伙伴的下一步操作页面，让用户继续完成真个操作流程。所以，调用这类接口时，必须传递参数retur
20、n_url（即合作伙伴的下一个操作页面）。立即返回（页面跳转）示意图n 异步返回处理结果，即用户从合作伙伴页面跳转到网银支付页面后（支付宝先做记录），在网银系统完成最后操作，用户不用再回到合作作伙伴页面。这类接口通常是通过通知接口异步获得处理结果。如果需要异步返回结果，那么必须传递notify_url参数，以指定通知返回的地址。如果不需要异步返回结果，那么可以不用传递notify_url参数。（具体流程可以参考：支付宝主动通知处理流程） 页面跳转（通过通知接口返回结果）示意图4.1.3 支付宝主动通知处理流程1.支付宝平台系统向外部商户系统发出通知，即访问外部商户提供的通知接收URL（参数no
21、tify_url）。2.外部商户系统接到通知请求，通过notify_id询问支付宝平台系统这个通知的真实性,通知验证。3.支付宝平台系统判断通知是否是自己发送，如果是返回true，否则返回false。4.商户系统得到支付宝平台系统的确认后，对通知进行处理。处理完毕后，返回结果给支付宝平台系统，处理结果的值见附件：通知返回结果枚举。5.支付宝平台系统处理商户系统返回的处理结果。4.1.4 通知验证从系统健康性角度考虑，在接收到支付宝平台系统通知以后，验证支付宝的系统通知的正确性（合法性）是非常有必要的。强烈建议外部商户系统加入此应用。 了保证该接口被合法利用，商户系统只能查找1分钟之内（目前为1
22、分钟，以后若有调整，恕不另行通知）的通知。 传递的参数格式：通知验证字段名变量名类型说明可空样例接口名称serviceStringcustomer_unsignNtrade_status_sync外部商户partnerString(16)外部商户在支付宝的用户IDN通知IDnotify_idString支付宝发送的通知IDN 基于HTTPS协议的通知验证接口程序在使用时按照以下要求发起一个HTTPS请求，获取该请求的结果即可，所有可能出现的结果见以下的输出参数表，这种验证通知的方式需要网站支持HTTPS访问，若网站不支持https的访问，可以使用另外一种验证方式：基于HTTP协议的通知验证接口
23、。接入URL：一个完整的验证请求实例： &partner=1234567890¬ify_id=abcdefghijklmnopqrst 基于HTTP协议的通知验证接口程序在使用时按照以下要求发起一个HTTP请求，获取该请求的结果即可，所有可能出现的结果见以下的输出参数表。接入URL：一个完整的验证请求实例：通知验证接口输出参数：输出内容说明可能的原因invalid传入的参数无效查找参数格式true验证通过false验证失败查找是否由于sign和mysign不相等引起的1分钟内失效的问题4.2 数字签名构造4.2.1 请求参数构造为了确保数据传输过程中的数据真实性和完整性，我们需要对数据进
24、行签名校验。HTTP请求中传递的所有参数(除sign和sign_type以外)按照参数名称字符升序的顺序串联起来（如：p1=v1&p2=v2&p3=v3），构成待签名数据。按照sign_type指定的方式对待签名数据进行签名。例如：调用某接口需要以下参数：service=cae_charge_agentpartner=2088006300000000email=test那么待签名数据就是：email=test&partner=2088006300000000&service= cae_charge_agent。4.2.1.1 签名算法对比 算法功能MD5DSARSA防篡改防抵赖加密电子签名法是
25、否承认4.2.1.2 MD5算法构造定义：MD5是一种摘要生成算法，本来是不能用于签名的。但是，通过在待签名数据之后加上一串私密内容（指令发送、接收双发事先规定好的，这里我们称其为签名密钥），就可以用于签名了。使用这种算法签名只能起到防数据篡改的功能，不能起到签名防抵赖的功能，因为双方都知道签名密钥例如：待签名数据 + securityCode值（支付宝为合作伙伴颁发的安全校验码）的MD5摘要作为签名。例如：安全校验码是mysecurityCode，那么前面会员查询接口示例的待签名数据就是：email=test&partner=2088006300000000&service=user_que
26、rymysecurityCode。4.2.1.3 DSA算法构造定义：DSA是一种非对称的签名算法，即签名密钥（私钥）与验签名密钥（公钥）是不一样的，私钥用于签名，公钥用于验签名。使用这种算法签名在起到防数据篡改功能的同时，还可以起到防抵赖的作用，因为私用只有签名者知道。例如：合作伙伴发送请求时，使用自己的密钥对待签名数据进行DSA签名，支付宝使用合作伙伴的公钥进行校验；支付宝返回数据时，使用支付宝的密钥对待签名数据进行DSA签名，合作伙伴使用支付宝的公钥进行校验。DSA公私钥可以使用OpenSSL生成，如下：1 生成DSA参数openssl dsaparam -out dsa_param.p
27、em 10242 生成私钥opensslgendsa -out dsa_private_key.pem dsa_param.pem3 生成公钥openssl dsa -in dsa_private_key.pem -pubout -out dsa_public_key.pem4.2.1.4 RSA算法构造定义：RSA也是一种非对称算法，同时，它还是一种加密算法，使用方法跟DSA签名算法类似1 RSA密钥生成命令生成RSA私钥openssl genrsa -out rsa_private_key.pem 1024生成RSA公钥openssl rsa -in rsa_private_key.pem
28、 -pubout -out rsa_public_key.pem将RSA私钥转换成PKCS8格式openssl pkcs8 -topk8 -inform PEM -in rsa_private_key.pem -outform PEM -nocrypt 2 签名/验签名命令RSA签名openssl sha1 -sign rsa_private_key.pem -out rsasign.bin plaintext.txtRSA验签名openssl sha1 -verify rsa_public_key.pem -signature rsasign.bin plaintext.txt4.3 公用枚
29、举表4.3.1 通知返回结果枚举 返回结果结果说明success处理成功，结束发送fail处理失败，重新发送（支付宝平台系统会在24小时内分6-10次发送客户信息，直到接受到外部商户发送的success）注意：不能包含任何其他的HTML脚本语言，否则支付宝接受数据会收到影响4.3.2 通用交易状态枚举表A正常交易状态枚举：交易状态列表值（变量值：trade_status）说明WAIT_BUYER_PAY交易创建TRADE_FINISHED支付成功，标准即时到账成功状态TRADE_SUCCESS支付成功，机票行业单笔退款成功（没有全部退完）TRADE_CLOSED交易关闭B退款交易状态枚举：状态
30、代码（变量值：refund_status）状态名称REFUND_SUCCESS 退款成功REFUND_CLOSED退款关闭备注：如果在支付宝平台操作退款，交易状态（trade_status）会出现2中情况：1. 不是全额退款，交易成功状态变成TRADE_SUCCESS，增加一个退款状态refund_status= REFUND_SUCCESS2. 全额退款，交易成功状态变成TRADE_CLOSED，增加一个退款状态refund_status= REFUND_SUCCESS。4.3.1 银行列表银行简码银行名称ICBCBTB中国工商银行(B2B)ABCBTB中国农业银行(B2B)SPDBB2B上
31、海浦东发展银行(B2B)CCBB2B中国建设银行(B2B)BOCB2C中国银行ICBCB2C中国工商银行CMB招商银行CCB中国建设银行ABC中国农业银行SPDB上海浦东发展银行CIB兴业银行GDB广东发展银行SDB深圳发展银行CMBC中国民生银行COMM交通银行CITIC中信银行HZCBB2C杭州银行CEBBANK中国光大银行SHBANK上海银行NBBANK宁波银行SPABANK平安银行bjbank101北京农村商业银行备注：如果没有需要网银简码，可以询问支付宝技术支持工程师，更多网银更新中。4.3.1 纯借记卡银行列表银行简码银行名称CMB-DEBIT招商银行CCB-DEBIT中国建设银行ICBC-DEBIT中国工商银行COMM-DEBIT交通银行GDB-DEBIT广东发展银行BOC-DEBIT中国银行CEB-DEBIT中国光大银行SPDB-DEBIT上海浦东发展银行PSBC-DEBIT中国邮政储蓄银行备注：其他银行陆续增加中。4.3.2 信用卡大额银行列表银行简码银行名称icbc301中国工商银行ccb301中国建设银行cmb301招商银行boc30
