How to connect

1. Apply for access

Contact our commercial team to obtain a merchant account number and key.

2. Merchant backend

• Test Service:https://test-manage.magiccompasspay.com
• Prod Service:https://manage.magiccompasspay.com

3. API Address

• Test Service:https://test-gateway.mcconnects.com/mc-payment/
• Prod Service:https://gateway.mcconnects.com/mc-payment/

4. Agreements & Norms

• Request method: POST

• Request parameters: JSON

• Encoding format: UTF-8

• Request message structure: The api will process two types of content in the request: Header (public parameters, stored in the HTTP headers attribute), Body (private parameters, stored in the HTTP headers attribute) Body attribute)

• Element appearance requirements:

  Symbol	Description
  R	This element must appear in the message (Required)
  O	This element is optional in the message (Optional)
  C	This element in the message appears under certain conditions (Conditional)

• Public parameters:

Public parameters (Header) are parameters used to identify products and interface authentication. These parameters need to be carried in the headers attribute of each request:

Parameter name	Type	Occurrence requirements	Description
X-Timestamp	long	R	Current UNIX timestamp (millisecond level)
X-Access-Key	string	R	Access-Key generated after creating a merchant on the platform
X-Signature	string	R	signature

// Set request header parameters
connection.setRequestProperty("X-Signature","adfasdfasdfasdfasdfasdf");
connection.

setRequestProperty("X-Access-Key","12345");
connection.

setRequestProperty("X-Timestamp","1649247752");
connection.

setRequestProperty("Content-Type","application/json");

• Response message structure:

All interface responses are in JSON format. Unless otherwise specified, the return value of each request contains the following fields:

Parameter name	Type	Occurrence requirements	Description
code	int	R	Response code, please see "Appendix A Response Code Description" for code definition
msg	string	R	response description
data	object	R	Parameters unique to each interface, see each interface definition for details

Example

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

5. Signature algorithm and signature verification

This service interface verification uses the AK/SK (Access Key/Secret Key) mechanism. The specific process is as follows:

1. Obtain the values of X-Timestamp, X-Access-Key, and X-Signature in the HTTP headers attribute of the request.
2. If the three parameters are not passed, the verification will not pass.
3. Compared with the current event, if the time difference between X-Timestamp is greater than 5 minutes, the verification will not pass.
4. Concatenate the X-Timestamp, X-Access-Key, and request URI into strings, and use the secretKey as the key to sign the HMAC-SHA512, and compare the result with the X-Signature to pass the verification.

Signature algorithm Java version:

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);
        }
    }
}

Example: API for querying the request asset list

String requestURI = "/external/api/v1/deposit/request";
String accessKey = "123456"; //  Get the value of the X-Access-Key parameter in the HTTP headers attribute of the request It will be generated after applying for a merchant, and can be used by MCPayment when testing the connection
String timestamp = "1649247752"; // The current millisecond timestamp
String secretKey = "abc";//   It will be generated after applying for a merchant, please keep it properly and do not leak it, there is a risk of forged requests for leakage, and it can be used by MCPayment when testing docking
String signature = AKSKUtil.calculateHMAC(accessKey + timestamp + requestURI, secretKey);

// Set the request header parameters
connection.

setRequestProperty("X-Signature",signature);
connection.

setRequestProperty("X-Access-Key",accessKey);
connection.

setRequestProperty("X-Timestamp",timestamp);
connection.

setRequestProperty("X-RequestURI",requestURI);

Appendix A Description of Response Codes

Response code	Description
200	Call succeeded
303	Parameter error
500	Error