合作商 API
合作商 API 面向需要统一接入并处理多个下游商户交易的平台、ISV、PSP、收单机构等合作伙伴。
定位
合作商使用自有 API 凭证（一级商户号）接入 ADOPAY，名下下游商户以二级商户形式管理：
- 请求头
X-Merchant-Id携带一级商户号，即合作商凭证。 - 请求字段
subMerchantNo标识本次操作归属的二级商户；具体位置以接口定义为准，Webhook 事件同样携带该编号，便于路由到对应商户。 - 请求体
accessMode声明接入模式：normal（普通商户）、saas_isv（SaaS / ISV）、acquirer（收单机构）、platform（平台服务商）。
与 Merchant API 的关系
合作商 API 与 Merchant API 复用同一交易核心，收款、退款、代付的字段与能力模型保持一致。差异集中在：
| 差异点 | Merchant API | 合作商 API |
|---|---|---|
| 凭证主体 | 商户本人 | 合作商（一级商户号） |
| 交易归属 | 商户自身 | 二级商户（subMerchantNo） |
| 接入模式参数 | - | accessMode 必填 |
接入流程
text
商务签约，获取合作商凭证（一级商户号 / 密钥 / keyId）
↓
确认 accessMode 与二级商户号 subMerchantNo 分配方式
↓
接入公共规范（认证 / 签名 / Webhook）
↓
按能力接入：账户 → 收款 → 退款 → 代付 → MED公共规范（认证、请求签名、响应结构、幂等、Webhook 规则）见 公共规范 Common。
接口目录
账户 Account
商户 merchant
收款 cashin
代付 cashout
PixKey 管理
商户和合作商共用同一组 PixKey 接口。
对账文件
MED API（特别退款机制）
处理巴西央行 MED 欺诈争议，代表名下二级商户查询、分析与处理违规报告。
规划中能力
以下能力尚未发布正式规格，正式发布前请勿对接：
- 合作商额度查询
- 商户管理（线上化）
- 结算与结算报表