Signature Algorithm

Please take two minutes to read the interface call instructions and conventions to avoid unnecessary trouble during integration.

• You will need to use the API key for integration, which you can obtain from the merchant backend
• For the domain part of the interface path prefix, please contact customer service

Call Style

Interfaces with POST requests only accept JSON data. Please set content-type to application/json in the HTTP request header. The current interface only returns data in JSON format.

Parameter Classification

Parameters have different names depending on their location when calling. For example, the following URL:

http://api.demo.com/[path_param]?query_param=1

Among them:

• [path_param] is called a Path parameter
• query_param is called a Query parameter
• When the request is POST, parameters passed through the Body are called Body parameters

Fixed Parameters

The following fixed parameters must be provided when calling the interface. These parameters must be included in every call:

• nonce: Random string, up to 32 characters
• timestamp: 10-digit UNIX timestamp
• sign: Parameter signature

Request Response

The response structure after calling the interface is as follows:

{
  "code": 200,
  "payload": {
    "id": "E123456789A",
    "orderUrl": "",
    "channel": "alipay",
    "others": "..."
  }
}

You can determine whether the interface call was successful based on the code status code. When successful, code is 200; when failed, code is 200. When failed, the HTTP response body will provide a message field indicating the reason for the error.

Request Failure Example

If the parameter signature provided when placing an order is incorrect, the following content will be returned:

{
  "code": 400,
  "errors": {
    "message": "Signature verification failed"
  }
}

Currently, only one error code is returned: 400.

Request Success Example

When the order is placed successfully, the following content will be returned:

{
  "code": 200,
  "payload": {
    "id": "E5df79e7fec2cef205f62d520",
    "trans_id": "TeOfB7HwJRsSiCyd5",
    "amount": "200.00",
    "channel": "alipay",
    "status": 0,
    "url": "http://cashier.demo.com/cashier/order?id=E5df79e7fec2cef205f62d520"
  }
}

Signature Algorithm

Before calling the interface, you need to sign the interface parameters. The interface supports two signature algorithms: MD5 and RSA. The default signature algorithm is MD5. If you need to use RSA signature, set alg to rsa. Note that parameters may be added, so be sure to sign all parameters except sign.

MD5 Signature

• Let all sent or received data be set M. Sort the non-empty parameter values in set M by parameter name in ASCII order (dictionary order)
• Use URL key-value pair format, i.e., key1=value1&key2=value2..., to concatenate into a string. Note: Empty parameters are not included in the signature
• Place the API key at the beginning of the string from step 1, joined with "&"
• Use md5 to calculate the digest of the string from the previous step (case-insensitive), and pass this digest as the sign parameter to the interface

For example, when calling a POST interface, the parameters are as follows, and the API Token is assumed to be: xoJb3BS8j40OCuPc6kzE:

{
  "mch_id": "M3pZtGCTQg7rJeoLy",
  "trans_id": 20181230213948,
  "amount": "200.00",
  "channel": "alipay",
  "remarks": "memo",
  "nonce": "7886356ioiasdf",
  "timestamp": 1678132123,
  "callback_url": "http://hd3tcp.javawebdata9.com/api/recharge/onlinePayAsyncCallback/20200627132036809474",
  "ip": "47.244.122.36"
}

According to the algorithm described above, the concatenated result is as follows (note, if there are Path parameters, they should also be sorted and merged into the string, and empty parameters are not included in the signature):

xoJb3BS8j40OCuPc6kzE&amount=200.00&callback_url=http://hd3tcp.javawebdata9.com/api/recharge/onlinePayAsyncCallback/20200627132036809474&channel=alipay&ip=47.244.122.36&mch_id=M3pZtGCTQg7rJeoLy&nonce=7886356ioiasdf&remarks=memo&trans_id=20181230213948

The digest result calculated from the above string (case-insensitive):

3147c167da0392a2317542c18d0017e1

When calling the interface, the Body parameters passed are:

{
  "mch_id": "M3pZtGCTQg7rJeoLy",
  "trans_id": 20181230213948,
  "amount": "200.00",
  "channel": "alipay",
  "remarks": "memo",
  "nonce": "7886356ioiasdf",
  "timestamp": 1678132123,
  "callback_url": "http://hd3tcp.javawebdata9.com/api/recharge/onlinePayAsyncCallback/20200627132036809474",
  "ip": "47.244.122.36",
  "sign": "3147c167da0392a2317542c18d0017e1"
}

For PHP/JAVA implementation of parameter signature, see the integration examples on the left

RSA Signature

(Not completed)