SuperAPI AI 工具集

setup-bayarlah

编程与开发

查看项目

更新于 11-17 02:09

技能介绍

用途

该技能面向 bayarlah(Beez Fintech Sdn Bhd)Upay Web API 的支付集成工作,可用于搭建、编写、调试、审查和讲解相关集成代码。在给出 API 事实性指导或编写集成代码前,应先阅读 references/bayarlah-api.md,其中包含端点目录、域名、激活与签到、请求签名、各请求与响应字段表、回调与事件推送验证、轮询时间表、退款、取消、状态值与错误码。当问题涉及如何获取 API 参数、向 bayarlah 提交什么、激活码来源、环境变量名、微信退款授权、结算时间或定价时,应阅读 references/account-setup.md;选择适用文档页或核查文档覆盖范围时,应阅读 references/source-map.md。

主要能力与核心流程

从 bayarlah 技术支持获取 vendor_sn、vendor_key 与 app_id(文档中没有自助沙箱)。在商户平台 https://s.bayarlah.net 生成门店激活码,然后对每个终端调用一次 /terminal/activate,使用 vendor_sn + vendor_key 签名。将返回的 terminal_sn 与 terminal_key 持久化在服务端;每个自然日的首次支付调用前调用 /terminal/checkin 并保存新密钥。调用 bayarlah 前先创建带唯一 client_sn 的本地待付订单。网站或自助终端二维码场景调用 /upay/v2/precreate,传入 payway(“1000” 为 DuitNow,“3” 为微信)、以分为单位的金额与 notify_url,渲染 qr_code 或 qr_code_image_url。微信内浏览器场景以大写 MD5 查询签名 302 跳转至 https://qr.bayarlah.net/gateway,return_url 仅用于展示。预下单成功后轮询 /upay/v2/query,同时接受 notify_url 回调,任一获得最终 order_status 即停止。回调验证方面,notify_url 使用 SHA256WithRSA 与 bayarlah 公钥,事件订单通知使用 MD5(body + app_secret)。仅当 client_sn、sn、total_amount、terminal 与 order_status = PAID 匹配时幂等结算。退款使用 /upay/v2/refund 并保持稳定的 refund_request_no;状态未知的微信支付使用 /upay/v2/cancel。

关键事实

API 域名为 https://api.bayarlah.net(文档只记录这一个域名,未发布沙箱域名)。所有 API 请求为 JSON、UTF-8、Content-Type: application/json;所有响应值为字符串。请求签名:sign = MD5(raw_body_bytes + key),以 Authorization: <sn> <sign> 发送。激活使用 vendor_sn/vendor_key 签名,其他调用使用 terminal_sn/terminal_key 签名。金额以分(sen)为单位,为最多 10 位数字的数值字符串(“100” = RM1.00)。响应包装结果:顶层 result_code(“200” 或 “400”),然后是 biz_response.result_code 与 biz_response.data。预下单成功:biz_response.result_code = “PRECREATE_SUCCESS” 或 data.order_status = “CREATED”。最终订单状态:PAID、PAY_CANCELED、REFUNDED、PARTIAL_REFUNDED、CANCELED。预下单支付窗口约 4 分钟;文档中的轮询时间表在 6 分钟进行最终轮询。notify_url 回调重试间隔为 1s、5s、30s、600s;回复字符串 success。激活码有效期 7 天且使用次数有限,切勿硬编码。退款须在支付后三个月内;取消/撤销仅限当天且每单一次。client_sn 在支付失败后不能复用,须新建。

关键规则

vendor_key、terminal_key、app_secret 与 RSA 公钥仅保存在服务端。对发送的确切字节签名,签名后不要重新序列化 JSON。签到后原子地存储最新 terminal_key,旧密钥会失效。不得依据 return_url、展示的二维码或前端结果标记已支付;应使用查询或经验证的回调。解析 JSON 前先对原始请求体验证回调签名,并使用恒定时间比较。按通道使用正确验证方式:notify_url 用 RSA,事件订单通知用 MD5 + app_id 校验。结算需在轮询、notify_url 重试与事件推送重试之间保持幂等。重试同一退款时保持 refund_request_no 不变,新退款则更换。支付(CPM)调用未返回明确结果时,先查询,仍未知则调用 cancel。bayarlah 推送的任何 URL 均使用 HTTPS。不要臆测未公开的值(完整 payway 列表、sub_payway 列表、API MD5 的十六进制大小写、RSA 签名编码),应与 bayarlah 支持确认。

完成标准

满足以下条件才算完成集成:激活只运行一次,terminal_sn/terminal_key 持久化在服务端持久存储;每日首次支付调用前完成签到并保存新密钥;每次 API 调用都以正确 sn 对确切发送字节计算 MD5(body + key) 签名;预下单在展示二维码前保存 sn、client_sn、金额与预期 payway;轮询遵循文档时间表并在最终状态或经验证回调时停止;回调处理器对原始请求体验证签名并回复 success;结算校验 client_sn、sn、total_amount、terminal_sn 与 order_status,且幂等;测试覆盖错误签名、重复回调、金额错误、预下单过期、终端密钥过期、退款重试与成功 PAID 订单;部署文档列出 references/account-setup.md 中的环境变量。

审查循环

当被问及某 bayarlah 策略是否“100% 确信”时,运行审查循环直至无事实缺口:列出信任边界(浏览器、二维码展示、return_url、后端签名器、终端密钥存储、bayarlah API、notify_url 接收器、事件推送接收器、原始请求体解析器、数据库、轮询任务、退款任务、商户平台);检查绕过可能(伪造 return_url 成功、伪造回调、对解析后 JSON 签名、密钥用错 vendor 与 terminal、签到后仍用旧终端密钥、签到响应丢失、复用 client_sn、金额用元而非分、payway 用错、轮询过早停止、重复回调、部分退款重复发送、当天之后取消、DuitNow 退款假设);补充修复(服务端对发送字节签名、原子密钥轮换并用旧密钥重试、唯一 client_sn、分转换、原始请求体验证、app_id 校验、持久事件日志、幂等键、稳定 refund_request_no);重新阅读相关章节;对文档未说明之处明确列出不确定性:沙箱、payway 附录、MD5 十六进制大小写、RSA 编码、DuitNow 退款、速率限制、IP 允许列表、结算与定价。

限制

资料未提供自助沙箱、完整 payway/sub_payway 列表、MD5 输出大小写规范、RSA 签名编码方式、DuitNow 退款细节、速率限制、IP 允许列表、结算时间与定价等具体值,这些内容需与 bayarlah 支持确认。