对接 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商户订单号。 
pmOrderNoPayerMax 系统生成的唯一支付订单号。 
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需掌握的关键参数

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

参考来源