纯担保交易接口开发流程
一、开发前期准备
1.1、查找PID(partner)和密钥（key）
a、首先查询合作者身份ID和安全校验码KEY；
b、RSA加密方式：公私钥由商户技术人员生成。
（1）首先生成商户公钥、私钥；
（2）其次上传生成的公钥，同时获取支付宝公钥。
1.2、网络环境的要求
a、支付宝提供的开发环境。
（1）生产环境。用商户自己的账户做测试。
（2）沙箱环境。提供资料沙箱环境网关地址、测试账号、密钥。
b、商户端开发环境：公网可访问的网络环境。
1.3、下载接口开发文档及配置开发环境
开发语言：支持C#、PHP、ASP、JAVA四种开发语言。
开发语言：支持http协议的开发语言。
1.4、业务术语
| 术语 | 解释 |
|---|---|
| CTU | 支付宝风险稽查系统。 |
| 担保交易 | 以支付宝为第三方担保，保证买卖双方在交易的过程中，买家能收到货，卖家能收到钱。其交易流程是：“买家付款”→“卖家发货”→“买家确认收货”→“卖家确认收款”。 |
| 返回 | 支付宝根据得到的数据处理完成后，支付宝将处理完成的结果信息反馈给商户网站。 |
| 防钓鱼 | “网络钓鱼”攻击利用欺骗性的电子邮件和伪造的Web站点来进行诈骗活动，受骗者往往会泄露自己的财务数据，如信用卡号、账户用户名、口令和社保编号等内容，造成损失。防钓鱼用来防止以上情况的发生。 |
| 分润 | 分润是指将交易金额中的一部分转账给其它账户。 |
| 快捷登录 | 快捷登录产品主要有以下功能： 用户在商户的网站上，可以使用支付宝快捷登录，并共享支付宝的收货地址等物流信息给商户； 如果用户在商户网站上使用了支付宝快捷登录，那么在支付宝支付时，不需要再次在支付宝登录。 |
| 敏感词 | 带有敏感政治倾向、暴力倾向、不健康色彩或不文明的词。 |
| 请求 | 通过HTTP协议把需要传输的数据发送给接收方的过程。 |
| 特殊字符 | 用做url转义字符，或在接口参数中用作分割符的特殊字符，包括：?、%、&、+、^、| |
二、开发联调阶段
2.1、安全说明
| 类型 | 细则 | 原因 |
|---|---|---|
| 安全 | 使用签约账号进行调试，必须保护PID与安全校验码key的隐私性。 | 防止接口无法正常使用或防止签约的账号信息被盗用，导致资金受损、被他人恶意利用等。 |
| 测试完毕后，要把测试账号立刻更换成签约账号。 | 使用测试账号时，手续费按照3%扣除。 | |
| 该接口必须使用https请求 | 避免请求参数暴露 | |
| 支付宝的通知服务器的出口IP段是121.0.26.0/23、110.75.128.0/19、110.75.225.0/24、110.75.242.0/24。该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 | |
| 只有开通了快捷登录，才能使用请求参数token（授权令牌码），且必须设置token。 | 减少用户付款时重复登录支付宝 | |
| 请求参数subjet、body的值，的备注表述信息中不要使用敏感词。 | 避免接口无法正常使用 | |
| 参数notify_url的设置必须是互联网上能访问到且访问正常的路径地址 | 避免商户网站无法收到支付宝的主动通知 | |
| 请求参数return_url的设置不能是http://localhost/这类地址，必须是服务器ip地址或者域名方式。（例如:127.0.0.1） | 避免付款成功后，当前页面停留在支付宝交易完成提醒页面，而不做任何跳转 | |
| 请求参数return_url的设置不能是含有“!”这类特殊字符的地址 | 避免付款成功后，当前页面停留在支付宝交易完成提醒页面，而不做任何跳转 | |
|
物流信息最多设置三组：每一组都要包含： 1、logistics_type物流类型、logistics_fee物流费用、logistics_payment物流支付类型。(第一组必须设置) 2、logistics_type_1物流类型、logistics_fee_1物流费用、logistics_payment_1物流支付类型。 3、logistics_type_2物流类型、logistics_fee_2物流费用、logistics_payment_2物流支付类型。 logistics_type每组最好不同。Logistics_fee可设置为0 |
避免参数顺序传错。 缺少第一组参数中的任何一个都会报 ILLEGAL_LOGISTICS_FORMAT |
|
| 最后计算的金额：price*quantity+discount+logistics_fee | 该金额是显示在支付宝收银台上的应付金额。 | |
|
如果设置收货人信息（receive_name、receive_address、receive_zip、receive_phone、receive_mobile）支付时，会省去用户填写。 l 如设置收货人信息，保证receive_name、receive_address不为空。 l 其他参数填写必须严格按照格式填写。 |
避免接口报错 | |
| 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赋值时，需注意区分大小写。 | 否则会引起银行直连调用失败 | |
|
如果是etao接入的商户，那么必须设置请求参数error_notify_url和item_orders_info； 如果不是etao接入商户，item_orders_info不要设置 |
error_notify_url请求支付宝报错时可以收到错误信息。需要支付宝开通参数权限。 item_orders_info购买商品的清单详情，能够同步到etao的订单列表中 |
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、通知说明
| 类型 | 细则 | 原因 |
|---|---|---|
| 返回数据处理 | 支付宝主动发送通知，当商户接收到通知数据后必须给支付宝返回“success”字符串，不允许返回其他多余字符。 |
如果商户返回给支付宝的信息不是“success”，支付宝最多重复发送8次通知。 说明： 一旦商户收到异步通知返回了纯字符串success给支付宝，支付宝就不会再发送异步通知，否则会继续按照发送时间发送通知。 |
| 必须保证设置的通知路径互联网上能访问得到，且访问顺畅。 | 避免接收不到支付宝发送的通知 | |
| 必须对返回的所有结果数据进行处理 | 以便商户能够了解接口的使用情况，以及进行商户的后续业务操作。 | |
| 必须判断发送支付请求以后的业务逻辑处理程序是否有重复执行 | 防止出现商户的业务操作被重复执行，导致出现资金损失，如重复充值、重复付款等。 | |
| 设置了notify_url且默认配置下，那么支付宝会根据交易状态及退款状态来发送服务器异步通知。 | 默认状态通知配置下，交易状态和退款状态变更都会发送异步通知 | |
| 如果设置了return_url，那么该页面只会接收到买家付款成功的交易状态，即WAIT_SELLER_SEND_GOODS. | Return_url（页面跳转同步通知）是买家付款完成以后触发的。 | |
| 建议每一次支付操作需以日志形式记录到商户网站的日志操作数据库中 | 用来在必要时检查或跟踪业务处理情况 | |
| 交易及退款状态 |
交易状态（TRADE_STATUS）的顺序： WAIT_BUYER_PAY(等待买家付款) WAIT_SELLER_SEND_GOODS(买家已付款，等待卖家发货) WAIT_BUYER_CONFIRM_GOODS(卖家已发货，等待买家收货) TRADE_FINISHED(买家已收货，交易完成) |
交易的通知顺序以支付宝系统第一次发送交易状态和退款状态的通知时间来排序的 |
|
退款状态（REFUND_STATUS）顺序： 1、已收货情况 WAIT_SELLER_AGRE(等待卖家同意退款) WAIT_BUYER_RETURN_GOOD(卖家同意退款，等待买家退货) WAIT_SELLER_CONFIRM_GOODS(买家退货，等待卖家收到退货) REFUND_SUCCESS(买家收到退货，退款成功，交易关闭) 2、未收货情况 WAIT_SELLER_AGREE(等待卖家同意退款) REFUND_SUCCESS(卖家同意退款，退款成功，交易关闭) 3、卖家未发货而退款成功，交易状态会变为TRADE_CLOSED 4、卖家发货而退款成功后，交易状态变为TRADE_FINISHED. |
交易的通知顺序以支付宝系统第一次发送交易状态和退款状态的通知时间来排序的 | |
| 退款流程中，买家申请退款时，卖家可以拒绝退款，退款状态为SELLR_REFUSE_BUYER,买家还可以再次申请退款，退款状态又会变为WAIT_SELLER_AGREE. | 当发生退款是，若交易退款状态不为REFUND_CLOSED或REFUND_SUCCESS时，买家可再申请退款。 |
2.5、验签说明
| 类型 | 细则 | 原因 |
|---|---|---|
| 通知返回验证 |
如果有设置通知路径及触发通知条件，则必须使用获取到的参数notify_id再次请求支付宝，获取是否是支付宝发送的验证结果。该请求链接是： https://mapi.alipay.com/gateway.do?partner=合作者身份ID¬ify_id=通知ID的值 |
验证是否是支付宝发来的请求 |
| 在对通知的参数做签名时，这些参数必须来源于支付宝通知回来的参数，并且除去列表中的参数sign、sign_type，根据参数名=参数值的格式，按首字符字典顺序（ascii值大小）排序，若遇到相同首字符，则判断第二个字符，以此类推，待签名字符串需要以“参数名1=参数值1&参数名2=参数值2&….&参数名N=参数值N”的规则进行拼接，得到的签名结果与获取到的参数sign值做比较。 | 验证返回的签名 |
2.6、业务使用流程
| 类型 | 细则 | 原因 |
|---|---|---|
| 业务使用流程 | 接口支持重复调用，前提是交易基本信息（买家、卖家、交易金额等）在多次使用中保持一致，且交易尚未完成支付，及交易状态是WAIT_BUYER_PAY. | 防止重复付款以及交易信息被篡改。 |
| 填写买家支付宝账号时，不能与卖家的支付宝账号相同。 | 避免报错，如BUYER_SELLER_EQUAL(交易卖家与买家是同一个人) | |
| 担保交易支持在交易创建后，（即交易状态是WAIT_BUYER_PAY），卖家修改价格。 | 该操作需要卖家（收款人）登陆支付宝网站，在交易管理中执行。 | |
| 担保交易支持卖家在交易创建后（即交易状态是WAIT_BUYER_PAY）,卖家关闭交易 | 该操作需要卖家登陆支付宝网站，在交易管理中执行，或者使用交易关闭接口。 | |
| 担保交易支持买家付款完成后（即交易状态是WAIT_SELLER_SEND_GOODS）,卖家执行发货操作。 | 该操作需要卖家登陆支付宝网站，在交易管理中执行，或者使用确认发货接口。 | |
| 不论卖家使用功能确认发货接口还是登陆到支付宝网站在交易管理中操作发货，发货是卖家填写的物流信息，必须与接口请求时设置的物流信息保持一致。 | 如果确认发货是填写的物流信息不一致，以卖家发货是填写的物流信息为准。 | |
| 担保交易支持卖家发货后（即交易状态是WAIT_BUYER_CONFIRM_GOODS）,买家确认收货。 | 该操作需要买家登陆支付宝网站，在交易管理中执行。 | |
| 买家可延迟收货时间，每次可延迟10天，一天可以多次。 | 该操作需要卖家登陆支付宝网站，在交易管理中执行。需买卖双方达成一致。 | |
| 担保交易支持退款流程 | 该操作需买卖双方登陆支付宝网站，在交易管理中执行。 |
三、开发完毕，测试验收。
3.1、测试流程
| 步骤 | 调试内容 | 备注 |
|---|---|---|
| 第一步：在本机单独对这个接口进行调试。 | 支付 返回 | 仅仅把接口配置好，不要放在商户的网站项目中。 |
| 第二步：在服务器上单独对这个接口进行调试 | 支付 返回 通知 | 本机调试没有问题后，再放入服务器中调试。 |
| 第三步：接口融合到网站项目中 | 无 | 把调试好的接口与商户网站项目的业务流程进行衔接和融合。 |
| 第四步：在本机对融合后的网站项目进行调试 |
整个业务操作流程 支付
返回
业务后续的执行 |
在本机调试衔接到网站项目后的接口。 |
| 第五步：在服务器对融合后的网站项目进行调试 |
整个业务操作流程 支付 返回 通知 业务后续的执行 |
本机调试没有问题后，再放入服务器中调试。 |