Api rule

The following specifies the rules for calling the API when a merchant accesses Trusty open platform：

Rule Description
Transfer Mode Use HTTPS for secure transactions
Submit Mode Use POST method
Data Format Data submitted and returned is in JSON format
Char Encoding Use UTF-8-character encoding
Signature Algorithm MD5 or HMACSHA256, Default as MD5
Signature Requirement Signature-checking is required for requesting and receiving data，The detail please reference the ''Security Specifications
Logic Judgment Determine protocol field, service field and transaction status.

Security Specifications

General steps to create a signature:

Step 1:

Presume all data sent and received is the set M. Sort non-empty values in M in ascending alphabetical order (i.e., lexicographical sequence), and join them into string A via the corresponding URL key-value format (e.g., key1=value1& key2=value2…).

Notes:

  • Sort parameter names in ascending alphabetical order based on their ASCII encoded names (e.g., lexicographical sequence);

  • Empty parameter values are excluded in the signature;

  • Parameter names are case-sensitive;

  • When checking returned data or a Trusty push notification signature, the transferred sign parameter is excluded in this signature as it is compared with the created signature;

  • The API interface may add fields, and the extended fields must be supported when verifying the signature.

Step 2:

Add "key= (API key value) to the end of stringA to get stringSignTemp, perform MD5 arithmetic on stringSignTemp, convert all result chars to upper case, thus get sign's value (signValue).

For the following transferred parameters:

 
{
  "body": "testbody",
  "appNo": "zav3pgg7rafzcxa0",
  "ddName": "testddd"
}
  • Sort ASCII code of parameter names by lexicographical sequence based on the format of "key=value": 
    
String stringA ="appNo=zav3pgg7rafzcxa0&body=testbody&ddName=testddd";

  • Join API Key

    Add "key= (API key value) to the end of stringA to get stringSignTemp, perform MD5 arithmetic on stringSignTemp, convert all result chars to upper case, thus get sign's value (signValue) 

    
//Note：The key is created by Trusty Open Platform for the merchant.
String stringSignTemp = stringA + "&key=192006250b4c09247ec02edce69f6a2d"
//Note:Signature Algorithm
//default:MD5
String sign = MD5(stringSignTemp).toUpperCase()="9A0A8659F005D6984697E2CA0A9CF3B7"
Or
//Note:HMAC-SHA256
String sign= HMACSHA256(stringSignTemp,key).toUpperCase()="6A9AE1657590FD6257D693A078E1C3E4BB6BA4DC30B23E0EE2496E54170DACD6"

Signature sample code

  /**
     * Create MD5
     *
     * @param data to be handle
     * @return MD5 result
     */
    public static String MD5(String data) throws Exception {
        java.security.MessageDigest md = MessageDigest.getInstance("MD5");
        byte[] array = md.digest(data.getBytes("UTF-8"));
        StringBuilder sb = new StringBuilder();
        for (byte item : array) {
            sb.append(Integer.toHexString((item & 0xFF) | 0x100).substring(1, 3));
        }
        return sb.toString().toUpperCase();
    }

    /**
     * Create HMACSHA256
     *
     * @param data data to be handle
     * @param key
     * @return HA256 Result
     * @throws Exception
     */
    public static String HMACSHA256(String data, String key) throws Exception {
        Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secret_key = new SecretKeySpec(key.getBytes("UTF-8"), "HmacSHA256");
        sha256_HMAC.init(secret_key);
        byte[] array = sha256_HMAC.doFinal(data.getBytes("UTF-8"));
        StringBuilder sb = new StringBuilder();
        for (byte item : array) {
            sb.append(Integer.toHexString((item & 0xFF) | 0x100).substring(1, 3));
        }
        return sb.toString().toUpperCase();
    }

Get the final data to be sent:


{
  "nonce_str": "VMBTKNGu0r8nxrtpY8auCrEJcTYYrD9V",
  "mchnt_id": "1000",
  "sign": "E7EB3EFFEF4DE0D2BC63E00E08516D74",
  "app_id": "zav3pgg7rafzcxa0",
  "body": "testbody",
  "appNo": "zav3pgg7rafzcxa0",
  "ddName": "testddd"
}

Random String Algorithm

nonce_str is included in Trusty payment API protocols to ensure unpredictability for signatures. We suggest calling the random() function to create a signature and convert its value into a string.