对接 PayerMax 支付接口,主要涉及 创建支付订单 和 处理支付回调 两个核心环节,所需参数因具体接口和支付方式而异。根据业务流程,关键的请求参数和其含义说明如下,主要参考收银台支付模式 。
相关服务:合作伙伴
一、 创建支付订单参数
当商户后台系统调用 PayerMax 的支付下单 API 时,需要构造一个包含业务信息、商户信息和签名验证信息的请求体。
| 参数分类 | 参数名 (示例) | 参数含义说明 | 是否必填 |
|---|---|---|---|
| 商户与基础信息 | merchantNo | 商户号,由 PayerMax 在商户入驻时分配的唯一标识。 | 是 |
appId | 应用 ID,商户在 PayerMax 后台创建应用后获得,用于标识具体的网站或APP。 | 是 | |
requestId | 商户请求唯一标识,用于幂等控制,避免重复下单。通常可使用订单号。 | 是 | |
| 订单信息 | orderNo | 商户系统内部的订单编号,必须保证唯一。 | 是 |
amount | 订单金额。单位通常为对应币种的最小单位(如分、cents)。 | 是 | |
currency | 订单币种,需遵循 ISO 4217 标准,如 USD, EUR, CNY。 | 是 | |
goodsName | 商品名称或订单描述。 | 是 | |
expireTime | 订单过期时间,格式为时间戳(毫秒)。 | 否 | |
| 用户与支付信息 | country | 用户所在国家/地区代码,遵循 ISO 3166-1 alpha-2 标准,如 US, SG。用于确定可用的本地支付方式。 | 是 |
payerInfo | 包含支付者信息的 JSON 对象,通常包括 firstName, lastName, email, phone 等。这有助于提高支付成功率。 | 否 | |
paymentMethod | 指定的支付方式代码,如 credit_card(信用卡)、dana(印尼电子钱包)、touch_n_go(马来西亚电子钱包)等。若为空,则用户可在收银台选择。 | 否 | |
| 回调与跳转 | notifyUrl | 服务器异步通知地址。支付成功后,PayerMax 服务器会向此 URL 发送 POST 请求通知支付结果。这是接收最终支付状态、进行业务处理(如发货)的关键配置。 | 是 |
returnUrl | 页面同步跳转地址。支付完成后,用户浏览器将被重定向到此 URL。通常用于展示感谢页面。 | 否 | |
| 安全与签名 | signType | 签名算法类型,当前通常为 RSA2 或 SHA256WithRSA。 | 是 |
sign | 请求参数的签名。商户使用自己的私钥对所有待签名参数(按特定规则排序并拼接成字符串)进行加密生成。PayerMax 使用商户提供的公钥验签,以确保请求未被篡改且来源可信。 | 是 |
以下是一个简化的 Java 代码示例,展示如何构造支付请求参数并生成签名:
import java.util.*;
public class PayerMaxPayRequest {
private String merchantNo;
private String appId;
private String requestId;
private String orderNo;
private String amount;
private String currency;
private String goodsName;
private String country;
private String notifyUrl;
private String sign;
// ... 其他参数及getter/setter
/**
* 生成待签名字符串
* 规则:排除sign字段本身,将其他所有参数按参数名ASCII码从小到大排序(字典序),使用URL键值对的格式(即key1=value1&key2=value2…)拼接成字符串。
*/
public String buildSignString() {
Map<String, String> params = new TreeMap<>(); // TreeMap自动按键排序
params.put("merchantNo", this.merchantNo);
params.put("appId", this.appId);
params.put("requestId", this.requestId);
params.put("orderNo", this.orderNo);
params.put("amount", this.amount);
params.put("currency", this.currency);
params.put("goodsName", this.goodsName);
params.put("country", this.country);
params.put("notifyUrl", this.notifyUrl);
// 注意:排除空值参数和sign参数
StringBuilder sb = new StringBuilder();
for (Map.Entry<String, String> entry : params.entrySet()) {
if (entry.getValue() != null && !entry.getValue().trim().isEmpty()) {
if (sb.length() > 0) {
sb.append("&");
}
sb.append(entry.getKey()).append("=").append(entry.getValue());
}
}
return sb.toString();
}
/**
* 使用商户私钥对签名字符串进行RSA签名
* @param signString 待签名字符串
* @param privateKey 商户私钥
* @return Base64编码后的签名值
*/
public String generateRSASign(String signString, String privateKey) throws Exception {
// 此处为示例,实际需使用如Java的Signature类完成签名
// Signature signature = Signature.getInstance("SHA256WithRSA");
// signature.initSign(loadPrivateKey(privateKey));
// signature.update(signString.getBytes(StandardCharsets.UTF_8));
// byte[] signed = signature.sign();
// return Base64.getEncoder().encodeToString(signed);
return "[这里应是通过私钥计算出的实际签名]";
}
}
二、 支付结果回调通知参数
支付成功后,PayerMax 会向商户配置的 notifyUrl 发起异步 POST 通知。商户服务器收到后,必须验证签名,然后根据通知参数更新订单状态。关键的回调参数如下 :
| 参数名 (示例) | 参数含义说明 | 备注 |
|---|---|---|
merchantNo | 商户号,与请求时一致。 | |
orderNo | 商户订单号。 | |
pmOrderNo | PayerMax 系统生成的唯一支付订单号。 | |
tradeNo | 支付渠道的交易流水号。 | |
amount | 订单金额。 | |
currency | 订单币种。 | |
status | 支付状态。这是最重要的参数,常见值有:SUCCESS(支付成功)、FAILED(支付失败)、PENDING(处理中)等。 | 商户需根据此状态处理业务逻辑。 |
payTime | 支付完成时间戳。 | |
sign | 回调数据的签名。由 PayerMax 使用其私钥生成。商户必须使用从 PayerMax 获取的支付公钥对这个签名进行验签,以确保通知来源真实、数据未被篡改。 | 安全核心步骤。 |
signType | 签名算法类型。 |
以下是对接收到的回调通知进行验签和处理的简化示例:
import javax.servlet.http.HttpServletRequest;
import java.util.*;
public class PayerMaxNotifyController {
// PayerMax提供的支付公钥,用于验签
private static final String PAYERMAX_PUBLIC_KEY = "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...";
public String handleNotify(HttpServletRequest request) {
// 1. 获取所有回调参数
Map<String, String> params = new HashMap<>();
Enumeration<String> paramNames = request.getParameterNames();
while (paramNames.hasMoreElements()) {
String paramName = paramNames.nextElement();
params.put(paramName, request.getParameter(paramName));
}
// 2. 获取回调签名和待验签数据
String receivedSign = params.get("sign");
params.remove("sign"); // 从待验签参数中移除sign本身
// 构建待验签字符串,规则与下单请求验签类似(排序、拼接)
String signString = buildSortedKeyValueString(params);
// 3. 使用PayerMax公钥验证签名
boolean isSignatureValid = verifyRSASign(signString, receivedSign, PAYERMAX_PUBLIC_KEY);
if (!isSignatureValid) {
return "FAIL"; // 签名无效,直接返回失败
}
// 4. 签名验证通过,处理业务逻辑
String orderNo = params.get("orderNo");
String status = params.get("status");
String pmOrderNo = params.get("pmOrderNo");
if ("SUCCESS".equals(status)) {
// TODO: 更新商户数据库订单状态为支付成功,并执行发货等后续业务
System.out.println("订单 " + orderNo + " 支付成功,PayerMax订单号:" + pmOrderNo);
} else {
// TODO: 处理支付失败或 pending 状态
System.out.println("订单 " + orderNo + " 支付状态为:" + status);
}
// 5. 处理完成后,必须返回成功的响应(如 "SUCCESS"),否则PayerMax会重复通知
return "SUCCESS";
}
private boolean verifyRSASign(String data, String sign, String publicKey) throws Exception {
// 示例:实际需使用Signature类进行验签
// Signature signature = Signature.getInstance("SHA256WithRSA");
// signature.initVerify(loadPublicKey(publicKey));
// signature.update(data.getBytes(StandardCharsets.UTF_8));
// return signature.verify(Base64.getDecoder().decode(sign));
return true; // 假设验签成功
}
private String buildSortedKeyValueString(Map<String, String> params) {
// 与下单时构建签名字符串的逻辑一致,按key排序后拼接
Map<String, String> sortedParams = new TreeMap<>(params);
// ... 拼接逻辑
return sortedParams.toString();
}
}
三、 核心参数要点总结

- 密钥对:对接前,商户需从 PayerMax 获取 RSA 密钥对。商户持有私钥用于对下发请求签名;PayerMax 持有公钥用于验签。同时,商户需配置 PayerMax 提供的支付公钥,用于验证回调通知的签名 。
country参数:此参数至关重要,它决定了 PayerMax 收银台向终端用户展示哪些本地化支付方式(如东南亚的各类电子钱包)。notifyUrl:这是服务器对服务器的通信,是保证支付状态可靠同步的核心机制,必须配置且能够公网访问、处理 POST 请求并正确返回响应。- 签名与验签:所有交互都必须包含签名 (
sign)。商户发起请求时使用自身私钥签名,PayerMax 使用商户公钥验签。PayerMax 发起回调时使用其私钥签名,商户使用 PayerMax 公钥验签。这是保障交易数据完整性、防止伪造请求的核心安全措施 。 paymentMethod:若商户希望用户使用特定支付方式(如只允许信用卡支付),则需传递此参数。若不传,用户可在收银台选择所有该国家支持的支付方式。