Qashier 支付网关技能,用于 Qashier(QashierPay Online 与 QashierPay 终端)支付集成工作。在给出事实性 API 指导或编写集成代码前,应先阅读 references/qashier-api.md;该文件是入口,涵盖环境、认证、端点目录、Checkout Session 字段、Webhook 与精确签名算法、退款、错误、速率限制、测试卡及文档化缺口。仅当用户将自有 POS 与 QashierPay 卡终端集成(Partner API,使用 x-qashier-partner 与 x-qashier-sign)时,阅读 references/qashier-instore.md。当用户询问注册、密钥来源、staging 与 production、支付方式激活、插件、Pay-by-Link、结算或定价时,阅读 references/account-setup.md。使用 references/source-map.md 选择正确官方页面或检查覆盖范围。
核心工作流:识别接入面(QashierPay Online 托管结账 API、Shopify/WooCommerce/Wix 插件、无需代码的 Pay-by-Link、门店终端 Partner API);识别环境(staging 为 api.staging.qashier.com,production 为 api.qashier.com,并使用匹配的 API 密钥);先创建本地待支付订单,金额以 sen 为单位,币种 MYR;服务端创建 Checkout Session:POST /checkout/sessions,使用 Basic Auth(API 密钥作为用户名,密码为空)和 Idempotency-Key 请求头;将返回的 session id 与本地订单关联,然后以 HTTP 303 将客户重定向到返回的 url;success_url 和 return_url 仅作为浏览器用户体验,绝不能据此履约;对每个 Webhook,在解析 JSON 前基于原始请求体验证 X-Qashier-Signature;在 checkout.session.completed 事件中,仅当 data.object.payment_status 为 paid 时履约,unpaid 表示尝试被拒;通过 GET /checkout/sessions/{id} 重新获取会话,并匹配 id、金额、币种、状态后幂等结算;对于弃单,在 expires_at 之后检索会话并确认状态为 expired;自然过期不会触发 Webhook。
核心事实:在线 API 基础地址为生产 https://api.qashier.com/v3/payment/qpay,staging 为 https://api.staging.qashier.com/v3/payment/qpay;认证为 HTTP Basic,API 密钥作为用户名,密码为空(Authorization: Basic base64("<API_KEY>:")),密钥在 Qashier Dashboard 管理;端点为 POST /checkout/sessions、GET /checkout/sessions、GET /checkout/sessions/{id}、POST /checkout/sessions/{id}/expire、POST /refund;创建时必填 currency、line_items[](unit_amount 为整数,单位为分,quantity 限制为 1)、return_url、success_url,可选 expires_at、customer_email;expires_at 为创建后 30 分钟至 24 小时,默认 24 小时;会话状态为 open、complete、expired,payment_status 为 paid、unpaid;Webhook 事件包括 checkout.session.completed、checkout.session.expired(仅当调用 expire 时)以及退款更新;签名为 header t=<ts>,v1=<hex>;signing_key = SHA256(webhook_secret);v1 = HMAC_SHA256(signing_key, "<t>.<raw_body>");使用恒定时间比较;退款通过 POST /refund,传入 sessionId 和可选金额(分),异步,状态为 pending、succeeded、failed;幂等键最大 255 字符,保留 24 小时,使用不同参数重用返回 409 idempotency_error;速率限制为每个 API 密钥每秒 100 次请求,超限返回 429 rate_limit_error;商户不能按会话选择支付方式,结账展示账户已启用的方式。
关键规则:API 密钥和 Webhook 密钥仅限服务端保存;绝不能仅凭事件名称履约,checkout.session.completed 在拒付时也会发送;基于收到的精确原始字节验证签名,不要重新序列化 JSON;不要因 Webhook 静默而推断弃单,应检索会话并检查状态;staging 与 production 使用独立密钥、Webhook URL 和密钥;结算应对 session id(及 Webhook 事件 id)幂等,重复事件不得重复履约;金额以 sen 为整数发送(RM20.00 = 2000),结算时确认金额和 MYR 币种;忽略文档页面 /docs/api/payments-example(POST /v1/payments,Bearer token),它是模板示例而非真实 API;生产前与 Qashier 确认文档化缺口(Webhook URL 注册、密钥位置、签名密钥编码、时间戳容忍度),见 references/qashier-api.md。
完成标准:仅当以下条件满足时,Qashier 集成才算完成:Checkout Session 创建在服务端运行,使用 Basic Auth 和 Idempotency-Key;本地订单在重定向前存储 session id、预期金额、币种、环境和状态;Webhook 处理器使用正确环境密钥基于原始体验证 X-Qashier-Signature,恒定时间比较;结算要求 payment_status: paid,匹配 session id、金额和币种,并通过服务端检索确认;拒付(unpaid)、重复事件、延迟 Webhook 和自然过期均被幂等处理;退款使用 POST /refund,退款状态通过退款 Webhook 或 refund_details 对账;测试覆盖无效签名、重放事件、拒付卡(unpaid)、错误金额/币种、过期会话和已支付会话,使用 staging 上的文档化测试卡;部署文档列出 QASHIER_API_KEY、QASHIER_WEBHOOK_SECRET、QASHIER_API_BASE、success/return URL、Webhook URL 以及 staging/production 分离。
漏洞审查循环:当被问及 Qashier 策略是否“100% 有信心”时,运行此循环直至无事实缺口:列出信任边界(浏览器、success/return 页面、后端会话创建器、Qashier API、Webhook 接收器、原始体解析器、数据库、履约任务、退款任务、仪表盘设置和支付方式激活);检查绕过(伪造成功重定向、伪造 Webhook、基于解析后 JSON 签名、错误密钥或密钥编码、staging/live 混用、将 completed 视为 paid、错误金额或币种、带旧时间戳的重放事件、重复 Webhook、过早将弃单标记为失败、退款重复发送、支付方式被禁用);添加修复(服务端创建会话、先建本地待支付订单、原始体 HMAC 验证、恒定时间比较、时间戳年龄检查、结算前检索、严格金额/币种/id 检查、持久事件日志、幂等键、独立环境配置);重读 references/qashier-api.md 中与任何缺口相关的章节;在依赖未文档化项(Webhook URL 设置、密钥位置、时间戳容忍度、退款幂等性)、账户审批、已启用方式、结算时间或定价处,说明剩余不确定性。