SuperAPI AI 工具集

setup-ahapay

编程与开发

查看项目

更新于 11-17 02:09

技能介绍

用途

本技能面向 AhaPay(马来西亚 BNPL 支付网关)的支付集成工作,可在以下任务中使用:搭建新的 AhaPay 支付集成、编写集成代码、排查集成问题、审查已有集成实现,以及解释 AhaPay API 与集成流程。

使用前应先阅读相应参考文件:涉及 API 事实或编写集成代码时读 references/ahapay-api.md;涉及注册、所需材料、API 密钥来源、Merchant 与 Partner 密钥区别、沙箱访问、插件(WooCommerce、EasyStore)、最低金额、结算、费用或支持联系方式时读 references/account-setup.md;需要确认某条事实出自哪个 AhaPay 文档页或插件文件时读 references/source-map.md。

主要能力

  • 区分环境:沙箱 https://api.bnpl-my.dev.mychili.id 与生产 https://api.ahapay.my。
  • 区分密钥类型:Merchant(Trade Outlet)密钥用于直接集成;Partner 密钥的每个创建请求都需附带 external_merchant_id。
  • 区分接入形态:在线收银台(POST /v2/orders/default)、POS 屏幕二维码(POST /v2/orders/pos)、QR POS 扫码(POST /v2/orders/qr_pos),或平台插件(WooCommerce、EasyStore)。
  • 岗位关注点:订单创建、支付跳转、回调校验、状态重新查询、幂等结算、退款与限额检查。

使用方式(核心工作流)

  1. 先在本地创建待支付订单,记录以 MYR 计价的预期金额。
  2. 在服务端使用 X-ApiKey 调用 AhaPay 创建订单,把本地订单 ID 作为 reference_number,并提供 HTTPS 的 callback_url。
  3. 保存响应中的 online_order_id,然后引导客户跳转到 online_order_payment_link(在线场景),或展示 link_qr(POS 场景)。
  4. success_redirect_url / failed_redirect_url 仅用于浏览器体验,不得据此判定支付成功。
  5. 收到回调时,确认 X-Api-Key-Hash 等于 API 密钥十六进制 SHA-256(常量时间比较),并尽快返回 HTTP 200。
  6. 由于该哈希不签名请求体,结算前须调用 GET /v2/orders/{online_order_id}/status 核实,核对 online_order_id、reference_number、金额与状态。
  7. 在 PAYMENT_SUCCESSFUL 时幂等结算;迟到的 PAYMENT_IN_PROGRESS 不得把已支付订单回退。

关键事实

  • 每个请求的认证头为 X-ApiKey: <API_KEY>,由服务端判断是 Merchant 还是 Partner 密钥。
  • 当前为 V2 接口:POST /v2/orders/default、POST /v2/orders/pos、POST /v2/orders/qr_pos、GET /v2/orders/{online_order_id}/status、POST /v2/orders/{online_order_id}/refund、GET /v2/daily_limit_status、GET /v2/health。
  • 旧版 V1 仍在文档中;官方插件 1.1.0 已迁移到 V2。
  • 金额为 MYR 十进制数(例如 288.90,不是分),MYR 是文档中唯一列出的币种。
  • 订单状态:PAYMENT_IN_PROGRESS、PAYMENT_SUCCESSFUL、CANCELLED、REFUNDED、UNAVAILABLE。
  • 回调:状态变化时以 POST 发往订单的 callback_url,头含 X-Api-Key-Hash,体含 online_order_status;必须返回 HTTP 200,超时为 65 秒。
  • 官方插件以 hash('sha256', api_key)(64 位十六进制)配合 hash_equals 验证回调。
  • 退款仅支持整单退款:POST /v2/orders/{online_order_id}/refund,无请求体。
  • QR POS 的 client_hash 不带 aha- 前缀,有效期 10 分钟。
  • HTTP 状态:200 OK;401 密钥过期/归档或 Partner 未绑定网点;404 网点或 Partner 不存在;500 密钥格式无效或密钥从未创建。
  • 官方 WooCommerce 插件为 WordPress.org 上的 ahapay-buy-now-pay-later,默认最低订单金额 55 MYR。

安全与限制要点

  • API 密钥只应保存在服务端;它既是请求凭证也是回调共享密钥。
  • 不得仅凭跳转、AhaPay 应用页面或单独的回调就标记已支付,必须先重新查询状态。
  • X-Api-Key-Hash 只证明发送方,不签名载荷与订单,需核对回调中的 online_order_id 是否与本地保存的一致。
  • 结算前核对重新查询的金额与本地订单总额;不一致应转人工审核。
  • 回调处理需幂等并按订单加锁,重复与乱序投递都可能发生。
  • 已支付状态只允许转为 REFUNDED,忽略回退到 PAYMENT_IN_PROGRESS。
  • 退款超时或无明确结果时不得重复发起,先重新查询状态。
  • API 密钥与基础 URL 必须属于同一环境;Partner 密钥必须带 external_merchant_id,Merchant 密钥不带。
  • 客户须被跳转到 online_order_payment_link;据官方插件,该链接是 V1 应用 deeplink。
  • 费用、限额、结算周期与已启用网点应以 AhaPay 当前确认为准。

完成标准

集成完成需满足:订单在服务端以正确的 X-ApiKey 与基础 URL 创建,并设置 reference_number 与 callback_url;跳转前已保存 online_order_id 与预期金额;回调端点使用 HTTPS、校验 X-Api-Key-Hash、65 秒内返回 200 且可公网访问;结算时重新查询并核对 ID、reference、金额与状态;重复、乱序与伪造回调不会造成重复履约或撤销支付;退款只发整单、只发一次,结果不明时重新查询;测试覆盖错误哈希、缺失哈希、未知订单 ID、金额不符、重复成功、成功后的迟到 in-progress、取消、不可用与已退款;部署文档列出 AHAPAY_API_KEY、AHAPAY_BASE_URL、可选 AHAPAY_EXTERNAL_MERCHANT_ID、回调 URL 以及沙箱/生产隔离。

待确认事项

文档未明确的内容包括:响应外层包装(data wrapper)、错误体结构、回调重试策略、IP 允许列表、部分退款,以及 Daily Limit 参数的位置。技能自身的安装命令、价格与支持平台细节暂未提供。