PC网关支付

一、支付产品介绍

1.1 产品概述

用户在商户页面选择网关支付，跳转至银行网关验证持卡人身份信息和银行账户信息后，向持卡人银行（发卡行）账户发起支付指令扣划资金的交易。持卡人可通过网上银行进行付款，实现商品购买网银支付。

1.2适用场景

根据场景需求，通联提供PC、H5、SDK网关支付相关接口，供商户调用发起网关支付。网关支付在多个领域都有广泛的应用：

业务场景	场景特点	典型应用案例
电商平台 PC 端	用户在PC端商户网站选购商品，通过网关支付完成在线购物	品牌自营PC官网、综合电商 PC 商城
企业对公服务	企业用户在PC端完成对公转账、服务采购等大额交易，支持全国主流银行企业网银直连，满足大额、合规的对公支付需求	企业SaaS软件年费订阅、云服务资源采购、供应商货款支付、企业内部采购平台
航空旅游出行	用户在PC端预订标准化大额服务，通过网关支付完成交易	航空公司官网机票预订、连锁酒店集团PC官网订房
教育医疗政务	用户在PC端通过官方渠道缴纳各类规费，通过网关支付完成资金划转	高校官网学费住宿费缴纳、公立医院住院缴费、职业资格考试报名费缴纳

1.3商户入网

1.3.1准入标准

1.商户主体合规合法，营业执照在有效期内，不属于通联支付禁止准入行业类目

2.完成通联收银宝商户号注册与实名认证，无不良经营记录与风控黑名单记录

3.商户经营内容与备案类目一致，不得超范围开展支付业务，不得转借支付接口

二、技术开发准备

第一步：密钥获取（云梯）

点击密钥管理获取商户公钥、私钥及加密密钥。

第二步：公共参数获取（云梯）

点击通联公钥下载通联公钥

第三步：对接规范

调用通联接口，统一使用POST形式提交，数据格式统一为JOSN，相关SDK及签名方法如下：SDK示例：https://prodoc.allinpay.com/doc/1360/

三、开发指引

3.1核心开发内容

开发模块	关联接口	接口描述
订单生成	【2085-消费申请】	支付模式固定传值payMode=GATEWAY_VSP，传入订单信息后返回支付网关跳转URL
支付结果回调	【订单结果异步通知】	通联主动推送支付终态结果至商户回调地址，商户验签通过后必须返回字符串success
订单查询	【3001-订单状态查询】、【3002-订单结果查询】	未收到异步通知时，主动查询订单最终状态，避免漏单
退款（可选）	【2294-退款申请】	支持全额/部分/多次退款，累计退款金额不得超过原订单实付金额
订单对账	【4002-对账单文件下载】	获取日度 / 月度交易、退款、手续费明细对账文件

3.2对接规范

测试地址：https://ibstest.allinpay.com/yst/yst-service-api/tx/handle

生产地址：https://ibsapi.allinpay.com/yst/yst-service-api/tx/handle

支付产品固定值：payMode=GATEWAY_VSP

请求方式：POST，数据格式 JSON，编码 UTF-8

开发文档：https://prodoc.allinpay.com/doc/1360/

3.3消费流程

1.用户在商户PC端页面选购商品/服务，提交订单并选择网关支付

2.页面跳转至网关支付页面，用户选择具体支付银行（中国工商银行、招商银行、中信银行、兴业银行等）

3.选择银行网银的用户跳转至对应银行官方网银页面，输入银行卡号、密码完成身份验证与付款；

4.支付完成后，页面自动跳转回支付结果页面，展示支付成功/失败信息

PC网关支付必填字段

字段	字段类型	是否必填	字段说明
payMode	JSONObject	是	支付模式固定传值：GATEWAY_VSP
reqTraceNum	String	是	商户订单号，全局唯一，不可重复
orderAmount	Long	是	订单总金额（单位：分）
payAmount	Long	是	实际支付金额（单位：分）

核心返回参数

字段	字段类型	是否必填	字段说明
respCode	String	是	业务返回码00000：代表接口调用成功66666、66667：交易处理中，需等待异步通知或调用订单查询接口获取终态其他返回码均代表接口调用失败
respTraceNum	String	是	通联系统生成的唯一订单号，用于后续订单查询、退款、对账等操作
chnlPayInfo	String	否	支付成功，返回网关支付跳转链接
respMsg	String	是	业务返回说明

3.4退款流程

PC网关支付退款支持全额退款、部分退款、多次退款，累计退款金额不得超过原订单实付金额，退款资金将原路退回，退款时效取决于发卡行清算规则。

退款必填参数

字段	字段类型	是否必填	字段说明
orderAmount	Long	是	本次退款金额（单位：分），单次退款金额需大于 0
reqTraceNum	String	是	商户退款单号，全局唯一，不可重复
orgRespTraceNum	String	否	原通联订单号（与原商户订单号二选一）
orgReqTraceNum	String	否	原商户订单号（与原通联订单号二选一）
orgTransDate	String	否	原订单交易日期，格式：yyyy-MM-dd（传原商户订单号时必填）
respUrl	String	否	退款结果异步通知地址，需为 HTTPS 域名，用于接收退款成功 / 失败通知

退款操作规则

1.调用退款接口时，orgRespTraceNum（原通联订单号）或orgReqTraceNum+orgTransDate（原商户订单号 + 原交易日期）两组参数二选一即可，无需重复传入。

2.多次退款时，每次退款需生成唯一的商户退款单号，避免重复退款；累计退款金额不得超过原订单实际支付金额，超出将被系统直接拒绝。

3.退款申请提交后，通联支付系统实时受理，银行处理时效为1-3 个工作日，退款结果将通过 respUrl 异步推送至商户系统；商户也可调用订单查询接口查询退款状态。

4.订单已完成资金结算、超过银联扫码支付退款有效期的，将无法通过接口发起退款，需通过线下人工方式处理。

3.5订单管理

PC网关支付订单在商户系统内需遵循统一状态流转规则，禁止自定义订单状态，确保交易全链路可追溯、可对账、可排查：

订单类型	订单状态	场景（根据产品扣单独的逻辑）
消费	0：进行中	待支付：商户已调用消费申请接口，成功获取支付网关 URL，等待用户跳转支付支付中：用户已跳转至网关支付页面，正在进行付款操作
	1：交易成功	支付成功：银行已完成扣款，通联已推送支付成功结果至商户系统
	2：交易失败	支付失败：用户主动取消支付、银行卡余额不足、风控拦截等原因导致支付终止已关闭：订单超过有效支付时长未支付，系统自动关闭；或商户主动关闭未支付订单
退款	0：进行中	退款中：商户已提交退款申请，通联已受理，银行正在处理退款流程
	1：交易成功	退款成功：退款资金已原路退回用户付款账户，退款流程正式完结
	2：交易失败	退款失败订单已清算、超过退款有效期、支付通道拒绝、商户账户余额不足等原因导致退款失败

3.6订单对账

为满足商户财务对账、资金核对需求，通联为商户提供多渠道对账文件下载方式，对账文件包含所有网关支付的交易、退款、手续费等明细，可与商户其他支付方式的对账文件合并展示，支持按日/按月查询。具体方式如下：

门户下载对账文件：可在商户门户【对账单下载】菜单下载对账文件

调用API接口获取对账文件

商户可调用接口自动下载对账文件，支持日度、月度对账文件获取，接口详情参考通联官方文档：https://prodoc.allinpay.com/doc/476/；接口调用支持批量下载、定时拉取，适配商户财务系统自动化对账需求，文件格式为CSV/Excel，包含订单号、交易金额、退款金额、手续费、交易时间、支付方式等核心字段。