> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 用 API 为商户或子商户提交进件申请

> 说明如何通过 API 为商户或子商户提交、更新和查询进件申请：四项按需接入的能力、必填字段、申请与支付方式状态、进件结果通知以及常见错误码。

本页回答：除了在 Portal 里填写验证向导，能不能通过 API 提交、修改和查询进件（入驻）申请？需要调哪几个接口、传什么、怎么收到结果？Portal 上的向导与文件要求见本模块其他页面；本页只讲 API 方式。

## 进件 API 是必须接入的吗？

不是。四项能力全部是「按需接入」（Conditional），由你根据业务决定是否集成：

| 能力 | 用途 |
| - | - |
| `POST /api/v1/onboarding/merchant/submit` | 提交进件申请 |
| `POST /api/v1/onboarding/merchant/update` | 申请因资料有误被退回后，更新申请 |
| `POST /api/v1/onboarding/merchant/inquiry` | 查询进件申请状态 |
| 进件结果通知（Webhook） | Waffo 把进件结果推送到你提供的地址 |

沙箱与生产环境的 API 地址分别为 `https://api-sandbox.waffo.com/` 和 `https://api.waffo.com/`。请求头、签名方式与其他 Waffo API 相同：请求体使用 JSON（UTF-8），用你的私钥签名（SHA256WithRSA），用 Waffo 的公钥验证响应签名。

## 进件类型 onboardingType 选哪个？

| 值 | 含义 |
| - | - |
| `1` | 商户（Merchant） |
| `2` | 子商户（Submerchant） |

当类型为 `2` 且申请状态为 `PARTIAL_SUCCESS` 或 `FULL_SUCCESS` 时，查询响应里会返回 Waffo 分配的 `assignedSubMerchantId`。

## 提交进件申请要传哪些字段？

下表是提交接口的必填字段（`required`）。其余字段为选填或有条件必填。

| 字段 | 说明 |
| - | - |
| `onboardingSubmissionId` | 你方生成的进件提交编号，最长 32 位，同时作为幂等键 |
| `merchantId` | Waffo 分配的商户号 |
| `onboardingType` | `1` 商户 / `2` 子商户 |
| `merchantName` | 公司注册名称 |
| `merchantBrandName` | 公司品牌名称 |
| `merchantShortName` | 商户简称 |
| `mcc` | 商户类别码 |
| `merchantType` | `Enterprise` 或 `Individual` |
| `incorporationDate` | 公司成立日期，格式 `DD/MM/YYYY` |
| `registrationNumber` | 公司注册号 |
| `registrationExpiryDate` | 注册证书到期日，格式 `DD/MM/YYYY` |
| `phoneNumber` | 客服联系电话，格式 `+国家码-手机号` |
| `AddressInfo.address`、`AddressInfo.city`、`AddressInfo.addressCountryCode` | 公司注册地址、城市、国家（ISO 3166-1 alpha-3） |
| `contactPersonInfo.contactPersonName`、`contactPersonPhone`、`contactPersonEmail` | 联系人姓名、电话、邮箱 |
| `payMethodInfo[].payMethodName`、`payMethodInfo[].country` | 申请开通的支付方式（如 `ALIPAY`、`WECHATPAY`、`GRABPAY`）及运营国家 |
| `requestedAt` | 你方请求时间 |
| `notifyUrl` | 接收进件结果通知的回调地址 |

几个容易漏的点：

* `siteInfo` 里的 `appSiteUrl` 与 `webSiteUrl` 都是选填，但应按实际业务至少提供一个。
* `authorizedPurchaseUrl` 和 `authorizedPurchaseDomain` 只在申请微信支付（`WECHATPAY`）时需要；域名最多五个，用 JSON 格式。
* 董事（`directorInfo`）和股东（`shareHolderInfo`）信息为选填数组。

## 选填字段有哪些？格式有什么要求？

* `AddressInfo.region`（州 / 省）、`AddressInfo.postcode`（邮编）为选填。
* `directorInfo[]`：每项含 `directorName`、`directorIdNumber`。
* `shareHolderInfo[]`：每项含 `shareHolderName`、`shareHolderNationality`（ISO 3166-1 alpha-3）、`shareHolderIdIdType`（`NATIONAL_ID_CARD`、`PASSPORT`、`DRIVER_LICENSE` 或 `OTHERS`）、`shareHolderIdNumber`、`shareHolderShares`（持股比例，如 40.00%）。
* `extendInfo`：预留字段，JSON 字符串，最长 128 个字符。
* 网址字段（`appSiteUrl`、`webSiteUrl`、`authorizedPurchaseUrl`）须以 http 或 https 开头，最长 256 个字符。
* 电话格式为 +国家码-号码，例如 +62-08990013157；日期格式为 DD/MM/YYYY；国家码一律用 ISO 3166-1 alpha-3。
* 请求头带 `X-API-KEY` 和 `X-SIGNATURE`；通知和你的应答同样要签名，Waffo 用你的公钥验签。

## 提交成功后我会拿到什么？

响应里有三个字段：

| 字段 | 含义 |
| - | - |
| `onboardingSubmissionId` | 你提交时的编号 |
| `onboardingApplicationId` | Waffo 分配的申请编号，后续查询用 |
| `onboardingStatus` | 申请总体状态 |

## 申请状态和每个支付方式的状态是什么意思？

申请总体状态 `onboardingStatus`：

| 状态 | 含义 |
| - | - |
| `PROCESSING` | Waffo 已受理，处理中 |
| `PARTIAL_SUCCESS` | 部分支付方式已通过，可用查询接口看明细 |
| `FULL_SUCCESS` | 所有支付方式均已通过 |
| `FAILED` | 没有任何支付方式通过 |

每个支付方式的状态 `payMethodOnboardingStatus`：

| 状态 | 含义 |
| - | - |
| `INIT` | 尚未提交 |
| `PROCESSING` | 处理中 |
| `SUCCESS` | 进件成功 |
| `FAILED` | 进件失败 |
| `NA` | 该支付方式不需要进件流程 |

失败时，查询结果里可能带有 `onboardingFailedCode` 和 `onboardingFailedReason`（均为选填）。

## 怎么查进件状态？

调用 `inquiry` 接口，`onboardingSubmissionId` 与 `onboardingApplicationId` 二选一提供即可。响应是一个完整的进件申请对象，包含总体状态、每个支付方式的状态和失败信息、`updatedAt`（最后更新时间）等。

## 申请被退回后怎么改？

调用 `update` 接口更新申请。它适用于申请最初因进件资料有误被拒绝的情形，字段结构与提交接口一致。申请仍在 `PROCESSING` 时不能更新，会返回 `A0010`。

## 怎么收到进件结果通知？

Waffo 会向你在 `notifyUrl` 提供的地址发送 HTTPS POST 回调，每个支付方式的进件状态有更新，就会发送一次。报文的 `eventType` 为 `ONBOARDING_NOTIFICATION`，`result` 是与查询接口相同的进件申请对象。

你的响应体 `message` 必须是以下之一：

| 值 | 含义 |
| - | - |
| `success` | 已收到 |
| `failed` / `unknown` | Waffo 会在 24 小时内重试通知 |

## 常见错误码

| 错误码 | 含义 |
| - | - |
| `A0001` | API 密钥无效 |
| `A0002` | 签名无效 |
| `A0003` | 参数校验失败 |
| `A0004` | 无权限 |
| `A0005` | 幂等参数不一致（同一个 `onboardingSubmissionId` 内容变了） |
| `A0006` | 缺少参数 |
| `A0007` | 商户状态异常 |
| `A0008` | 申请中的支付方式与当前商户合同不匹配 |
| `A0009` | 所申请支付方式的进件已通过，不能再次提交 |
| `A0010` | 申请仍在处理中，不能更新 |
| `A0011` | 申请中有支付方式不需要进件，不能提交 |
| `C0001` | 系统错误 |

## 我该用 API 还是 Portal？

两种方式都可以。如果你只有少量商户、自己手工填写即可，用 Portal 的验证向导更直观；如果你是平台、需要批量为子商户提交进件并自动接收结果，用这组 API。是否开通 API 权限、如何拿到凭证，请联系你的对接人。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.