SuperAPI AI 工具集

setup-shopeepay-gateway

编程与开发

查看项目

更新于 11-17 02:10

技能介绍

用途

此技能面向直接对接 ShopeePay 商户 API(ShopeePay Malaysia Sdn Bhd)的工程工作,用于搭建、开发、调试、代码审查和方案讲解。它明确不适用于通过其他聚合网关接入 ShopeePay 的场景。

参考资料结构

技能以本地参考文档为事实来源,使用前应先阅读:

  • references/shopeepay-gateway-api.md:主机地址、请求头、签名算法与已验证测试向量、端点目录、Checkout with ShopeePay、MPM、CPM、作废、退款、Notify Transaction Status、Check Transaction Status、常用枚举、错误码与重试策略。
  • references/shopeepay-gateway-hosted-gateway.md:独立的 ShopeePay Payment Gateway 产品(/v1/checkout、/v1/refund、webhook 事件),运行在 api.gw.* 主机上。
  • references/shopeepay-gateway-tokenized.md:Account Linking、访问令牌、Link & Pay、订阅、Auth & Capture 及风险 additional_info 对象。
  • references/account-setup.md:入驻、凭据、沙箱、插件、回调 URL 注册与马来西亚可用性。
  • references/source-map.md:官方页面索引、文档覆盖范围与已知缺口。

核心工作流

  1. 识别产品形态:Checkout with ShopeePay(在线跳转)、ShopeePay Payment Gateway(托管多方式收银台)、MPM 动态二维码、CPM 扫码、Link & Pay、订阅或 Auth & Capture。
  2. 确认环境与主机:钱包 API 为 api.uat.wallet.airpay.com.my(测试)/ api.wallet.airpay.com.my(生产);托管网关为 api.gw.uat.airpay.com.my / api.gw.airpay.com.my。
  3. 在调用 ShopeePay 前,本地先创建待支付订单,使用唯一 payment_reference_id,金额以 sen 为单位(RM x 100)。
  4. 将 JSON 请求体只序列化一次,对完全相同的字节做 HMAC-SHA256 签名,再做 Base64 编码,随 X-Airpay-ClientId 与 X-Airpay-Req-H 请求头发送。所有钱包 API 调用都是服务端 POST。
  5. 每次响应都检查 errcode(0 为成功);将 -1、-2、5、超时和 “processing” 视为未知状态,不得当作失败。
  6. Checkout 流程将客户跳转至 redirect_url_http;MPM 流程展示 qr_content。return_url 仅用于用户体验。
  7. 对 Notify Transaction Status 回调,按原始请求体验证签名,核对 payment_reference_id 与金额,然后返回 {"errcode":0}。
  8. 马来西亚回调只发送一次,因此必须按文档给出的退避计划调用 Check Transaction Status 兜底。
  9. 幂等结算;对放弃的订单或二维码执行作废;退款使用唯一 refund_reference_id。

关键事实

  • 签名:X-Airpay-Req-H = Base64(HMAC-SHA256(secret_key, 原始请求体));客户端 ID 放在 X-Airpay-ClientId。
  • 协议:HTTPS、POST、JSON、UTF-8、UNIX 秒、TLS 1.2 或 1.3,无 SDK,仅直接 REST。
  • 金额为放大 100 倍的整数(RM 10.00 = 1000)。
  • Checkout with ShopeePay:POST /v3/merchant-host/order/create,返回 redirect_url_http;马来西亚最长有效期 3600 秒,默认 1200 秒。
  • MPM 动态二维码:POST /v3/merchant-host/qr/create;马来西亚最长 3600 秒,默认 1200 秒;qr_url 有效 5 分钟。
  • CPM:POST /v3/merchant-host/transaction/payment/create,提交扫描得到的 payment_code。
  • 状态查询:POST /v3/merchant-host/transaction/check,参数含 reference_id、transaction_type(13 支付、15 退款)与原始金额。
  • 退款:POST /v3/merchant-host/transaction/refund/create-new;支持全额或部分退款;365 天窗口;相同请求体幂等。
  • 马来西亚回调成功标志:payment_status = 1(CPM/MPM/Checkout)或 transaction_status = 3(Link & Pay/Subscription)。
  • 交易状态枚举:1 初始、2 处理中、3 成功、4 失败、6 过期、7 已作废。
  • 回调 URL 在入驻时向 ShopeePay 集成团队注册,不能按请求单独指定。
  • 凭据(Client ID、Secret Key、merchant_ext_id、store_ext_id)在签署 NDA 与商务协议后发放;没有自助沙箱。

关键规则

  • 密钥仅保存在服务端,禁止在浏览器或移动端签名。
  • 对实际发送的字节串签名,签名与发送之间不得重新序列化。
  • 解析前先用常量时间比较验证回调 X-Airpay-Req-H(基于原始请求体)。
  • 不得仅凭 return_url、前端状态或客户截图标记已支付。
  • 标记已支付前必须核对金额与 payment_reference_id 是否与原请求一致。
  • 回调与状态中的 payment_method 表示产品流程(发起方式),不是可靠校验值,文档明确不建议默认据此校验。
  • 不要为 redirect_url_http 设置域名或 IP 白名单。
  • request_id 每次调用唯一,payment_reference_id 每笔订单唯一;errcode 11 表示重复请求。
  • 部分退款需等上一笔完成;当地时间 0 点至 5 点默认禁止退款(errcode 601)。
  • 忽略未知响应字段与字段顺序,因为 ShopeePay 会在不通知的情况下新增字段。

完成标准

  • 所有调用在服务端执行,请求头正确,签名单元测试通过官方测试向量。
  • 本地订单在跳转或展示二维码前存储 payment_reference_id、request_id、以 sen 计的金额、币种 MYR、环境与状态。
  • 回调处理验证原始请求体签名、核对引用号与金额、幂等,并返回 {"errcode":0}。
  • 查询任务按 5 秒步退避至 100 秒,之后每 5 分钟一次,最长 24 小时。
  • 放弃订单调用 Invalidate Order(Checkout)或 Invalidate QR(MPM)。
  • 退款使用唯一 refund_reference_id,处理 errcode 5 与 320,并以 transaction_type 15 复查。
  • 测试覆盖错误签名、金额错误、重复回调、errcode -1/5/超时、订单过期与退款失败。
  • 配置记录 SHOPEEPAY_CLIENT_ID、SHOPEEPAY_SECRET_KEY、SHOPEEPAY_MERCHANT_EXT_ID、SHOPEEPAY_STORE_EXT_ID、SHOPEEPAY_ENV 以及注册的回调 URL。

漏洞审查循环

当被问及某 ShopeePay 方案是否 “100% 有信心” 时,可按以下循环执行:列出信任边界(浏览器、ShopeePay 应用或网页、return_url、后端签名器、ShopeePay API、回调接收器、原始请求体解析器、数据库、查询任务、退款任务、插件配置);检查绕过点(伪造回调、对重新编码的 JSON 签名、密钥或主机错误(UAT 与生产、钱包与 gw)、金额用林吉特而非 sen、复用 payment_reference_id、把 errcode -1 当失败、漏掉马来西亚单次回调、过期订单被晚付款、重复退款、封禁时段退款、访问令牌过期、未绑定账户仍被扣款);补充修复(仅服务端签名、原始请求体 HMAC、常量时间比较、严格核对引用号与金额、唯一 ID、持久化回调日志、查询退避、取消时作废、幂等结算与退款记录);针对缺口重读相关参考章节;说明剩余不确定性。

适用场景

适用于需要直接对接 ShopeePay 马来西亚钱包 API 或托管网关的商户后端开发、集成评审与问题排查,尤其是涉及签名、回调验真、状态查询兜底、幂等与退款控制的场景。

限制

以下内容资料未发布,需向 ShopeePay 集成团队确认:响应签名头名称、回调 IP 段、沙箱测试数据、速率限制、托管网关各支付方式的可用性以及定价。此技能不适用于通过第三方聚合网关接入的 ShopeePay,也不适用于没有 NDA 与商务协议、无法获取凭据的情形。