create-merchant-platform

创建商户平台

版本检查（先运行此步骤）

在发布任何消息或启动流程之前，请确认此技能为最新版本：

1. 从上方 frontmatter 中的 metadata.version 字段读取此技能的版本。
2. 获取已发布版本并读取其 metadata.version： https://raw.githubusercontent.com/payroc/skills/main/plugins/payroc/boarding/skills/create-merchant-platform/SKILL.md
3. 将两者按语义化版本进行比较：

   • 此版本 >= 已发布版本 → 静默继续，不发送消息。（开发者使用尚未发布的较新版本是正常且可接受的。）

   • 此版本 < 已发布版本 → 告知开发者：

     ⚠️ 此技能有较新版本（v<published>）已发布 — 你当前使用的是 v<current>。建议升级以获得最佳效果。

     然后询问他们是要继续使用当前版本，还是停止并先升级，并遵从他们的选择。

   • 无法获取（离线、网络错误、404）→ 简要说明无法验证版本，然后继续。

---

POST https://api.payroc.com/v1/merchant-platforms 会启动新商户的入驻流程。Payroc 会审核提交内容并分配 merchantPlatformId 和 processingAccountId — 请保存这两个 ID，因为订购终端和后续所有入驻操作都需要它们。

如需完整的字段参考和附注示例请求，请阅读 references/api-schema.md（需要枚举值、嵌套字段详情或完整示例时加载）。

---

快速参考

POST  https://api.payroc.com/v1/merchant-platforms
Authorization:   Bearer <token>
Idempotency-Key: <uuid-v4>
Content-Type:    application/json

---

步骤 1 — 获取 bearer token

在输出任何身份验证代码之前，请先阅读 references/identity-call.md。不要猜测端点 URL、标头名称或响应格式 — 只能使用参考文档中的信息。

令牌约 1 小时后过期。请在每个会话开始前使用 API 密钥换取令牌（或主动刷新）。

# Test / sandbox
curl -X POST https://identity.uat.payroc.com/authorize \
  -H "x-api-key: YOUR_API_KEY"

# Production
curl -X POST https://identity.payroc.com/authorize \
  -H "x-api-key: YOUR_API_KEY"

响应：

{
  "access_token": "eyJhbGc....",
  "expires_in": 3600,
  "token_type": "Bearer"
}

在后续每个请求中使用 Authorization: Bearer <access_token>。

---

步骤 2 — 构建请求正文

正文包含两个必需的顶层键：

{
  "business": { ... },
  "processingAccounts": [ { ... } ],
  "metadata": {}
}

metadata 为可选项 — 可用它附加你自己的键值对（例如内部客户 ID），Payroc 会在响应中原样返回。

企业对象

描述法人实体。必需字段：

字段	类型	说明
name	string	企业法定名称
taxId	string	EIN（美国）
organizationType	enum	取值请参阅架构参考
countryOfOperation	string	"US"
addresses	array	必须包含一个 "type": "legalAddress" 条目
contactMethods	array	必须至少包含一个 "type": "email" 条目

处理账户

每个元素都会开通一个 MID。数组中至少要有一项。每个账户必填的关键字段：

字段	说明
doingBusinessAs	商号／DBA 名称
merchandiseOrServiceSold	通俗易懂的商品或服务说明
businessStartDate	YYYY-MM-DD
timezone	例如 "America/New_York" — 完整列表请参阅架构参考
address	企业的实际地址
contactMethods	必须提供电子邮箱
owners	请参阅下方的所有权规则
processing	交易量和银行卡受理情况
funding	银行账户和结算计划
pricing	定价意向 ID 或完整定价协议
signature	商户签署合同的方式
addendums	数组 — 如果不适用任何特殊表格，则填写 []；请参阅下方的附加条款

businessType（retail、restaurant、internet、moto、lodging、notForProfit）和 categoryCode（4 位 MCC 整数）为可选字段 — 已知时请提供，因为下游开户审核仍会使用这些字段。processor（tsys | fiserv，默认值为 tsys）也为可选字段；请明确提供，而不要依赖默认值。

附加条款 — 询问商户是否需要随协议一并发送以下任何表格： 分期付款、货币服务、远程医疗、枪支、药房无卡交易合规、CBD、 烟草无卡交易、捐赠、Clover 设备或 Roc Giving。请求中必须包含 addendums，若都不适用，填写 [] 即可。各类型的负载结构请参阅 references/api-schema.md#addendums（Clover 和 Roc Giving 包含实际字段；其余仅需确认声明）。

所有权规则 — 每个处理账户都需要：

• 恰好一位所有者设置 relationship.isControlProng: true（只能有一位控制权所有者）
• 至少一位所有者设置 relationship.isAuthorizedSignatory: true

同一位所有者不能兼具这两种身份 — API 会拒绝同时设置了这两个标志的所有者（“必须二选一，或都不选”），因此至少需要两位所有者（一位控制权所有者，另一位授权签字人）。每位所有者还需要提供 firstName、lastName、dateOfBirth（YYYY-MM-DD）、address、identifiers（国家身份证件／SSN），以及 contactMethods 中的电子邮箱。

定价快捷方式 — 如果有定价模板，请使用：

{ "type": "intent", "pricingIntentId": "<id>" }

否则，请提供完整的 agreement 对象（结构请参阅架构参考）。

签名 — 通过电子邮件发送签署链接：

{ "type": "requestedViaEmail" }

如果要自行管理重定向，也可以使用 "requestedViaDirectLink" 和 HATEOAS 链接对象。

交易量明细 — processing.volumeBreakdown.cardPresent + mailOrTelephone + ecommerce 的总和必须恰好为 100。

金额单位为美分 — transactionAmounts.average: 5000 表示 50.00 美元。

---

第 3 步 — 发送请求

始终为 Idempotency-Key 生成全新的 UUID v4。该键与请求正文绑定，因此只有在重试字节级完全相同的提交时，才能复用同一个键 — 此时 API 会返回原始响应，而不是创建重复记录。提交全新请求时，或修正 400 错误后重新提交时（修正后的正文已不再匹配旧键），请生成新的 UUID — 如果正文已更改却复用旧键，将返回 409。

curl -X POST https://api.payroc.com/v1/merchant-platforms \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d @merchant-payload.json

---

第 4 步 — 处理响应

201 Created — 开户申请已受理：

{
  "merchantPlatformId": "MP-XXXX",
  "processingAccounts": [
    {
      "processingAccountId": "PA-XXXX",
      "status": "entered"   // may also be "pending" depending on timing
    }
  ],
  "links": [ ... ]
}

立即保存 merchantPlatformId 和每个 processingAccountId。初始 status 通常为 "entered"（已收到，尚未审核），但也可能因处理时机而显示为 "pending" — 请通过轮询或使用 Webhook 检测状态变化，而不要依赖创建响应中的状态值。

ID 为不透明字符串。 示例中的 MP-XXXX / PA-XXXX / PI-XXXX 形式仅为便于阅读。请将每个 ID 都视为不透明字符串，其格式没有保证，且会因环境而异 — 在 UAT 中，它们会以普通整数的形式返回（例如 9815）。不要根据 PREFIX-XXXX 模式验证或解析这些 ID。

---

步骤 5 — 处理错误

错误遵循 RFC 7807，包含一个指向 Payroc 文档的 type URL，以及一个用于验证失败的 errors 数组。

状态	场景	操作
400 validation	字段问题	修正 errors[].parameter 中指出的每个字段；使用新的幂等键重新提交（修正后的请求体需要使用新键）
400 idempotencyKeyMissing	缺少标头	在请求中添加 Idempotency-Key: <uuid-v4>
400 addendum/processor validation	addendums[].type 无法识别或重复、附录缺少必填字段，或 processor 无法识别	这不是致命错误或意外错误——请参阅 references/api-schema.md 中的附录/处理方错误表；修正被标记的字段并重新提交
401	令牌已过期或无效	重新进行身份验证并获取新的 bearer 令牌
403	权限不足	检查 API 密钥的作用范围；联系 Payroc 支持
409 resourceAlreadyExists	商户重复	检查商户是否已完成入驻；检索现有记录
409 idempotencyKeyInUse	使用不同的载荷重复使用密钥	为新提交生成新的 UUID
409 taxIdInUse	已存在具有该 Tax ID 的商户	改为检索现有商户平台
500	服务器错误	使用指数退避重试；如果存在 errors 数组，则显示该数组

读取验证错误 — 响应使用 RFC 7807 问题详情封装（type、 title、status、detail、instance）；Payroc 在此基础上扩展了 RFC 7807 未定义的 errors 数组。每个 errors[] 项都包含 parameter（失败字段的 JSON 路径）、detail（简短原因——与顶层的 detail 不同）和 message（面向用户的说明）。封装结构和规范错误 type 目录请参阅 references/error-response-format.md。来自 UAT 的实际 400 响应（空请求体）：

{
  "type": "https://docs.payroc.com/api/errors#bad-request",
  "title": "Bad request",
  "status": 400,
  "detail": "One or more validation errors occurred, see error section for more info",
  "instance": "https://api.uat.payroc.com/v1/merchant-platforms",
  "errors": [
    {
      "parameter": "merchantPlatform.business",
      "detail": "Invalid value",
      "message": "'business' must not be empty."
    },
    {
      "parameter": "merchantPlatform.processingAccounts",
      "detail": "Required field not populated",
      "message": "'processingAccounts' must not be empty."
    }
  ]
}

每个 parameter 路径都映射到请求体中失败的字段——使用它来定位并修正每个问题。在单个修正后的载荷中修正所有被标记的字段，然后重新提交。（已发布的 OpenAPI 规范仅列出每个项目的 message，但实际 API 还会返回 parameter 和 detail——已根据 UAT 验证，2026-06-16。）

---

常见问题

• 没有控制人 / 授权签字人：每个处理账户的 owners 数组中都必须包含这两种角色——但同一所有人不能同时担任两种角色（API 会拒绝），因此至少需要两位所有人（一位控制人，另一位授权签字人）
• 电话/传真 value 中包含非数字字符：phone/mobile/fax 的 value 只能包含数字——不能有 +、空格或标点符号（例如 5125550199，不能是 +1 512 555 0199）
• 交易量明细总和不等于 100：cardPresent + mailOrTelephone + ecommerce 必须恰好等于 100；如果 ecommerce > 0，则账户必须填写 website
• 金额以美分为单位：所有货币值（transactionAmounts、monthlyAmounts、acceleratedFundingFee）都以美分为单位，且必须为整数
• 日期格式：dateOfBirth 和 businessStartDate 必须采用 YYYY-MM-DD 格式
• 缺少幂等键：所有 POST 请求都必须包含 Idempotency-Key，否则会收到 400 错误
• 对不同载荷重复使用同一密钥：每次不同的提交都需要使用各自的 UUID

---

完整字段参考

请阅读 references/api-schema.md，了解：

• 所有枚举值（organizationType、businessType、timezone、fundingSchedule 等）
• 完整的嵌套对象架构（owners、processing、funding、pricing、signature）
• 附带注释的端到端请求体示例