用途
本技能面向 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)。 - 岗位关注点:订单创建、支付跳转、回调校验、状态重新查询、幂等结算、退款与限额检查。
使用方式(核心工作流)
- 先在本地创建待支付订单,记录以 MYR 计价的预期金额。
- 在服务端使用
X-ApiKey调用 AhaPay 创建订单,把本地订单 ID 作为reference_number,并提供 HTTPS 的callback_url。 - 保存响应中的
online_order_id,然后引导客户跳转到online_order_payment_link(在线场景),或展示link_qr(POS 场景)。 success_redirect_url/failed_redirect_url仅用于浏览器体验,不得据此判定支付成功。- 收到回调时,确认
X-Api-Key-Hash等于 API 密钥十六进制 SHA-256(常量时间比较),并尽快返回 HTTP 200。 - 由于该哈希不签名请求体,结算前须调用
GET /v2/orders/{online_order_id}/status核实,核对online_order_id、reference_number、金额与状态。 - 在
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 参数的位置。技能自身的安装命令、价格与支持平台细节暂未提供。