SuperAPI AI 工具集

setup-spaylater

编程与开发

查看项目

更新于 11-17 03:10

技能介绍

用途

该技能面向在马来西亚商户自有网站、应用或店铺中受理 SPayLater(Shopee PayLater,即 ShopeePay 先买后付)的场景,提供接入搭建、代码编写、调试、审查与解释。SPayLater 通过 ShopeePay 的 API 受理,是一种支付方式(spay_later),不是独立 API。Shopee 平台卖家无需进行集成。

资料结构

使用前需阅读以下参考文档:references/spaylater-api.md(主机、认证与签名及已验证测试向量、端点目录、Gateway v1 与 Checkout v3 字段表、状态、回调、退款、作废/取消、错误码及所有枚举,含 SPayLater 支付渠道);references/spaylater-tokenized.md(商户在自有收银台展示分期、关联 ShopeePay 账户、周期扣款、授权与捕获);references/spaylater-widget.md(“低至 RM X/月”推广信息及品牌规范,支持 Web、Android、iOS、Shopify);references/account-setup.md(入驻、凭证、环境变量、沙箱、插件、结算与定价指引);references/source-map.md(选取官方页面、覆盖范围及仅 ShopeePay 能回答的缺口)。

主要能力与工作流

  1. 确认商户已签署包含 SPayLater 的 ShopeePay 协议,并具备对应环境的 Client ID、Secret Key、merchant_ext_id、store_ext_id。
  2. 选择接入面:Payment Gateway v1 托管收银台、ShopeePay Checkout v3、Link & Pay(自有分期选择)、插件(Shopify、WooCommerce)或线下 MPM/CPM。
  3. 选择该接入面与环境对应的主机对(wallet:api.uat.wallet.airpay.com.my / api.wallet.airpay.com.my;gateway:api.gw.uat.airpay.com.my / api.gw.airpay.com.my)。
  4. 本地创建待支付记录(reference、金额×100、币种 MYR、环境)。
  5. 服务端创建订单,对发送的精确 JSON 字符串用 HMAC-SHA256 + Base64 签名并放入 X-Airpay-Req-H。
  6. 选择 SPayLater:v1 用 allowed_payment_method: ["spay_later"];v3 用 preferred_payment_method_type: "spay_later";Link & Pay 用 payment_method_type: "spay_later" 加分期的 payment_option_reference。
  7. 跳转 checkout_url 或 redirect_url_http;返回 URL 仅视为用户体验,不得据此判定支付成功。
  8. 对每个回调基于原始报文验签,匹配 reference、商户、店铺、金额与币种,去重后结算,并回复 {"errcode":0}。
  9. 马来西亚 v3 回调只发送一次且不重试;未收到回调时按文档计划轮询 Check Transaction Status(或 Get Checkout Status),随后作废或取消。
  10. 通过对应接入面的 API 发起退款,并重查退款状态。

核心事实

马来西亚地区代码 com.my。Wallet API 生产 https://api.wallet.airpay.com.my,预发 https://api.uat.wallet.airpay.com.my。Payment Gateway 生产 https://api.gw.airpay.com.my,沙箱 https://api.gw.uat.airpay.com.my。请求头:X-Airpay-ClientId: <CLIENT_ID>,X-Airpay-Req-H: base64(hmac_sha256(secret, raw_body))。Checkout v3:POST /v3/merchant-host/order/create;马来西亚 validity_period 最大 3600 秒,默认 1200 秒。Gateway v1:POST /v1/checkout、GET /v1/checkout/{checkout_id}、POST /v1/checkout/cancel/{checkout_id}、POST /v1/refund、GET /v1/refund/{refund_id}。状态查询:POST /v3/merchant-host/transaction/check(transaction_type 13 为支付,15 为退款);status 3 表示成功。退款 v3:POST /v3/merchant-host/transaction/refund/create-new;允许部分退款;默认本地时间 0 点至 5 点禁止退款。金额为整数×100(RM 12.34 = 1234)。SPayLater 支付渠道:4 为 BNPL,5=2M,6=3M,7=6M,8=12M,9=18M,10=24M,11=4M,12=5M。马来西亚 v3 回调成功:payment_status 1(Checkout/MPM/CPM)或 transaction_status 3(Link & Pay/Subscription)。Gateway 回调事件:checkout.successful、checkout.expired、checkout.cancelled、refund.successful、refund.failed。轮询:每 5 秒递增至 100 秒,之后每 5 分钟直至 24 小时。SPayLater 在马来西亚由 Monee Capital Malaysia Sdn. Bhd. 提供;ShopeePay Malaysia 为平台合作方与支付 Facilitator。结算:每日 T+1、每周一或每月首日;打款可再延 2 天。速率限制、回调 IP、SPayLater 最小/最大金额及公开测试用户暂未提供(资料检查日期 2026-10-21)。

关键规则

Secret Key 仅保留在服务端;只有 SPL widget 的 Access Key 可下发浏览器。签名与发送必须使用同一序列化字符串,签名后不得重新序列化。回调验签必须基于原始报文并使用常量时间比较,且在解析前完成。绝不能依据返回 URL 或其查询参数标记已支付。结算前须核对金额与 reference 是否与原始请求一致(ShopeePay 要求)。回调处理须幂等(Gateway 用 event_id 或 reference + transaction_sn 作为键)。马来西亚不能仅依赖回调(不重试)。SPayLater CPM/Checkout 的 “Processing” 应视为待处理而非失败。Gateway 状态字符串比较不区分大小写;退款接受 succeeded 与 successful。validity_period 与 expiry_time 不可同时发送。不要对 ShopeePay 跳转 URL 做域名白名单或 IP 限制。仅展示 is_available: true 的 SPayLater 分期并显示 compliance_notices。不得使用保证通过类措辞,遵守 widget 合规规则。不引用商户费率(由商业协议确定)。

完成标准

订单创建在服务端运行,使用正确主机、X-Airpay-ClientId,且签名在单元测试中与文档测试向量一致;按所选取接入面选择或提供 SPayLater,且协议确认已启用;回调 URL 已按环境注册到 ShopeePay;回调处理器对原始报文验证 X-Airpay-Req-H,检查 reference、商户、店铺、金额、币种,去重并回复 errcode 0;轮询器按文档计划覆盖缺失回调,随后作废或取消;全额与部分退款及退款重查可用且幂等;测试覆盖错误签名、重放回调、金额/reference 不符、处理中后成功、过期、取消、退款失败、0 点至 5 点退款阻断;部署文档列出 SHOPEEPAY_CLIENT_ID、SHOPEEPAY_SECRET_KEY、SHOPEEPAY_MERCHANT_EXT_ID、SHOPEEPAY_STORE_EXT_ID、SHOPEEPAY_ENV、回调 URL、返回 URL 及预发/生产隔离。

漏洞审查循环

当被问及某 SPayLater 策略是否“100% 有把握”时,循环执行直至无事实缺口:列出信任边界(浏览器返回 URL、Shopee/ShopeePay 应用跳转、托管收银台、商户后端、ShopeePay wallet API、gateway API、回调接收器、原始报文解析器、数据库、轮询器、退款任务、widget 脚本、插件设置);检查绕过点(伪造回调、对已解析 JSON 验签、错误密钥或环境、错误主机族、伪造返回 URL 参数、错误金额/币种/reference/店铺、重复回调、无重试的丢失回调、将 SPayLater “Processing” 视为失败、过期订单迟付、重复退款、阻断时段退款、分期选项不可用、SPayLater 未上线却展示 widget);补充修复(服务端创建、本地待支付记录、原始报文 HMAC 与常量时间比较、严格字段匹配、持久事件日志、幂等键、文档化轮询、超时作废/取消、预发/生产配置隔离、合规审查);重读 references/spaylater-api.md 与 references/spaylater-tokenized.md 相关章节;说明 references/source-map.md 缺口清单中的剩余不确定性(GET 签名、响应签名头、Gateway 回调确认、最小/最大金额、退款窗口、产品在马来西亚的可用性)。

适用场景与限制

适用于马来西亚商户自有渠道的 SPayLater 受理、分期展示、周期扣款、授权捕获、促销信息展示及插件接入。不适用于 Shopee 平台卖家(无需集成)。费率由商业协议确定;速率限制、回调 IP、最小/最大金额及公开测试用户暂未提供。