商户接口配置（讨论）

1. 路由配置与寻址

余额方需要在开放平台后台配置以下核心服务地址，确保开放平台能将支付和退款请求正确转发到您的服务器。所有通信必须通过 HTTPS 协议。

配置项	必填	标识	业务说明
获取TOKEN接口[新]	是	`token_url`	用于获取访问凭证（Token），供后续支付、退款、查询等接口调用时进行身份鉴权。
支付请求地址	是	`pay_url`	开放平台转发扫码扣款请求的接口地址。
退款请求地址	是	`refund_url`	开放平台转发退款/冲正请求的接口地址。
会员查询接口	是	`member_url`	开放平台转发会员详情请求的接口地址。

2. 接口定义

所有请求方式为 POST，Content-Type 为 application/json。

2.0 获取访问凭证 (Token Request) [新]

URL: 配置的 token_url

用途: 开放平台向余额方换取访问凭证（Token）。后续的支付、退款、查询等接口请求头或参数中需携带此 Token 以验证身份。通常采用 Client Credentials (客户端凭证) 模式。

请求参数 (开放平台 $\to$ 余额方):

{
  "appid": "OP_20250001",           // 余额方分配的或约定的应用ID
  "appsecret": "Kjsdhf234..."       // 约定的鉴权密钥
}

响应参数 (余额方 $\to$ 开放平台):

{
    "success": true,
    "message": "获取成功",
    "data": {
        "access_token": "eyJhbGciOiJIUzI1Ni...",  // 访问凭证
        "expires_in": 7200,                       // 凭证有效期（秒），如 2小时
        "token_type": "Bearer"                    // 凭证类型（可选）
    }
}

字段	类型	描述
`success`	Boolean	请求状态。 `true`: 获取成功，解析 data。 `false`: 获取失败
`message`	String	结果描述（如：无效的 app_id 或 secret）
`data.access_token`	String	用于后续接口调用的鉴权令牌
`data.expires_in`	Number	Token 的有效时长，建议余额方设置合理的过期时间（如7200秒）

2.1 支付扣款接口 (Pay Request)

URL: 配置的 pay_url

用途: 接收用户扫码后，执行扣款操作。

请求参数 (开放平台 $\to$ 余额方):

{
  "signature": "a8f314e1c|...",             // 二维码签名串
  "amount": "10.05",                        // 交易金额
  "order_no": "P123456789**",               // 平台生成的唯一流水号
  "out_store_id": "10041",                  // 门店ID（收银方）
  "store_trade_no": "POSTEST2025101**",     // 门店订单号
  "store_goods": "[{"goods_id":"6937962199173","goods_name":"金龙鱼稻花香5kg(5kg)","price":49.90,"quantity":24},{"goods_id":"6948195805120","goods_name":"金龙鱼特香低芥酸菜籽油5L(5L)","price":59.90,"quantity":24}]" // 门店订单商品信息，该字段暂用于留档，不参与金额校验。由于商户侧可能存在分分钱级别的抹零处理，因此不能以此字段作为验证依据。
}

响应参数 (余额方 $\to$ 开放平台):

{
    "success": true,
    "message": "支付成功",
    "data": {
        "merchant_trade_no": "YYYYYY123456789"    // 余额方订单号
    },
}

字段	类型	描述
`success`	Boolean	请求状态。 `true`: 请求成功，解析 data 数据。 `false`: 请求失败
`message`	String	结果描述（如：验签失败、余额不足）
`data.merchant_trade_no`	String	余额方内部交易流水号

2.2 退款/冲正接口 (Refund Request)

URL: 配置的 refund_url

用途: 处理商户或平台发起的退款，或支付超时后的冲正操作。

请求参数 (开放平台 $\to$ 余额方):

{
    "order_no": "P123456789**",   // 平台生成的唯一流水号
    "refund_amount": "10.05",     // 退款金额
    "refund_no": "P123456789"     // 平台生成的唯一退款订单流水号
}

响应参数 (余额方 $\to$ 开放平台):

{
    "success": true,
    "message": "退款成功", 
    "data": {
        "merchant_refund_no": "YYYYYY123456789"
    },
}

字段	类型	描述
`success`	Boolean	请求状态。 `true`: 请求成功，解析 data 数据。 `false`: 请求失败
`message`	String	结果描述（如：验签失败、退款失败）
`data.merchant_refund_no`	String	余额方内部退款流水号

2.3 会员信息查询接口（Member Query）

URL: 配置的 member_url

用途: 开放平台将门店发起的会员查询请求转发到余额方，用于获取用户基础资料、余额、积分等信息。

请求参数（开放平台 → 余额方）

{
  "signature": "a8f314e1c|..." 
}

字段	类型	描述
signature	String	二维码解析出的核心签名串

响应参数 (开放平台 $\to$ 余额方):

{
    "success": true,
    "message": "ok",
    "data": {
        "id": 1,
        "name": "冯齐跃",
        "mobile": "15881551001",
        "balance": "85.00",
        "points": 96
    }
}

3. 角色分工与开发指引

角色	主要职责
余额方	签名、密钥管理、防重放、有效期控制、余额扣减/回补。
开放平台	格式校验、AppID 校验、交易路由、商户回调。

1. 路由配置与寻址#

2. 接口定义#

2.0 获取访问凭证 (Token Request) [新]#

2.1 支付扣款接口 (Pay Request)#

2.2 退款/冲正接口 (Refund Request)#

2.3 会员信息查询接口（Member Query）#

3. 角色分工与开发指引#

1. 路由配置与寻址

2. 接口定义

2.0 获取访问凭证 (Token Request) [新]

2.1 支付扣款接口 (Pay Request)

2.2 退款/冲正接口 (Refund Request)

2.3 会员信息查询接口（Member Query）

3. 角色分工与开发指引