SuperAPI AI 工具集

setup-affanpay

编程与开发

查看项目

更新于 11-17 02:09

技能介绍

用途

本技能用于 AffanPay 支付网关的集成工作,涵盖搭建、构建、调试、审查和讲解 AffanPay 支付集成。所有事实性指导与集成代码编写前,应阅读 references/affanpay-api.md,其中包含端点目录、基础 URL、令牌认证、Create Bill 字段、Requery、回调请求体、HMAC 签名算法、状态码以及文档未覆盖的内容。涉及注册、所需文件、API 令牌与 secret key 位置、沙箱与生产账户、环境变量名、支付方式审批、结算或价格时,阅读 references/account-setup.md。references/source-map.md 用于查看每个事实对应的官方页面及已检查但未找到的内容。

主要能力

  • 环境区分:沙箱 https://sandbox.affanpay.my 与生产 https://app.affanpay.my,二者为独立主机与独立账户。
  • 端点:POST /v1/bill(创建账单)、GET /v1/requery(查询状态),以及向 callback_url 发起的出站回调 POST。文档未记录其他端点。
  • 认证:Authorization: Bearer <token>,令牌在 Settings > Developer > API tokens 生成且仅显示一次。所有 API 响应(含错误)均为 JSON;未认证返回 HTTP 401 {"message":"Unauthenticated."}。
  • Create Bill 必填字段:name、amount、external_ref、customer_name、customer_email。amount 为十进制令吉,最多两位小数,最低 5.00。返回 {"success": true, "id": "<bill_id>", "url": "https://app.affanpay.my/<bill_id>"}。
  • Requery 必须且只能传 bill_id 或 payment_ref 之一,返回 data.payments[],含 payment_ref、status_code、status、nett_amount、payment_channel。
  • 状态码:1 Success、2 Pending、3 Failed、4 No Action。回调仅针对 1 和 3 触发。
  • 回调请求头:Content-Type: application/json、X-AFFANPAY-TIMESTAMP(Unix 秒)、X-AFFANPAY-HMAC。签名为 hex(HMAC_SHA256(secret_key, timestamp + "." + raw_body)),小写;secret key 位于 Settings > Developer,与 API 令牌不同。回调须在处理完成后才返回 HTTP 200,任何 400 及以上状态会被记录为投递失败。
  • 当 fee_charge_payer 将服务费转由付款方承担时,paid_amount 可能超过 bill.amount。
  • 截至 2026-10-21 检查,退款、取消、订阅、令牌化、付款与结算报告 API 均未记录。

使用方式(核心工作流)

  1. 识别环境:沙箱 https://sandbox.affanpay.my 或生产 https://app.affanpay.my。
  2. 确认仪表盘设置:从同一环境的 Settings > Developer 获取 API 令牌与 secret key,可选账单 Category ID,以及已批准的支付渠道。
  3. 调用 AffanPay 前,先在本地创建待处理订单,使用唯一 external_ref 与预期金额。
  4. 服务端创建账单:POST {base}/api/v1/bill,请求头 Authorization: Bearer <API_TOKEN>、Accept: application/json、Content-Type: application/json。
  5. 将返回的 bill id 与订单关联存储,然后把客户重定向到返回的 url。
  6. redirect_url 仅用于浏览器体验,不得据此完成履约。
  7. 接收发往 callback_url 的 POST。校验 X-AFFANPAY-HMAC:对 timestamp + "." + rawBody 以 secret key 做 HMAC-SHA256,小写十六进制,使用常量时间比较,并拒绝超过 300 秒的时间戳。
  8. 依据整数 status_code(1 成功、3 失败)判断,绝不依据 status 标签。在标记已支付前匹配 bill.id、bill.external_ref 与金额。
  9. 以 payment_ref 为键幂等结算;每个回调会发送两次(约间隔 5 秒与 10 秒)。
  10. 回调缺失时,使用 GET {base}/api/v1/requery?bill_id=...(或 payment_ref=...)作为兜底。

适用场景

适用于需要在服务端创建 AffanPay 账单、跳转托管支付页、处理回调签名校验与幂等入账、以及通过 Requery 补偿缺失回调的集成工作。也适用于对现有集成进行调试与审查,检查环境混用、令牌泄露、签名校验缺失、金额比较错误、重复回调处理等问题。

限制

  • 退款、取消、订阅、令牌化、付款与结算报告 API 未记录;不要虚构退款或取消端点,退款在文档化 API 之外处理,需与 AffanPay 支持确认。
  • 回调签名校验在 AffanPay 侧为可选,但处理器中应视为强制,因为回调 URL 是公开的。
  • 必须对原始请求体校验 HMAC 后再解析 JSON;重新编码的 JSON 不会匹配。
  • 比较金额前,需将 paid_amount、bill.amount 与 requery 的 nett_amount(可能带前导空格)转为十进制,不得按字符串比较;订单价值对比 bill.amount,paid_amount 可能包含付款方承担的费用。
  • 处理失败时应返回非 2xx,不得在处理器崩溃时返回 200。
  • 令牌、secret key 与基础 URL 必须来自同一环境;API 令牌与 secret key 仅限服务端保存。
  • 文档未覆盖:重定向查询参数、账单过期行为、错误响应体结构、速率限制、IP 白名单、退款、沙箱测试数据、渠道审批。