商户技术对接流程注意事项【交易篇】

时间: 2018-09-12 | 点击: | 栏目: 接口说明

在对接交易类接口之前必须先了解一些机制

 

    1.新浪异步推送机制

 

在之前会员类的接口中,大部分都是同步响应的,以商户程序语言PHP为例(其他语言雷同):

    p2p程序curl方法请求新浪 -> 新浪响应【同步】提交成功 -> p2p程序拿到响应码进行业务处理以及数据库更新。

 

而在交易类动作接口中,将比常规的接口多一步骤:

    p2p程序curl方法请求新浪 -> 新浪响应【同步】提交成功 -> p2p程序拿到响应码进行业务处理以及数据库更新 -> 拿到交易状态,一般为【处理中】

    

    若干时间后,一般为5秒,新浪主动发起POST请求,请求的目标地址为:【之前同步请求中基本参数中的异步地址】:

    

    新浪发起POST请求 -> p2p程序中的异步地址拿到$_request数据并且做日志保存 -> p2p程序在异步地址的页面响应一个SUCCESS用于告诉新浪已经收到该数据 ->  p2p程序更新数据库中交易状态,以及业务处理

 

    注意事项:

        1.所有交易类动作接口的最终状态都是大部分以【交易状态】为准,

        2.传送门:如果商户因为网络原因或者服务器异常无法响应SUCCESS,新浪会如何处理?是否会有补单机制?

 

    2.RSA签名机制

 

    商户->新浪

    p2p程序按照规则生成一个字符串,然后用rsa私钥A进行签名,算出一个值,得到签名。然后连同其他参数一起发给新浪,新浪使用rsa公钥A对商户发过来的签名进行验证。新浪验证成功则继续走业务,验证失败则在报文直接报错并且推出业务逻辑执行。rsa私钥Arsa公钥A必须为同一对KEY才会验证通过。

    新浪->商户

    那在商户端如何验证新浪的响应报文是否正确呢?无论新浪异步响应的参数,还是异步推送的参数,新浪同样以以上的方法进行签名计算的:

    sina程序按照规则生成一个字符串,然后用rsa私钥B进行签名,算出一个值,得到签名。然后连同其他参数一起响应或者POST推送给p2p程序,p2p程序端使用rsa公钥B对新浪发过来的签名进行验证。得出校验结果,并且做对应业务处理。rsa私钥Brsa公钥B必须为同一对KEY才会验证通过。

    

    以上总结出,商户程序在签名机制中会用到两套签名:rsa私钥A 和 rsa公钥B

    其中联调环境,新浪技术支持已经把这两个密钥生成好了,并且放到demo中调通了,商户在植入程序的时候直接用就可以了

    而生产环境,以下表提供地址为准

    传送门:签名规则    传送门:rsa密钥如何生成

总结一下商户所用到的KEY:

    

  p2p程序使用的KEY 新浪程序使用的KEY

RSA关键数据加密KEY对(新浪生成)

【敏感字段加密专用,与签名机制无关】

商户加密数据公钥

(生产公钥提供位置:微钱包-API证书-新浪支付公钥-加密公钥

(联调环境demo中的命名为:rsa_public.pem

商户加密数据私钥

RSA商户回调签名KEY对(新浪生成)

【签名机制专用】

商户RSA回调验签公钥

(生产公钥提供位置:微钱包-API证书-新浪支付公钥-验签公钥

(联调环境demo中的命名为:rsa_sign_public.pem)

商户RSA验签私钥

商户计算签名的KEY对(商户生成)

【签名机制专用】

商户RSA计算签名私钥

(生产私钥提供位置:微钱包-API证书申请-邮箱接收审核结果-下载后导出

(联调环境demo中的命名为:rsa_sign_private.pem)


新浪验证商户来源签名公钥

(联调环境无需发送,直接使用demo中的KEY即可完成接口编写)

 

p2p程序业务逻辑与新浪交易接口如何匹配

 

    1.常规的p2p业务主要分两部分:投标与还款,细分下来有 借款人或者平台发标,投资人抢标,满标放款给借款人,平台方获取自身业务收益,借款人还款充值,p2p程序向投资人发放收益等等等等。对接中注意:接口程序猿必须清楚里面的资金流向如何,一切涉及到资金的逻辑才与新浪交易接口有关。所以清晰知道钱从哪里到哪里,方有明确的对接业务代码方向。

    2.新浪接口是不区分角色的,无论是投资或者借款人或者合作方,只要有需要参与到新浪资金管理体系的角色,都必须走一遍前文说到的个人会员交易条件,所有UID不满足交易条件,不允许参与任何交易类接口。

    3.新浪提供资金入口【充值】以及资金出口【提现】,以供每个客户把钱冲到自己的余额下,以及把自己余额下的钱提现到自己的银行卡内。

    4.接口中【代收】【代付】为一切资金交易流转的核心,并且两者没有必然的联系。

    代收 = 某个UID的余额 -> 关联号的可代付剩余资金下

    代付 = 关联号的可代付剩余资金下 -> 一个或者多个UID的余额下

    5.平台方在接口中参与交易参数:用户标识类型用EMAIL,标识信息用登陆企业微钱包的邮箱网址,账户类型传基本户,这样平台方的基本户就参与交易了

    

    综上,常规p2p业务对应调用接口逻辑(其他业务雷同):

 

 投资业务,钱从多个投资人进来,最终目标到借款人账户中:

     p2p程序:        1.投资人充钱 -> 2.投资人的钱到关联号的可代付剩余资金下 -> 3.标满后放款给借款人 -> 4.平台方获取业务收益。

     sina接口:       1.充值 -> 2.代收 -> 3.代付 或者 代付到体现卡交易 -> 4.代付给平台。

    

 还款业务,钱从借款人账户中进来,最终目标给到多个投资人

 

     p2p程序:        1.借款人充钱 -> 2.借款人的钱到关联号的可代付剩余资金下 -> 3.p2p程序计算收益并且分发给各个投资人 -> 4.各个投资人自行提现。

     sina接口:       1.充值 -> 2.代收 -> 3.代付 或者 批量代付接口 -> 4.提现。

 

总结一下:新浪提供真实资金流,商户程序无论是业务如何,只需要清晰知道想钱从哪到哪儿,调用对应的接口即可完成业务对接。收银台模式商户必须跳转收银台操作。

 

    

具体的接口逻辑以及注意事项

 

    全局逻辑:收银台商户:UID所有的资金流转收银台商户必须跳转收银台操作。诸如充值充值,代收,提现,代收冻结等。另外代付是不需要跳转收银台的。

 

充值接口:

        【必做】【对应充值查询接口、收支明细查询接口】【扩展支付推进接口】【有且以异步推送结果为准】

        1.目前版本新浪为个人用户提供2个账户,【基本户】【存钱罐户】,此接口通过账户类型参数充值指定的账户下,两个账户独立存在,若不传这个参数,新浪默认为充值到基本户中,对接时候必须注意哪个账户下有多少钱。否则调用其他代收接口时候会引起余额不足的情况。

        2.收银台商户下的UID只能跳收银台进行充值,跳收银台的方法:支付方式只能传:pay_method=online_bank^金额^SINAPAY,DEBIT,C 。online_bank+SINAPAY组合视为特殊组组合,该组合理解为跳转收银台充值。收银台商户不允许传其他组合参数,诸如binding_pay、online_bank+银行、quick_pay这种新浪会响应支付方式不支持。

        3.非收银台商户无视上一条,并且不能传online_bank+SINAPAY特殊组合。

        4.【基本户】支持网银支付。【存钱罐户】支持网银支付、绑卡支付、快捷支付。

        5.企业会员只支持网银支付。

        6.生产环境所支持的各个支付银行的列表和限额详细见网盘上的【资金通路表】。

        7.安全卡概念及注意事项

        8.参数user_fee协议手续费使用规则

        9.由于基本户不支持帮卡支付的特性,收银台商户:手机端跳收银台以后只有存钱罐账户才有支付方式【绑卡充值】选项,没有【网银支付】选项;  手机端基本户跳收银台是没有任何支付方式的。  

        10.收银台商户请无视【支付推进接口】。非收银台商户请求帮卡支付、快捷支付后,新浪会发送验证码到客户请求【帮卡支付】的手机号上,验证码通过【支付推进】接口提交给新浪并且提交成功后,等待异步推送充值结果。

 

提现接口:

        【必做】【对应提现查询接口、收支明细查询接口】【有且以异步推送结果为准】

        1.手续费user_feej计算规则以及用法:

                接口中传该值,新浪协议中的手续费就会在此扣取,视为客人承担手续费。例如:

                在存钱罐提现金额传值100,手续费协议中此次计算得出手续费为2(存钱罐余额必须大于或者等于102,否则报错余额不足):

                    user_fee传值2,那么最终结果银行卡到账为100元,新浪存钱罐余额减少102元;其他规则与充值雷同。

        2.若此用户存在安全卡,只能提现到该安全卡的卡ID下。

 

代收接口:

        【必做】【对应交易查询接口】【配套退款接口、交易支付接口、支付结果查询接口】【有且以异步推送结果为准】

        1.此接口一般用于交易,视为某个UID将自己的钱付到关联号的可代付剩余资金下,支付方式只有2种【余额支付】和【网银支付】,收银台商户只能跳转收银台,才会有此两种支付方式显示,不允许传其他组合参数。手机端逻辑同充值。

        2.参数trade_close_time交易关闭时间,管理整个代收交易,若超出时间,该交易将自动关闭

        3.参数传值collect_trade_type=pre_auth将视为【代收冻结交易】,代收冻结交易与代收是两个独立的接口,两者没有任何关联。代收冻结逻辑另外说明

        4.代收参数can_repay_on_failed怎么用?

        5.在p2p买标、抢标超标、客人要求退款、流标退款等场景中,p2p程序会有退款需求,代收到【关联号的可代付剩余资金】的钱可以用【退款】或者【代付】接口将钱返回去。

        6.整笔代收交易以异步推送trade_status=TRADE_FINISHED钱才算真正的到了关联号的可代付剩余资金【退款】发起的退款必须以订单状态为TRADE_FINISHED方可发起请求成功。

        7.用户A的钱->用户B的钱小技巧

                发起代收A100 -> 代收操作完成 -> 异步通知入口判断是否为trade_status=TRADE_FINISHED->调用代付100给用户B。

 

 

代收冻结接口:

        【选做】【对应交易查询接口】【配套代收撤销接口、代收完成接口】【有且以异步推送结果为准】

        1.篇幅较长,另开帖说明

 

代付接口:

        【必做】【对应交易查询接口、收支明细查询接口】【拓展批量代付接口、交易批次查询】【有且以异步推送结果为准】

        1.此接口为从关联号的可代付剩余资金的资金->一个或者多个UID的余额下,只要关联号的可代付剩余资金有钱并且满足代付金额,就能实现代付成功,代付调用必须谨慎。

        2.分账参数使用说明:

            例1 代付给A,A分给B,A分给C,A分给D。

            例2 代付给A,A分给B,B分给C,C分给D。其中A、B、C必须是收到钱才有权限分钱给其他角色,不允许【代付给A,A分给B,C分给D】

        3.分账金额必须小于等于收款金额。

 

转账接口:

        【选做】【有且以异步推送结果为准】

        1.此接口是用于客户基本户升级存钱罐的,不是A转B用的,A转B请用代收代付

 

标的录入接口:

        【建议做】【管理创建单笔代付到提现卡交易接口、创建批量代付到提现卡交易接口】

        1.此接口的参数列表涉及到【创建单笔代付到提现卡交易】、【创建批量代付到提现卡交易】两个接口的使用,可以理解为管理这两个从属接口。

        2.具体管理事项: 创建单笔代付到提现卡交易”使用之前,必须先做标的录入接口。

                                    “创建单笔代付到提现卡交易”以标的号goods_id与标的录入来关联

                                    创建单笔代付到提现卡交易”接口中的“金额”不能大于“标的录入”接口中请求参数“标的总金额”,否则系统报错。

                                    “创建单笔代付到提现卡交易”接口中的“收款人”必须是“标的录入”接口中请求参数“借款人集合”的其中之一。

        3.标的录入接口,对于商户自身业务不做任何限制,用于新浪内部风控使用,以及接口限制使用,无论商户满标还是不满标,新浪都不会有任何干预。

        4.代付到提现卡交易资金流向:关联号的可代付剩余资金的钱-》直接到某个UID的银行卡上,视为提现出款交易,用提现查询。有切以异步推送为准,一般用于满标后给借款人放款,额度较大。

        5.代付到提现卡交易出款时,受到安全卡规则限制,如果出款对象当前状态存在安全卡,只能出款到该安全卡内。

        6.批量代付到提现卡交易接口,类推上述规则,并且不支持分账,最大交易笔数100笔。                              


 

 

 


  • 上一篇:绑卡接口说明,绑定银行卡,绑定支付
  • 下一篇:商户对新浪网关的并发数量是多少?

与此文章相关还有:

like article