用途
该技能面向 Paydee(Paydee Sdn Bhd,前身为 Synergy Cards)的 Payment Acceptance Gateway 集成工作。Paydee 将面向商户的 API 称为“MPI”(Merchant Plug-In)服务器。适用于搭建、开发、调试、审查和讲解 Paydee 支付集成。
参考资料
在给出事实性 API 指导或编写集成代码前,应先阅读 references/paydee-api.md,其中包含端点目录、环境、密钥交换、请求与响应字段表、精确的 MAC 待签字符串顺序、状态与错误码、撤销/退款规则、循环扣款字段、测试卡以及官方来源之间存在记录在案的冲突。
在映射任何 errorCode、MPI_ERROR_CODE、MPI_REFERRAL_CODE、MPI_AUTH_STATUS 或 MPI_STATUS_REASON 值时,阅读 references/paydee-codes.md。
当用户询问如何成为商户、凭据来源、沙箱与生产访问、RSA 密钥登记、支付方式启用、结算或定价时,阅读 references/account-setup.md。
需要选择正确的官方页面或文件(开发者站点、规范 PDF、Swagger JSON、消息表 XLSX)以及查看哪些内容无法读取时,阅读 references/source-map.md。
核心流程
- 识别环境:测试环境(https://devlink.paydee.co/mpi,来自 Paydee 公布的 Swagger)或生产环境(登录/入驻后由 Paydee 发布的端点)。
- 识别接口形态:托管支付页(/mercReq,由 Paydee 渲染结账页)或非托管(/mpReq,商户页面,外加所有服务端 INQ/VSALES/REFUND/RECURR/TERMINATE/SALESCOMPL 调用)。
- 在任何 Paydee 调用前,用新的唯一交易 ID 在本地创建待处理支付(最长 20 字符、最少 6 位数字;纯数字 ID 最安全,因为请求表将其类型定义为 N)。
- 为本次支付会话生成新的 RSA-2048 密钥对。调用 POST /mkReq(JSON),传入 merchantId、purchaseId(等于交易 ID)、pubKey(Base64Url)、可选 paymentMethod,以及若已登记密钥交换 MAC 则传 mac。保存 Paydee 返回的会话 pubKey。
- 构建 MPI_* 表单字段,计算 MPI_MAC = Base64Url(SHA256withRSA(商户会话私钥, 按文档顺序拼接的值))。
- 托管模式:从持卡人浏览器自动提交表单到 /mercReq。非托管 SALES:携带来自 /channels 的 MPI_PAYMENT_CHANNEL_ID 提交到 /mpReq。
- 在重定向和回调上,先按文档响应字段顺序用 Paydee 会话公钥验证响应 MPI_MAC,再信任任何字段。
- 仅当 MPI_MERC_ID、MPI_TRXN_ID、金额和币种与本地记录一致,且 MPI_ERROR_CODE 为 000、MPI_STATUS 为 1(Payment Success,或后续 INQ 中为 7 Payment Settled)时才结算。结算须幂等。
- 若无响应、超时或浏览器关闭:在重试销售前先执行 INQ(新密钥交换、新交易 ID,MPI_ORI_TRXN_ID = 原始交易 ID)。
- 截止时间前撤销,否则退款;两者均为异步,需通过 INQ 确认(Paydee 建议约 30 分钟后)并读取 MPI_STATUS。
核心事实
- 除获取支付渠道(GET /channels,按规范使用 JSON 请求体)外,每个 API 调用均为 HTTPS POST。
- 端点:/mkReq(密钥交换,JSON)、/mercReq(托管页,表单数据)、/mpReq(非托管及服务端操作,表单数据 application/x-www-form-urlencoded)、/channels(渠道列表)。
- 官方 Swagger 中的测试服务器:https://devlink.paydee.co/mpi。生产 URL 位于开发者门户登录之后。
- 密钥交换必须先于其他所有调用。/mkReq 中的 purchaseId 等于下一请求中的 MPI_TRXN_ID;每个新操作(INQ、VOID、REFUND、RECURR)使用新 ID 及各自的密钥交换。
- 签名:SHA256withRSA,Base64Url 编码,用发送方私钥签名,用 /mkReq 中交换的对端公钥验证。
- 金额为最小货币单位的整数(MYR 10.23 = 1023);币种为 ISO 4217 数字(458 = MYR)。XLSX 显示 Paydee 仅接受 MYR。
- MPI_PURCH_DATE 格式为 yyyyMMddHHmmss(24 小时制)。
- MPI_EMAIL 为必填;账单地址为条件必填(C1);至少需要一对电话号码(C2)。这些由 2024 年 2 月 12 日起生效的 Visa 规则驱动。
- 支付方式(paymentMethod / MPI_CUST_PAYMENT_METHOD):CC、EWALLETS、FPX、TRD(Trade Credit)、DNQR(DuitNow QR)。
- MPI_STATUS:0 已请求、1 成功、2 已取消、3/4 冲正请求/成功、5/6 退款请求/成功、7 已结算、8 循环扣款终止、-1 失败、-2 冲正失败、-3 退款失败、-4 销售请求失败。
- Paydee 要求结账页按 EMV 3-D Secure 2.0 以 iframe 实现。
- 若最终金额超过 PREAUTH 金额 20% 以上,SALESCOMPL 会被拒绝。
- 网银(FPX)退款功能已在规范 v3.0.3(2025 年 7 月 1 日)中移除。
- 公布的沙箱测试卡:Visa 4100000000000100、Mastercard 5100000000000107(无摩擦成功);挑战卡使用 OTP 123456。仅限沙箱。
关键规则
- RSA 私钥必须保存在服务端。切勿从非 PCI 服务器发送卡数据;非托管卡字段(MPI_PAN、MPI_CVV2)会使你进入 PCI DSS 范围。
- 切勿仅凭浏览器重定向标记已支付;在重定向和回调上均验证 MPI_MAC,存疑时以 INQ 为准。
- MAC 字符串必须严格按文档字段顺序构建,缺失字段用空字符串。与 Paydee 确认空白处理(样本显示空格被移除)。
- 用同一会话 /mkReq 响应中的 Paydee 公钥验证,而非其他会话的缓存密钥。
- 将 004(处理中)以及撤销/退款确认视为非最终结果。
- 切勿复用交易 ID;重复会被拒绝(594),且(商户 ID, 交易 ID)组合标识一笔交易。
- 测试与生产商户 ID、密钥和端点须分开保存。
完成标准
仅当以下条件全部满足时,Paydee 集成才算完成:每个支付会话生成自己的 RSA 密钥对并在服务端执行 /mkReq,Paydee 会话密钥随支付保存;请求 MPI_MAC 按文档顺序生成并被测试服务器接受(无 5A0);重定向与回调处理器在结算前验证响应 MPI_MAC、商户 ID、交易 ID、金额和币种;结算要求 MPI_ERROR_CODE=000 且 MPI_STATUS=1,幂等并处理重复;存在针对超时、浏览器关闭和待处理状态的 INQ 回退,撤销/退款结果由 INQ 确认;非托管流程加载 /channels 并禁用被阻止(=B)的渠道;测试覆盖错误 MAC、错误金额、错误交易 ID、失败卡(4100000000300005)、挑战流程和重复回调;部署文档列出 PAYDEE_ENV、PAYDEE_ENDPOINT、PAYDEE_MERCHANT_ID、已登记密钥交换密钥路径(如使用)以及与 Paydee 商定的回调/重定向 URL。
漏洞审查循环
当被问及某 Paydee 策略是否“100% 确信”时,运行此循环直至无事实缺口:列出信任边界(持卡人浏览器、托管页、商户结账页、/mkReq 调用方、密钥库、MAC 构建器、回调接收器、重定向处理器、INQ 任务、撤销/退款任务、循环调度器、数据库);检查绕过点(伪造重定向、用错误会话密钥验证 MAC、MAC 字符串顺序或空白错误、缺失空字段、复用交易 ID、以令吉而非分计金额、测试/生产混用、信任 004、信任撤销/退款确认、被阻止渠道仍可选、SALESCOMPL 超过 120%、循环扣款未带原始交易 ID);添加修复(每会话密钥、严格字段顺序、固定格式金额、服务端 INQ 确认、(merchant_id, trxn_id)幂等键、持久回调日志、独立环境配置);重读 references/paydee-api.md 中与缺口相关的部分,尤其是“Documented conflicts”;说明剩余不确定性:回调 URL 设置、生产端点、循环扣款字段名、MAC 字符串中的空白处理、响应 MAC 顺序和 IP 白名单在公开文档中未完全明确,须与 Paydee(help@paydee.co)确认。
适用场景与限制
适用于使用 Paydee MPI 网关的马来西亚支付集成开发、审查与排障。公开文档未覆盖的回调 URL 配置、生产端点、循环扣款字段名、MAC 空白处理、响应 MAC 顺序与 IP 白名单等事项暂未提供,需向 Paydee 确认。