即时到账接口开发流程

文档说明

本文档是《即时到账交易接口、纯网关接口、大额信用卡接口、快捷支付前置接口、 快捷支付网关接口、信用卡分期支付接口(create_direct_pay_by_user)》附录文档, 它详细解释了在技术接入与使用过程中需要注意的地方,以帮助商户避免风险产生。 阅读后如有疑问,请联系支付宝相关技术支持。

开发前期准备

查找PID(partner)和密钥（key）

1. 首先查询合作者身份ID和安全校验码KEY；
2. RSA加密方式：公私钥由商户技术人员生成。
   1. 首先生成商户公钥、私钥
   2. 其次上传生成的公钥，同时获取支付宝公钥。

网络环境的要求

1. 支付宝提供的开发环境。
   1. 生产环境。用商户自己的账户做测试。
   2. 沙箱环境。提供资料沙箱环境网关地址、测试账号、密钥。
2. 商户端开发环境：公网可访问的网络环境。

下载接口开发文档及配置开发环境

接口文档获取途径：登陆到支付宝账户产品商店即可下载到对应的接口文档。如所需其他接口文档可以由支付宝技术支持提供。 开发语言：支持C#、PHP、ASP、JAVA四种开发语言。

业务术语

CTU

支付宝风险稽查系统

定向支付

用户事先指定支付金额的收款方，对应的交易只能将金额转入指定的收款方账户中

请求

通过HTTP协议把需要传输的数据发送给接收方的过程

防钓鱼

“网络钓鱼”攻击利用欺骗性的电子邮件和伪造的Web站点来进行诈骗活动，受骗者往往会泄露自己的财务数据，如信用卡号、账户用户名、口令和社保编号等内容，造成损失。防钓鱼用来防止以上情况的发生

分润

分润是指将交易金额中的一部分转账给其它账户

快捷登录

快捷登录产品主要有以下功能： 用户在商户的网站上，可以使用支付宝快捷登录，并共享支付宝的收货地址等物流信息给商户； 如果用户在商户网站上使用了支付宝快捷登录，那么在支付宝支付时，不需要再次在支付宝登录

敏感词

带有敏感政治倾向、暴力倾向、不健康色彩或不文明的词

特殊字符

用做url转义字符，或在接口参数中用作分割符的特殊字符，包括：#、%、&、+、^、|

返回

支付宝根据得到的数据处理完成后，支付宝将处理完成的结果信息反馈给商户网站

开发联调阶段

安全说明

• 使用签约账号进行调试，必须保护合作者身份ID与安全校验码key的隐私性。

  • 防止接口无法正常使用或防止签约的账号信息被盗用，导致资金受损、被他人恶意利用等。

• 测试完毕后，要把测试账号立刻更换成签约账号。

  • 使用测试账号时，手续费按照3%扣除。

• 该接口必须使用https请求

  • 避免请求参数暴露

• 支付宝的通知服务器的出口IP是121.0.26.0/23和110.75.128.0/19，该IP段地址不是商户访问支付宝的地址

  • 如果商户网站设置了IP白名单（即IP过滤），需要把支付宝的通知IP地址加入白名单中。这里面提供的是ip段，需要商户自己算出ip。

• 商户必须以DNS解析的方式访问支付宝接口，不要设置DNS cache，不要绑定支付宝IP。如果为了商户自身安全必须绑定支付宝IP时，必须向支付宝的技术支持人员备案。

  • 支付宝IP地址一旦变更，会导致商户无法请求或访问支付宝，致使商户业务直接不可用

参数说明

• 必须设置请求参数_input_charset（编码格式），即该参数不能为空，并让该参数加入签名运算。

  • 避免接口无法正常使用

• 当设置paymethod（默认支付方式）为directPay（余额支付）时，请求参数defaultbank（默认网银）不要设置或不要传递。

  • 避免该交易按其他支付方式执行

• 只有开通了自定义超时功能，才能使用请求参数it_b_pay（超时时间）。。

  • 避免接口报错误码SELF_TIMEOUT_NOT_SUPPORT

• 只有开通了防钓鱼功能且开通了防钓鱼时间戳，才能使用请求参数anti_phishing_key（防钓鱼时间戳）。

  • 避免接口无法正常使用

• 只有开通了防钓鱼功能且开通了IP地址检查，才能使用请求参数exter_invoke_ip（客户端IP）。

  • 避免接口无法正常使用

• 只有开通了网银支付时是否做CTU校验，才能使用请求参数need_ctu_check（网银支付时是否做CTU校验）。

  • 避免接口无法正常使用

• 只有开通了快捷登录，才能使用请求参数token（授权令牌码），且必须设置token。

  • 减少用户付款时重复登录支付宝

• 请求参数subjet、body的值，以及extend_param、item_orders_info、royalty_parameters的备注表述信息中不要使用敏感词。 |避免接口无法正常使用

• 参数notify_url的设置必须是互联网上能访问到且访问正常的路径地址

  • 避免商户网站无法收到支付宝的主动通知

• 请求参数return_url的设置不能是 http://localhost/ 这类地址，必须是服务器ip地址或者域名方式。（例如: 127.0.0.1 ）

  • 避免付款成功后，当前页面停留在支付宝交易完成提醒页面，而不做任何跳转

• 请求参数return_url的设置不能是含有“!”这类特殊字符的地址 避免付款成功后，当前页面停留在支付宝交易完成提醒页面，而不做任何跳转 royalty_parameters（分润账号集）、extend_param（公用业务扩展参数）参数中的备注描述信息中不能出现用作字段分割符的“^”、“&#124”特殊字符。

  • 避免出现数据格式错误，导致分润失败。

• 当使用了分润功能时，在设置请求参数royalty_parameters（分润账号集）的值时，分润的总金额不能超过付款总金额减去支付宝手续费所余下的金额。

  • 避免分润失败，而导致接口无法正常使用。

• 当使用了分润功能时，在设置请求参数royalty_parameters（分润账号集）的值时，分润的收款账户必须是有效的收款账号。

  • 避免分润失败，而导致接口无法正常使用。

• seller_id（卖家支付宝用户号）、seller_account_name（卖家别名支付宝账号）、seller_email（卖家支付宝账号）不能全部为空，至少有一项不为空。在都不为空的情况下，优先级顺序为：seller_id >seller_account_name >seller_email

  • 数据完整一致，避免出现卖家信息错误。

• 如果设置了买家支付宝账号（如buyer_email等），那么买家支付宝账号不能与卖家支付宝账号相同，即：buyer_emai与seller_email不能相同、buyer_id与seller_id不能相同、buyer_account与seller_account不能相同）。

  • 避免报错，如错误码：BUYER_SELLER_EQUAL。

• price（商品单价）、quantity（购买数量）会替换total_fee（交易金额）。即total_fee不能与price、quantity同时存在；存在price、quantity，就不能存在total_fee。

  • 防止出现支付金额错误

• 在给请求参数defaultbank、paymethod赋值时，需注意区分大小写

  • 否则会引起银行直连调用失败

• 只有开通了纯网关（即网银直连），且paymethod赋值为bankPay时，才有纯网关的效果。如果没有开通，则paymethod禁止赋值为bankPay。

  • 如果没有开通该功能，而又设置了paymethod为bankPay，那么会出现以下两种情况：从来没有开通过，报没有开通该产品的提示错误； 曾经有开通过，交易费率按照纯网关的测试费率3%收取。

• 只有开通了大额信用卡功能，且paymethod=CREDITCARD credit_card_pay=Y credit_card_default_display=Y 如此设置以上3个参数值时，才有大额信用卡的效果

  • 如果没开通该功能，即使paymethod赋值为CREDITCARD也无效，甚至会报没有开通该产品的提示错误。

• 只有开通了信用支付，且paymethod赋值为creditPay时，才有信用支付的效果。

  • 如果没开通该功能，即使paymethod赋值为creditPay也无效，甚至会报没有开通该产品的提示错误。

• 只有开通了信用卡分期，且paymethod赋值为CCIP时，才有信用卡分期的效果。

  • 如果没开通该功能，即使paymethod赋值为CCIP也无效，甚至会报没有开通该产品的提示错误。

• 只有开通了快捷支付前置，且paymethod赋值为motoPay时，才有快捷支付前置的效果。

  • 如果没开通该功能，即使paymethod赋值为motoPay也无效，甚至会报没有开通该产品的提示错误。

• 只有开通了快捷支付网关，且paymethod赋值为以下3个值之一：expressGatewayDebit（快捷支付网关借记卡单通道） expressGatewayCredit（快捷支付网关信用卡单通道） expressGateway（快捷支付网关双通道）且default_login赋值为Y，以上2个参数必须都设置，才有快捷支付网关的效果

  • 如果没开通该功能，即使paymethod赋值为对应的值也无效，甚至会报没有开通该产品的提示错误。

• 如果是etao接入的商户，那么必须设置请求参数error_notify_url和item_orders_info； 如果不是etao接入商户，item_orders_info不要设置。

  • 果没有开通该功能，而又设置了paymethod为bankPay，那么会出现以下两种情况：从来没有开通过，报没有开通该产品的提示错误；曾经有开通过，交易费率按照纯网关的测试费率3%收取。

• 传递请求出错时的通知页面路径error_notify_url（需要联系支付宝开通该参数权限）

  • 方便商户定位接口报错

签名说明

• 请求的所有参数，需要根据参数名=参数值的格式，按首字符字典顺序（ascii值大小）排序，若遇到相同首字符，则判断第二个字符，以此类推，待签名字符串需要以“参数名1=参数值1&参数名2=参数值2&….&参数名N=参数值N”的规则进行拼接。

  • 避免接口无法正常使用

• 在对请求的参数做签名时，这些参数必须来源于请求参数列表，并且除去列表中的参数sign、sign_type。

  • 避免接口无法正常使用

• 在对请求的参数做签名时，对于请求参数列表中那些可空的参数，如果选择使用它们，那么这些参数的参数值必须不能为空或空值。

  • 避免接口无法正常使用

• 签名时将字符转化成字节流时指定的字符集与_input_charset保持一致；如果传递了_input_charset参数，这个参数也应该包含在待签名数据中。

  • 避免接口无法正常使用

• 待签名数据应该是参数原始值而不是url encoding之后的值，例如：调用某接口需要对请求参数email进行数字签名，那么待签名数据应该是[email protected]，而不是email=test%40msn.com。

  • 避免接口无法正常使用

异步通知说明

• 设置了请求参数item_orders_info的情况下，建议使用post方式提交请求。

  • 避免地址栏中地址数据过长，导致传递的数据丢失。

• 支付宝主动发送通知，当商户接收到通知数据后必须给支付宝返回“success”字符串，不允许返回其他多余字符。

  • 如果商户返回给支付宝的信息不是“success”，支付宝最多重复发送8次通知。说明：一旦商户收到异步通知返回了纯字符串success给支付宝，支付宝就不会再发送异步通知，否则会继续按照发送时间发送通知。

• 必须保证设置的通知路径互联网上能访问得到，且访问顺畅。 避

  • 免接收不到支付宝发送的通知

• 必须对返回的所有结果数据进行处理

  • 以便商户能够了解接口的使用情况，以及进行商户的后续业务操作。

• 必须判断发送支付请求以后的业务逻辑处理程序是否有重复执行

  • 防止出现商户的业务操作被重复执行，导致出现资金损失，如重复充值、重复付款等。

• 如果交易付款完成时发送的交易状态是TRADE_SUCCESS（可对交易做其他操作，如退款、分润等），则当超过签约合同指定的可退款时间段时，支付宝会主动发送TRADE_FINISHED（不能对该交易再做任何操作）交易状态。此时，需要根据商户自身业务情况，来判断是否需对这次的交易完成通知进一步处理。

  • 防止出现商户的业务操作被重复执行，导致出现资金损失，如重复充值、重复付款或订单数据错乱等。

• 建议每一次支付操作需以日志形式记录到商户网站的日志操作数据库中

  • 用来在必要时检查或跟踪业务处理情况

验签说明

• 如果有设置通知路径及触发通知条件，则必须使用获取到的参数 notify_id 再次请求支付宝，获取是否是支付宝发送的验证结果。 该请求链接是： https://mapi.alipay.com/gateway.do?partner=合作者身份ID&notify_id=通知ID的值

  • 验证是否是支付宝发来的请求

• 在对通知的参数做签名时，这些参数必须来源于支付宝通知回来的参数，并且除去列表中的参数sign、sign_type，根据参数名=参数值的格式，按首字符字典顺序（ascii值大小）排序，若遇到相同首字符，则判断第二个字符，以此类推，待签名字符串需要以“参数名1=参数值1&参数名2=参数值2&….&参数名N=参数值N”的规则进行拼接，得到的签名结果与获取到的参数sign值做比较。

  • 验证返回的签名

开发完毕，测试验收

接口使用规则

• 接口支持重复调用,前提是交易基本信息(买家、卖家、交易金额、超时时间等)在多次调用中保持一致,且交易尚未完成支付。

  • 防止重复付款以及交易信息被篡改，说明:
    • 如果发现买家不一致、卖家不一致或交易金额不一致,系统会报错不能继续支付;
    • 如果超时时间不一致,则交易状态为等待买家支付,但买家支付时系统会报错。

• 即时到账的优势:快捷,不存在卖家发货、买家确认收货的操作,直接将买家的资金转入卖家的支付宝账号。

  • 即时到账交易主要用于虚拟物品和不存在卖家发货、买家确认收货的交易场景,比如手机话费交易、游戏币充值、网上订餐类网站等。
• 填写买家支付宝账号时,不能与卖家的支付宝账号相同。
  • 避免报错,如错误码:BUYER_SELLER_EQUAL。
• 即时到账交易不允许卖家在交易创建后修改价格
  • 会影响同一笔交易的支付
• 支付宝每一次退款成功,都会向商户的即时到账异步通知地址 notify_url发送一条交易成功的通知,其中状态有 refund_status、refund_success
  • 注意
    • 商户要注意做防订单重复更新的代码处理。
    • 交易关闭的状态不会发送通知,因此当进行全额退款操作时,会出现收不到通知的情况,而在部分退款操作时,能收到即时到账接口的交易通知。解决方案是:商户使用退款接口,把退款的商户业务逻辑程序写到退款接口的通知页面里去,而即时到账接口中不对退款的通知做任何判断。
  • 如果不处理或者处理错误会将商户自己的业务逻辑执行 2 次以上
• 如果商户的一笔交易在退款期限内,没有进行退款操作,则支付宝系统会默认将交易的状态改为“交易完成”(即不可退款模式),并主动发送一条交易状态为trade_finished 的异步通知(可以联系支付宝关闭发送),商户需要根据通知,结合自身业务逻辑做交易不可退款的数据库状态变更。
  • 处理错误会导致商户业务逻辑重复 2 次付款成功
• 本接口支持的众多支付通道中,储蓄卡支付和信用卡支付一旦进入网银系统页面,支付宝将无法控制订单的支付效率问题。
  • 便于做支付渠道区分
• 如果想要买家不安装数字证书也能进行余额支付,商户需要申请开通非证书余额支付功能;否则,买家必须申请安装数字证书才能用支付宝余额支付。
  • 说明:该种情况只有在买家从来没有申请过数字证书的情况下才有效。
  • 保护买家账户安全

平级分润规则

平级分润格式:

收款方 Email_1^金额 1^备注 1|收款方Email_2^金额 2^备注 2

功能效果:

平级分润规则买家付出了交易金额 100 元,同时,金额 1 给了收款方 Email_1,金额 2 给了收款方 Email_2,seller_email 获得剩下的金额(剩下的金额为:100-金额 1-金额 2-支付宝手续费)。

金额计算规则:

• 买家交易金额=金额 1+金额 2+seller_email收款金额+支付宝手续费
• 收款方 Email_1 实际获得金额=金额 1
• 收款方 Email_2 实际获得金额=金额 2
• seller_email 实际获得金额=买家交易金额-金额 1-金额 2-支付宝手续费

多级分润规则

多级分润格式:

收款方 Email_1^金额 1^备注 1|收款方Email_1^收款方 Email_2^金额 2^备注 2

功能效果:

买家付出了交易金额 100 元,同时,金额 1 给了收款方 Email_1,收款方 Email_1 把获得的金额中的金额2给了收款方Email_2,seller_email获得剩下的金额(剩下的金额可以为:100-金额 1-支付宝手续费)。

金额计算规则:

• 买家交易金额=金额 1+seller_email 收款金额+支付宝手续费
• 收款方 Email_1 实际获得金额=金额 1-金额2(金额 1 必须大于等于金额 2)
• 收款方 Email_2 实际获得金额=金额 2 seller_email实际获得金额=买家交易金额-金额 1-支付宝手续费

业务应用注意事项

1. 如果商户签约的是纯网关,那么必须配置请求参数 paymethod 为bankPay,defaultbank 为某家银行简码。
   • 如果没有设置这两个请求参数,那么支付宝就不会按照纯网关的手续费来收取,而 是按照即时到账接口收取费用,导致商户多支出费用。
2. 站内不能关闭交易,只能通过站外接口关闭交易。可通过自定义超时参数实现控制交易关闭时间。
   • 交易订单自定义超时关闭功能
3. 当商户开通了纯网关、大额信用卡、信用卡分期、快捷支付前置、快捷支付网关之中的一个功能时,使用请求参数 defaultbank (默认网银)后,用户付款时支付宝会自动略过网银选择界面。各功能都有自己的网银简码列表,具体请参考接口技术文档的附录部分。
   • 不同功能使用不同的网银简码才能达到网银前置的效果
4. 在快捷支付前置接口中,请求参数default_login 可设置也可不设置;在快捷支付网关接口中,请求参数default_login 必须设置。
5. 一般情况下,异步通知比同步通知慢 3 秒左右。但在网络环境、服务器处理速度等因素影响下,有时异步通知会比同步通知快一些,所以商户需要使用数据库数据锁防止订单重复更新。
6. 支付宝支付手续费扣取模式分为两种:
   1. 实时扣费模式:一般都是收款账户扣费,或采用合同指定固定扣款支付宝账户扣费;
   2. 月结手续费模式:实时交易不扣手续费,月底账单统一结算。
   3. 实时扣费时,在扣费支付宝账号的账务明细中可马上查到扣费记录;但月结模式下,则不会查到。
7. 如果商户请求时传递了extra_common_param参数,支付宝会在同步和异步通知中返回该参数。
   • 支持商户自定义公用回传参数(extra_common_param)
8. 建议商户不要使用类似 js 的window.open、location.replace等没有访问记录的重定向函数跳转到支付网关,强烈建议使用 form 表单提交数据。
   • 规范代码使用规则及减少弹出控件拦截支付(导致支付成功率下降)
9. 在集成接口的过程中,如果商户使用seller_email作为收款账户,则当需要修改该支付宝账户名称时,商户必须在程序中做相应修改,否则在支付过程中会出现卖家账户不存在的错误。推荐使用 seller_id 做为商户收款账户。
   • seller_id 值是支付宝分配给商户的唯一身份 ID,不会改变,使用 seller_id 作为收款账户可以避免 seller_email 变更导致商户无法收款的问题。(可在集成时联系支付宝技术支持获取 seller_id 值。)
10. 卖家发起退款操作后,买家是通过什么渠道付款的,则款项原路退回。比如,买家用的是支付宝账号余额付款,则钱退回到支付宝账号;借记卡付款,则退回借记卡;信用卡付款,则退回信用卡。
    • 买家通过何种渠道付款,则款项原路退回。
11. 不能把接口嵌入 iframe 框架中
    • 避免接口无法正常使用

错误码处理

1. 常见错误码问题,请参见:http://help.alipay.com/support/234878-235357/0-235357.htm?sh=Y&info_type=9
2. 遇到特殊错误码(如:UNKNOWN_EXCEPTION、GENERIC_FAILURE、SYSTEM_ERROR),须暂停后续一切操作,或者联系支付宝技术支持协助处理。
   • 一般这种情况有可能请求已经提交到支付宝,支付宝系统失去响应但有可能由恢复机制自动回复并提交请求。
3. 如果遇到错误码“TRADE_BUYER_NOT_MATC”,表明支付使用的账户与原来的不一致,请使用原来的账户,或重新创建交易付款。
4. 如果遇到错误码“ILLEGAL_FEE_PARAM”,表明交易金额错误,请检查交易金额是否正确。遵循如下规则:
   • 总价和单价不可以同时出现;
   • 如果存在总价,则应该输入商品数量,如果未输入商品数量,系统不报错,默认为1;
   • 如果存在单价,则商品数量必须存在。
5. 如果遇到错误码“TRADE_PRICE_NOT_MATCH”、“TRADE_TOTALFEE_NOT_MATCH”,表明商品价格或总价可能发生了变化,请重新创建交易付款。
6. 如果遇到错误码“FAIL_CREATE_CASHIER_PAY_ORDER”,可能是支付宝收银台系统出现异常,请稍候重试或联系支付宝技术支持协助处理。
7. 错误码“BUYER_EMAIL_ID_MUST_NULL”表示使用纯网关产品时输入了买家账号
8. 错误码“DIRECTIONAL_PAY_FORBIDDEN”表示买家、平台商、卖家、分润方不符合定向支付条件。可能原因:
   • 买家未签署定向支付协议;
   • 买家签署了定向支付协议,但买家、平台商、卖家不符合定向支付条件;或者买家、平台商、分润方不符合定向支付条件
9. 如果交易状态是“TRADE_CLOSED”,可能是交易超时。
10. 如果交易状态出现“TRADE_PENDING”,则表明收款方账号未激活或收款方账号被锁定,请重新登录支付宝激活账号。

责任归属

文档中所涉及到的规则都是根据在接入与使用支付宝接口的过程中出现的一些主 要风险而做的防范措施,请商户予以关注。请在接入及使用支付宝接口的过程中, 严格依照支付宝提供的接口技术文档(即时到账交易接口、纯网关接口、大额信用 卡接口、快捷支付前置接口、快捷支付网关接口、信用卡分期支付接口 (create_direct_pay_by_user).pdf)、代码示例、本文档(即时到账交易接口、纯 网关接口、大额信用卡接口、快捷支付前置接口、快捷支付网关接口、信用卡分期 支付接口(create_direct_pay_by_user)接入与使用规则)等接口资料,否则由此导 致的风险以及资金损失或者扩大情形需商户自行承担。