收付款产品商户对接流程注意事项

时间: 2020-11-26 | 点击: | 栏目: 微账户

1、必看

    1.由于收付款模式(未签署账户类协议)平台下的会员没有账户(基本户、存钱罐户),所以与账户相关的接口如充值、提现,支付方式如余额支付可以忽略不看。
    2.收付款、收付款+账户(以下简称收付账”)模式都支持匿名购买(匿名支付暂不支持对公网银),所以会员类接口平台可以根据自己的业务选择性开发。如果不开发会员类接口则交易创建中的卖家只能由平台充当
    3.收付款模式下的卖家只能由平台充当,收付账模式卖家可以是平台也可以是平台下的会员。
    4.收付款与收付账的区别请参考:收付款、收付款+账户(收付账)模式的区别

      5.平台作为收款方或者分账方,只能使用基本户,暂时无法使用存钱罐账户.

2、异步通知机制

传送门:请参考商户技术对接流程注意事项【交易篇】第一节异步通知机制

3、RSA签名机制

传送门:请参考商户技术对接流程注意事项【交易篇】第二节异步通知机制
验签失败的常见原因:
    请参考:订单类网关错误码解析 中的验签未通过
    3.1、密钥错误
    3.2、请求参数多传或少传
    3.3、加签参数中前或后多空格,或者加签参数为空
    3.4、加签后未对参数进行编码处理(URLEncoder.encode())
    3.5、代码执行的逻辑顺序:
    商户:获取前台数据->对需要加密的数据进行加密(联调环境密钥<rsa_public.pem>)->对参数加签(加签参数非空)->对加签后的参数做urlencode处理->发送post请求->新浪响应->使用验签公钥验签(空参数不参加验签)->商户后台响应
 

4、接口文档参数介绍

1.接口文档中的参数是分两部分的,(1)基本参数,(2)业务参数
    基本参数中除了个别参数(servicereturn_url等)外其他参数都是接口共有的,
    业务参数是各个接口业务内需要的参数,商户平台开发过程中应遵循接口文档规范来传参。

2.接口文档从调用网关的角度大致分为两类:会员类接口交易类接口,其中会员类接口商户根据自己的业务需求来选择开发;交易类接口交易创建、交易结算、交易撤销、交易关闭、退款这些接口支撑起整个收付款业务的运行。
3.基本参数中的partner_id为平台的商户号。
4.请求新浪接口的方式为post。
5.请求时间request_time有效期为15分钟(该时间以北京时间为准)。
6.对于交易类有异步通知的接口,请商户传入异步通知地址(notify_url)用于接收异步通知。

5、商户(平台)程序与新浪接口的交互

程序全局逻辑:
  1. 日志记录了整个程序的运行过程,对于一个系统来说必须要有完备的日志模块,来记录程序运行的状态,调用接口的请求、响应信息一定要记录在日志中,便于排查接口调用过程中的报错信息,然后准确的解决问题。当需要讨论组提供技术支持的时候也是需要贴报文或者请求号,并且要求报文完整,不允许截图
  2. 接口文档说明中,每一个动作接口,都配置一个对应的查询类接口,用于提供商户查询对应的状态,每做一个动作,都必须做一个对应的查询接口到b2c后台以供其他有权限同事使用,也可以按照设计提供给前台的客户使用,例如【绑定银行卡】信息接口,对应的有【查询银行卡信息接口】。
  3. 注意接口文档中参数说明那一列如果有“密文”字样,那么该字段的值要做加密处理。联调环境的加密密钥demo中已经给出(rsa_public.pem)生产环境需要在微钱包后台申请获取。
  4. 新浪提供资金入口【充值】以及资金出口【提现】(收付账模式),以供每个客户把钱冲到自己的余额下,以及把自己余额下的钱提现到自己的银行卡内。
  5. 平台方在接口中参与交易参数:用户标识类型用EMAIL,标识信息用登陆企业微钱包的邮箱网址,账户类型传基本户,这样平台方的基本户就参与交易了。
  6. 新浪提供真实资金流,商户程序无论是业务如何,只需要清晰知道想钱从哪到哪儿,调用对应的接口即可完成业务对接。收银台模式(签署了相关协议)商户必须跳转收银台操作
  7. 平台基本户的余额可以在微钱包后台申请提现。

5.1会员类接口

1.平台下创建会员的业务流程:
个人会员:创建会员 -> 实名  -> 设置支付密码接口(
设置支付密码后在创建支付账户)->绑定银行卡(收付款模式该接口不做) -> 访问交易类接口
       企业会员
(收付账模式):创建会员 -> 请求会员资质接口 -> 新浪审核回调成功 ->设置支付密码接口 -> 访问交易类接口
2. 由于收付账、收付款模式支持匿名购买,所以会员类接口商户平台可以根据自己的业务需求选择性开发相关接口。
3. 平台签署了绑卡支付、余额支付的相关协议后,交易创建时可以选择相应的支付方式,这种情况下商户平台需要开发会员类接口,使用余额支付要求平台下的会员要有账户(基本户、存钱罐户)。
4.如果商户平台不开发会员类接口则该模式为收付款模式,卖家由商户平台充当。

 
会员类相关接口开发说明:商户技术对接流程注意事项【会员中心篇】
注意事项:

  1. 联调环境身份证号码mock奇数开头实名成功,偶数开头实名失败。不校验真实性。
  2. 联调环境只校验卡bin(卡的前6位),不校验真实性。
  3. 联调环境mock:名字叫张三的绑卡失败,卡号有连续777的绑卡失败。
  4. 商户可以通过调用查询银行卡接口获取用户的绑卡id(card_id)。
  5. 经办人信息接口是用户企业用户开通存钱罐(企业会员默认开通基本户,个人会员建议使用存钱罐)使用,一家企业只能填写一个经办人信息,一个经办人信息适用于一家企业;若需要修改经办人信息,需要提交修改企业资质申请到新浪支付运营;
  6. 一个身份证可以开通一个个人会员、一个企业会员。
  7. 联调环境企业会员审核不校验身份证信息,是否审核通过由商户决定。

5.1.1【商户报备(merchant_report)】

为什么要报备?
当支付方式为扫码支付、APP支付、公众号支付时平台必须报备,平台调用该接口填写相关信息,提交到新浪支付端进行报备。该接口支持支付宝报备、微信报备
如何进行报备?
报备方填写真实信息,调用商户报备接口进行报备。

平台报备时传参
merchant_identitiy_type:MEMBER_ID  merchant_identity_id:微钱包后台显示的id
(partner_id)
         或merchant_identitiy_type:EMAIL  merchant_identity_id:微钱包后台登陆账号
 
注意:未报备成功则可以再次报备,如果都报备成功则不可以再次报备(报备成功再次调用报备接口新浪这边不会去再次报备,除非appid有变化),报备信息不可修改。
只需要平台报备一次,交易创建如需传值的话传入该报备信息即可(上报商户标志类型,上报商户标志)。

所有的卖家可以公用平台的报备信息  平台下的会员作为卖家的时候报备人可以是平台或卖家自己  平台作为卖家的时候报备人必须是平台自己。
报备参数APPID如何获取?
公众号支付和APP支付报备时该字段是必填的,APPID的获取请参考微信支付相关说明、及 附件收付款产品_微信支付接入专项指导_V1.0.0.docx
传送门:
微信小程序APPID的获取流程   微信支付接入指导   微信公众号开发介绍  调起起微信支付控件
注意:接入微信支付的商户请先阅读微信支付官方说明

报备要审核吗?
不需要审核,
    同步响应信息wechat_result为true时表示微信报备成功
    同步响应信息ali_result为true时表示支付宝报备成功


 
微信支付授权目录即用户在公众号中下单并呼起微信支付的页面url,设置请参考:支付目录设置


报备字段中的【商户简称】:商家自定义,会展示在微信账单上面。
报备信息需正确填写,银联会对信息进行核查。

5.1.2【委托扣款相关接口】

1.业务逻辑(商户签署了委托扣款协议)
接口中的单笔额度、日累计额度为商户平台设置的用户可选择的最低额度,也就是说用户在开通委托扣款页面填写的额度要大于商户请求接口的传值。
注:银行卡委托扣款跟余额委托扣款不能同时开通,一次只能开通一张银行卡的委托扣款,如果要换卡只能解约重新签约。

1.1余额委托代扣(传值ACCOUNT)  收付款模式可忽略
1.1.1用户注册,实名后 直接调用委托扣款接口->跳入新浪开通委托扣款页面会提示输入认证手机、设置支付密码->设置支付密码成功->开通委托扣款页面->输入支付密码后委托扣款设置成功
1.1.2用户注册,实名认证,设置支付密码后 调用委托扣款接口->跳转到开通委托扣款页面->输入支付密码后委托扣款设置成功

1.2银行卡委托代扣(传值ALL@ONE)收付款模式可忽略
1.2.1用户注册->实名认证->委托扣款接口->跳入新浪开通委托扣款页面会提示输入认证手机、设置支付密码->设置支付密码成功->开通委托扣款页面->添加银行卡->输入验证码->设置额度输入支付密码->开通成功
1.2.2用户注册->实名认证->设置支付密码->添加银行卡->跳入开通委托扣款页面->输入信息、支付密码->开通成功
设置支付密码、添加银行卡无先后顺序要求,如果先调添加银行卡接口,在绑定银行卡的过程中会提示设置支付密码

2.使用场景
用户开通了委托扣款商户平台可直接扣除用户余额或者银行卡中的资金。商户平台可以根据自己的业务选择是否要开发委托扣款相关接口。
传送门:
委托代扣接口说明

5.1.3【新浪支付子商户平台重定向(smerchant_url_get)】建议商户使用

该接口是一个标准的网关接口,是新浪支付为其合作商户提供的一个web站点,该站点有如下功能
1.个人用户:会员注册(如果UID不存在则会注册)、个人会员实名、银行卡管理、提现(可关闭)、交易查询、账务明细查询等
2.企业会员:会员注册(如果UID不存在则会注册)、企业资质提交、取现(可关闭)、交易查询、账务查询等
该接口方便了用户对自己账户信息的查询

通知时间说明:

    1.会员信息综合通知事件明细中新增企业资质审核建议,审核状态. 

    2这两个是子商户平台的审核通知事件,区别于"企业会员审核结果通知"

    3.会员信息综合通知事件结果新增以下四个事件结果,均来自子商户平台的操作通知:

        创建会员成功,个人会员身份证实名认证成功,企业会员资质审核认证通过,企业会员资质审核认证不通过.

 

5.1.4【修改商户配置(set_merchant_config)】

为方便商户自定义收银台部分功能,运行部分商户配置可由商户自行修改。
可修改内容:
    1.会员综合信息通知商户url
MEMBER_INFO_GENERAL_NOTIFY_URL
    2.个人中心单项控制展示【CENTER_CUSTOM_CONF】(收银台个人中心绑卡、解绑卡的展示)
配置完成后需要等待十分钟缓存刷新后才会生效


5.1.5【查询商户配置(query_merchant_config)】

该接口用于查询商户的配置,key值请参考修改商户配置,比如查询配置的会员综合通知地址

5.1.6【协议签约重定向(handle_contract_sign)收付款模式可忽略

(1)分账协议
合规要求:平台需要引导分账付款方(除平台外)进行签署分账协议,分账收款方无需签署分账协议
举例:分账时,A(分账付款方)需分账10元给B(分账收款方),则A需签署分账协议,B无需签署;但退分账时,B退款5元给A,则B(退分账付款方)需签署分账协议

(2)委托提现协议
用户签署基本户委托提现协议后,平台可通过提现接口指定提现金额,用户无需跳转新浪支付收银台,即可完成将用户基本户余额提现到其账户绑定银行卡中到其账户绑定银行卡中
该接口可以引导平台下的会员签署上述两个协议,来实现相应的功能
签署上述协议的入口有两个
1,设置支付密码接口传入参数 指引协议签约类型(navigate_contract_type),引导用户设置完支付密码后签署基本户委托提现协议或分账协议

2,协议签约重定向接口

5.1.7【查询会员及账户状态接口(query_account_info)】
该接口可以查询会员信息,会员账户状态,是否被冻结,及被冻结原因

5.2交易类接口

商户平台需要根据接口文档及自己的业务逻辑对数据进行合理的建表保存,如交易创建的交易订单号、结算请求号这些都需要保存,用于后续的查询,撤销等操作。
交易相关的请求号要入库保存,如果接口返回失败,便于查找失败原因。请求号在商户系统中不允许重复,在生成时要做唯一性校验。
全局逻辑:收银台商户:UID所有的资金流转收银台商户必须跳转收银台操作。诸如充值充值,提现,交易创建(收付账模式)
 
业务逻辑概述:

1、 交易创建->用户未付款(交易状态等待付款)->交易关闭(交易超时关闭或者平台主动发起关闭TRADE_CLOSED
2、 交易创建->用户付款(付款完成pay_finished)->交易结算(自动结算或者平台调用结算接口)->交易完成(trade_finished)
3、 交易创建->用户付款(付款完成pay_finished)->交易撤销(调用交易撤销接口)->交易失败(TRADE_FAILED)
4、 交易完成后调用退款接口->退款成功(SUCCESS)
5、 结算后的资金记录可以调用收支明细接口查询。
注:买家付款后资金将进入新浪账户,到结算时间后新浪将资金转入卖家账户

5.2.1【交易创建(create_b2c_order)】

此接口商户平台必须开发,它是交易的核心
 
1.创建交易的参数中上报商户标识类型、上报商户标识的填写要与商户报备的信息保持一致。
2.买家信息不传时(买家标识、买家标识类型)该交易为匿名交易。
3.商户订单号由商户自己生成(不要包含特殊字符)并入库保存,后面的一系列交易都跟这一个订单号有关。
4.交易过期时间说明:买家支付后但并未返回支付成功或失败该笔交易到了交易过期时间后将自动关闭,设置该字段与平台调用交易关闭接口效果相同。

5.设置交易结算时间与调用交易结算接口效果相同,该参数将影响交易撤销接口的使用。
5.交易创建将会有两次异步通知,买家付款完成(pay_finished),交易结算完成(trade_finished)
6.支付方式请参考:
支付方式说明
7.买家标识类型值为UID,买家标识为创建会员时传给新浪的用户标识(这两个参数不传表示匿名购买)
8.卖家标识类型:
                  标识类型:MEMBER_ID  标识:平台商户号
                  标识类型:EMAIL  标识:微钱包后台登陆账号

9.上报商户报备标识类型:与商户报备接口中的商户标识类型一致
  上报商户报备标识:与商户报备接口中的商户标识一致
10.分账参数使用说明:
            例1 结算给A,A分给B,A分给C,A分给D。
            例2 结算给A,A分给B,B分给C,C分给D。其中A、B、C必须是收到钱才有权限分钱给其他角色,
不允许【结算给A,A分给B,C分给D】,不支持【A->B->C->A】
         分账金额必须小于等于收款金额。
收付款模式该参数可以忽略(平台下会员无账户)。
 11.支持收款到平台余额待结算账户(
BALANCE_SETTLE),该账户只能用于收款、分账不能用于充值、提现。余额查询、收支明细查询接口可以查询待结算账户的余额及明细。
12.payer_ip 必须使用用户ip,不能使用服务器ip,否则在响应中会被拦截。

13.跳转到收银台后的异常处理:
    未设置支付密码:跳转到设置支付密码页面
    其他异常:跳转到该订单商户的return_url对应的页面。

14.该接口收款方/分账方账户类型不支持存钱罐。
15.该接口根据监管要求需要上送风控参数 risk_info、device_info,请参数风控参数说明文档
16.
交易创建时间 = 调用交易创建接口的时间.
17.
交易关闭时间. 交易创建接口传入时间长度,长度范围1m~15d,为空默认24h.以交易创建时间为基准来计算.
18.
自动结算时间. 交易创建接口传入时间长度,长度范围1m~45d,为空表示支付成功后立即结算.以交易创建时间为基准来计算.

5.2.2【再次支付(pay_order)】

此接口商户根据自己的业务需求选择性开发。
1.对为完成的交易进行付款,如下单的时候未支付或者支付失败,且该交易订单运行重复支付。
2.原交易状态必须为等待付款。
3.支付结果同步返回,交易结果异步通知。


5.2.3【交易结算(settle_b2c_order)】

此接口商户根据自己的业务需求选择性开发。
1.当交易创建时商户选择延迟结算(结算时间不为0)且还未到结算时间时商户平台可以自己调用此接口来发起结算。
2.结算的资金最终去向:由交易创建中传入的卖家账户类型决定。
3.订单请求号由商户平台生成,并保存待后续查询使用。
4.商户订单号为交易创建时候的商户平台生成的订单号。
5.交易创建的结算时间最长为45天。
6.该接口根据监管要求需要上送风控参数
risk_info、device_info,请参数风控参数说明文档

 

5.2.4【交易关闭(close_b2c_order)】

此接口商户根据自己的业务选择性开发。
1.    调用的前提是交易状态为“
等待付款”。
2.    交易过期时间:默认交易过期时间15分钟,商户可以根据自己需要传入,付款未成功的订单在到交易过期时间后也将自动关闭。
3.    订单关闭请求号有商户平台生成并入库保存。
4.    交易订单号为交易创建时的订单号。

5.2.5【交易撤销(cancel_b2c_order)】

此接口建议商户开发,在一些特定的场景比如买家付款,商家未发货的场景使用。
1.    前提条件是订单状态为
付款完成(PAY_FINISHED)。
2.    撤销后资金原路退回,撤销必须全额。
3.    撤销请求号由商户平台生成并入库保存
4.    交易订单号为创建交易的订单号。
5.    该接口受交易结算接口的影响。

5.2.6【延长交易结算时间(extend_settle_time)】

此接口商户平台根据自身的业务选择性开发。
1.调用之前一定要注意交易状态不能是交易结束
2.延长的时候是在之前交易创建时的结算时间的基础上增加
3.请求号由商户平台生成并入库保存。
4.交易订单号为交易创建时的订单号
5.
自动结算时间(更新). 延长交易结算接口传入,时间范围 1m~45d,累计自动结算时间长度不能超过45d; 
更新的自动结算时间点 = 原自动结算时间点 + 延长时间长度(延长交易结算接口的时间).

5.2.7【退款(create_hosting_refund)】

此接口建议商户开发。当买家退货的时候,需要将资金退还给买家。
1.    前提条件是交易状态为交易完成(TRADE_FINISHED)。
2.    资金原路退回,如果收款方使用存钱罐账户收款,则暂不支持部分退款。
3.    商户订单号为该笔退款交易的订单号,由商户平台生成并入库保存
4.    需要退款的商户订单号为交易创建时的订单号
5.    有分账的订单退款,将从分账人的账户扣回,如果余额不足则退款失败。
6.    支持从平台余额待结算账户退款。
7.    可以根据卖家进行查询。

8.    退款的时间限制为90天。

9.    交易创建接口新浪收取的协议手续费,退款的时候会退回给商户(原来退回)。


5.2.8【退款查询(query_hosting_refund)】

此接口建议商户开发。当买家选择退款后可以查询退款的进度。对退款结果进行查询
注意:退款订单号是退款时商户生成的订单号,而不是交易创建时生成的订单号

             请求参数中的用户标识是买家标识,该接口暂不支持匿名购买的退款查询。

5.2.9【交易查询(query_hosting_trade)】

此接口建议商户开发,用于查询历史交易记录。
 

5.2.10【批量付款到银行卡(create_batch_pay2bank)】

此接口建议商户开发。平台可以通过该接口将平台资金付款到其他用户的银行卡。
商户平台付款到其他银行卡账户,资金从平台基本户或准备金账户扣除,该接口有异步通知。
该接口参数中的省份信息为开户行所在地信息,该接口目前支持20条记录。

该接口只能从平台出款。

5.2.11【出款批次查询(query_b2c_batch_fundout_order)】

该接口与批量付款到银行卡接口配套使用,用于查询批量付款到银行卡的信息。该接口支持分页查询,参数参见接口文档。

5.2.12【批量付款到账户接口(create_batch_pay2account)】 收付款模式可忽略

该接口用于将资金从平台账户付款到其他账户
平台账户可以是平台基本户或平台准备金账户,入款到平台下的个人/企业的基本户

该接口只能从平台出款。
该接口收款方不支持存钱罐账户。

5.2.13【交易批次查询接口(query_hosting_batch_trade】 收付款模式可忽略

该接口用于查询批量付款到账户的批次。
该接口配合批量付款到账户接口的使用,商户可以自行查询付款批次的状态。

该接口支持分页查询。

5.2.14【充值、提现接口】 收付款模式可忽略

如果平台下的会员有账户且平台签署了余额支付协议,则平台需要开发这两个接口。
具体介绍请参考
商户技术对接流程注意事项【交易篇】中的充值、提现接口介绍
交易流程如下:
买家充值->平台账户有余额->交易创建->余额扣款->卖家账户余额->余额提现
买家充值->平台账户有余额->买家提现

充值支持的支付方式<参考
支付方式说明>:
1、充值新增微信"扫码支付"支付方式.目前支持直连和收银台两种模式.支持微信余额, 对私借记卡.  
 scan_pay^1.01^TENPAY,DEBIT,C,
2、充值新增微信"公众号支付"支付方式.目前支持直连模式.支持微信余额, 对私借记卡. 
3、充值新增微信"APP支付”支付方式.目前支持直连模式,支持微信余额, 对私借记卡.
4、充值新增微信"小程序支付"支付方式.目前支持直连模式,支持微信余额, 对私借记卡.

注意:
支付方式中的appid是平台报备信息中的appid
 

5.2.15【分账接口(receipt_split)】 收付款模式可忽略

该接口包含两个部分:可以实现分账和退分账功能,退分账是分账的逆过程
1、分账类型传值为N时,该接口实现分账功能,传值为R时该接口实现退分账功能
2、使用该接口要注意失效(该笔交易结束后的45天内)
3、分账金额受到订单总金额的限制
4、该接口有异步通知,最终交易结果以异步通知为准

5、调用分账查询接口(query_receipt_split)可以查询历史分账信息
6、分账接口的订单不支持退款接口退款,如果分错再次调用分账接口分账。
7、退分账金额计算策略为 “厘舍去” 例:
原订单10元,分账5.05元,原订单退款5元.  退分账金额为 5.05*(5/10) = 2.525 ≈ 2.52。
8、支持指定退交易分账的金额。
9、平台作为收款方或者分账方,只能使用基本户,暂时无法使用存钱罐账户。当平台为分账方时支持平台余额待结算账户。
例:分账(分账类型为分账),付款人支持平台余额待结算账户,收款人不支持平台余额待结算账户;分账(分账类型为退分账),收款人支持平台余额待结算账户,付款人不支持平台余额待结算账户;不支持分账到平台余额待结算账户
10、分账金额不能大于原订单金额。

11、收款方为个人且实名成功,则交易中自动开户。
12、该接口与交易创建接口中的分账的作用没有区别。
13、该接口收款方的账户类型不支持存钱罐。

 


18-12-新浪支付_微信支付接入专项指导_v1.2.pdf

新浪支付-收付款产品接口风控参数说明-V[0.4]_release.pdf


与此文章相关还有:

like article