SuperAPI AI 工具集

setup-herepay

编程与开发

查看项目

更新于 11-17 02:10

技能介绍

用途

本技能用于 Herepay 支付网关的集成工作,覆盖搭建、构建、调试、审查和解释 Herepay 支付集成等场景。在给出 API 事实性指导或编写集成代码前,应先阅读随技能提供的参考文件。

参考资料

  • references/herepay-api.md:环境、认证头、支付渠道与发起流程、请求字段、校验和算法、回调与重定向字段、状态码、重查、支付链接、沙箱测试银行,以及文档中记录的不一致之处。
  • references/herepay-codes.md:银行代码(B2C 与 B2B)、UAT 测试银行、状态与回调枚举、HTTP 状态码。
  • references/account-setup.md:注册方式、所需凭证、密钥来源、UAT 设置、回调/重定向 URL 设置、支付方式、定价或结算时间等问题时阅读。
  • references/source-map.md:用于判断应参考哪个 Herepay 文档页面或官方仓库文件。

核心工作流

  1. 确认环境:UAT(https://uat.herepay.org)或生产(https://app.herepay.org)。
  2. 确认接入方式:直连 API(商户自建银行选择器)、支付链接(Herepay 支付页)或 WooCommerce 插件。
  3. 确认该环境下的凭证:SecretKey、XApiKey、用于校验和的 Private Key,以及在 Herepay 后台设置的回调与重定向 URL。
  4. 调用 Herepay 前,先在本地创建带唯一 payment_code 的待支付记录。
  5. 在服务端通过 GET /api/v1/herepay/payment/channels 获取渠道;仅展示 Active 渠道,并保留 prefix 与 payment_method。
  6. 构造发起请求载荷,对发送的每个字段(不含 checksum)计算校验和,然后在服务端携带 SecretKey 与 XApiKey 头 POST /api/v1/herepay/initiate。
  7. 将 Herepay 返回的 HTML body 返回给浏览器;该内容会以表单 POST 方式将客户跳转至银行。
  8. 将重定向 URL 的 POST 仅视为浏览器用户体验,不要据此完成履约。
  9. 在服务端到服务端回调中,使用 Private Key 以常量时间比较方式校验校验和,然后基于 payment_code、金额、币种和状态幂等结算。
  10. 当回调缺失、处于 pending 或存在歧义时,重查 GET /api/v1/herepay/transactions/{reference_code}。

核心事实

  • UAT 基础地址:https://uat.herepay.org;生产基础地址:https://app.herepay.org。两套密钥不可互换。
  • 每次 V1 调用的认证头为 SecretKey 与 XApiKey;支付链接仅使用 SecretKey。
  • 支付渠道接口:GET /api/v1/herepay/payment/channels。
  • 创建支付:POST /api/v1/herepay/initiate,字段包括 payment_code、created_at(YYYY-MM-DD hh:mm:ss)、amount(单位为 ringgit,不是 sen)、name、email、phone、description、bank_prefix、payment_method、checksum;官方示例还会发送可选的 redirect_url。
  • 状态重查:GET /api/v1/herepay/transactions/{reference_code};列表:GET /api/v1/herepay/transactions。
  • 支付链接(仅官方示例):POST /api/integration/create-payment-link,然后跳转至 data.pay_url。
  • 校验和算法:按 key 排序字段,嵌套值做 JSON 编码,用 , 连接各值,以 Private Key 做 HMAC-SHA256,输出小写十六进制。
  • 回调为 POST(表单数据),包含 reference_code、payment_code、transaction_id、status、status_code、message、amount、currency、payment_method、fpx_type、bank_name、checksum。
  • 状态码:状态码页面与官方示例使用 00 成功、29 待处理、30 失败、41 未授权;回调参考页面则列出 1 已完成、2 待处理、0 失败。需同时兼容两套。
  • 发起请求格式错误时,浏览器只显示 “Checksum verification failed”,没有详细错误。
  • UAT 测试银行:TEST0021、TEST0022、TEST0023(SBI Bank A/B/C)、ABB0234、LOAD001;测试银行登录 1234 / 1234。
  • API 中的支付方式:Online Banking(B2C)与 Corporate Banking(B2B)。B2B 可能保持待处理,直到授权人批准。
  • 官方文档中退款、循环计费与令牌化暂无 API(核查于 2026-10-21)。
  • 支持联系方式:WhatsApp +60 11-5140 4297(来自入门页面)。

关键规则

  • SecretKey、XApiKey 与 Private Key 仅可保存在服务端,切勿从浏览器调用 Herepay。
  • 必须对发送的确切值、以发送的确切字符串形式签名(例如 "10.50" 与 10.5 会改变哈希)。
  • 如果增加 redirect_url 或任何其他字段,必须将其纳入校验和输入。
  • 在信任任何字段之前,先对除 checksum 外的所有回调字段校验校验和。
  • 使用常量时间比较(hash_equals、crypto.timingSafeEqual、hmac.compare_digest)。
  • 不得仅凭重定向 POST、银行页面或前端消息标记为已支付。
  • 标记已支付前,须确认 payment_code、金额、币种 MYR 与成功状态。
  • 回调处理必须幂等;重复回调不得重复履约。
  • 保存回调中的 reference_code;重查需要用到它。
  • UAT 与生产的密钥、URL 和回调端点须保持隔离。
  • 不要直接使用公开的 PHP SDK generateChecksum,它通过 openssl_pkey_get_private 传递密钥,与其他官方示例不同。
  • 不要把费率数字复制到代码或文档中;请链接到定价页面。

完成标准

Herepay 集成仅在以下条件满足时才算完成:

  • 渠道获取与发起请求在服务端使用对应环境的 SecretKey 与 XApiKey 运行。
  • 发起请求的校验和符合官方算法,并覆盖所有发送字段。
  • 回调 URL 已在对应环境的后台注册,且可公开访问。
  • 回调处理器使用 Private Key 以常量时间校验校验和。
  • 结算检查 payment_code、金额、币种与状态,仅在签名校验通过后接受 00 和 1 两种成功码。
  • 待处理(29 / 2)与 B2B 授权待处理的支付保持待处理,并稍后重查。
  • 测试覆盖错误校验和、重复回调、错误金额、失败状态、待处理状态与成功。
  • 部署文档列出 HEREPAY_SECRET_KEY、HEREPAY_API_KEY、HEREPAY_PRIVATE_KEY、HEREPAY_SANDBOX、回调 URL 与重定向 URL。

漏洞审查循环

当被问及某个 Herepay 策略是否“100% 有信心”时,运行此循环直到没有事实缺口:

  1. 列出信任边界:浏览器结账表单、商户发起路由、Herepay API、银行页面、重定向处理器、回调接收方、数据库、履约任务、后台 URL 设置。
  2. 检查绕过点:伪造回调、校验和覆盖字段集不同、数字格式漂移、未签名的 redirect_url、伪造重定向 POST、UAT/生产密钥混用、错误金额、复用 payment_code、重复回调、B2B 待处理被当作失败、状态码 1 与 00 混淆、选中非活跃银行。
  3. 补充修复:仅服务端发起、先建本地待支付记录、唯一 payment_code、常量时间校验和检查、严格金额/币种/状态检查、幂等结算、按 reference_code 重查、按环境隔离配置。
  4. 重读 references/herepay-api.md 中与任何缺口相关的章节。
  5. 说明剩余不确定性:账户回调发送哪套状态码、回调重试策略、速率限制、卡/电子钱包 payment_method 取值、退款流程、created_at 时区均无文档说明;需向 Herepay 支持确认。

适用场景与限制

适用于使用 Herepay 支付网关的商户或开发者进行支付集成的设计、实现、调试与审查,尤其涉及马来西亚在线银行(B2C)与企业银行(B2B)支付。限制在于:退款、循环计费与令牌化暂无官方 API;部分回调行为、速率限制、支付方式取值与退款流程未在文档中说明,需向官方支持确认。