create-pricing-intent

创建定价意图

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

在宣布任何内容或启动流程之前，请确认此技能是最新版本：

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

   • 此版本 >= 已发布版本 → 静默继续，不发送消息。（开发者运行尚未发布的较新版本是预期情况，也没有问题。）

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

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

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

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

---

定价意图是一种可重复使用的商户处理协议（MPA）模板。你只需定义一次费用，由 Payroc 审核并批准，然后在商户入驻期间将其 id 分配给处理账户——一个简短的引用即可替代层层嵌套的定价协议。

POST https://api.payroc.com/v1/pricing-intents 会创建该模板。Payroc 会返回一个 id 和状态 pendingReview；状态变为 active 后，你可以在 create-merchant-platform 中引用它（参见下方的“使用 ID”）。

定价意图不是“支付意图”。 定价意图是在商户入驻期间使用的可重复使用的费用模板——它不会收取、授权或扣取任何资金。某些其他支付网关（例如 Stripe）使用“支付意图”指交易／授权对象；Payroc 没有此类端点（支付功能属于单独的交易 API）。如果开发者提到“支付意图”，或似乎想要刷卡收费或收取款项，而不是定义费用，请暂停并确认他们的具体需求，然后再进行任何操作——如果他们想要转移资金，请引导他们使用支付／交易 API，而不是此技能。

定价意图是可选的。 create-merchant-platform 接受 pricing.type: "intent"（引用 pricingIntentId）或 pricing.type: "agreement"（直接内嵌完整费用对象）。如果要为许多商户使用相同的费用结构，请使用定价意图；如果是一次性协议，则可跳过。

完整字段参考——包括每个枚举、各计划的 fees 结构以及完整示例——请阅读 references/api-schema.md。需要枚举值、嵌套字段详情或单位时，都要加载该文件。请从该参考中获取枚举值和字段名称，不要凭记忆填写。

---

工作方式

此技能采用访谈方式，而不是待填写的表单。开发者会用通俗的业务语言描述其定价——“交换费加成，Mastercard/Visa/Discover 收取 0.25% + 10¢，年费 $99，网关费每月 $25”——此技能会将其转换为正确的嵌套多态 JSON 请求体。不要要求开发者提交完整的 JSON 结构，也不要直接给他们一份空白模板：通过对话收集数值（从步骤 2 的 planType 开始），然后组装请求。

如果开发者确实粘贴了完整或部分 JSON 请求体，请原样采用并补齐缺失部分——根据 references/api-schema.md 验证，并且只询问缺少的信息。

---

快速参考

Base URL (test):  https://api.uat.payroc.com/v1
Base URL (prod):  https://api.payroc.com/v1

GET    /pricing-intents                     # list (paginated)
POST   /pricing-intents                     # create            (Idempotency-Key required)
GET    /pricing-intents/{pricingIntentId}   # retrieve
PUT    /pricing-intents/{pricingIntentId}   # full replace      -> 204 No Content
PATCH  /pricing-intents/{pricingIntentId}   # JSON Patch (RFC 6902, Idempotency-Key required)
DELETE /pricing-intents/{pricingIntentId}   # delete            -> 204 No Content

Authorization:   Bearer <token>     (all operations)
Idempotency-Key: <uuid-v4>          (POST and PATCH only)
Content-Type:    application/json    (POST, PUT, PATCH)

---

步骤 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 — 选择定价方案

影响最大的决定是 processor.card.planType——它决定 fees 对象的结构。请选择一种：

planType	定价模式	适用场景
interchangePlus	交换费直通 + 固定加价	透明的成本加成；最常见
interchangePlusPlus	交换费 + 加价，按合格/中等/不合格档拆分	按费率档划分的成本加成
tiered3	3 个档位：合格 / 中等合格 / 不合格	简单的分档定价
tiered4	3 个档位 + 高端档	含高端卡档位的分档定价
tiered6	高端档 + 受监管 / 不受监管的借记卡档位	精细的分档定价
flatRate	单一固定百分比 + 每笔交易费用	简单、可预测的定价
consumerChoice	月度订阅 + 对非现金支付收取附加费 / 提供现金折扣	附加费 / 现金折扣方案
rewardPayChoice	订阅 + 分别处理借记卡和信用卡	区分奖励卡

在构建请求体之前，请阅读 references/api-schema.md 中对应的小节，了解该变体所需的确切 fees 字段。planType 判别值必须来自参考文档。

---

步骤 3 — 构建请求体

以下四个顶层键为必填项：key、country、version、base。processor、gateway、 services 和 metadata 为可选项（但你几乎总会包含 processor 和 gateway）。

{
  "key": "RETAIL-STANDARD-2026",
  "country": "US",
  "version": "5.2",
  "base": { ... },
  "processor": { "card": { "planType": "...", "fees": { ... } }, "ach": { ... } },
  "gateway": { "fees": { ... } },
  "services": [ ... ],
  "metadata": {}
}

关键规则：

• key 是你为模板指定的标识符（用于自己的记录），不同于 Payroc 分配的 id。此项为必填。
• country 仅接受 US；version 仅接受 5.2。
• 所有金额均以美分为单位——transaction: 10 表示 $0.10，monthly: 2500 表示 $25.00。
• 百分比（volume、折扣率）是最多保留 2 位小数的数字——0.25 表示 0.25%。
• base 必须包含以下全部七项：addressVerification、annualFee（一个自身包含必填项 amount 的对象）、regulatoryAssistanceProgram、merchantAdvantage、maintenance、minimum 和 batch——每个键都必须存在且值为数字，否则会返回 400。OpenAPI 规范将 addressVerification、regulatoryAssistanceProgram 和 merchantAdvantage 标记为可空，但线上 UAT API 会拒绝这三项的 null 值（“must not be empty”，已于 2026-06-19 验证）——因此请传入数字，商户无需支付某项费用时使用 0。也不要省略这些键；省略必填键同样会导致验证失败。可选费用（pciNonCompliance、chargeback 等）有服务器默认值——请参阅参考文档。
• processor.card.fees 的结构因 planType 而异（请参阅步骤 2 和参考文档）。对于 interchangePlus，必须提供 fees.mastercardVisaDiscover。
• gateway.fees 必须包含 monthly、setup、perTransaction 和 perDeviceMonthly。
• 仅限 ACH 的模板：processor.card 为可选项——如果商户仅处理 ACH，请完全省略 card，只传入 processor.ach（其 fees 对象也有自己的必填键；请参阅参考文档）。gateway 也为可选项：没有网关时，请省略整个对象，不要传入费用均为零的网关对象。仅限 ACH 的模板仍必须包含 base。

interchangePlus 的最简示例：

{
  "key": "RETAIL-STANDARD-2026",
  "country": "US",
  "version": "5.2",
  "base": {
    "addressVerification": 10,
    "annualFee": { "amount": 9900, "billInMonth": "december" },
    "regulatoryAssistanceProgram": 0,
    "merchantAdvantage": 0,
    "maintenance": 995,
    "minimum": 2500,
    "batch": 25
  },
  "processor": {
    "card": {
      "planType": "interchangePlus",
      "fees": {
        "mastercardVisaDiscover": { "volume": 0.25, "transaction": 10 },
        "amex": { "type": "optBlue", "volume": 0.30, "transaction": 10 }
      }
    }
  },
  "gateway": {
    "fees": { "monthly": 2500, "setup": 0, "perTransaction": 10, "perDeviceMonthly": 0 }
  }
}

flatRate 的最简示例——请注意，卡片 fees 使用 standardCards（没有 mastercardVisaDiscover），此处 amex 仅支持 direct 变体；规范中标记为可空的 base 字段传入 0（UAT 会拒绝 null）：

{
  "key": "SOFTWARE-SUBS-FLATRATE-2026",
  "country": "US",
  "version": "5.2",
  "base": {
    "addressVerification": 0,
    "annualFee": { "amount": 0, "billInMonth": "december" },
    "regulatoryAssistanceProgram": 0,
    "merchantAdvantage": 0,
    "maintenance": 0,
    "minimum": 0,
    "batch": 0
  },
  "processor": {
    "card": {
      "planType": "flatRate",
      "fees": {
        "standardCards": { "volume": 2.90, "transaction": 30 }
      }
    }
  },
  "gateway": {
    "fees": { "monthly": 0, "setup": 0, "perTransaction": 0, "perDeviceMonthly": 0 }
  }
}

对于任何其他 planType，请阅读 references/api-schema.md 中对应的小节，了解确切的 fees 结构，不要猜测——只有 interchangePlus 使用扁平的 mastercardVisaDiscover，分档方案使用 qualRates 风格的对象，而订阅方案（consumerChoice、rewardPayChoice）使用 monthlySubscription 结构。

建议的起始值

规范为部分 base 费用定义了默认值——如果开发者未指定，可将这些值作为起始值（单位均为美分）：

字段	默认值
base.pciNonCompliance	7495（每月）
base.voiceAuthorization	95
base.chargeback	2500
base.retrieval	1500
base.earlyTermination	57500
base.annualFee.billInMonth	december
base.platinumSecurity.amount	1295 每月 / 15540 每年
rewardPayChoice 信用卡 cardChargePercentage	3
rewardPayChoice 信用卡 merchantChargePercentage	0.9

可协商费率没有 API 强制的范围，也没有文档记录的“典型”值——加价 volume 百分比和每笔 transaction 费用由商户协商确定。不要臆造可能的范围或建议“常规”费率；请向开发者询问商定的数值。（这些默认值是规范提供的唯一数值参考——参见 references/api-schema.md。）

---

第 4 步 — 创建定价意向（POST）

始终为 Idempotency-Key 生成一个新的 UUID v4。重试同一次提交时，重复使用相同的键——API 会返回原始响应，而不是创建重复项。对于真正的新提交，则生成新的 UUID。

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

201 Created — 意向已创建，等待审批：

{
  "id": "PI-XXXX",
  "key": "RETAIL-STANDARD-2026",
  "status": "pendingReview",
  "createdDate": "2026-06-16T12:00:00Z",
  "base": { ... },
  "processor": { ... }
}

立即持久化保存 id。在 Payroc 审核之前，status 为 pendingReview；之后会变为 active（已批准）或 rejected。只有当意向处于 active 状态时，才能将其分配给商户。

ID 是不透明的。 示例中使用的 PI-XXXX 形式仅为便于阅读。应将 id 视为不透明字符串，其格式不作保证，且会因环境而异——在 UAT 中，它会以纯整数形式返回（例如 5722）。不要按照 PREFIX-XXXX 模式验证或解析它。

将组装好的请求体交给开发者。 创建成功后，向他们提供最终构建的请求 JSON（或将其写入文件）。保留这份内容有助于审计，也可作为后续修改的起点——通过 PUT 重新提交完整内容（全量替换），或复制一份后通过 PATCH 修改（参见第 6 步）。

---

第 5 步 — 读取和列出（GET）

按 ID 检索单项：

curl https://api.payroc.com/v1/pricing-intents/PI-XXXX \
  -H "Authorization: Bearer $ACCESS_TOKEN"

列出（分页——使用 limit，以及 before/after 游标，两者不能同时使用）：

curl "https://api.payroc.com/v1/pricing-intents?limit=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

列表响应会将结果封装在 { limit, count, hasMore, links, data: [ ... ] } 中。使用 links 或 after 游标继续翻页。如果没有 id，可使用列表查找意向。

---

第 6 步 — 更新（PUT 与 PATCH）

更新定价意向不会更改已完成入驻的商户。文档未说明更新是否会使意向本身重新变为 pendingReview 并需要再次审批——因此，回答时不要假设需要（或不需要）重新审核。如果工作流依赖更新后的状态，请重新 GET 意向并查看其 status，不要猜测。

PUT — 全量替换。 发送完整的 pricingIntent 请求体（结构与创建时相同）。返回 204 No Content。无需幂等键。

curl -X PUT https://api.payroc.com/v1/pricing-intents/PI-XXXX \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @full-pricing-intent.json

PATCH — 使用 RFC 6902 JSON Patch 进行部分更新。 请求体是一个操作数组，不是部分对象。需要 Idempotency-Key。返回 200 和更新后的意向。

curl -X PATCH https://api.payroc.com/v1/pricing-intents/PI-XXXX \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '[ { "op": "replace", "path": "/gateway/fees/monthly", "value": 1995 } ]'

安全的单字段 PATCH。 RFC 6902 允许在操作前添加 test 操作，用于断言当前值；如果断言失败，整个 PATCH 会被拒绝，因此绝不会覆盖与预期不符的值（有助于应对并发编辑）。修改单项费用时，建议采用这种写法：

[
  { "op": "test",    "path": "/gateway/fees/monthly", "value": 2500 },
  { "op": "replace", "path": "/gateway/fees/monthly", "value": 1995 }
]

对定点修改（单项费用）使用 PATCH；替换整个模板时使用 PUT。你可以更新费用、自定义 key/名称以及 services 数组。

第 7 步 — 删除（DELETE）

curl -X DELETE https://api.payroc.com/v1/pricing-intents/PI-XXXX \
  -H "Authorization: Bearer $ACCESS_TOKEN"

返回 204 No Content。删除操作不可撤销——之后无法恢复该意向，也无法将其分配给未来的入网申请。

---

第 8 步 — 处理错误

错误采用 RFC 7807 问题详情格式作为信封：顶层的 type、title、status、detail 和 instance 是 RFC 标准成员。Payroc 在信封中扩展了一个 errors 数组——该数组及其内容由 Payroc 自行定义，并非 RFC 7807 所规定。每个 errors[] 条目都包含 parameter、detail 和 message——parameter 是出错字段的 JSON 路径（例如 country、base.annualFee.amount）；detail 是简短原因（"Invalid format"、"Required field not populated"），与顶层 RFC detail 不同；message 是面向用户的说明。使用 parameter 将每个错误直接对应到请求正文中的字段。（信封结构和规范错误 type 目录，请参阅 references/error-response-format.md。）

已发布的 OpenAPI 规范仅记录了每个条目中的 message，但线上 API 也会返回 parameter 和 detail（已根据 UAT 验证，2026-06-16）。请读取 parameter——它是最快找到需要修正内容的方式。

状态	场景	操作
400	验证错误	使用各项 errors[].parameter 查找字段，并根据 message/detail 了解原因；修正正文后，使用全新的幂等键重新提交（修正后的正文有所不同，因此重用旧键可能导致 409——请参阅下方说明）
401	令牌已过期或无效	重新进行身份验证并获取新的 bearer token
403	权限不足	检查 API 密钥的作用域；instance/resource 会说明尝试执行的操作
404	未找到定价意向	验证 pricingIntentId；使用列表查找
406	不可接受	检查 Content-Type / Accept 标头和正文结构
409	冲突——幂等键被用于内容已更改的正文	不要不假思索地使用新键重新 POST；请参阅下方说明——你可能已经创建了该意向
500	服务器错误	使用指数退避重试；如果存在 errors，请展示出来

创建时遇到 409 需要谨慎处理——你可能已经创建了该意向。 409 表示 Idempotency-Key 被用于内容不同的正文（典型情况：你修正了拼写错误，却使用原来的键重新提交）。重新提交前，请先确认第一次 POST 是否实际成功——因为两种情况的处理方式不同：

• 已成功（你收到了 201/id，或该意向出现在 GET /pricing-intents 中）→ 该意向已使用旧值创建。请使用 PATCH（或 PUT）就地修正——不要重新 POST，否则会留下重复的 pendingReview 意向。
• 未创建任何内容（从未返回过 id）→ 使用全新的 UUID Idempotency-Key 和修正后的正文再次 POST。

只有在重试逐字节完全相同的请求时才重用同一个键；正文有任何更改都需要使用新键。（如果不确定，请使用 GET /pricing-intents 检查已有内容。）

---

将 ID 用于 create-merchant-platform

定价意向变为 active 后，在入网时将其分配给处理账户的 pricing 字段：

"pricing": {
  "type": "intent",
  "pricingIntentId": "PI-XXXX"
}

这是 merchant-platform pricing 对象的 intent 变体；另一种是内联的 agreement 变体。请参阅 create-merchant-platform。

---

常见陷阱

• PATCH 使用的是 JSON Patch，而不是部分对象：发送 [{ "op": "...", "path": "...", "value": ... }]，而不是 { "gateway": { ... } }
• PUT 返回 204，且没有响应体：不要期待返回更新后的记录；如有需要，请重新 GET
• base 费用必须是数字，不能是 null：addressVerification、regulatoryAssistanceProgram 和 merchantAdvantage 是必填键；尽管规范允许其值为 null，UAT 仍会拒绝 null（提示“不得为空”）——请发送数字（不收费时为 0），且绝不能省略该键
• 构建完整请求体，包括修复 400 错误时：更正后的负载仍必须包含所有必填的 base 键和全部四个 gateway.fees 键，否则只会再次收到 400 错误
• 金额以分为单位：每项费用都是以分为单位的整数；百分比为数字（最多 2 位小数）
• key 是必填项，且由你提供：它是你自己的模板标识符，与 Payroc 的 id 不同
• 仅 POST 和 PATCH 使用幂等键：PUT、GET 和 DELETE 不需要
• fees 的结构取决于 planType：填写前请阅读匹配的参考小节
• 仅支持 US / 5.2：目前 country 和 version 各自只接受一个值

---

完整字段参考

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

• 所有枚举值（planType、status、amex.type、billInMonth、billingFrequency 等）
• 各 planType 对应的 fees 架构（interchange plus、tiered 3/4/6、flat rate、consumer/reward choice）
• 带单位的 base、gateway、ach 和 services 对象架构
• 附注说明的创建请求和 PATCH 示例，以及错误架构