跳到主要内容

如何对接

1. 申请接入​

联系我们的商务团队，获取商户账号和密钥。

2. 商户后台​

  • 测试环境：https://test-manage.magiccompasspay.com
  • 生产环境：https://manage.magiccompasspay.com

3. 接口地址​

  • 测试环境：https://test-gateway.mcconnects.com/mc-payment/
  • 生产环境：https://gateway.mcconnects.com/mc-payment/

4. 约定&规范​

  • 请求方式: POST

  • 请求参数: JSON格式

  • 编码格式: UTF-8

  • 请求报文结构: 接口会处理请求了两种内容:Header（公有参数,存在在HTTP headers属性中）、Body（私有参数,存放在HTTP Body属性中）

  • 元素出现要求:

    符号说明
    R报文中该元素必须出现（Required）
    O报文中该元素可选出现（Optional）
    C报文中该元素在一定条件下出现（Conditional）

  • 公共参数:

公共参数（Header）是用于标识产品及接口鉴权的参数，每次请求的headers属性中均需要携带这些参数：

参数名称类型出现要求描述
X-TimestamplongR当前UNIX时间戳（毫秒级）
X-Access-KeystringR在平台创建完商户后生成的Access-Key
X-SignaturestringR签名
X-RequestURIstringO请求接口的requestURI (和参与签名计算的要保持一致)
// 设置请求头参数
connection.setRequestProperty("X-Signature","adfasdfasdfasdfasdfasdf");
connection.setRequestProperty("X-Access-Key","12345");
connection.setRequestProperty("X-Timestamp","1649247752");
connection.setRequestProperty("Content-Type","application/json");
  • 响应报文结构:

所有接口响应均采用JSON格式，如无特殊说明，每次请求的返回值中，都包含下列字段：

参数名称类型出现要求描述
codeintR响应码，代码定义请见“附录A 响应码说明”
msgstringR响应描述
dataobjectR每个接口特有的参数，详见每个接口定义

示例

{
    "code":200,
    "msg":"调用成功",
    "data":{
        "Channel":"A10086",
        "Type":7004
    }
}

5. 签名算法及验签​

本服务接口验证使用的是AK/SK（Access Key/Secret Key）机制，具体流程如下：

  1. 获取请求的HTTP headers属性中的X-Timestamp、X-Access-Key、X-Signature参数值；
  2. 三个参数如果未传值，则校验不通过；
  3. X-Timestamp 与当前事件比较，如果时间差大于5分钟，则校验不通过；
  4. 将X-Timestamp、X-Access-Key、请求requestURI 拼接成字符串，并使用secretKey作为密钥进行HMAC-SHA512签名，将结果与X-Signature比较相等则校验通过；

签名算法Java版本：

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;

public class AKSKUtil {

    public static final String HMAC_SHA_512 = "HmacSHA512";

    public static String calculateHMAC(String data, String secretKey) {
        try {
            SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), HMAC_SHA_512);
            Mac mac = Mac.getInstance(HMAC_SHA_512);
            mac.init(secretKeySpec);
            byte[] rawHmac = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));
            return Base64.getEncoder().encodeToString(rawHmac);
        } catch (NoSuchAlgorithmException | InvalidKeyException e) {
            throw new RuntimeException("Failed to calculate HMAC: " + e.getMessage(), e);
        }
    }
}

例子： 请求资产列表查询接口

String requestURI = "/external/api/v1/deposit/request";
String accessKey = "123456"; // 获取请求的HTTP headers属性中的X-Access-Key参数值 申请商户后会生成，测试对接时可用由MCPayment给出
String timestamp = "1649247752"; // 当前毫秒时间戳
String secretKey = "abc";//   申请商户后会生成,请妥善保存不要泄露，泄露有伪造请求风险，测试对接时可用由MCPayment给出
String signature = AKSKUtil.calculateHMAC(accessKey+timestamp+requestURI, secretKey);

// 设置请求头参数
connection.setRequestProperty("X-Signature",signature);
connection.setRequestProperty("X-Access-Key",accessKey);
connection.setRequestProperty("X-Timestamp",timestamp);
connection.setRequestProperty("X-RequestURI",requestURI);

附录A 响应码说明​

响应码描述
200调用成功
303参数错误
500错误