交易报文

报文格式

• 接口中格式描述为参数类型+最大长度，()中数值为最大长度，例如：String(32)最大长度不超过32位的字符串。

• 请参考SDK传入参数。

---

请求公共报文

请求头 Headers

域名	变量名	格式	限定要求	备注
版本号	version	String(32)	M	版本号:固定1.0.0
商户号	merchantNo	String(32)	M	平台分配商户号
请求唯一ID	requestId	String(32)	M	标识唯一请求ID
请求时间	requestTime	Long	M	请求时间格式(时间戳)
签名	sign	String	M	header中除sign外+body参数排序后的签名,签名方式详见 签名方式

请求体 Body

域名	变量名	格式	限定要求	备注
产品编码	productNo	String(32)	M	产品编码:详见各业务接口productNo值
接口数据	data	String	M	AES加密后的接口请求参数,加密方式详见 加密方式

---

响应公共报文

响应头 Headers

域名	变量名	格式	出现要求	备注
版本号	version	String(32)	R	版本号:固定1.0.0
商户号	merchantNo	String(32)	R	平台分配商户号
请求唯一ID	requestId	String(32)	R	标识唯一请求ID
请求时间	requestTime	Long	R	请求时间格式(时间戳)
签名	sign	String	C	header中除sign外+body参数排序后的签名,签名方式详见 签名方式
响应时间	responseTime	Long	M	响应时间格式(时间戳)

响应体 Body

域名	变量名	格式	出现要求	备注
产品编码	productNo	String(32)	M	产品编码:详见各业务接口productNo值
请求结果	success	boolean	M	请求结果(true：成功；false：失败)
交易码	code	String	M	交易码详见 响应码列表
交易描述信息	message	String	C
接口数据	data	String	C	AES加密后的接口响应参数,加密方式详见 加密方式

---

符号约定

	符号	含义
数据元数值符号	M	必须填写的域
	C	满足条件时必须填写的域
	O	自选填写的域
	R	必须与先前报文中对应域的值相同的域

---

加密方式

将请求的明文变成json串后进行AES加密，作为传输数据，秘钥需要在商户平台查看，注意请勿泄露。

AES加解密

class Demo{
    // 解密
    public static String decrypt(String sSrc, String sKey) throws Exception {
        // 判断Key是否正确
        if (sKey == null) {
            return null;
        }

        byte[] raw = sKey.getBytes("utf-8");
        SecretKeySpec skeySpec = new SecretKeySpec(raw, "AES");
        Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5Padding");
        cipher.init(Cipher.DECRYPT_MODE, skeySpec);
        // 先用base64解密
        byte[] encrypted1 = Base64.getDecoder().decode(sSrc);
        byte[] original = cipher.doFinal(encrypted1);
        String originalString = new String(original, "utf-8");
        return originalString;
    }

    //加密
    public static String encrypt(String sSrc, String sKey) throws Exception {
        if (sKey == null) {
            return null;
        }

        byte[] raw = sKey.getBytes("utf-8");
        SecretKeySpec skeySpec = new SecretKeySpec(raw, "AES");
        // "算法/模式/补码方式"
        Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5Padding");
        cipher.init(Cipher.ENCRYPT_MODE, skeySpec);
        byte[] encrypted = cipher.doFinal(sSrc.getBytes("utf-8"));
        // 此处使用BASE64做转码功能，同时能起到2次加密的作用。
        return Base64.getEncoder().encodeToString(encrypted);
    }
}

加密示例

下述为 查询交易状态 为例子加密进行加密：

aesKey: z/qyoYG7qdRpCN8w7lEX7A==

data明文参数

{
  "country": "MX",
  "orderProductNo": "TRANSFER",
  "merchantOrderNo": "MON_000000120250306103931798"
}

加密后data

aKIJJY4vg47A4UM7G/Ld4cD6ZuopG9iJCJ77jNn3xBCid0lVo1j7IMLS6npJUYFBAgQPhAOrtATIjUIAAc0GgAjxH4+qf7EK83rq3uKSq6v2+m

---

签名方式

平台采用的是 RSA2 非对称加密方式，即商户请求我们接口时使用商户私钥对请求参数进行签名，平台使用商户公钥进行验签； 平台对接口返回参数使用平台私钥进行签名，商户使用平台公钥进行验签。

• 接口中参数(请求公共报文中除sign外全部参数：headers+body除sign外全部参数)按照参数名ASCII码从⼩到⼤排序，然后以key1=value1&key2=value2的形式进行拼接作为待签名原始串。

• 值为null时，该参数需要拼接到待签名串中进行签名和验签。

• 请参考SDK中RSA2签名和验签。

签名示例

Headers:

version: 1.0.0
merchantNo: MER253617362573463554
requestId: 20250304150657143
requestTime: 1741072017143

Body:

{
  "productNo": "TRANSFER",
  "data": "xxxxxxxxxxxx"
}

待签名data串

data=xxxxxxxxxxx&merchantNo=MER253617362573463554&productNo=TRANSFER&requestId=20250304150657143&requestTime=1741072017143&version=1.0.0

注：上述拼接后的字符串按照参数名ASCII码从⼩到⼤排序进行RSA2签名后即为sign参数。