LeanX 支付网关技能简介
用途 该技能面向 LeanX(Lean.x,Leanis Solutions)的收款与代付集成工作,可用于搭建、开发、调试、审查和解释相关集成。技能要求在进行事实性 API 说明或编写集成代码前先阅读参考文档,包括 references/leanx-api.md(端点目录、基础 URL、认证头、X-Signature 算法、账单创建字段、支付服务列表、回调 JWT 格式、状态 API、代付流程、错误码及已记录的文档不一致之处)、references/account-setup.md(注册、Auth Token / UUID / Hash Key 位置、沙箱与生产门户、环境变量名、插件设置、代付池充值、定价)以及 references/source-map.md(按主题选择官方文档页并查看覆盖情况)。
主要能力与核心流程 技能定义了识别环境(沙箱 https://api.leanx.dev 或生产 https://api.leanx.io)与集成界面的步骤,界面包括托管支付页(create-bill-page)、自建银行选择页(list-payment-services + create-bill-silent)、DuitNow QR(带 QR 元数据的静默账单)、卡表单(Credit Card JS 库)、插件或代付。流程要求确认门户设置(API key 已创建并启用、Auth Token、UUID、Hash Key、Collection UUID、X-Signature 开关、生产 IP 白名单),先在本地创建带唯一 invoice_ref 的待支付记录,再在服务端以 auth-token 头(启用 X-Signature 时附加 x-signature、x-timestamp、x-nonce)创建账单,将客户重定向到返回的 URL(支付页用 data.redirect_url,静默账单用 data.payment_url)或根据 data.metadata 渲染二维码。redirect_url 仅作为浏览器体验,不得据此履约。回调为 {"data": "<JWT>", "response_code": 2100},需用 Hash Key 验证并解码 HS256 JWT,再调用 manual-checking-transaction 复查;仅在发票号、invoice_ref、金额、invoice_status == "SUCCESS"、环境与商户均匹配后幂等结算。由于回调仅针对成功支付发送,需对 pending 账单运行定时复查任务。
核心事实 生产 API 基础为 https://api.leanx.io,沙箱为 https://api.leanx.dev,路径均在 /api/v1/merchant/... 下。认证头为 auth-token: <MERCHANT_ID>|<UUID>|<secret>(门户 API 页面中的完整 Auth Token 字符串),令牌为静态。可选 X-Signature 为 HMAC-SHA256(hex),对 HTTP_METHOD|UUID|URL_PATH|TIME_STAMP|AUTH_TOKEN|NONCE 以 Hash Key 为密钥计算,发送 x-signature、x-timestamp(Unix 秒)、x-nonce(UUID4),有效期 5 分钟。托管页为 POST /api/v1/merchant/create-bill-page(可选查询 invoice_no);自建页为 POST /api/v1/merchant/create-bill-silent 并携带 payment_service_id。每个账单都需要 collection_uuid,一个 collection 可无限复用。amount 为 MYR 令吉的 Decimal(10,2)(例如 10.00),不是分。支付服务列表为 POST /api/v1/merchant/list-payment-services,携带 payment_type、payment_status、payment_model_reference_id(1 = B2C/默认,2 = FPX B2B)。支付类型包括 WEB_PAYMENT(FPX)、CI_VISA_MASTERCARD、GLOBAL_CARD_PAYMENT、DIGITAL_PAYMENT(电子钱包)、BUY_NOW_PAY_LATER、SWITCH_PAYPAL、GLOBAL_CARD_PAYMENT_STRIPE、DUITNOW_ONLINE_BANKING、QR_PAYMENT(DuitNow QR)。回调体为 JSON,data 为 HS256 JWT,用 Hash Key 解码;仅成功交易发送,最多重试 3 次,除非返回 HTTP 200。状态复查为 POST /api/v1/merchant/manual-checking-transaction?invoice_no=<账单 invoice_no 或自己的 invoice_ref>,文档推荐优先于回调。账单状态包括 SUCCESS(invoice_status_id 2)、PENDING(1)、FAILED;插件还将 FPX_STOP_CHECK_FROM_PS 与 SENANGPAY_STOP_CHECK_FROM_PS 视为失败。成功信封为 response_code: 2000、description: "SUCCESS";错误使用数字码如 4008 Invalid HMAC signature、5688 Invalid Token、4626 Bill Invoices Already Exist。公开 API 文档未记录退款、循环计费与令牌化(核查于 2026-10-21)。代付为 POST /api/v1/merchant/create-payout-invoice,从预充值池(virtual_pool_reference)发起,池最低余额 RM2.00,状态通过 get-payout-transaction-by-id 查询。生产支持 IP 白名单,沙箱不支持,IP 地址未公开。
关键规则 Auth Token 与 Hash Key 仅保留在服务端;Hash Key 既签名请求也验证回调。不得依据 redirect_url、浏览器状态或卡库结果标记已支付。回调 JWT 须用固定 HS256 的 JWT 库与 Hash Key 本地验证,拒绝其他 alg,不得将 Hash Key 发往远程解码端点。解码后须以 manual-checking-transaction 确认再结算,金额按十进制字符串比较。每次尝试生成唯一 invoice_ref,重复会返回 4626 或 3614。仅在持久化处理后对回调返回 HTTP 200,处理需在 3 次重试间幂等。每个环境使用匹配的 base URL、Auth Token、Hash Key、Collection UUID 与支付服务 ID;服务 ID 在沙箱与生产不同(生产卡为 1100)。应每日刷新支付服务列表而非硬编码银行 ID。代付须先验证账户,以 external_invoice_ref 为键做状态检查,PENDING / STATUS_PENDING_APPROVAL 视为非终态。
完成标准与审查循环 集成完成需满足:服务端以 auth-token(及启用的 X-Signature 头)和唯一 invoice_ref 创建账单;重定向仅触发状态复查、不直接履约;回调处理验证 HS256 JWT、拒绝错误签名、仅在持久化后返回 200;结算前检查发票号、invoice_ref、金额、invoice_status、环境与商户;定时复查将 pending 账单解析为 SUCCESS 或 FAILED;测试覆盖无效 JWT、错误 alg、重复回调、错误金额、未知发票、FAILED 与 PENDING 状态及成功;部署文档列出 LEANX_API_URL、LEANX_AUTH_TOKEN、LEANX_UUID、LEANX_HASH_KEY、LEANX_COLLECTION_UUID、回调 URL、重定向 URL 及沙箱/生产隔离。被问及策略是否「100% 确信」时,技能要求运行审查循环:列出信任边界(浏览器重定向、支付页、自建银行选择页、QR 页、卡库、后端账单创建、LeanX API、回调接收、JWT 验证、数据库、复查任务、代付任务、门户设置),检查绕过(伪造重定向、伪造回调、alg: none 或错误密钥的 JWT、Hash Key 泄露至远程解码器、沙箱/生产密钥混用、错误 collection、重复 invoice_ref、金额不符、回调过期或缺失、失败支付无上报、重复代付、代付至错误账户名、池余额不足、X-Signature 时钟偏移),补充修复(本地待支付记录优先、服务端创建账单、本地 HS256 验证、结算前状态复查、十进制金额比较、唯一引用、幂等更新、定时复查、代付前银行验证、NTP 同步时钟),重读参考文档相关章节(含「已记录的文档不一致之处」),并说明剩余不确定性(回调 JWT 密钥编码、带查询串签名请求的确切 URL_PATH、退款流程、结算时机、已启用支付服务、IP 白名单取值需与 LeanX 确认或在沙箱验证)。
适用场景与限制 适用于 LeanX 收款与代付集成的开发、调试、审查与说明工作。资料未提供安装命令、价格、收费、具体平台支持范围或插件安装步骤;退款、循环计费、令牌化不在公开文档内,需以官方或沙箱验证为准。