商家帮助中心 > 技术支持 > 技术文档 > 即时到帐

即时到账接口开发流程

【字号：大 中 小】【打印】【收藏】

一、开发前期准备

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

a、首先查询合作者身份ID和安全校验码KEY；
b、RSA加密方式：公私钥由商户技术人员生成。
（1）首先生成商户公钥、私钥
（2）其次上传生成的公钥，同时获取支付宝公钥。
1.2、网络环境的要求
1.2.1、支付宝提供的开发环境。
 （1）.生产环境。用商户自己的账户做测试。
 （2）.沙箱环境。提供资料沙箱环境网关地址、测试账号、密钥。
1.2.2、商户端开发环境：公网可访问的网络环境。

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

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

1.4、业务术语

术语 解释
CTU 支付宝风险稽查系统
定向支付 用户事先指定支付金额的收款方，对应的交易只能将金额转入指定的收款方账户中
请求 通过HTTP协议把需要传输的数据发送给接收方的过程
防钓鱼 “网络钓鱼”攻击利用欺骗性的电子邮件和伪造的Web站点来进行诈骗活动，受骗者往往会泄露自己的财务数据，如信用卡号、账户用户名、口令和社保编号等内容，造成损失。防钓鱼用来防止以上情况的发生
分润 分润是指将交易金额中的一部分转账给其它账户
快捷登录 快捷登录产品主要有以下功能： 用户在商户的网站上，可以使用支付宝快捷登录，并共享支付宝的收货地址等物流信息给商户； 如果用户在商户网站上使用了支付宝快捷登录，那么在支付宝支付时，不需要再次在支付宝登录
敏感词 带有敏感政治倾向、暴力倾向、不健康色彩或不文明的词
特殊字符 用做url转义字符，或在接口参数中用作分割符的特殊字符，包括：#、%、&、+、^、|
返回 支付宝根据得到的数据处理完成后，支付宝将处理完成的结果信息反馈给商户网站

二、开发联调阶段

2.1、安全说明

类型  细则  原因 
安全  使用签约账号进行调试，必须保护合作者身份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地址一旦变更，会导致商户无法请求或访问支付宝，致使商户业务直接不可用

2.2、参数说明

类型 细则 原因
参数配置  必须设置请求参数_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（公用业务扩展参数）参数中的备注描述信息中不能出现用作字段分割符的“^”、“|”特殊字符。 避免出现数据格式错误，导致分润失败。
当使用了分润功能时，在设置请求参数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（需要联系支付宝开通该参数权限） 方便商户定位接口报错

2.3、签名说明

类型  细则  原因 
签名  请求的所有参数，需要根据参数名=参数值的格式，按首字符字典顺序（ascii值大小）排序，若遇到相同首字符，则判断第二个字符，以此类推，待签名字符串需要以“参数名1=参数值1&参数名2=参数值2&….&参数名N=参数值N”的规则进行拼接。 避免接口无法正常使用
在对请求的参数做签名时，这些参数必须来源于请求参数列表，并且除去列表中的参数sign、sign_type。 避免接口无法正常使用
在对请求的参数做签名时，对于请求参数列表中那些可空的参数，如果选择使用它们，那么这些参数的参数值必须不能为空或空值。 避免接口无法正常使用
签名时将字符转化成字节流时指定的字符集与_input_charset保持一致；如果传递了_input_charset参数，这个参数也应该包含在待签名数据中。 避免接口无法正常使用
待签名数据应该是参数原始值而不是url encoding之后的值，例如：调用某接口需要对请求参数email进行数字签名，那么待签名数据应该是email=test@msn.com，而不是email=test%40msn.com。 避免接口无法正常使用

2.4、异步通知说明

类型 细则 原因
返回数据处理  设置了请求参数item_orders_info的情况下，建议使用post方式提交请求。 避免地址栏中地址数据过长，导致传递的数据丢失。
支付宝主动发送通知，当商户接收到通知数据后必须给支付宝返回“success”字符串，不允许返回其他多余字符。 如果商户返回给支付宝的信息不是“success”，支付宝最多重复发送8次通知。
说明：
一旦商户收到异步通知返回了纯字符串success给支付宝，支付宝就不会再发送异步通知，否则会继续按照发送时间发送通知。
必须保证设置的通知路径互联网上能访问得到，且访问顺畅。 避免接收不到支付宝发送的通知 
必须对返回的所有结果数据进行处理  以便商户能够了解接口的使用情况，以及进行商户的后续业务操作。
必须判断发送支付请求以后的业务逻辑处理程序是否有重复执行 防止出现商户的业务操作被重复执行，导致出现资金损失，如重复充值、重复付款等。
如果交易付款完成时发送的交易状态是TRADE_SUCCESS（可对交易做其他操作，如退款、分润等），则当超过签约合同指定的可退款时间段时，支付宝会主动发送TRADE_FINISHED（不能对该交易再做任何操作）交易状态。此时，需要根据商户自身业务情况，来判断是否需对这次的交易完成通知进一步处理。 防止出现商户的业务操作被重复执行，导致出现资金损失，如重复充值、重复付款或订单数据错乱等。
建议每一次支付操作需以日志形式记录到商户网站的日志操作数据库中 用来在必要时检查或跟踪业务处理情况

2.5、验签说明

类型 细则 原因
通知返回验证  如果有设置通知路径及触发通知条件，则必须使用获取到的参数notify_id再次请求支付宝，获取是否是支付宝发送的验证结果。该请求链接是：
https://mapi.alipay.com/gateway.do?partner=合作者身份ID&notify_id=通知ID的值		 验证是否是支付宝发来的请求 
在对通知的参数做签名时，这些参数必须来源于支付宝通知回来的参数，并且除去列表中的参数sign、sign_type，根据参数名=参数值的格式，按首字符字典顺序（ascii值大小）排序，若遇到相同首字符，则判断第二个字符，以此类推，待签名字符串需要以“参数名1=参数值1&参数名2=参数值2&….&参数名N=参数值N”的规则进行拼接，得到的签名结果与获取到的参数sign值做比较。 验证返回的签名 

三、开发完毕，测试验收

3.1、测试流程

步骤  调试内容  备注 
第一步：在本机单独对这个接口进行调试。 l 支付
l 返回 		 仅仅把接口配置好，不要放在商户的网站项目中。
第二步：在服务器上单独对这个接口进行调试 l 支付
l 返回
l 通知 		 本机调试没有问题后，再放入服务器中调试。
第三步：接口融合到网站项目中 无  把调试好的接口与商户网站项目的业务流程进行衔接和融合。
第四步：在本机对融合后的网站项目进行调试 l 整个业务操作流程
l 支付
l 返回
l 业务后续的执行		 在本机调试衔接到网站项目后的接口。
第五步：在服务器对融合后的网站项目进行调试 l 整个业务操作流程
l 支付
l 返回
l 通知
l 业务后续的执行		 本机调试没有问题后，再放入服务器中调试。