SuperAPI AI 工具集

setup-grab-paylater

编程与开发

查看项目

更新于 11-17 02:10

技能介绍

该技能面向 GrabPay 钱包和 PayLater by Grab 的在线结账集成工作,基于 Grab Partner API,不涉及线下 QR。使用前需先阅读 references/grab-paylater-api.md 以获取端点目录、环境、HMAC 算法、一次性扣款完整流程、webhook 负载、状态查询、退款、金额规则、速率限制和令牌有效期等事实信息。

主要能力包括:

  • 根据官方文档提供 API 使用指导并编写集成代码,覆盖 charge/init、OAuth 令牌交换、charge/complete、状态查询和退款等核心调用。
  • 支持插件方式(Shopify、WooCommerce、Magento、EasyStore)或直连 API 方式接入。
  • 提供 PKCE 授权流程、服务端 HMAC 签名、Bearer 加 POP 认证的实现要点。
  • 提供 webhook 签名验证、幂等处理和状态查询确认。
  • 提供 Tokenisation v4 用于保存钱包、重复扣款或订阅扣款(bind、charge、top-up、promo、unbind)。
  • 提供账户开通、凭证获取、集成管理器(Integration Manager)入驻、插件、Price Divider、品牌规则和结算报告等参考。

使用方式:

  1. 确认商户已完成开通,Grab 下发 partner_id、partner_secret、client_id、client_secret、merchant_id,并注册 redirect URL 和 webhook URL。无自助沙箱注册。
  2. 选择接入方式:插件或直连 API。一次性结账使用 OTC,重复扣款使用 Tokenisation v4。
  3. 本地创建待处理订单,生成唯一 partnerTxID(最多 32 字符,[a-zA-Z0-9-_]),金额以 sen 为整数单位,货币 MYR。
  4. 服务端 POST /grabpay/partner/v2/charge/init,使用 partner HMAC 签名(Authorization: {partner_id}:{signature}),保存返回的 request。
  5. 构造 GrabID 授权 URL,携带 PKCE(S256)、state、nonce、acr_values=consent_ctx:countryCode=MY,currency=MYR、request、scope openid payment.one_time_charge,并在服务端保存 code_verifier 和 state。
  6. 重定向用户,返回时校验 state、处理错误值、提取 code。
  7. 服务端 POST /grabid/v1/oauth2/token 换取 access_token,加密存储。
  8. 服务端 POST /grabpay/partner/v2/charge/complete,使用 Bearer 令牌和新的 X-GID-AUX-POP,此步骤完成资金划转;未完成则授权过期,Grab 取消并退款。
  9. 仅当 complete、状态查询或已验证的 webhook 返回最终 txStatus 为 success,且 partnerTxID、金额、货币和商户匹配时,标记为已支付。
  10. processing 状态通过 webhook 或每 2 分钟最多一次的状态轮询处理。退款使用新的 refund partnerTxID 和原 charge txID 作为 originTxID。

关键事实:

  • 生产 API 基础地址:https://partner-api.grab.com;测试基础地址:https://partner-api.stg-myteksi.com。
  • 当前 OTC 文档说明使用生产测试凭证和集成管理器发放的测试 Grab 账户进行测试,各端点仍列出测试 URL。
  • Partner HMAC 待签名字符串:METHOD\nContent-Type\nDate\nPATH[?QUERY]\nBASE64(SHA256(body))\n,使用 partner_secret 做 HMAC-SHA256,base64 编码。
  • X-GID-AUX-POP = base64url(JSON {"time_since_epoch":<unix>,"sig":base64url(HMAC-SHA256(client_secret, <unix> + access_token))}),无填充。
  • Date 头使用 RFC 7231 GMT 格式,头和签名中的值一致;时钟偏差超过 5 分钟导致 401。
  • 金额为最小单位整数:MYR 10.00 = 1000。
  • PayLater 不是独立 API,出现在 Grab 结账中(POSTPAID、INSTALMENT_4/8/12)。可通过 hidePaymentMethods: ["INSTALMENT","POSTPAID"] 隐藏,钱包不可隐藏。PayLater 分期交易需要 metaInfo。
  • 有效期:request code 20 分钟,OAuth code 15 分钟,OTC access token 约 1 年(expires_in 31535999)。未完成的扣款在 15 分钟后取消并自动退款;需在授权 webhook 或重定向后 10 分钟内调用 complete。
  • Webhook 的 Authorization 为 {partner_id}:{hmac};重新计算时使用 Content-Type application/json; charset=utf-8。使用 txStatus,不使用已弃用的 status/newStatus。
  • 速率限制:每个 Partner ID 每秒最多 50 次 API 调用;429 时使用带抖动的退避。
  • 马来西亚退款窗口 365 天。商户钱包每日提现,退款可能因 merchant_insufficient_balance 失败。
  • 结算报告通过 SFTP 或 Grab Merchant Portal(https://merchant.grab.com/)获取,T+1 12:00 交付,截止 23:59:59,格式为 CSV(管道分隔)或 XLS。

关键规则:

  • partner_secret、client_secret 和 access token 仅保存在服务端;Grab 建议使用 KMS 存储密钥,不要放在配置文件、代码仓库或 Redis 中。
  • 不得仅凭重定向 code 标记已支付;只有 /charge/complete 返回 success 后扣款才完成。
  • 对发送的确切字节进行签名;签名和发送之间不要重新序列化 JSON。
  • 每次 init 和退款生成新的 partnerTxID;重复使用会返回已有交易或 transaction_already_exists。
  • 重定向时校验 state,校验 id_token 中的 nonce,不匹配则拒绝。
  • 未知 reason code 视为非最终状态,需重新查询;扣款只有 success 和 failed 是最终状态。
  • 验证 webhook 签名后,在履约前通过状态查询确认,因为文档未明确 webhook 签名路径。
  • 不要用 cURL 或 Postman 测试生产环境(Grab 安全指南);避免密钥进入 shell 历史。
  • 不要复制定价;MDR 需协商,链接到 Grab 商户页面。

完成标准:

  • charge init、令牌交换、complete、状态查询和退款调用均在服务端运行,使用正确的 HMAC 或 Bearer 加 POP 认证。
  • 每个订单生成 PKCE verifier、state 和 nonce,服务端存储并校验。
  • 重定向处理器覆盖 code、所有文档化错误以及缺失或不匹配的 state。
  • webhook 处理器验证 Authorization,按 partnerTxID + txType 幂等,并快速返回 HTTP 200。
  • 结算时校验 partnerTxID、txID、金额、货币、merchantID、最终 txStatus 和环境。
  • processing 和已授权未完成状态由任务恢复(状态查询,然后 complete 或标记失败)。
  • 测试覆盖错误签名、时钟偏差、重复 webhook、用户取消、会话过期、余额不足、部分退款和退款处理。
  • 部署文档列出各环境的 GRAB_PARTNER_ID、GRAB_PARTNER_SECRET、GRAB_CLIENT_ID、GRAB_CLIENT_SECRET、GRAB_MERCHANT_ID、GRAB_REDIRECT_URI、webhook URL 和基础地址。

适用场景:需要在线接入 GrabPay 钱包或 PayLater 的电商结账、重复扣款或订阅场景。限制:无自助沙箱,依赖 Grab 开通和集成管理器;webhook 签名路径、GET body 哈希约定、启用的支付方式、PayLater 审批、马来西亚测试账户和定价均取决于 Grab 入驻流程和集成管理器,资料未提供具体细节。