integrate-midtrans-payments

集成 Midtrans 支付

操作原则

请将其视为支付系统集成，而非通用 API 接线。在修改代码之前，先了解商家的结账架构、支付产品、持久化模型、回调路径、认证／会话边界、环境管理、部署目标和测试框架。

在推荐 Midtrans 产品或编写代码之前，请完成商家就绪预检：账户状态、沙盒凭据、已启用的支付方式、预期的客户流程、控制面板回调 URL，以及商家要求的验证级别。如果这些信息缺失，且无法从项目中推断出来，请暂停并询问，不要默默做出假设。

每次都使用最新的 Midtrans 文档。先搜索 https://docs.midtrans.com/llms.txt，然后打开所实施支付方式对应的产品页面；llms.txt 提供了每个页面的 .md 版本链接，请获取这些版本，而不是 HTML。

优先级：对于端点、参数、字段名称和产品可用性，以 docs.midtrans.com 上的实时文档内容为准；对于集成规范（状态模型、幂等性、签名处理和验证），以本技能为准。技能版本 0.3.2，已根据 2026-06-25 的 docs.midtrans.com 验证。如果当前文档页面与本技能矛盾，请遵循文档，并请商家通过 https://github.com/veritrans/midtrans-agent-skills/issues 报告不一致之处。

工作流程

1. 运行商家就绪预检

   • 在选择产品或编写代码之前，完成 merchant-readiness-preflight.md。
   • 从环境变量、部署配置、运行手册、测试、提供商代码和规范中推断信息；只询问缺失的阻碍项。
   • 对不可用的支付方式通过配置进行限制，并说明仍需执行哪些控制面板／商家操作。

2. 分类集成类型

   • 确定商家需要的是托管式结账、自定义 UI、定期／令牌化支付、市场／合作伙伴行为，还是混合模式。
   • 编写代码前，将每种所需支付方式映射到对应的 Midtrans 产品。
   • 不要混用 Snap、Core API 和 BI-SNAP 的请求格式、认证请求头、回调语义或状态对象。
   • 如果商家的需求不明确，请阅读 merchant-decision-tree.md，并提出尽可能少的澄清问题。

3. 检查项目（必须满足的前置条件）

   • 在推荐产品、编写代码或编辑配置之前，完成 project-adaptation.md。
   • 阅读仓库说明、环境变量示例、支付文档、结账／订单／支付代码、数据库架构、测试和部署配置。
   • 找出已有的 HTTP、领域、提供商客户端、持久化、UI、运维和日志边界；除非商家要求更改架构，否则应予以保留。
   • 如果无法检查项目（无访问权限、没有仓库或项目从零开始），请明确说明，并暂停操作，直到商家确认目标技术栈。不要编造通用答案。

4. 设计支付状态模型

   • 将结账表示为明确的状态：选择支付方式、创建支付、等待支付、已支付、失败／已取消、已过期、已退款。
   • 在调用提供商之前，将订单转换到 creating_payment（或等效）状态，以确保提供商调用失败时，订单不会处于无法识别的状态。
   • 持久化刷新后仍需使用的提供商数据：商家订单 ID、提供商引用、支付方式、支付说明、重定向／二维码／虚拟账户数据、过期时间、提供商最新状态和安全的原始元数据。
   • 确保回调具备幂等性且状态只朝有效方向推进：绝不能让较晚到达的 pending 或 cancelled 回调覆盖已支付／已履约／已退款状态。

5. 在服务端构建支付服务商客户端

   • 如果商户技术栈适用，优先使用 Midtrans 官方库；即使使用轻量封装，也应由它负责环境变量配置、重试、日志记录和支付状态管理。
   • 将 Midtrans 密钥、签名、访问令牌、客户授权令牌以及支付服务商请求负载签名保留在后端。
   • 对于 Snap/Core API，使用服务器密钥和空密码进行 Basic Auth。
   • 对于 BI-SNAP，分别处理访问令牌签名、交易签名和通知签名。
   • 对将要发送的请求正文，按原始字节或字符串进行签名。
   • 有关特定产品的模式和注意事项，请参阅 midtrans-runtime-patterns.md。

6. 接入回调并恢复状态

   • 在商户控制面板中使用可公开访问的 HTTPS 回调 URL。
   • 更改订单状态前，先验证通知的真实性。
   • 验证浏览器回调或面向用户的支付结果时，应通过后端查询状态，不要信任前端回调数据。
   • 仅在安全地接受回调，或有意将其存储以供后续对账后，才返回 2xx。

7. 添加监控并验证

   • 为支付创建、支付服务商响应、回调、状态轮询、账户关联、取消、退款和对账添加结构化日志。
   • 对机密、签名、授权标头、令牌、客户个人身份信息以及完整的支付服务商请求负载进行脱敏，除非明确允许记录。
   • 覆盖状态映射、签名生成与验证、幂等回调处理、过期支付、已禁用的支付方式、退款流程以及环境变量与部署配置不一致等情况。
   • 请参阅 verification-playbook.md。
   • 当用户要求在沙盒中验证集成、重放 Webhook、轮询状态、运行冒烟测试或诊断沙盒行为时，请阅读 sandbox-interaction-helper.md。

8. 准备可移植到不同 Agent 的输出

   • 如果要求将经验打包为技能，请保持 SKILL.md 简洁，并将产品详情移至参考文档。
   • 除非目标 Agent 有更多要求，否则仅使用标准 frontmatter 字段。
   • 有关 Claude、Codex、Copilot、Cursor、OpenCode 以及不支持原生技能的工具，请参阅 agent-portability.md。

Pathway References

仅加载与商户请求相关的参考资料：

商户请求或症状	阅读
任何新的 Midtrans 实现、迁移或验证请求	merchant-readiness-preflight.md 和 project-adaptation.md
不确定该使用 Snap、Core API、BI-SNAP、Payment Link，还是混合方案	merchant-decision-tree.md
仅限 Snap 的托管结账、Snap 弹窗／重定向／嵌入、Snap webhook 或状态错误	snap-checkout.md
移动应用／WebView／深度链接	mobile-sdk.md
BI-SNAP QRIS、VA、一次性 Direct Debit、签名、访问令牌、通知分发器	bisnap-core.md
GoPay 关联、令牌化钱包、GoPayLater、Binding Inquiry、取消账户关联	gopay-tokenization.md
通过 API 或仪表板创建 Payment Link、发票／聊天收款、社交电商、无代码分享链接	payment-links.md
Subscription API、定期信用卡扣款、使用已保存令牌进行定期扣款、定期通知路由	subscriptions.md
传统 Core API 信用卡／3DS／一键支付／分期、OTC（Alfamart／Indomaret）、旧版 VA	core-api-classic.md
上述内容未涵盖的跨产品运行时模式和注意事项	midtrans-runtime-patterns.md 和当前文档
发起退款（全额或部分）、refund_key／partnerRefundNo 幂等性、BI-SNAP 退款、退款 webhook 处理	refund-operations.md
Sandbox／正式环境切换、回调、日志、密钥、冒烟测试、生产就绪情况	operations-and-go-live.md
Sandbox 交互、冒烟测试、webhook 重放、状态轮询、BI-SNAP 签名试运行、凭据安全的测试命令	sandbox-interaction-helper.md 和 scripts/README.md
改进此技能，或检查 Agent 是否正确遵循此技能	evaluation-prompts.md 和 evaluations.json

关键配对规则

• Snap gross_amount：创建 Snap 令牌时使用整数；验证通知签名时使用提供商返回的原始字符串。对金额重新格式化后再进行哈希处理，是最常见的 Snap 签名错误。
• BI-SNAP 签名：有三个彼此独立的辅助函数——访问令牌（非对称 RSA-SHA256）、交易（对 method:path:accessToken:bodyHashHex:timestamp 使用 HMAC-SHA512）和通知（使用 Midtrans 公钥验证 POST:path:bodyHashHex:timestamp）。这三种场景绝不能共用同一个辅助函数。
• GoPay 流程：一次性 GoPay 直接扣款、令牌化 GoPay 钱包支付、GoPayLater、账户关联和取消关联是 五种不同的请求结构。令牌化支付还必须携带 Authorization-Customer: Bearer <customer_authorization_token> 标头，一次性支付则不得发送此标头。
• 无缝数据签名（GoPay 关联）：当当前文档要求无缝签名时，必须先对数据进行 encodeURIComponent(...) 包装，再使用 RSA-SHA256 签名。在沙盒环境中，对原始字符串签名会静默失败。
• 退款幂等性：每次退款调用都要传入 refund_key（Snap/Core/Payment Link）或 partnerRefundNo（BI-SNAP）。不带幂等键重试退款会导致重复退款。
• 订阅归属：对于客户订阅，应选择由 Midtrans 管理的 Subscription API，或由商户驱动的周期性扣款。两种方式同时运行会产生重复的预定扣款。
• 周期性扣款通知：周期性扣款可能使用控制面板中的 Recurring Notification URL，而非普通的 Payment Notification URL。应将周期性扣款尝试与一次性支付分开路由和对账。

输出要求

回复用户时，请说明：

• 检测到的 Midtrans 产品划分及其原因，
• 已确认、推断得出和仍缺失的商户准备情况，
• 找到的项目专属文件和边界，
• 需要商户或控制面板确认的假设，
• 包含测试的实现或修复计划，
• 已完成的具体验证，以及仍需进行的沙盒/生产环境冒烟测试步骤。

实施时，应保持改动精简、便于测试，并与目标项目现有的支付架构兼容。