recyc/fengketrade

Fork 0

mirror of https://gitee.com/liuxioabin/fengketrade.git synced 2026-04-17 21:03:17 +08:00

Billy 2dc5ff423f 接口文档

2025-10-21 10:29:22 +08:00

25 KiB

Raw Blame History

建行生活API接口文档

文档版本: v1.1.6 生成时间: 2025-01-21 来源: 建行生活输入通讯报文v1.1.6【最新】.xlsx

📑 目录

1. 修订记录
2. 接口规范
3. 核心接口

1. 修订记录

修订日期	修订内容	上线状态
2021-11-22	接口增加字段PLAT_MCT_ID、增加退款和订单查询接口	已上线
2022-11-11	增加订单子系统新接口	已上线
2023-03-28	订单推送新增GOODS_NM/PLATFORM_POINT两个字段	已上线
2024-01-24	修改报文顺序、内容	已上线
2024-02-23	订单更新新增PLATFORM_POINT、PAY_MODE、GOODS_NM字段	已上线
2024-02-26	增加权益信息查询接口	已上线
2025-06-09	增加SKU_LIST字段	待上线

2. 接口规范

2.1 公共报文头

请求体（CLD_HEADER）

栏位项目名称	中文名称	栏位属性	必须	数据项说明
CLD_TX_CHNL	通讯渠道号	C	Y	跟svcid相同，YS44开头的字符串
CLD_TX_TIME	通讯时间	C	Y	yyyyMMddHHmmss（请求通讯时间）
CLD_TX_CODE	服务ID	C	Y	如A3341TP01
CLD_TX_SEQ	全局事件流水号	C	Y	唯一流水号

响应体（CLD_HEADER）

栏位项目名称	中文名称	栏位属性	必须	数据项说明
CLD_TX_CHNL	通讯渠道号	C	Y	跟svcid相同，YS44开头的字符串
CLD_TX_TIME	通讯时间	C	Y	yyyyMMddHHmmss（响应通讯时间）
CLD_TX_CODE	服务ID	C	Y	如A3341TP01
CLD_TX_SEQ	全局事件流水号	C	Y	唯一流水号
CLD_CODE	响应码	C	Y	详见响应字典
CLD_DESC	响应描述	C	N	响应描述信息

2.2 通讯地址

UAT 测试环境

http://128.192.179.60/uat_new/tp_service/txCtrl/server?txcode=XX

生产环境

https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=XX

注意: XX 为服务ID，每个接口不同

接口地址示例

接口	服务ID	完整URL
订单推送	A3341TP01	https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP01
订单更新	A3341TP02	https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP02
订单查询	A3341TP03	https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP03
订单退款	A3341TP04	https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP04
权益查询	A3341TP05	https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP05
订单补充信息	A3341TP13	https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP13

提示: 当调用接口出现404时，请求头中加上：

Accept: application/json

Content-Type: application/json

2.3 接口索引

服务码	服务名称	服务类型	版本	备注
A3341TP01	服务方订单推送	直接调用	01	新接口
A3341TP02	服务方订单更新	直接调用	01	新接口
A3341TP03	服务方订单查询	直接调用	01	新接口
A3341TP04	服务方订单退款	直接调用	01	新接口
A3341TP05	订单支付权益查询	直接调用	01	新接口
A3341TP13	服务方订单补充信息	直接调用	01	新接口

3. 核心接口

3.1 A3341TP01 - 服务方订单推送

接口说明

项目	说明
服务码	A3341TP01
服务名称	服务方订单推送
服务类型	直接调用
功能描述	用户在服务方下单成功后推送，支付时会校验订单信息
URL	https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP01

请求参数（CLD_BODY）

字段名	中文名称	数据类型	必须	说明
USER_ID	客户编号	varChar(30)	Y	建行生活的会员编号
ORDER_ID	订单编号	varChar(30)	Y	用户订单号，建行生活订单列表展示的订单订单号（对应收银台USER_ORDERID字段，支付时会校验订单信息）
ORDER_DT	订单日期	Char(14)	Y	yyyyMMddHHmmss
TOTAL_AMT	订单原金额	number(15,2)	Y	第三方原始金额
PAY_AMT	订单实际支付金额	number(15,2)	N	支付网关支付金额。此处如果为空必须在状态变更时推送
DISCOUNT_AMT	第三方平台优惠金额	number(15,2)	N	第三方平台优惠金额。此处如果为空必须在状态变更时推送
DISCOUNT_AMT_DESC	第三方平台优惠定义	varChar(1000)	N	各金额之和等于第三方平台优惠金额，格式：名称=金额\|@\|名称=金额
ORDER_STATUS	订单状态	Char(1)	Y	0-待支付 1-支付成功 2-已过期 3-支付失败 4-取消
REFUND_STATUS	退款状态	Char(1)	Y	0-无退款 1-退款申请 2-已退款 3-部分退款
INV_DT	订单过期日期	Char(14)	N	yyyyMMddHHmmss
MCT_NM	商户名称	varChar(218)	Y	商户名称
CUS_ORDER_URL	自定义订单链接	varChar(256)	N	订单详情地址(需要推送完整的订单详情URL)
OCC_MCT_LOGO_URL	服务方商户logo图片地址	varChar(512)	N	必须以http://或https://开头
PAY_FLOW_ID	支付流水号	varChar(30)	Y	支付流水号，调用收银台时上送的支付流水号（对应收银台ORDERID字段）
PAY_USER_ID	支付客户编号	varChar(30)	N	支付客户编号
TOTAL_REFUND_AMT	累计退款金额	number(15,2)	N	若支持多次退款，此次推送的金额为多次退款累计已退金额
PREFTL_MRCH_ID	门店商户号	varChar(50)	N	999的门店商户号，商户终端对应的建行生活门店编号
PAY_MRCH_ID	支付商户号	Char(15)	Y	调用收银台时上送的商户号
PLAT_MCT_ID	服务商门店编号	varChar(21)	N	外部平台商户号，不为空以这个字段为准
OCCCOUP_DISCOUNT_AMT	建行专属优惠金额	number(15,2)	N	第三方平台的建行专属优惠金额
OCCCOUP_DISCOUNT_AMT_DESC	建行专属优惠定义	varChar(1000)	N	格式：券实例号=金额\|@\|券实例号=金额
SPECIAL_STATUS	特殊附加状态	Char(5)	N	P0000-正常状态 P0001-待使用 P0002-待审核 P0003-已支付 P0004-待退款 P0005-退款中 P0006-待发货 P0007-已发货 P0008-进行中 P0009-预定中 P0010-预定成功 P0011-预定失败 P0012-已入住 P0013-已离店 P0014-未入住 P0015-配送中 P0016-出券中
PLAT_ORDER_TYPE	服务方订单类型	Char(5)	N	T0000-普通类型 T0001-洗车 T0002-加油 T0003-停车 T0004-修车 T0005-充电 T0006-年检代办 T0007-道路救援 T0008-云南中石油充值
GOODS_NM	商品名称	varChar(200)	N	用户购买商品名称
PLATFORM_POINT	积分值	number(15,2)	N	订单使用积分抵扣积分值
PAY_MODE	支付方式	varChar(8)	N	STSL-刷脸 STSK-刷卡
PLATFORM	下单场景	Char(2)	N	99-建行生活APP 98-微应用
SKU_LIST	商品信息	varchar(3000)	N	商品信息列表(JSON字符串)，商品售价SKU_SELL_PRICE不能大于商品定价SKU_REF_PRICE

SKU_LIST 字段说明（JSON数组）

[
  {
    "SKU_NAME": "商品名称",
    "SKU_REF_PRICE": 15.01,
    "SKU_NUM": 1,
    "SKU_SELL_PRICE": 10.01
  },
  {
    "SKU_NAME": "商品名称2",
    "SKU_REF_PRICE": 15.01,
    "SKU_NUM": 2,
    "SKU_SELL_PRICE": 10.01
  }
]

字段名	中文名称	数据类型	必须	说明
SKU_NAME	商品名称	varChar	Y	商品名称
SKU_REF_PRICE	商品参考价	number(15,2)	Y	商品参考价，支持两位小数
SKU_NUM	商品数量	number(11,2)	Y	商品数量
SKU_SELL_PRICE	商品单价	number(15,2)	Y	商品单价，支持两位小数

响应参数

字段名	中文名称	数据类型	必须	说明
CCB_DISCOUNT_AMT	建行支付侧优惠金额	number(15,2)	N	因业务调整，后续下线字段
CCB_DISCOUNT_AMT_DESC	建行支付侧优惠定义	varChar(1000)	N	因业务调整，后续下线字段

3.2 A3341TP02 - 服务方订单更新

接口说明

项目	说明
服务码	A3341TP02
服务名称	服务方订单更新
服务类型	直接调用
功能描述	在用户订单状态有变动时调用，比如电影出票成功、外卖配送中等
URL	https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP02
重要说明	通知类型为"支付状态修改"时，支付状态不能为空，退款状态为空；通知类型为"退款状态修改"时，退款状态不能为空，支付状态为空

请求参数

字段名	中文名称	数据类型	必须	说明
ORDER_ID	订单编号	varChar(30)	Y	用户订单号（对应收银台USER_ORDERID字段）
INFORM_ID	通知类型	Char(1)	Y	0-支付状态修改 1-退款状态修改
PAY_STATUS	支付状态	Char(1)	N	0-待支付 1-支付成功 2-已过期 3-支付失败 4-取消
REFUND_STATUS	退款状态	Char(1)	N	0-无退款 1-退款申请 2-已退款 3-部分退款
PAY_AMT	订单实际支付金额	number(15,2)	N	订单实际支付金额
DISCOUNT_AMT	第三方平台优惠金额	number(15,2)	N	第三方平台优惠金额
DISCOUNT_AMT_DESC	第三方平台优惠定义	varChar(1000)	N	格式：名称=金额\|@\|名称=金额
CUS_ORDER_URL	自定义订单链接	varChar(256)	N	订单详情地址(需要推送完整的订单详情URL)
OCC_MCT_LOGO_URL	服务方商户logo图片地址	varChar(512)	N	http:// 或 https:// 为起始
PAY_FLOW_ID	支付流水号	varChar(30)	Y	调用收银台时上送的支付流水号（对应收银台ORDERID字段）
PAY_USER_ID	支付客户编号	varChar(150)	N	支付客户编号
TOTAL_REFUND_AMT	累计退款金额	number(15,2)	N	若支持多次退款，此次推送的金额为多次退款累计已退金额
PREFTL_MRCH_ID	门店商户号	varChar(50)	N	999的门店商户号
PAY_MRCH_ID	支付商户号	Char(15)	Y	调用收银台时上送的商户号
PLAT_MCT_ID	服务商门店编号	varChar(21)	N	外部平台商户号，不为空以这个字段为准
OCCCOUP_DISCOUNT_AMT	建行专属优惠金额	number(15,2)	N	第三方平台的建行专属优惠金额
OCCCOUP_DISCOUNT_AMT_DESC	建行专属优惠定义	varChar(1000)	N	格式：券实例号=金额\|@\|券实例号=金额
SPECIAL_STATUS	特殊附加状态	Char(5)	N	同订单推送
PLAT_ORDER_TYPE	服务方订单类型	Char(5)	N	同订单推送
GOODS_NM	商品名称	varChar(200)	N	用户购买商品名称
PLATFORM_POINT	积分值	number(15,2)	N	订单使用积分抵扣积分值
PAY_MODE	支付方式	varChar(8)	N	STSL-刷脸 STSK-刷卡
PLATFORM	下单场景	Char(2)	N	99-建行生活APP 98-微应用
SKU_LIST	商品信息	varchar(3000)	N	商品信息列表(JSON字符串)，格式同订单推送

响应参数

字段名	中文名称	数据类型	必须	说明
IS_SUCCESS	是否更新成功	Char(1)	Y	0-否 1-是
CCB_DISCOUNT_AMT	建行支付侧优惠金额	number(15,2)	N	因业务调整，后续下线字段
CCB_DISCOUNT_AMT_DESC	建行支付侧优惠定义	varChar(1000)	N	因业务调整，后续下线字段

3.3 A3341TP03 - 服务方订单查询

接口说明

项目	说明
服务码	A3341TP03
服务名称	服务方订单查询
服务类型	直接调用
功能描述	订单主动查询，在未收到支付结果通知时使用。查询结果存在延时情况，接口返回未查到可以适当重复查询
URL	https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP03
流控限制	默认流控值为 100/TPM

请求参数

字段名	中文名称	数据类型	必须	说明
TX_TYPE	交易类型	varChar(1)	Y	0-支付交易 1-退款交易 a-查询可退款的订单
TXN_PRD_TPCD	查询时间范围类型	varChar(2)	Y	99-自定义时间段查询
STDT_TM	开始日期时间	Char(14)	N	查询时间范围类型为99时必输，格式yyyyMMddhhmiss
EDDT_TM	结束日期时间	Char(14)	N	查询时间范围类型为99时必输，格式yyyyMMddhhmiss
ONLN_PY_TXN_ORDR_ID	订单编号	varChar(60)	N	调用收银台时支付流水号，对应字段ORDERID
SCN_IDR	场景标识	varChar(3)	N	BHK-本行卡 THK-他行卡 ZFB-支付宝 CFT-微信
PLAT_MCT_ID	服务商门店编号	varChar(21)	N	外部平台商户号，不为空以这个字段为准
CUSTOMERID	商户号	varChar(21)	N	建行商户编号，与外部平台商户号不能同时为空
BRANCHID	一级分行号	varChar(9)	N	商户一级分行号，用建行商户编号时不能为空
POS_CODE	柜台号	varChar(9)	N	柜台号
POS_ID	POS终端编号	varChar(19)	N	POS终端编号
TXN_STATUS	交易状态	varChar(2)	Y	00-交易成功 01-交易失败 02-不确定
MSGRP_JRNL_NO	商户的流水号	varChar(60)	N	商户支付流水号或者退款流水号
PAGE	当前页次	number(10)	Y	当前页次

响应参数（摘要）

字段名	中文名称	数据类型	必须	说明
CUR_PAGE	当前页次	number(10)	N	每页最多返回10条记录
PAGE_COUNT	总页次	number(10)	N	总页次
ED_CRD_PRTY_IDR_CD	商户号	varChar(15)	N	商户号
PY_AMT	支付金额	number(16,2)	N	单位：元
MRCH_RFND_AMT	商户退款金额	number(16,2)	N	单位：元
LIST	订单列表	Array	N	订单详情列表（见下表）

LIST 数组字段（订单列表）

字段名	中文名称	数据类型	说明
ONLN_PY_TXN_ORDR_ID	订单编号	varChar(120)	订单编号
CLRG_STM_DT_TM	交易时间	varChar(14)	格式yyyyMMddhhmiss
ACQ_FNDS_CLRG_DT	记账日期	varChar(8)	格式yyyyMMdd
ORDR_TM	原支付订单时间	varChar(42)	格式yyyyMMddhhmiss
AHN_TXNAMT	交易金额	number(16,2)	单位：元
ORDR_PYRFD_AMT	退款总额	number(16,2)	单位：元
TXN_CLRGAMT	结算金额	number(16,2)	单位：元
MRCHCMSN_AMT	手续费金额	number(16,2)	单位：元
ORIG_AMT	订单金额	number(16,2)	单位：元
DISCOUNT_AMT	优惠金额	number(16,2)	订单金额-交易金额=优惠金额
RETGDS_ORIG_TXNAMT	原支付金额	number(16,2)	单位：元
CST_ACCNO	支付卡号	varChar(32)	支付卡号
CCYCD	币种	varChar(3)	币种
TXN_STATUS	交易状态	varChar(2)	00-成功 01-失败 02/04-不确定 TO-超时
ORIOVRLSTTNEV_TRCK_NO	银行流水号	varChar(25)	银行流水号
MSGRP_JRNL_NO	商户流水号	varChar(240)	退款时商户上送的退款流水号
PAY_MODE	支付方式	Char(3)	BHK-建行 THK-他行 ZFB-支付宝 CFT-微信

更多字段请参考Excel原文档

3.4 A3341TP04 - 服务方订单退款

接口说明

项目	说明
服务码	A3341TP04
服务名称	服务方订单退款
服务类型	直接调用
功能描述	订单退款时使用。在退款结果未返回结果时，建议先查询退款结果再做后续处理
URL	https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP04

请求参数

字段名	中文名称	数据类型	必须	说明
PLAT_MCT_ID	服务商门店编号	varChar(21)	N	外部平台商户号，不为空以这个字段为准
CUSTOMERID	商户号	varChar(21)	N	建行商户编号，与外部平台商户号不能同时为空
BRANCHID	一级分行号	varChar(9)	N	商户一级分行号，用建行商户编号时不能为空
MONEY	退款金额	number(16,2)	Y	单位：元
ORDER	订单号	varChar(30)	Y	调用收银台时支付流水号，对应字段ORDERID
STDT_TM	开始日期时间	Char(14)	Y	根据支付时间往前加4小时，格式yyyyMMddhhmiss
EDDT_TM	结束日期时间	Char(14)	Y	根据支付时间往后加4小时，但日期不能超过当前日期，格式yyyyMMddhhmiss
REFUND_CODE	退款流水号	varChar(30)	N	可不填，商户可根据需要填写，退款流水号由商户的系统生成（在未收到退款接口返回时，可用此字段查询退款结果）

响应参数

字段名	中文名称	数据类型	必须	说明
ORDER_NUM	订单号	varChar(30)	Y	订单号
PAY_AMOUNT	支付金额	number(16,2)	Y	单位：元
AMOUNT	退款金额	number(16,2)	Y	单位：元
Cst_AccNo	客户账户	varChar(32)	N	脱敏后客户退款账号

3.5 A3341TP05 - 订单支付权益查询

接口说明

项目	说明
服务码	A3341TP05
服务名称	订单支付权益查询
服务类型	直接调用
功能描述	查询订单支付时使用的权益信息。此接口跟订单支付结果一起计算流控TPM
URL	https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP05

请求参数

字段名	中文名称	数据类型	必须	说明
PLAT_MCT_ID	服务商门店编号	varChar(21)	N	外部平台商户号（暂不支持）
CUSTOMERID	商户号	varChar(21)	N	建行商户编号，与外部平台商户号不能同时为空
BRANCHID	一级分行号	varChar(9)	N	商户一级分行号，用建行商户编号时不能为空
TX_SPECIAL_EC	交易类型	varChar(1)	Y	0-支付交易 1-退款交易
ORDER_ID	订单号	varChar(30)	Y	调用收银台时支付流水号，对应字段ORDERID
OriOvrlsttnEV_Trck_No	原银行流水号	varChar(25)	N	原银行流水号
Txn_Prd_TpCd	交易期间类型代码	varChar(2)	N	08-1个小时内，送空则为08
POS_ID	终端号	varChar(19)	N	终端号
Jrnl_TpCd	流水类型代码	varChar(2)	N	XM-数字人民币 PT-普通收单 YH-单纯查券优惠 AL-全部，送空则为YH

响应参数（摘要）

字段名	中文名称	数据类型	说明
Py_Amt	总支付金额	varChar(19)	总支付金额
Mrch_Rfnd_Amt	总退款金额	varChar(10)	总退款金额
Py_Ordr_Amt	总支付订单金额	varChar(18)	总支付订单金额
Rght_Cgy_Inf	权益类信息	varChar(3000)	权益信息（见下方说明）
LIST	订单列表	Array	订单详情列表

Rght_Cgy_Inf 权益类信息说明

权益位图格式示例：

P6:{FL3:有价折扣券,AM1:30.00,AM2:30.00},P3:{FL2:02,FL3:满减活动,AM1:30.00,AM2:30.00}

字段说明:

P6: 商户券
FL1: 优惠度量（如积分数、券数量）
FL2: 清算方式（01-后结算 02-在线一笔清算 03-在线异步清算）
FL3: 优惠类型（如满减活动、满减券、有价券等）
FL4: 优惠名称（如活动描述或券名称）
AM1: 优惠金额
AM2: 清算金额
AM3: 银行出资金额
AM4: 商户出资金额
AM5: 优惠券面额
AM6: 客户实付金额
AM7: 积分抵扣金额

P6 优惠券类型:

免费折扣券
免费代金券
免费实物券
免费定额券
有价折扣券
有价代金券
有价实物券
有价定额券

3.6 A3341TP13 - 服务方订单补充信息

接口说明

项目	说明
服务码	A3341TP13
服务名称	服务方订单补充信息
服务类型	直接调用
功能描述	补充订单的商品信息（SKU_LIST）
URL	https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP13

请求参数

字段名	中文名称	数据类型	必须	说明
USER_ID	会员编号	varChar(40)	Y	会员编号
ORDER_ID	订单编号	varChar(40)	Y	订单编号
SKU_LIST	商品信息列表	varChar(3000)	N	商品信息列表(JSON字符串)，格式同订单推送接口

SKU_LIST 字段说明

同订单推送接口的 SKU_LIST 字段，包含：

SKU_NAME：商品名称
SKU_REF_PRICE：商品参考价
SKU_NUM：商品数量
SKU_SELL_PRICE：商品单价

⚠️ 重要提示：商品售价 SKU_SELL_PRICE 不能大于商品定价 SKU_REF_PRICE，字段长度为字节，注意中文字段长度。

附录

A. 订单状态枚举

订单状态（ORDER_STATUS / PAY_STATUS）

0 - 待支付
1 - 支付成功
2 - 已过期
3 - 支付失败
4 - 取消

退款状态（REFUND_STATUS）

0 - 无退款
1 - 退款申请
2 - 已退款
3 - 部分退款

特殊附加状态（SPECIAL_STATUS）

P0000 - 正常状态
P0001 - 待使用
P0002 - 待审核
P0003 - 已支付
P0004 - 待退款
P0005 - 退款中
P0006 - 待发货
P0007 - 已发货
P0008 - 进行中
P0009 - 预定中
P0010 - 预定成功
P0011 - 预定失败
P0012 - 已入住
P0013 - 已离店
P0014 - 未入住
P0015 - 配送中
P0016 - 出券中

B. 服务方订单类型（PLAT_ORDER_TYPE）

T0000 - 普通类型
T0001 - 洗车
T0002 - 加油
T0003 - 停车
T0004 - 修车
T0005 - 充电
T0006 - 年检代办
T0007 - 道路救援
T0008 - 云南中石油充值

C. 支付方式（PAY_MODE / Scn_Idr）

STSL - 刷脸
STSK - 刷卡
BHK - 本行卡
THK - 他行卡
ZFB - 支付宝
CFT - 微信

D. 交易状态（TXN_STATUS / Txn_Status）

00 - 交易成功
01 - 交易失败
02 - 不确定
04 - 不确定（前端无须发冲正）
TO - 交易超时

开发指南

1. 接口调用流程

1. 构建公共报文头（CLD_HEADER）
   ├── CLD_TX_CHNL：服务方ID（如YS44000009001853）
   ├── CLD_TX_TIME：当前时间（YmdHis格式）
   ├── CLD_TX_CODE：服务码（如A3341TP01）
   └── CLD_TX_SEQ：唯一流水号

2. 构建业务参数（CLD_BODY）
   └── 根据具体接口填充业务参数

3. 整体报文加密
   ├── 将CLD_HEADER + CLD_BODY转JSON
   ├── 使用建行公钥RSA加密
   └── 生成MD5签名（mac字段）

4. 发送HTTP POST请求
   ├── URL：基础地址 + ?txcode=服务码
   ├── 参数：cnt（加密内容）、mac（签名）
   └── 请求头：Content-Type: application/x-www-form-urlencoded

5. 处理响应
   ├── 使用商户私钥解密响应cnt字段
   ├── 验证响应mac签名
   └── 解析CLD_HEADER和CLD_BODY

2. 重要提示

⚠️ 密钥管理

商户私钥：用于解密建行返回的数据
商户公钥：参与支付串的MD5签名计算
建行公钥：用于加密发送给建行的数据

⚠️ 字段校验

SKU_SELL_PRICE（商品售价）不能大于 SKU_REF_PRICE（商品定价）
通知类型为"支付状态修改"时，PAY_STATUS 必填，REFUND_STATUS 为空
通知类型为"退款状态修改"时，REFUND_STATUS 必填，PAY_STATUS 为空

⚠️ 流控限制

订单查询接口（A3341TP03）：默认流控值为 100/TPM
权益查询接口（A3341TP05）：与订单支付结果一起计算流控TPM

⚠️ 时间格式

所有时间字段统一使用：yyyyMMddHHmmss 格式
示例：20250121120000

3. 错误处理

接口返回404：请在请求头中添加 Accept: application/json 和 Content-Type: application/json
查询结果延时：订单查询接口存在延时，返回未查到时可适当重复查询
退款未返回：建议先调用订单查询接口查询退款结果，再做后续处理

文档结束

25 KiB Raw Blame History Unescape Escape

建行生活API接口文档

📑 目录

1. 修订记录

2. 接口规范

2.1 公共报文头

请求体（CLD_HEADER）

响应体（CLD_HEADER）

2.2 通讯地址

UAT 测试环境

生产环境

接口地址示例

2.3 接口索引

3. 核心接口

3.1 A3341TP01 - 服务方订单推送

接口说明

请求参数（CLD_BODY）

SKU_LIST 字段说明（JSON数组）

响应参数

3.2 A3341TP02 - 服务方订单更新

接口说明

请求参数

响应参数

3.3 A3341TP03 - 服务方订单查询

接口说明

请求参数

响应参数（摘要）

LIST 数组字段（订单列表）

3.4 A3341TP04 - 服务方订单退款

接口说明

请求参数

响应参数

3.5 A3341TP05 - 订单支付权益查询

接口说明

请求参数

响应参数（摘要）

Rght_Cgy_Inf 权益类信息说明

3.6 A3341TP13 - 服务方订单补充信息

接口说明

请求参数

SKU_LIST 字段说明

附录

A. 订单状态枚举

订单状态（ORDER_STATUS / PAY_STATUS）

退款状态（REFUND_STATUS）

特殊附加状态（SPECIAL_STATUS）

B. 服务方订单类型（PLAT_ORDER_TYPE）

C. 支付方式（PAY_MODE / Scn_Idr）

D. 交易状态（TXN_STATUS / Txn_Status）

开发指南

1. 接口调用流程

2. 重要提示

3. 错误处理

25 KiB

Raw Blame History