Luminarix 支付网关集成技能。该技能用于 Luminarix(Luminarix Sdn. Bhd.,https://www.lmnrx.com)支付集成相关工作,覆盖搭建、开发、调试、审查与解释。
【资料基础】 Luminarix 未公开开发者文档(资料称检查于 2026-10-21)。技能中的 API 事实均来自 Luminarix 发布在 WordPress.org 上的官方 WooCommerce 插件源码(v1.6.0),该插件被视为参考实现;标注为“未文档化”的内容需通过 Luminarix 入驻流程确认。技能内附参考文件:references/luminarix-api.md(端点目录、请求头、请求/响应字段、各调用的签名串、回调验证、状态值、退款、重试与限流、已知缺口)、references/account-setup.md(注册、凭证、沙箱与生产、按支付方式的凭证、环境变量名、WooCommerce 插件配置、定价与结算)、references/source-map.md(事实来源对照及未文档化项)。
【主要能力】
- 支付创建:服务端向 {base}/v1/payments/deposit 发送 JSON POST,请求头 X-Signature = Base64(HMAC-SHA256(clientSecret, subMerchantId|orderId|amount|currency|returnUrl|callbackUrl)),保存返回的 transactionId,跳转 checkoutUrl;若无 checkoutUrl,则展示支付说明字段(二维码、虚拟账户、银行信息)。
- 回调处理:验证 X-Signature = Base64(HMAC-SHA256(clientSecret, X-Timestamp + "|" + rawBody)),限制时间戳窗口(插件默认 600 秒),去重,返回 HTTP 200 {"status":"SUCCESS"}。
- 状态确认:结算前调用 POST /v1/payments/transaction-status(签名串 subMerchantId|transactionId|orderId|amount|currency)确认 SUCCESS。
- 退款:支持全额或部分退款,签名方式同状态查询,响应返回独立的退款 transactionId,退款状态通过同一回调 URL 到达。
- 轮询兜底:插件每 5 分钟轮询一次,最长 72 小时,小批量处理,遇到 429 时退避。
【接口要点】
- 端点(相对于 base):POST /v1/payments/deposit、POST /v1/payments/transaction-status、POST /v1/payments/refund。
- 所有调用为 JSON POST,带 Content-Type: application/json、Accept: application/json 与 X-Signature;插件另发 X-Trace-Id(UUID)与描述性 User-Agent。
- 校验和为原始 HMAC-SHA256 字节的 Base64,密钥为 Client Secret,消息为以 | 连接的字段;签名放在 X-Signature 头而非请求体。
- amount 为两位小数的马币字符串(如 "10.00"),非 sen。
- 凭证按支付方式区分:每个 Payment System Code(如 MYR_TNG)有独立 Merchant ID、Sub-Merchant ID 与 Client Secret;验证回调须使用创建订单的方法与环境的密钥。
- 响应信封:success(布尔)、data(对象)、code、description、errors[].message。
- 插件中出现的代码:OK、TRANSACTION_NOT_FOUND、VALIDATION_FAILED、INTERNAL_ERROR、PROVIDER_UNAVAILABLE;HTTP 429 带 Retry-After。
- 处理的状态:SUCCESS、PENDING、ACCEPTED、APPROVED、FAILED、CANCELLED、REFUNDED(插件另有防御性归一化别名)。
- API 位于 Cloudflare 之后,返回 HTML 403 表示服务器 IP 被拦截,需请 Luminarix 加入白名单。
- 若发送 payer 对象,deposit API 要求 countryCallingCode(插件 1.6.0 变更日志)。
【关键规则】 Client Secret 仅存服务端,禁止在浏览器签名;回调须在任何 JSON 解析或清洗前基于原始请求体字节验签;签名与已存引用使用常量时间比较;拒绝时间戳超出容忍窗口的回调,并按原始请求体与签名的哈希去重;orderId 或 transactionId 与存储不匹配的回调应拒绝(插件返回 409);不得仅凭返回 URL 或回调状态履约,须先经 transaction-status 确认 SUCCESS;returnUrl 与 callbackUrl 在请求体与签名串中使用完全相同的字符串,returnUrl 不得自带查询串(Luminarix 会追加自己的 ?);每次尝试使用新 orderId(最长 255 字符,插件限制为 [A-Za-z0-9._-]);沙箱与生产的 base URL 和凭证严格分离并在订单上记录环境;不得自造 Payment System Code 或渠道代码,须从 Luminarix 获取。
【完成标准】 存款创建在服务端执行且签名正确、orderId 唯一并在调用前保存;客户被跳转 checkoutUrl,或在无 URL 时展示说明;回调处理基于原始请求体、使用正确的按方法按环境密钥验签并返回 200;结算经 transaction-status 确认并核对 orderId、transactionId、金额、币种与环境;重复、乱序回调、退款与轮询均幂等,已支付订单不降级;测试覆盖坏签名、过期时间戳、重放、引用不匹配、金额错误、FAILED、CANCELLED、SUCCESS 与退款回调;部署文档按环境列出 LUMINARIX_BASE_URL、LUMINARIX_MERCHANT_ID、LUMINARIX_SUB_MERCHANT_ID、LUMINARIX_CLIENT_SECRET、LUMINARIX_PAYMENT_SYSTEM_CODE、回调 URL 与返回 URL。
【错漏审查循环】 被问及策略是否“100% 确认”时,技能会循环检查信任边界(浏览器返回、托管收银台、后端存款创建、Cloudflare 后的 Luminarix API、回调接收、原始请求体读取、数据库、履约任务、退款任务、轮询任务、按方法凭证存储),排查伪造返回查询、伪造回调、对已解析 JSON 验签、错误方法密钥、沙箱/生产混用、重放、过期时间戳、引用不匹配、金额错误、复用 orderId、SUCCESS 后迟到的 FAILED、退款回调误当支付、429 风暴、Cloudflare 拦截掩盖错误等,并给出修复项;同时明确剩余不确定性。
【适用场景】 在服务端接入 Luminarix 支付、实现或审查回调验签与幂等结算、排查 403/429 与签名错误、编写 Luminarix 集成测试与部署配置。
【限制】 资料明确指出未公开文档的内容:base URL、Payment System Code 列表、回调重试策略、时间戳格式、沙箱测试数据、限流数值与错误代码;这些须向 Luminarix 确认。技能不提供定价信息(暂未提供)。