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