integrate-payment-links

Payroc Payment Links 集成

版本检查（请先执行）

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

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

   • 此版本 >= 已发布版本 → 静默继续，不发送消息。（开发者使用尚未发布的较新版本是预期情况，可以继续。）

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

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

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

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

---

首次调用时，向开发者宣布：

Payroc Payment Links 集成 我将引导你完成从设置到可正常运行的集成 — 创建链接、可选地通过电子邮件分享链接，以及管理其生命周期。

Payment Links 的工作方式：

1. 你调用 Payroc 的 API 创建支付链接 — 并获得一个 URL
2. 你（或 Payroc 的电子邮件服务）将该 URL 分享给客户
3. 客户点击链接，并在 Payroc 托管的支付页面上付款
4. 链接会变为 completed（单次使用），或保持 active（多次使用）

Payment Links、Hosted Pages 与 Hosted Fields 的区别：

• Payment Links — 你生成一个 URL，并通过任意方式分享（电子邮件、SMS、发票）。你的网站上无需结账表单。本技能。
• Hosted Pages（HPP） — 客户在你的网站上结账，流程中途会被重定向到 Payroc 的支付页面，然后返回。请参阅其他技能。
• Hosted Fields — Payroc 的卡片输入小组件直接嵌入你自己的结账表单中。无需重定向。请参阅其他技能。

[如果有 MCP 连接检查工具，请在此运行，并在继续前展示结果。]

---

快速参考

POST  https://api.uat.payroc.com/v1/processing-terminals/{processingTerminalId}/payment-links
Authorization:   Bearer <token>
Idempotency-Key: <uuid-v4>
Content-Type:    application/json

---

参考资料

所有枚举值和架构均位于下方本地 references/ 文件中 — 本技能依据这些文件生成内容，而非实时查询或记忆。Payment Links 是纯 REST/JSON API；没有表单 POST 接口。

来源	本地文件	用途
API 架构参考	references/api-schema.md	所有枚举值、必填字段、请求/响应架构、扣款结构、JSON Patch 操作
错误响应格式	references/error-response-format.md	错误封装（RFC 7807）+ Payroc errors[] + 规范错误类型目录
创建和分享指南	references/create-and-share-a-payment-link.md	创建和分享的分步说明
扩展功能指南	references/extend-your-integration.md	获取、列出、更新、停用、分享事件

这些是本技能的本地快照，具有权威性。其源 URL 和上次同步日期记录在 references/_sources.md 中 — 如果内容看起来已过时，请从该文件重新生成。

---

核心原则

1. 先检查，再提问 — 提问前先阅读代码库；根据发现跳过显而易见的问题，并提出有针对性的问题。
2. 先提问，再编码 — 编写实现代码前，先通过信息收集了解未知事项；错误的假设会浪费开发者的时间。
3. 输出任何枚举值前，先阅读架构参考文档。 所有接受固定字符串集合的字段——type、authType、paymentMethods[] 的值、status、sharingMethod、JSON Patch 的 op 值——都记录在 references/api-schema.md 中，这是本技能的权威参考文档。输出这些值前先阅读该文档。不要根据训练数据猜测。看似合理、但不在文档枚举中的字符串会导致 400 错误或静默不匹配。审查开发者提供的代码时也适用同一规则：判断枚举值或字段名称是否正确前，请查阅 references/api-schema.md，切勿凭记忆验证。
4. 除 /deactivate 外，每个 POST 和 PATCH 请求都必须包含 Idempotency-Key。 该请求头的值必须是 UUID v4。这是必需的请求头，不是可选项——省略会导致 400 错误。每个不同的操作都生成新的 UUID（不要在不同请求间重复使用同一个键）。唯一例外是 POST /v1/payment-links/{paymentLinkId}/deactivate，此请求不需要该请求头；即使发送了也无妨，但省略不会导致 400 错误。
5. 绝不硬编码凭据。 API 密钥和终端 ID 必须来自环境变量或密钥管理器，不能写入源代码或提交到版本控制的配置文件。
6. Bearer 令牌过期时间。 身份服务颁发的令牌会在 3,600 秒（1 小时）后过期。对于短脚本，这没有问题；对于长期运行的服务，请实现令牌刷新逻辑。
7. 验证通过后再继续 — 当前步骤的检查点在 UAT 中通过前，不要进入下一步。
8. 先诊断，再继续 — 如果某一步失败，请暂停并按错误分类排查后再继续。

---

信息收集

首先，扫描代码库。 查找以下内容：

• 服务端语言和框架
• 现有的发票、订单或账单相关代码
• 现有的 HTTP 客户端配置或凭据配置
• 环境变量的管理方式

利用发现的信息预先填写显而易见的答案，并提出有针对性的问题。然后展示以下清单——开发者的回答决定你需要实现哪些部分：

---

你的集成需要哪些功能？请开发者选择所有适用项：

• [始终包含] 创建付款链接（必需的核心功能）
• 通过 Payroc 的 API 发送邮件分享链接
• 获取特定链接的详细信息
• 列出／搜索某个终端的所有链接
• 更新链接（更改到期日期、标签或金额）
• 永久停用链接
• 查看分享历史记录（列出分享事件）
• 将付款详情令牌化／保存，以便未来收费（credentialOnFile）

另请确认：

• 链接类型： 单次使用（成功付款一次后变为 completed）还是多次使用（付款次数不限）？
• 交易类型： 销售（立即扣款）还是预授权（冻结资金，之后再扣款）？
• 付款方式： 卡、银行转账，还是两者都有？
• 金额： 固定（由你设置）还是由客户输入（提示客户填写）？

根据回答跳过不适用的部分。如果开发者的使用场景不明确（例如“我想发送发票”），请先提出一个有针对性的澄清问题再继续。

---

前提条件

以下条件是运行和测试 UAT 集成所需的，并非编写代码所需。如果开发者已经具备这些条件，那就很好。如果没有，也不要停下来：让代码从环境变量读取每个值，然后继续构建。开发者可以在测试前填入这些变量。

1. API 密钥 — 用于从 Payroc 身份服务生成 Bearer 令牌。由 Payroc Integrations 团队在提供 UAT 访问权限时一并配置。
2. 处理终端 ID — 在创建链接端点路径中使用的 processingTerminalId。开发者应已从 UAT 设置中获知此值。
3. UAT 环境 — Payroc 的测试环境。无法自行注册；UAT 终端由 Payroc Integrations 团队手动配置。

如果缺少任何内容——发出提醒，不要阻止开发。 检查代码库中是否已有环境变量命名约定，并沿用该约定；否则，建议使用 PAYROC_API_KEY 和 PAYROC_TERMINAL_ID 等名称。编写代码以从这些变量读取凭据，然后明确告知开发者：

⚠️ 我已将代码设置为从 <VAR names> 读取 API 密钥和终端 ID。要实际运行或测试，你需要 Payroc UAT 终端和 API 密钥——请联系 Payroc Integrations 团队获取，并在测试前设置这些变量。同时我可以继续构建。

主动提出协助获取缺少的内容；如果开发者愿意，则继续开发。

检查点

凭据已确认，或者开发者已了解尚缺少哪些内容、如何获取，以及代码从哪些环境变量读取这些内容，并已选择继续。不要对缺少的项目只字不提，但也不要因此阻塞开发。

---

步骤 1 — 身份验证

在编写任何身份验证代码之前，请先阅读 references/identity-call.md。不要猜测端点 URL、标头名称或响应结构——仅使用参考文档中说明的信息。

端点：

• UAT/测试：POST https://identity.uat.payroc.com/authorize
• 生产环境：POST https://identity.payroc.com/authorize

标头：x-api-key: <api-key>

响应包含 access_token、expires_in（3600）和 token_type（"Bearer"）。所有后续 API 请求都使用 Authorization: Bearer <access_token>。

使用开发者所用的语言实现令牌生成辅助函数。对于生产代码，请加入过期跟踪和刷新逻辑——令牌在操作过程中途过期，会导致原本有效的请求返回 401。

将 API 密钥存储在环境变量中（例如 PAYROC_API_KEY）。切勿将其直接写入代码。

检查点

辅助函数能否在不报错的情况下生成 Bearer 令牌？如果不能，请检查 x-api-key 标头，并确认 API 密钥适用于 UAT 环境。

---

步骤 2 — 创建支付链接

端点：POST https://api.uat.payroc.com/v1/processing-terminals/{processingTerminalId}/payment-links

必需的标头：

Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: <UUID v4>

编写请求正文前，请先阅读 references/api-schema.md。 type、authType、paymentMethods 数组元素的取值以及 charge 对象结构均在其中定义。请勿使用训练数据中的任何内容——参考文档才是依据。

根据受理问题的答案，需要实现以下关键决策：

请根据参考文档确认完整的必填字段集。 不要依赖记忆中的必填字段列表——请阅读 references/api-schema.md 中的创建链接请求架构，检查哪些根级字段必填（例如 merchantReference），以及哪些字段取决于链接类型。审查开发者代码时，关于缺少必填字段的判断必须以架构参考为依据，而不是凭记忆；看起来“可选”的字段也可能是必填项。

链接类型

• singleUse — 仅允许一次成功付款。根据架构，单次使用链接需要额外字段（例如 order 对象中的 orderId，以及 YYYY-MM-DD 格式的 expiresOn）——请在 references/api-schema.md 中确认确切的条件要求。付款后：链接状态变为 completed。
• multiUse — 可接受无限次付款。单次使用专属字段不必填写。

交易类型（authType）

• sale — 立即扣款
• preAuthorization — 暂时冻结资金；之后必须使用该付款的 ID 调用 capture 端点

付款方式

• 数组中包含 card、bankTransfer，或两者都有——编写前请先从 references/api-schema.md 中读取有效取值
• 银行转账 + 多次使用 + 预授权是有效组合，但在示例中较少出现——务必查阅参考文档，不要依赖仅涉及银行卡的流程模式

Charge — charge 是一个由 type 字段区分的单层对象。preset 和 prompt 是 type 可取的值，而不是要嵌套在其下的键。金额和货币字段与 type 并列：

// preset — you set the amount
"charge": { "type": "preset", "amount": 10000, "currency": "GBP" }

// prompt — customer enters the amount at payment time (no amount field)
"charge": { "type": "prompt", "currency": "GBP" }

常见错误——嵌套 preset 陷阱。 编写 "charge": { "preset": { "amount": …, "currency": … } }（或嵌套的 prompt 键）是错误的，API 会以 400 错误拒绝请求。不存在 preset/prompt 键——preset/prompt 是 type 的值，而 amount/currency 与 type 并列。审查开发者代码时，请明确指出这一点：必须移除嵌套的 preset/prompt 包装，而不只是“添加一个 type 字段”。此代码片段仅展示结构——请阅读 references/api-schema.md，确认确切的 charge 架构和任何附加字段。

从响应中保存 paymentLinkId 和 assets.paymentUrl——后续所有操作都需要它们。

检查点

API 是否返回包含 paymentLinkId 和 assets.paymentUrl 的 HTTP 201 响应？如果没有，请逐项排查错误分类。

---

步骤 3 — 通过电子邮件分享

（如果开发者选择了“通过电子邮件分享链接”，请包含此部分）

端点：POST https://api.uat.payroc.com/v1/payment-links/{paymentLinkId}/sharing-events

必需的标头：

Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: <UUID v4>      ← generate a new UUID; do not reuse Step 2's key

请求正文：

{
  "sharingMethod": "email",
  "recipients": [
    { "name": "Customer Name", "email": "[email protected]" }
  ],
  "message": "Optional message to include with the payment link",
  "merchantCopy": false
}

编写 sharingMethod 值前，请先阅读 references/api-schema.md——使用文档中定义的枚举值，不要猜测。

响应（HTTP 201）包含用于追踪的 sharingEventId。如果应用需要分享历史记录，请保存此值。

检查点

API 是否返回包含 sharingEventId 的 HTTP 201 响应？如果没有，请确认 paymentLinkId 正确，并且 Idempotency-Key 是一个新生成的 UUID。

---

步骤 4 — 扩展功能

（仅实现开发者在受理阶段选择的小节）

获取链接

GET https://api.uat.payroc.com/v1/payment-links/{paymentLinkId}

标头：Authorization: Bearer <token>

返回包含当前 status 的完整链接对象。可用于检查单次使用链接是否已完成。

列出终端的链接

GET https://api.uat.payroc.com/v1/processing-terminals/{processingTerminalId}/payment-links

请求头：Authorization: Bearer <token>

支持的查询筛选条件：merchantReference、linkType（singleUse/multiUse）、chargeType、status（active/completed/deactivated/expired）、recipientName、recipientEmail、createdOn、expiresOn。

分页：通过 limit、after、before 查询参数进行基于游标的分页。响应中的 hasMore 字段表示是否还有后续页面。

编写筛选逻辑前，请阅读 references/api-schema.md，了解 linkType 和 status 的确切枚举值。

---

更新链接（部分更新）

PATCH https://api.uat.payroc.com/v1/payment-links/{paymentLinkId}

必需请求头：Authorization: Bearer <token>、Idempotency-Key: <UUID v4>

请求正文是 RFC 6902 JSON Patch 数组，而不是 PUT 正文：

[
  { "op": "replace", "path": "/expiresOn", "value": "2026-12-31" }
]

支持的 op 值：add、remove、replace、move、copy、test。有关补丁操作集合和各类型约束，请参阅 references/api-schema.md。

**重要提示：**更新单次使用链接会重新生成 paymentUrl 和 paymentButton。如果你已经分发了旧 URL，则必须重新分享新 URL。

---

停用链接

POST https://api.uat.payroc.com/v1/payment-links/{paymentLinkId}/deactivate

必需请求头：Authorization: Bearer <token>

编写停用代码前：请向开发者确认，他们了解此操作是永久且不可逆的。停用的链接：

• 无法重新启用
• 在之后的所有检索调用中均会返回 deactivated 状态
• 任何尝试使用该 URL 的客户都无法付款

如果目的是暂时暂停付款，请询问是否可以通过 PATCH 将 expiresOn 更新为过去的日期来实现——之后可通过延长 expiresOn 重新启用该链接。只有在开发者明确确认要永久停用后，才能继续编写停用代码。

---

列出分享事件

GET https://api.uat.payroc.com/v1/payment-links/{paymentLinkId}/sharing-events

请求头：Authorization: Bearer <token>

筛选条件：recipientName、recipientEmail。分页：limit、before、after（基于游标；只能使用其中一个，不能同时使用）。

返回带分页的分享事件列表，其中包含时间戳、收件人详细信息以及可选的消息文本。

---

错误分类

症状	可能原因	修复方法
任意请求都返回 401	缺少令牌、令牌已过期或 API 密钥错误	重新生成令牌；确认 x-api-key 标头中的值是正确的 UAT API 密钥
400 — 验证错误提及 type、authType 或 paymentMethods	枚举值不在参考文档中	阅读 references/api-schema.md，并使用文档中规定的值
400 — 缺少或格式错误的 Idempotency-Key	未提供标头或标头值不是 UUID v4	为除 /deactivate 之外的每个 POST 和 PATCH 请求添加 Idempotency-Key: <UUID v4>；每项操作都生成新的 UUID
400 — 单次使用链接缺少必填字段	缺少架构标记为必填的字段	阅读 references/api-schema.md 中的创建链接架构；添加所有必填字段（单次使用链接通常需要在 order 中包含 orderId，并提供 expiresOn）
400 — charge 对象被拒绝或格式错误	charge 被嵌套在 preset/prompt 键中（charge.preset.amount）	将其展平：charge 是一个对象，其中 type（preset/prompt）与 amount/currency 是同级字段，不能有嵌套包装键
409 — Idempotency-Key 重复	同一个键被用于不同的操作	为每项不同的操作生成一个新的 UUID
PATCH 意外重新生成 paymentUrl	按设计，更新单次使用链接时会重新生成 URL	从更新后的响应中重新分享新 URL
链接 status: expired，客户无法付款	expiresOn 已过期	如果仍要保持链接有效，请通过 PATCH 延长 expiresOn
链接 status: deactivated，客户无法付款	链接已被永久停用	创建新链接 — 已停用的链接无法重新激活
付款链接端点返回 404	paymentLinkId 错误或链接不存在	确认使用创建响应中的 ID；检查列表端点以确认链接是否存在
预授权：资金已冻结，但从未扣款	未实现或未调用扣款步骤	使用 Payments API 中该笔付款的 ID 实现扣款；预授权会在发卡机构的冻结期限后过期

---

验证清单

• API 密钥来自环境变量 — 绝不硬编码
• Bearer 令牌由身份服务生成 — 绝不硬编码
• 除 /deactivate 外的每个 POST 和 PATCH 请求都包含 Idempotency-Key 标头，且其值为 UUID v4
• type、authType、paymentMethods[] 的值以及所有其他枚举值均从 references/api-schema.md 中读取 — 不使用训练数据中的值
• 从创建响应中获取 paymentLinkId 并保存，以供后续操作使用
• 单次使用链接：创建请求中包含所有必填字段（依据 references/api-schema.md 确认，而不是凭记忆）
• charge 是扁平对象 — type（preset/prompt）与 amount/currency 是同级字段；没有嵌套的 preset/prompt 包装键
• 停用：编写代码前，开发者已明确确认该操作是永久性的
• PATCH 操作：使用 RFC 6902 JSON Patch 数组格式（而非 PUT/POST 请求体）
• 使用 UAT 端点（api.uat.payroc.com）— 测试期间不使用生产端点

---

完成

完成所有检查清单项后：

**集成完成。**你已构建：

• 身份验证 — 通过 Payroc 身份服务生成持有者令牌；凭据存储在环境变量中。
• 创建支付链接 — [总结：类型、authType、paymentMethods、收费类型]
• 通过电子邮件分享（如已构建）— 通过 Payroc 的 API 将支付 URL 发送给收件人；存储 sharingEventId。
• 扩展功能（列出已构建的功能）— 检索、列出、更新、停用、分享事件。
• 已在 UAT 中验证 — 已确认端到端流程。

**上线前：**将 api.uat.payroc.com 替换为 api.payroc.com，并将 identity.uat.payroc.com 替换为 identity.payroc.com。将凭据指向生产终端和 API 密钥。

提供后续步骤：

• 令牌化 / 定期账单 — 使用 credentialOnFile 保存支付详情，以便日后由商户发起扣款
• Webhook 通知 — 接收服务器端支付事件，而不是轮询 Payments API
• Hosted Fields — 将 Payroc 卡片输入控件直接嵌入你自己的结账表单（无需重定向）