引言 - Merchant API Documentation

预期读者

本接口文档适用于对接平台支付能力的商户平台产品、开发、测试、运维、安全合规及相关审批人员。

商户在接入前，应理解接口调用流程、身份认证机制、报文加密规则、签名验签规则、响应解密规则及异常处理方式，确保商户系统能够安全、稳定地完成接口调用。

平台对外 API 遵循 RESTful 风格设计，所有商户侧接口请求必须使用 HTTPS 协议发起，禁止使用 HTTP 明文传输。

除特殊说明外，接口统一使用 POST 请求方式，请求和响应的外层消息体均使用 JSON 格式。

为保障接口传输安全，商户调用平台 API 时，请求报文需按照平台约定完成身份认证、签名生成及业务数据加密处理；平台返回响应时，业务数据也会按照约定进行加密返回。

接口请求和响应采用统一 JSON 外壳结构，业务参数放置在 data 字段中：

请求时：data 为加密后的业务请求数据；
响应时：data 为加密后的业务响应数据；
code、msg、livemode 等外层字段用于表达接口处理结果、提示信息及环境标识。

商户系统收到响应后，应先判断接口响应状态，再根据加密规则对 data 字段进行解密，并按解密后的业务 JSON 进行后续处理。

平台通过商户身份信息、时间戳、随机数和请求签名验证商户身份及请求完整性。

商户调用接口时，需在 HTTP Header 中携带平台要求的认证信息，包括但不限于商户号、时间戳、随机数、签名值等信息。平台会根据商户号定位对应的签名密钥，并对请求进行验签。

签名算法采用 HMAC-SHA256。商户应按照平台约定的签名原文组装规则，使用商户签名密钥生成签名，并将签名信息通过 HTTP Header 传递。

未携带认证信息、签名缺失、签名错误、时间戳超出有效范围、随机数重复或请求内容被篡改的请求，平台均会拒绝执行。

为防止重放攻击，商户每次请求应生成唯一随机数，并确保时间戳为当前有效时间范围内的时间。相同商户在有效时间窗口内重复提交相同随机数的请求，可能会被平台识别为重复请求并拒绝处理。

平台接口采用混合加密方案保护业务数据安全。

业务请求数据在传输前应先序列化为 JSON 字符串，再使用平台约定的对称加密算法进行加密。对称密钥相关信息应按照平台约定使用非对称加密方式进行保护。

加密规则如下：

业务数据使用 AES-256-GCM 进行加密；

对称密钥使用 RSA-OAEP-256 进行加密保护；

请求业务参数统一放入外层 JSON 的 data 字段；

响应业务数据同样通过 data 字段加密返回；

商户应使用自身持有的对应密钥对平台响应数据进行解密；

解密失败、密文格式错误、密钥不匹配或报文被篡改时，商户应按接口调用失败处理。

商户不得将敏感业务参数以明文形式放在 URL 查询参数、Header 非约定字段或日志中。涉及卡号、证件号、手机号、邮箱、密钥、签名、密文等敏感信息时，商户系统应做好脱敏展示、日志脱敏和访问权限控制。

请求是否成功，与请求 JSON 中键值对出现的顺序无关；

请求是否成功，与业务参数在解密后 JSON 中的字段顺序无关；

处理响应时，不应假设响应 JSON 中键值对出现的顺序；

新的 API 版本可能新增请求参数、响应参数或 JSON 键值对，商户系统应具备兼容未知字段的能力；

商户应严格按照字段类型、长度、格式、枚举值及必填规则传入参数；

金额、币种、订单号、时间等关键字段应以接口文档定义为准，不应自行转换含义；

API 响应中的数据可能包含商户传入的数据，也可能包含未经商户侧充分校验的用户输入内容。为避免 XSS 攻击，调用方在展示或使用响应数据前，应根据实际场景进行必要的转义、过滤或脱敏处理；

商户系统应避免在日志中完整记录明文请求参数、明文响应参数、签名密钥、加密密钥、完整卡号等敏感信息。