2C2P 支付网关技能用于 2C2P(PGW v4.x)支付网关集成工作,面向需要接入马来西亚支付渠道的开发者。
用途
该技能覆盖 2C2P 支付集成的完整流程:环境识别、凭证配置、Payment Token 创建、重定向支付、Direct API 自有结账界面、Drop-In UI、移动 SDK(Android、iOS、Flutter、React Native)、插件、QuickPay 支付链接与代付、批量对账、SoftPOS 以及定期维护(退款、作废、结算、退款状态、卡与客户令牌维护)。
主要能力
- 基于官方文档提供 API 事实指导,包括环境、四种安全方案、端点目录、Payment Token 字段、重定向流程、前后端通知格式、支付查询、金额规则、结算清单和沙盒数据。
- 支持自有结账 UI(Payment Option、Do Payment、Transaction Status、Secure Pay JS、Drop-In UI、Apple Pay、Google Pay、马来西亚渠道形态)。
- 支持维护操作:退款、作废、结算、退款状态、退款通知、定期维护、卡和客户令牌维护,以及 JWE + JWS 密钥设置。
- 提供响应码、马来西亚渠道、FPX 和代理代码、截止时间和测试卡信息。
- 提供账户设置、密钥、沙盒、定价和结算问题的参考,以及官方页面来源映射。
使用方式
核心工作流:
- 识别环境(沙盒或生产)和接入面(托管重定向、Direct API、Drop-In UI、移动 SDK、插件、QuickPay 链接、定期计划、代付或 SoftPOS)。
- 确认凭证与设置:Merchant ID、Secret Key、已启用渠道、返回 URL;维护操作还需 RSA 密钥对和 2C2P 公钥。
- 在调用 2C2P 前创建本地待处理订单,包含唯一 invoiceNo、预期金额和货币。
- 服务端调用 Payment Token,请求体为 JWT HS256 {"payload"},仅当 respCode 为 0000 时继续。
- 重定向到 webPaymentUrl,或使用 paymentToken 执行 Direct API / SDK 流程。
- 前端返回(paymentResponse,未签名 base64url)和 Transaction Status 仅作为用户体验参考。
- 使用 Secret Key 验证后端通知 JWT,并检查商户、发票、金额、货币和 respCode。
- 幂等结算;对缺失、延迟或可疑结果使用 Payment Inquiry。
- 通过 Payment Maintenance 执行退款、作废和捕获,使用 JWE + JWS,并保证幂等和状态检查。
关键事实
- PGW API 主机:沙盒 https://sandbox-pgw.2c2p.com,生产 https://pgw.2c2p.com。
- Payment Token:POST /payment/4.5/paymentToken(文档页面)或 /payment/4.3/paymenttoken(OpenAPI 4.3),需一致使用一个版本。
- Payment Inquiry:POST /payment/4.5/paymentInquiry,使用 merchantID 加 invoiceNo 或 paymentToken。
- PGW 签名:使用商户 Secret Key 字符串的 JWT HS256;请求和响应体为 {"payload":"<jwt>"}。
- Payment Token 必填字段:merchantID、invoiceNo、description、amount、currencyCode;paymentToken 有效期 30 分钟。
- amount 为林吉特十进制数(150.00),不是分;currencyCode 为 MYR。
- 后端通知:POST {"payload":"<JWT>"} 到 backendReturnUrl(或门户默认),声明与 Payment Inquiry 匹配。
- 成功为 respCode 0000;0001 待处理;流程码 2000 表示“已完成,检查后端或查询”。
- Payment Maintenance:沙盒 https://demo2.2c2p.com/PaymentAction/2.0/action,生产 https://t.2c2p.com/PaymentAction/2.0/action;XML PaymentProcessRequest v4.6,使用 2C2P 公钥的 JWE RSA-OAEP + A256GCM,然后使用商户私钥的 JWS PS256,text/plain。
- processType:I 查询、R 退款、RS 退款状态、V 作废、S 结算;维护 respCode 00 为成功。
- FPX 使用渠道 123,代理渠道 WEBPAY,代理代码 MY...(例如 MYM2U);旧版 FPX_* 代码必须迁移。
- 马来西亚沙盒演示商户 JT07(MYR);FPX 测试银行 MYSBIA、MYSBIB、MYSBIC;测试 Visa 4111111111111111,OTP 123456。
适用场景
适合需要集成 2C2P 支付网关的马来西亚电商、应用或服务端系统,尤其是使用 FPX、卡支付、钱包、定期扣款、代付或批量对账的场景。也适合审查现有 2C2P 集成安全性、调试支付通知和结算问题。
限制
- Secret Key 和商户私钥必须仅保存在服务端,绝不能出现在浏览器、应用或仓库中。
- 不得仅凭前端返回、Transaction Status、Do Payment 响应、SDK 结果、iframe postMessage 或二维码显示标记已支付。
- 每个 JWT 必须使用 HS256 验证并拒绝其他算法;维护响应必须先验证 JWS PS256 再解密。
- invoiceNo 不可重复使用,否则触发重复发票错误(9015、5005)。
- 仅对已结算交易退款;仅在同一日收单机构截止前作废;重试前发送 idempotencyID 并检查 RS / I。
- REFUND_PENDING(RP,代码 42)视为未完成,需轮询退款状态或验证 notifyURL 回调。
- 不引用费用或结算时间,2C2P 未公布马来西亚费率卡。
- 速率限制、通知 IP 范围和重试计划标注为“官方文档未记录”,不得猜测。
- 关于商户配置文件版本、已启用渠道、收单机构对卡存档的支持、结算条款等,存在不确定性时需明确说明。