SuperAPI AI 工具集

setup-ezypay

编程与开发

查看项目

更新于 11-17 03:09

技能介绍

该技能面向 Ezypay 订阅计费和卡片收款工作,提供从环境配置、令牌获取、客户创建、卡片采集、发票与订阅创建,到 webhook 验签、结算与退款处理的端到端说明。

使用方式

先阅读 references/ezypay-api.md,其中包含环境、基础 URL、认证、马来西亚范围、服务器端完整流程、端点目录、状态、错误码、金额规则和签名摘要。其余参考文件分别覆盖:ezypay-billing.md(客户、支付方式、发票、退款、计划、订阅、未来发票、结账、交易、贷项通知单、结算、报表、合作伙伴计费的请求与响应字段表)、ezypay-webhooks.md(事件类型、负载结构、HMAC-SHA1 验证与官方测试向量、重试与去重)、ezypay-payment-methods.md(Payment Capture Page 的 iframe、postMessage、样式、移动端 WebView,Apple Pay、Google Pay、支付方式负载、沙箱测试数据、马来西亚卡失败码)、account-setup.md(入驻、凭据、沙箱访问、上线清单、费用模型、结算时间)、source-map.md(用于定位官方页面)。

核心流程

  1. 确认计费模型:按需发票(由开发者调度)或 Ezypay 订阅(由 Ezypay 调度);Checkout 为托管的一次性卡片页面。
  2. 确认凭据:partner 的 client_id 与 client_secret,以及每个商户的用户名、密码和 merchant ID;每个分支使用各自的商户账户。
  3. 在身份主机上以 grant_type=password 获取 bearer token,在过期前复用(60 分钟)。
  4. 通过 POST /v2/billing/customers 创建客户并保存 id。
  5. 用 Payment Capture Page iframe 采集卡片,从 postMessage 读取 token 并检查 link_status。
  6. 在本地创建待处理支付,然后以 externalInvoiceId 作为幂等键 POST /v2/billing/invoices,或创建计划与订阅。
  7. 将 Checkout 的 successUrl 参数与 iframe 消息仅视为用户体验信号。
  8. 验证 X-Ezypay-Signature webhook 头(用 client key 对原始请求体做 HMAC-SHA1 十六进制),按 requestId 去重,再重新查询 GET /v2/billing/invoices/{invoiceId}。
  9. 在 invoice_paid 且发票 id、externalInvoiceId、商户 ID、MYR 币种和项目金额匹配时结算。
  10. 处理 invoice_past_due:显示 failedPaymentReason、替换无效支付方式、重试、核销或记录外部支付。

核心事实

沙箱主机包括 identity-sandbox.ezypay.com、vault-sandbox.ezypay.com、api-sandbox.ezypay.com、hosted-global-sandbox.ezypay.com;生产主机包括 identity.ezypay.com、vault.ezypay.com、api-global.ezypay.com、hosted-global.ezypay.com。计费基础地址为 https://api-sandbox.ezypay.com/v2,路径以 /billing/ 开头;webhook 基础为 .../v2/webhooks。令牌请求为 POST https://identity-sandbox.ezypay.com/token,使用表单编码,scope 为 integrator billing_profile create_payment_method offline_access。每次计费调用需携带 Authorization: Bearer <token> 和 merchant: <MERCHANT_ID> 头。马来西亚支持 Visa 和 Mastercard,Apple Pay 与 Google Pay 为测试版,不提供银行直接借记、PayTo、钱包、FPX 或 DuitNow;不支持 3D Secure,不要求 CVV,仅以 MYR 收费(不支持跨境),允许小数;金额使用小数主单位,如 { "currency": "MYR", "value": 49.90 },而非分。Ezypay 费用可作为额外项目加入发票(transaction_fee、load_fee、failed_payment_fee)。webhook 签名为 X-Ezypay-Signature = 小写十六进制 HMAC-SHA1(clientKey, 原始请求体),每小时重试一次,最多 24 次。退款为 PUT /v2/billing/invoices/{invoiceId}/refund,空请求体表示全额,跟踪 credit_note_paid 或 credit_note_failed。马来西亚结算持有期为 T+3 个工作日,频率为每周或每月。

关键规则

client_secret、商户密码、client key 和 bearer token 须保留在服务器端;PCP iframe URL 会暴露 token,须按会话构建。不得凭 iframe 消息、Checkout successUrl 查询字符串或发票创建响应标记为已支付(PROCESSING 不是已支付)。在解析 JSON 前对精确原始字节验签,并使用常量时间比较。每个 webhook 必须注册 clientKey,否则无内容可验证。每张发票发送唯一 externalInvoiceId,避免自身请求重试导致重复扣款。启用客户付费费用时,比较所收项目金额而非发票总额。结算前保存 invoice id、documentNumber、customerId、paymentMethodToken 和商户 ID。每个分支使用一个商户账户,不得跨分支共享。不得承诺马来西亚的 FPX、DuitNow、电子钱包或 3DS,这些均不提供。上线前须与 Ezypay 确认 Apple Pay 与 Google Pay 的启用,二者均为测试版。

完成标准

令牌在服务器端获取、缓存并在 60 分钟后刷新或重建,且符合令牌速率限制;客户已创建并在资料变更时同步,PCP 返回与客户关联的 token;发票或订阅在服务器端创建,带商户头和唯一 externalInvoiceId;每个商户注册一个带 clientKey 和最少事件集的 webhook;处理器对原始请求体验证 X-Ezypay-Signature、按 requestId 去重、重新查询发票并仅结算一次;失败支付显示原因与费用,支持重试、核销、记录外部支付和 Pay Now;退款与拒付根据贷项通知单事件更新本地状态;测试覆盖错误签名、重放 requestId、错误商户、错误币种或金额、PAST_DUE、退款失败,以及使用测试卡完成一张沙箱发票支付;部署文档列出 EZYPAY_* 变量、webhook URL、client key 以及沙箱与生产主机。

漏洞审查循环

当被问及 Ezypay 方案是否“100% 确信”时,反复执行直至无事实缺口:列出信任边界(浏览器 iframe、postMessage 监听器、Checkout 重定向、后端令牌缓存、身份主机、计费 API、vault、webhook 接收器、原始请求体解析器、数据库、履约、退款任务、重试任务);检查绕过路径(他源伪造 postMessage、伪造 successUrl 查询、未签名 webhook、对重新序列化 JSON 验签、错误 client key、沙箱与生产混用、错误商户头、发票跨客户复用、重复 requestId、将 PROCESSING 视为已支付、费用项目破坏金额校验、批次中途令牌过期、无效支付方式自动停止重扣款、钱包余额不足时退款、已支付后拒付冲正);补充修复(对 message 事件校验来源、服务器重新查询发票、原始请求体 HMAC 常量时间比较、按商户划分 webhook 与密钥、以 invoice id 为键的幂等结算、externalInvoiceId 唯一性、事件日志、环境配置分离);对任何缺口重读相关参考文件;说明仍依赖 Ezypay 账户配置的事项:启用的支付方式、费用配置、重试设置、结账尝试次数限制、结算计划、Apple Pay 域名注册和 Google Pay 审批。

限制

具体功能、收费、价格、平台与效果以 Ezypay 官方文档与实际账户配置为准;资料未提供的细节暂未给出。