From 2dc5ff423f5f84c1f5e48e0e6e23eec72d542595 Mon Sep 17 00:00:00 2001 From: Billy <641833868@qq.com> Date: Tue, 21 Oct 2025 10:29:22 +0800 Subject: [PATCH] =?UTF-8?q?=E6=8E=A5=E5=8F=A3=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/建行生活API接口文档.md | 568 +++++++++++++++++++++++++++++ 1 file changed, 568 insertions(+) create mode 100644 doc/建行生活API接口文档.md diff --git a/doc/建行生活API接口文档.md b/doc/建行生活API接口文档.md new file mode 100644 index 0000000..628edc3 --- /dev/null +++ b/doc/建行生活API接口文档.md @@ -0,0 +1,568 @@ +# 建行生活API接口文档 + +> 文档版本: v1.1.6 +> 生成时间: 2025-01-21 +> 来源: 建行生活输入通讯报文v1.1.6【最新】.xlsx + +--- + +## 📑 目录 + +- [1. 修订记录](#1-修订记录) +- [2. 接口规范](#2-接口规范) + - [2.1 公共报文头](#21-公共报文头) + - [2.2 通讯地址](#22-通讯地址) + - [2.3 接口索引](#23-接口索引) +- [3. 核心接口](#3-核心接口) + - [3.1 A3341TP01 - 服务方订单推送](#31-a3341tp01---服务方订单推送) + - [3.2 A3341TP02 - 服务方订单更新](#32-a3341tp02---服务方订单更新) + - [3.3 A3341TP03 - 服务方订单查询](#33-a3341tp03---服务方订单查询) + - [3.4 A3341TP04 - 服务方订单退款](#34-a3341tp04---服务方订单退款) + - [3.5 A3341TP05 - 订单支付权益查询](#35-a3341tp05---订单支付权益查询) + - [3.6 A3341TP13 - 服务方订单补充信息](#36-a3341tp13---服务方订单补充信息) + +--- + +## 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数组） + +```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` +- 查询结果延时：订单查询接口存在延时，返回未查到时可适当重复查询 +- 退款未返回：建议先调用订单查询接口查询退款结果，再做后续处理 + +--- + +**文档结束**