接入指南

1.银行机构准备工作

签约内容:支付宝业务经理直接为银行机构签约“当面付”以及“银行间连商户入驻”产品包。

测试账号:在银行机构完成正式账号签约前,可使用支付宝沙箱环境直接进行测试(了解沙箱环境)。

对账SFTP申请:正式账号签约完成后,由支付宝业务经理为银行机构申请SFTP账号,并且需要银行机构提供公网/专线出口IP,用于添加至支付宝防火墙白名单。如果需要支付宝为无交易日提供空报表文件,也请在提交SFTP申请时提出所有业务需求,统一由业务经理提交申请。

专线申请:下载并填写专线申请模板,使用工作邮箱发送至间连专线network@list.alibaba-inc.com申请开通专线,专线相关问题可邮件咨询或在项目群咨询。如果银行机构已有专线连接至支付宝,则可复用该专线。如果银行机构同时有申请专线和专线SFTP的需求,需要在申请专线的流程中说明。

清算配置:正式账号签约完成后,由支付宝业务经理为银行机构申请清算配置,务必在业务上线前验证清算资金是否正确。同行D+1自然日约7:00发起打款(周五交易周六清算到账,周六交易周日清算到账),跨行T+1工作日(周五周六交易周一清算到账,国家法定节假日顺延)约9:30发起打款。

泛金融账号配置:正式账号签约完成后,由支付宝业务经理为银行机构申请泛金融账号配置,请务必在使用正式账号测试之前完成,否则交易会报错“支付失败,本商户没有权限使用该产品”,“error_seller_certify_level_limit“或”账号认证等级受限”。如出现该错误请联系支付宝业务经理确认正式账号配置流程是否完成。

source字段如何获取:对于已有企业支付宝账户的银行机构和ISV,请填写企业支付宝账号的partner_id(简称pid,点此登录查看PID);对于没有企业支付宝账户的ISV,可以自助签约企业支付宝(点此注册企业账户点此查看注册帮助);对于没有企业支付宝账号的银行机构,请联系支付宝业务经理进行签约。

2.整体技术接入流程

商户入驻流程(商户入驻接入指南):受理机构首先调用支付宝分级商户入驻接口(ant.merchant.expand.indirect.create),完成商户入驻后,支付宝会返回唯一标识该商户的编号(sub_merchant_id简称smid),受理机构可通过(ant.merchant.expand.indirect.query)接口查询入驻信息,通过(ant.merchant.expand.indirect.modify)接口修改信息,目前无删除接口和查询列表接口,也无管理系统可直接进行入驻等操作。

支付流程(当面付接入文档):商户入驻成功,获取smid后,银行机构通过支付接口的sub_merchant字段传递smid,从而发起间连当面付交易。store_id字段标识受理商户的门店号,terminal_id标识受理商户的终端号,由于监管要求,间连当面付需要根据真实情况传递间连受理商户的门店、终端编号。如门店二维码需上传门店号、终端机具需上传终端号。

3.开发前必读

3.1测试环境

测试使用蚂蚁沙箱环境(一个与支付宝生产环境隔离的独立环境,有独立的支付宝APP、测试网关、测试参数)。使用个人/企业支付宝账号登录沙箱后,系统会自动分配对应沙箱测试账号,并开通所有接口权限。
测试支付使用沙箱支付宝钱包。生成密钥并上传密钥(引导教程),专线申请同准备工作专线申请,借贷标识可通过绑定测试银行卡进行测试,沙箱环境对账单为手工生成,需自行输入账单相关信息后自助生成账单
当面付Demo(点击访问)最新SDK下载(点此下载

3.2资金流向和打款时间

受理商户的交易资金会实时进入银行在支付宝系统的内部户。并根据是否同行决定打款时间。同行D+1自然日约7:00发起打款(周五交易周六清算到账,周六交易周日清算到账),跨行T+1工作日(周五周六交易周一清算到账,国家法定节假日顺延)约9:30发起打款。

3.3退款条件、顺序、流向和时间

当面付退款时,支付宝首先会检查当天该间连受理商户的交易收益余额是否足够退款,如果充足则可以退款,该受理商户的收益资金退还给顾客后,支付宝再向银行(受理机构)退还手续费。如果该受理商户今日收益不足,则退款报错余额不足。如银行希望以银行维度计算头寸,需要向支付宝业务经理提出申请,由支付宝业务经理改变头寸控制,修改为银行维度退款头寸后,只要银行进入收入足够,则商户即可退款。
支付宝退款为原路退回,所以退款时无需并且也不能指定退款账号。退款请求发起后,支付宝会实时向支付渠道发起退款请求并向商户返回退款受理结果,只要退款返回受理成功,则标识该笔退款一定会退成功。用户退款金额到账时间根据用户使用的银行来决定。如果用户支付渠道为支付宝体系内的支付渠道,如余额、余额宝等,退款金额会实时到账。支付宝默认支持三个月内的退款,在银行与支付宝签约时指定,如果需要支持更长的退款时间,请在签约时联系支付宝业务经理说明。
当面付退款遵循优先的支付工具先退,还有剩余的资金就再退下一个支付工具。支付工具优先级:
PCREDIT(花呗)->BANKCARD(银行卡)->ALIPAYACCOUNT(支付宝账户)->MCARD(商家储值卡)->PCARD(预付卡)->POINT(集分宝)->COUPON(支付宝红包)->DISCOUNT(折扣券)->MCOUPON(商户红包)->MDISCOUNT(商户优惠券)
举例:
订单金额100,用户实付70,使用商户优惠券20,集分宝抵扣10元,发生部分退款的退款顺序如下:
1、退款75元,实付70退完,集分宝退5元;
2、退款85元,实付70退完了,集分宝退10元,商户优惠券退5元。

3.4手续费计算

支付手续费按单笔交易的商户实收(receipt_amount字段)计算。计算公式为实收金额 支付手续费率后四舍五入到分,计算结果小于1分钱则免手续费。退款手续费按退款金额比例退还手续费,计算公式为退款金额 支付手续费率后四舍五入,计算结果小于1分钱不退手续费,多次退款情况下,最后一笔退款会全单退还手续费。

3.5对账单获取

对账单中的数据来源于自然日期间所有发生账务变动的交易,即所有支付成功的交易、所有因撤销(支付反交易)或者退款导致的退款交易。对账单即清算报表交易时间为交易付款时间(gmt_payment),在查询接口为本次交易打款给卖家的时间(send_pay_date),两者同交易用户付款时间。对账单数据字典(点此访问
获取时间:T日交易的对账文件一般在T+1日9点可提供下载,并且资金同时清算至对应的银行账户,供受理机构进行对账和为受理商户清分。
平台下载:通过支付宝商家中心b.alipay.com管理系统下载对账单
接口下载:查询对账单下载地址接口文档
SFTP获取:SFTP账号申请完成后,受理机构可以通过分配的账号密码登录SFTP服务器下载对账文件,SFTP域名为antsftp.alipay.com,端口22
SFTP目录结构和生成规则:download/YYYYMMDD/pid0156_YYYYMMDD.zip,目录结构为download目录下,根据日期建立子目录,子目录中包含对账文件,文件名以银行pid加上0156(人民币币种代码)再加下划线和日期构成。是否生成空账单和账单名称中英文选择,请在申请SFTP的时候向支付宝业务经理说明。

4.当面付接入方案

4.1条码支付(调用流程

条码支付一般用于商超便利店、快餐水果店等用户购物后需要到收银台结账的场景,一般支付流程为商户收银员扫描用户支付宝手机付款码完成支付(付款码可以离线生成,方便顾客在地下超市等弱网环境使用)。当收银机通过受理机构服务器向支付宝发起条码支付请求时,请求结果可能有下面三种情况。
一、支付宝返回明确的支付成功(返回码10000)或者失败(除去系统异常),受理机构可以直接将支付结果反馈给终端/收银机,并进行成功或失败的相应业务处理;
二、支付宝返回用户正在支付中(返回码10003),此类情况大多是由于支付宝风控系统触发安全检测机制,或支付金额大于等于1000元,从而要求用户输入密码验证身份。此时受理机构服务端需要通过外部订单号(out_trade_no)调用当面付查询接口(alipay.trade.query)查询当前交易的状态(在客户端支持多线程的情况下,可以同步信息至终端/收银机,告诉收银员当前用户正在支付中,提高收银员体验)。如果当前交易查询结果依然为用户支付中,则等待一段时间后再次调用查询接口查询当前订单状态,如此反复查询若干次(推荐每隔5秒查询一次,重复查询12次,即最长查询时间为60秒)后,如果查询结果依然为用户支付中,则用户支付时间超过我们规定的支付超时时间,系统需要马上调用当面付撤销接口(alipay.trade.cancel)将当前交易撤销,撤销结果就是当前交易被关闭,并且用户无法在手机上继续完成支付,收银员可以重新发起支付流程,并提示用户尽快输入支付密码。(tip:合作伙伴可记录付款码数字后等待3分钟再进行测试,此时即可唤起收银台,而不用使用大金额)
三、支付宝返回系统异常(返回码20000)、或由于网络原因未接收到支付宝返回的应答,或者网络出现异常,此时受理机构服务端不知道当前订单交易状态,所以受理机构需要调用当面付交易查询接口查询当前订单交易状态,然后根据查询结果成功与否做相应处理。如果查询也超时,可以重试一次,当超过设置的最大重试次数后依然查询不到正常结果,则可以记录该笔状态未知的交易,等待后续处理。
条码支付不支持异步通知,因为线下场景复杂,网络质量差异大,而且实时性要求很高,通过异步通知时间不可控,通知可能丢包从而不能通知到终端,所以只能通过终端主动发起交易查询。返回码说明

4.2门店固定二维码支付(一码多付方案

门店固定二维码支付主要适用于没有对接条码支付的小店,商家在店铺收银台放置固定二维码,用户使用支付宝APP扫描该二维码,即可用支付宝进行支付。如果用户使用微信、百度钱包等其他APP扫码,则可使用其他第三方支付平台进行支付。即所谓“一码多付”。
门店固定二维码支付需要由间连受理机构生成门店固定二维码,每个固定二维码需要能标识当前门店,当用户使用手机APP扫描二维码后,会使用对应APP内置浏览器打开受理机构开发的支付网页,受理机构可以根据浏览器的User-Agent识别出用户扫码的APP类型。当用户在支付页面输入订单金额(必填)、不可打折金额(选填)后,点击付款即调用对应第三方支付平台的创建订单接口,支付宝对应为alipay.trade.create接口,订单创建完成后,通过JSAPI在付款页面唤起收银台,从而完成支付,支付结果可以通过后台异步通知的方式同步给受理机构,异步通知参数同扫码支付异步通知参数。用户支付成功后,前台页面跳转至间连受理机构开发的支付成功页。
支付成功页必须体现支付结果、订单金额、用户支付金额、受理商户名称、商户订单号(或支付宝交易号)、受理机构为该页面提供技术支持的标识。建议体现受理店铺名称、商品信息、付款时间。

4.3扫码支付说明

扫码支付主要用于正餐,用户坐下点餐后,POS机或收银设备通过扫码支付接口生成订单码,打印成小票二维码,用户使用支付宝钱包扫码支付,扫码支付完成后,支付宝会通过notify_url参数指定的回调地址,完成支付成功的异步通知。由于扫码支付在二维码被用户扫描之前,只确定了收款金额、收款方等信息,不能确定付款用户,而且产生的二维码容易被传播,所以存在一定的安全风险,二维码有可能被误扫并被用户支付掉,所以不推荐使用扫码支付。如果需要使用扫码支付,一定要与支付宝技术支持确认业务场景,扫码支付交易超时时间(timeout_express)需要根据业务需求设置尽可能短的订单超时时间,以免交易被用户误支付而产生客诉。

4.4接口参数说明

当面付包含条码支付(alipay.trade.pay),用于收银员使用扫描枪扫描用户支付宝手机app的付款码进行支付;统一收单交易创建接口(alipay.trade.create),主要用于在支付宝手机app的H5页面内的支付,首先通过该接口创建支付宝订单,然后使用支付宝JSAPI唤起收银台进行支付;扫码支付(alipay.trade.precreate),用于POS机产生二维码或打印二维码小票,用户使用支付宝手机app扫二维码支付;三个当面付接口API的参数基本相同。
store_id:商户门店号。接口文档上为选填,但是间连业务必须要传的参数,用于标识受理商户交易所发生的门店,如果银行机构没有为商户分配门店号,建议使用数字加字母的方式分配门店号。比如上海的肯德基门店号可以编号为SHKFC001、 SHKFC002。
terminal_id:商户终端号。接口文档上为选填,但是间连业务必须要传的参数,用于标识受理商户交易所发生的终端,按照8583报文规范,银行机构的交易报文是包含此字段的,需要透传至支付宝。
sub_merchant:间连受理商户结构,为一个json字符串,银行ISV将商户入驻得到的sub_merchant_id填写至merchant_id子字符串中,用于标识该交易来自的受理商户。该字段间连业务必填,如果银行机构的受理商户信息字段未填写,或者填写了未入驻的受理商户编号,会返回“参数无效”的错误,需要银行ISV在调用当面付接口之前检查受理商户编号是否有传,并且该受理商户编号是否已经入驻。
buyer_id:支付宝用户唯一id,当面付统一收单交易创建接口必填,通过用用户授权的方式获取会员信息
timeout_express:支付宝订单有效期。需要注意在预下单接口中的行为,预下单,顾名思义是未创建订单,因为创建订单需要付款人、收款人、金额三要素,预下单只提供了金额和收款人,并没有付款人,所以接口返回的是一个预下单二维码,此时订单并没有生成,等待用户扫码后才创建支付宝订单。所以timeout_express的计时是从用户扫码创建订单时开始计算。而未扫码的时候,二维码有效期是2小时。如果没有传timeout_express的话,支付宝订单有效期为一周左右。
disable_pay_channels:用于当面付接口限制支付渠道(全部渠道点此访问
merchant_order_no:当受理机构调用支付宝接口时需要自行生成订单号时,通过该字段传递渠道订单号,从而支付宝账单中可根据该字段展示商户端原始订单号,方便商户端系统验证以及扫码退款。

4.5接入规范化

为规范化系统集成、杜绝因系统对接原因造成的单边帐,我们提供了相关处理方案,需要在技术设计时加以考虑。
异步通知特性(文档

  • 什么情况下发起通知:当支付宝交易系统中存在该交易,并且该交易状态发生变化时,才可能发起通知。如用户扫码创建订单后支付宝发起交易创建通知,用户付款成功后发起交易成功通知等。
  • 如何获取通知信息:支付宝通过HTTP POST方法,以表单的形式通知消息,开发者可以通过获取表单参数的形式获取对应字段值。如获取交易状态字段(trade_status)可参考如下方法,java参考request.getParameter("trade_status");asp参考reques.Form("trade_status");php参考$_POST['trade_status']。
  • 商户接收通知地址的要求:通知地址公网可访问,且仅支持80和443端口,地址形式如 https://www.test.com/pay/notify。对于https地址,商户证书必须为认证机构颁发的证书,不可使用非授信组织颁发的测试证书,如不可使用自行颁发的证书。
  • 如何判断交易成功:首先签名(sign)必须验证通过,其次判断交易状态(trade_status)必须为支付成功状态(如TRADE_STATUS),此时可保证该通知为支付宝支付成功通知。在此基础上,可以额外判断订单号是否在商户系统存在、订单金额是否与下单时金额一致等,以加强订单相关一致性校验。
  • 处理通知后如何返回:如果商户系统处理业务成功,则返回success字符串。否则返回其他信息、抛异常或者无返回,支付宝均会认为商户系统处理失败,并进行重复通知。
  • 如何重复通知:当第一次通知失败后,支付宝以4m,10m,10m,1h,2h,6h,15h的时间间隔,在25小时内完成8次通知,以防止通知丢失等异常情况。
  • 关于通知无序性说明:由于互联网中存在拥塞、丢包、重发等现象,所以支付宝异步通知可能在极端情况下以未定义的顺序到达商户服务端,比如在开启了通知用户支付中和通知交易成功的情况下,可能用户支付中的通知处理失败导致触发支付宝重发支付中通知,又或可能存在由于网络延时、丢包等原因,导致商户系统接收到交易成功通知后,接收到相同交易的交易创建通知(甚至重复接收到支付成功通知),此时需要商户端对支付成功通知做且仅做一次成功业务的处理。

借贷标识
间连当面付提供了交易借贷标识字段,在当面付条码支付(alipay.trade.pay),交易查询(alipay.trade.query),以及主扫支付异步通知结果中,以fund_bill_list字段标识。该字段为json结构体,结构如下,当资金渠道fund_channel为银行卡渠道(BANKCARD)时,可以通过fund_type字段获取该交易借贷类型。其他情况下fund_type字段为空。(注意,由于历史原因,在当面付异步通知中,资金渠道各参数分别为驼峰表示,资金渠道为fundChannel,借贷标识字段为fundType,请一定注意)
目前测试账号已支持借贷标识,银行机构可以使用测试账号进行测试。银行机构正式账号借贷标识开通需要银行机构联系对应支付宝业务经理,并通过邮件进行申请,请提供交易的appid和对应pid,发送支付宝业务经理邮箱,并抄送间连借贷标识flag@list.alibaba-inc.com进行审核处理。

参数 类型 是否必填 最大长度 示例值 描述
fund_channel 字符串 32 BANKCARD 资金渠道名称(银行卡渠道为BANKCARD,全渠道明细
amount 字符串 20 11 渠道支付金额
real_amount 字符串 16 11 渠道实付金额(目前只在商户预付卡情况下才使用,间连无需考虑)
fund_type 字符串 64 32 渠道的借贷类型(目前只在银行卡类型才返回)
借(借记卡):DEBIT_CARD
贷(信用卡):CREDIT_CARD
混合(非常少的网银渠道):MIXED_CARD

5.上线前准备

5.1业务验收

为了减少线上业务风险和故障,请银行ISV在业务上线前务必联系支付宝技术支持进行间连当面付业务验收(点此下载checklist)。验收点如下:
1、商户入驻参数传递是否规范,如是否上送受理商户名称、上送信息是否规范
2、当面付受理商户信息、终端门店号是否规范传递等
3、当面付用户输入密码时的处理逻辑
4、网络异常时、支付宝返回异常等错误码时客户端的处理
5、银行账号清算打款的验证以及对账验证

5.2压力测试

为保证上线系统稳定,上线前请务必进行生产环境压测,并将压力测试报告(无格式要求)发送至间连保障safeguard@list.alibaba-inc.com备案,访问支付宝压测环境

5.3获取银行正式账号

银行与支付宝完成合同签约后(请银行业务和支付宝业务协作并进行双方商务推动),支付宝会向银行在支付宝的预留邮箱发送设置初始密码的邮件。合同签约完成后,登录开放平台管理中心可以看到支付宝创建好的服务窗应用(包含间连当面付接口权限),按照教程设置应用,就可以切换为正式账号进行生产测试了。

6.业务上线后必读

6.1异常处理流程

如何判定交易成功,用户和商户系统交易状态不一致时该以谁为准?
判断交易是否成功必须以商户收银系统状态为准。商户收银系统的状态可以通过支付响应报文获取或通过商户系统向支付宝服务端主动查询获得。如果用户银行扣款但是支付宝交易失败,用户所扣资金会在一个工作日后原路退回。此时需要商家引导用户再付款一次,并将第一笔交易进行撤销。如果商户端查询支付宝交易不存在或者状态为失败,但是顾客提供了支付宝APP交易成功的账单截图,则首先需要怀疑顾客伪造了账单,可以进一步让顾客提供发卡方扣款凭证等材料进行证明,商户依然按照商家系统,或支付宝服务端交易状态对待该笔交易。

6.2疑似单边帐排查

对于控制上线后由于系统原因造成单边帐投诉风险,支付宝提供了云监控、健康度等一系列机制供银行机构和ISV自查。对于因单边帐投诉过高的银行机构和ISV,支付宝会启动整改机制。(如何减少单边帐

6.3人传人红包不能核销

如遇到红包不能核销,可能有如下几方面原因:
1、支付接口中使用了我们不推荐的支付渠道白名单字段,以白名单的方式限制了比如只能使用储蓄卡的方式进行支付,而红包是作为其他支付渠道进行消费的,所以无法享受红包优惠,如系统有限制过支付渠道,请先排查是否限制了红包支付渠道的使用。
2、如系统未限制支付渠道,则交易很大可能是触发了支付宝风控系统的相关模型,如用户为真实交易,可统一按如下格式,通过银行的工作邮箱向风控申诉for-justice@list.alibaba-inc.com发送申诉邮件,风控团队会在一个工作日内完成响应和申诉处理。
红包不能核销-xxxxx门店小卖部

商户全称 xxxxxxxx门店小卖部
商户smid(间连子商户号) 2088xxxx1234
支付宝交易号(支付宝账单页可找到) 201712122100100xxxx1234
商户背景信息(注明是否实体、连锁、商户性质。
越完整申诉成功率越大,文件可通过附件上传)
商户为实体门店,属于早点摊位,非全国连锁,需要申请解限

6.4风控申述流程

如果用户在付款(或商户在收款)过程中遇到类似ALI40793等错误码,或提示“商户收款存在异常”等各种“收款异常”的错误提示时,说明该商户交易被风控系统拦截,拦截原因一般涉嫌赌博、刷单、诈骗等。
如果商户有异议,可由入驻的银行进行申诉(由于申诉的时候需要提供银行方的支付宝账号,所以商户务必通过银行来申诉)。
申诉方式:
1、登录https://riskgo.alipay.com进行自助申诉(推荐,银行、ISV首次登录需要完善联系人信息,按页面提示录入即可,使用文档下载
2、申诉电话:95188(工作时间:8:00 - 24:00;申述流程及材料下载)。

6.5常见收银台风控拦截文案和处理方法

类型 用户提醒文案 安全拦截原因 处理结果 商户如何应对
交易失败 请警惕兼职刷单、投资,假冒客服、公检法及熟人等骗局。若确认无风险,请重试。 交易嫌疑有欺诈风险 仅拦截该笔风险交易,可以尝试重新付款 若交易正常,可继续支付,无需申诉
刷单有风险,不要轻信“高佣金”、“先垫付”等兼职骗局,为了你的资金安全,已中断本次操作。 交易嫌疑有兼职刷单欺诈风险 仅拦截该笔风险交易,未暂停商户全部交易 需商户从事正常交易(不会拦截),若商户核实后无异常,可申诉
本次交易可能存在风险,请再次确认商户身份,谨慎付款 交易嫌疑有欺诈风险 仅拦截该笔风险交易,未暂停商户全部交易 需商户从事正常交易(不会拦截),若商户核实后无异常,可申诉
该商户被多人投诉,本次交易因风险被中断。请警惕;兼职刷单;高额返利;套现;等骗局,谨慎付款。 商户被多人投诉且被定性为欺诈 暂停商户全部交易 若商户无异常,可申诉
商户收款存在异常,暂时无法向该商户付款; 交易嫌疑有赌博风险 拦截该商户的嫌疑赌博交易 需商户从事正常交易(不会拦截),若商户核实后无异常,可申诉
本次付款不支持信用卡,请更换储蓄卡付款 交易嫌疑有套现风险 仅拦截该商户的信用卡嫌疑套现交易 需商户从事正常交易(不会拦截),若商户核实后无异常,可申诉
校验 你正在付款#totalFee#元,警惕兼职、高额回报、套现等骗术。验证码#AckNum#,唯一热线:95188 交易嫌疑有欺诈风险 仅校验提醒,未拦截 可继续支付,无需申诉
交易失败 商户收款存在异常,已中断本次操作。 交易嫌疑线下产品用于线上交易风险 拦截该商户线下产品的线上交易 需商户从事正常交易(不会拦截),若商户核实后无异常,可申诉(仅线下实体)

7.ISV额外工作

以下工作需要由ISV完成,银行无需操作。
入驻支付宝开放平台:银行ISV帮助银行对接支付宝,ISV自身必须要有支付宝账号,而且需要入驻支付宝开放平台(ISV开始开发
获取银行授权:当系统商帮银行开发系统对接支付宝,并且系统由系统商维护时,银行可通过第三方应用授权,将银行的支付宝账号权限授权给系统商进行当面付交易而无需向系统商提供账号密码。获取银行授权前,ISV需要向支付宝业务经理、间连子商户submerchant@list.alibaba-inc.com发送申请挂载接口包邮件,说明业务原因、授权的银行全称、ISV的appid,待接口包挂载后,再联系银行授权,获取银行授权令牌后,通过在请求公共参数中带上银行授权令牌发起请求。

onlineServer