卡密核销 · 商户接入

商户下单、查询、请求签名、防重放及异步通知沿用现有网关合同。卡密由用户在平台收银台提交，商户不传入用户身份、IP、设备指纹或卡密。

接入流程

创建商户 → 配置来源 IP 白名单 → 逐条绑定通道并设置商户费率 → 获取产品编码 → 创建订单 → 将 cashier_url 提供给用户 → 查询订单或接收通知。

创建订单：POST /api/v1/gateway/orders；查询：GET /api/v1/gateway/orders/{merchant_order_no}。

产品编码必传

产品独立维护；通道关联渠道商和产品，并配置成本费率与金额限额。例如 0001 为京东卡，0002 为永辉卡。下单必须传入字符串 product_code（如 "0001"），保留前导零；total_amount 为订单金额。平台按产品编码、商户绑定、启停状态和通道限额匹配可用通道，多个匹配时优先低成本。限额支持 10,20,100-500 组合，命中任一值或范围即可，留空不限制。收银台展示下单时的产品名称和金额。编码不存在、产品或渠道停用、商户未绑定通道时均拒绝新下单。

通道权限和费率

每条通道独立授权，渠道商绑定不能代替通道绑定。未绑定或绑定停用时，不能使用该通道下单、查询其订单或重复提交。查单还必须满足订单归属本商户。费率使用小数，0.03 表示 3%；100 元订单手续费 3 元，应结金额 97 元。订单保存创建时的费率和费用，修改配置不影响旧订单；费用快照不代表已经完成核销结算。

超时与幂等重试

网络超时、连接中断、429 或 503 不代表交易失败。请遵守 Retry-After，退避后使用原商户订单号查询或以原参数重试，不要换订单号重新下单。503 SERVICE_BUSY 表示服务暂忙；503 RESULT_UNCONFIRMED 表示结果暂未确认，订单可能已经提交，优先查原单。每次请求重新生成 X-Nonce、时间戳及签名；业务订单号保持不变。收银台过期不代表核销失败，最终结果以平台查询和有效通知为准。

固定测试产品

使用 SYS_TEST 进行本地模拟联调，订单 24 小时有效，金额 0.01–9999.99，自动绑定固定测试通道。商户使用自己的签名、来源 IP 白名单与公网 HTTPS 回调地址。测试收银台领取并提交本订单专用测试卡后，按正常流程查单与接收签名通知；通知包含 test_order:true 和 status_source:CARD_TEST。模拟交易不调用真实上游、不计入正式交易统计。24 小时不是通知重试截止时间。

真实渠道

功夫熊猫测试卡已完成一次真实取卡、锁卡、解锁和核销。真实通道仍需配置费率、商户权限并开启；结果不明时保持待确认，禁止重复核销。详见 merchant-api.md 与 gongfu-panda-integration.md。