SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场setup-hitpay

setup-hitpay

编程与开发

查看项目

更新于 10-15 10:10

技能介绍

用途

该技能面向 HitPay 支付网关的集成工作，用于搭建、构建、调试、审查和讲解 HitPay 支付集成。它依据官方 HitPay 文档，覆盖 Payment Request API、托管结账、Drop-In UI、Webhook 等集成面。

主要能力

技能提供三类参考文档：

  • references/hitpay-api.md：在给出事实性 API 指导或编写集成代码前阅读，包含来源 URL、环境基址、认证、支付请求流程、结账呈现、Webhook、状态检查、退款、速率限制、沙箱、IP 允许列表以及结算/安全注意事项。
  • references/account-setup.md：当用户询问如何注册、需要哪些凭据、密钥来源、沙箱设置、仪表盘设置、支付方式激活、马来西亚特定支付方式、定价、打款时间或运营状态时阅读。
  • references/source-map.md：在选择适用于 API 结账、Webhook、沙箱、退款、插件、支付方式、状态、循环计费、打款、平台 API 或生产就绪的 HitPay 文档页面时阅读。

使用方式（核心工作流）

  1. 识别环境：沙箱或生产。
  2. 识别集成面：Payment Request API、托管结账重定向、Drop-In UI、嵌入式 QR、插件、支付链接、发票、循环计费、打款、平台账户或 POS。
  3. 确认仪表盘设置：API 密钥、Webhook 端点、Webhook 盐值、已启用支付方式、企业验证以及环境特定 URL。
  4. 在创建 HitPay Payment Request 之前，先创建本地待处理支付。
  5. 使用 X-BUSINESS-API-KEY 在服务端创建 Payment Request。
  6. 将客户发送到返回的 url，或使用服务端流程返回的值渲染受支持的 Drop-In UI。
  7. 将 redirect_url 仅视为浏览器 UX，不要仅凭重定向完成履约。
  8. 使用 HMAC-SHA256 对原始 JSON 载荷和正确环境盐值验证 Webhook 的 Hitpay-Signature。
  9. 仅在支付请求 ID、本地参考号、金额、币种、状态、环境、商户账户和支付方式均符合预期后，才幂等地结算。
  10. 当 Webhook 延迟或失败时，使用状态重查作为回退；不要用轮询替代 Webhook。

核心事实

  • 生产 API 基址：https://api.hit-pay.com。
  • 沙箱 API 基址：https://api.sandbox.hit-pay.com。
  • 支付请求端点：POST /v1/payment-requests。
  • 支付状态端点：GET /v1/payment-requests/{request_id}。
  • 认证使用 X-BUSINESS-API-KEY 请求头。
  • API 密钥位于 Dashboard > Settings > API Keys。
  • Webhook 在 Dashboard > Developers > Webhook Endpoints 注册。
  • Webhook 签名使用 Hitpay-Signature 请求头，对原始 JSON 载荷和仪表盘盐值做 HMAC-SHA256。
  • 对于 API 结账，HitPay 表示订单应仅在收到并验证 Webhook 后才标记为已支付。
  • Payment Request 状态包括 pending、completed、failed、expired、canceled 和 inactive。
  • API 概览速率限制通常为每分钟 400 次请求，每分钟 70 次支付创建。
  • 沙箱与生产是独立账户，拥有独立的密钥、盐值、URL、仪表盘、Webhook 和请求日志。
  • 沙箱仪表盘：https://dashboard.sandbox.hit-pay.com/login。
  • 生产仪表盘：https://dashboard.hit-pay.com。
  • HitPay 记录的 Webhook IP：生产 3.1.13.32、52.77.254.34；沙箱 54.179.156.147。
  • HitPay 状态页：https://status.hitpayapp.com/。

关键规则

  • API 密钥和 Webhook 盐值仅保存在服务端。
  • 不要仅凭 redirect_url、前端回调、Drop-In UI 结果、QR 显示或仪表盘截图标记已支付。
  • 在解析或规范化 JSON 之前，始终对原始请求体验证 Webhook 签名。
  • 使用常量时间签名比较。
  • 使用与 Webhook/API 基址 URL 相同环境的盐值和 API 密钥。
  • 在重定向客户之前，存储提供商请求 ID、本地参考号、预期金额、预期币种、所选环境和结算状态。
  • 使 Webhook 处理幂等；重复事件或重试不得重复履约。
  • 在标记已支付前确认金额、币种、支付请求 ID、本地 reference_number 和状态。
  • 将 Webhook IP 允许列表视为网络加固步骤，而非 HMAC 验证的替代。
  • 为沙箱和生产使用不同的 Webhook URL。
  • 默认以 Webhook 确认作为结算路径，状态 API 仅作回退。
  • 当仪表盘 Webhook 端点是当前集中管理 Webhook 的正确路径时，不要依赖已弃用的支付请求 Webhook 参数。
  • 在声称生产确定性之前，在仪表盘/文档/状态页验证实时支付方式可用性、激活时间、打款计划、定价、当前事件和企业验证。

完成标准

HitPay 集成仅在以下条件满足时才算完成：

  • Payment Request 创建在服务端使用 X-BUSINESS-API-KEY 运行。
  • 重定向结账、Drop-In UI 或嵌入式 QR 仅向后端返回提供商状态；不直接履约访问。
  • 为正确环境注册了仪表盘 Webhook 端点。
  • Webhook 处理器使用正确 Webhook 盐值对原始请求体验证 Hitpay-Signature。
  • 结算检查支付请求 ID、本地 reference_number、金额、币种、状态、环境和商户账户。
  • 重复 Webhook、延迟 QR 完成和状态重查均幂等。
  • 测试覆盖无效签名、重复 Webhook/事件重放、错误金额/币种/参考号、失败/过期状态以及成功完成的支付。
  • 部署文档包含 HITPAY_API_KEY、HITPAY_WEBHOOK_SALT 或应用等效的 Webhook 密钥名称、重定向 URL、Webhook URL 以及沙箱/生产分离。

漏洞审查循环

当被问及 HitPay 策略是否“100% 确信”时，运行此循环直到没有事实缺口：

  1. 列出信任边界：浏览器重定向、Drop-In UI、结账页、后端支付创建器、HitPay API、Webhook 接收器、原始体解析器、数据库、履约任务、退款任务、仪表盘设置、状态页和支付方式激活。
  2. 检查绕过：伪造成功重定向、伪造 Webhook、对解析后 JSON 而非原始体签名、错误盐值、沙箱/生产混用、错误 API 密钥、错误金额、错误币种、错误参考号、过期状态轮询、重复 Webhook、部分处理后 Webhook 重试、过早将放弃的 QR 标记为失败、未激活支付方式、未验证企业、HitPay 服务不可用、重复退款以及插件 Webhook 被服务器安全阻止。
  3. 添加修复：服务端 Payment Request 创建、先创建本地待处理支付、原始体 HMAC 验证、常量时间比较、严格金额/币种/参考号检查、持久事件日志、幂等键、独立环境配置、必要时 Webhook IP 允许列表、状态页检查、状态 API 回退以及仪表盘能力验证。
  4. 重新阅读 references/hitpay-api.md 中与任何缺口相关的章节。
  5. 如果剩余不确定性取决于当前账户验证、已启用支付方式、激活窗口、打款计划、定价、平台批准、插件行为或实时运营状态，请说明。

适用场景

适用于需要集成 HitPay 支付网关的开发者与团队，包括 API 结账、托管结账、Drop-In UI、嵌入式 QR、插件、支付链接、发票、循环计费、打款、平台账户或 POS 等集成面，以及沙箱与生产环境的配置、调试、审查与讲解。

限制

  • 实时支付方式可用性、激活时间、打款计划、定价、当前事件和企业验证需在仪表盘/文档/状态页确认，技能本身不提供这些实时数据。
  • 沙箱与生产为独立账户，配置不可混用。
  • 具体定价、收费与平台支持情况在资料中暂未提供。