Skip to main content

Order Query API Introduction​

Used to query the latest status of payment orders and marketing orders.

Request Processing​

All API requests must use HTTPS, and the HTTP Method is always POST.

The interface uses JSON as the data exchange format for the message body. The request must set the following HTTP headers:

Content-Type: application/json
Accept: application/json

Integration Resources​

Error Handling​

MidasBuy uses HTTP status codes to represent the result of request processing.

  • Successfully processed requests will return 200
  • For failed request processing, such as missing necessary input parameters or insufficient balance during payment, a 4xx range error code will be returned
  • If a service system error occurs on the Midas side during request processing, a status code of 500/501/503 will be returned. This situation is rare.

Error Codes and Error Messages​

When request processing fails, in addition to the HTTP status code indicating the error, the API will return an error response in the message body explaining the specific error reason.

  • name: Unique error code, required.
  • message: Used to describe the response, optional.
  • links: May return document addresses for solving the problem when a failure occurs, optional.
  • details: Used to provide more detailed information, such as retry details, quota errors, channel errors, etc.; optional.
  • causes: Solutions to this exception; optional.
  • debug_id: Identifier for the current request, used to represent a Midas request. Can be included when reporting issues, optional.

Error code example:

{
    "name": "INVALID_ARGUMENT",
    "message": "invalid CreateOrderRequest.ApplicationContext: embedded message failed validation | caused by: invalid ApplicationContext.RegionCode: value does not match regex pattern \"^[A-Z]{2}$\"",
    "details": [
        {
            "@type": "type.apis.com/rpc.BadRequest.FieldViolation",
            "field": "ApplicationContext",
            "description": "embedded message failed validation",
            "value": ""
        }
    ],
    "links": [],
    "debug_id": "247df6a6ed3ab364",
    "causes": []
}

Signature Method​

Constructing the Signature String​

The signature string consists of five lines, each line being a parameter. Each line ends with \n (newline character, ASCII encoding value 0x0A), including the last line. If the parameter itself ends with \n, an additional \n should be appended.

HTTP request method\n
URL\n
Request timestamp\n
Request random string\n
Request message body\n

Step 1: Get the HTTP request method (requests are uniformly POST)

POST

Step 2: Get the absolute URL of the request, remove the domain part to obtain the URL participating in the signature. If there are query parameters in the request, the URL should end with '?' and the corresponding query string.

/midasbuy/v2/orders

Step 3: Get the current system timestamp when initiating the request, which is the total number of seconds from Greenwich Mean Time January 1, 1970, 00:00:00 (Beijing time January 1, 1970, 08:00:00) to now, as the request timestamp. MidasPay will refuse to process requests initiated more than 24 hours ago, so merchants should keep their system time accurate.

$ date +%s
1725519185

Step 4: Generate a request random string. Here, use the command line to generate one directly.

$ hexdump -n 16 -e '4/4 "%08X" 1 "\n"' /dev/random
593BEC0C930BF1AFEB40B4A08C8FB242

Step 5: Get the request message body from the request.

  • When the request method is POST, use the actual JSON payload sent.

For the certificate download interface, the request message body is an empty string.

Step 6: According to the aforementioned rules, the constructed request signature string is:

POST
/midasbuy/v2/orders
1554208460
593BEC0C930BF1AFEB40B4A08C8FB242
${body}

${body} is a placeholder for the request message body, please fill in the actual message body.

Calculating the Signature Value​

Most programming languages provide signature functions that support signing signature data. It is strongly recommended that merchants call such functions, use the merchant's private key to perform SHA256 with RSA signature on the string to be signed, and Base64 encode the signature result to obtain the signature value. Here's a command-line demonstration of how to generate a signature.

$ echo -n -e \
"POST\n/midasbuy/v2/orders\n1725519185\n593BEC0C930BF1AFEB40B4A08C8FB242\n$\{body\}\n" \
| openssl dgst -sha256 -sign apiclient_key.pem \
| openssl base64 -A
uOVRnA4qG/MNnYzdQxJanN+zU+lTgIcnU9BxGw5dKjK+VdEUz2FeIoC+D5sB/LN+nGzX3hfZg6r5wT1pl2ZobmIc6p0ldN7J6yDgUzbX8Uk3sD4a4eZVPTBvqNDoUqcYMlZ9uuDdCvNv4TM3c1WzsXUrExwVkI1XO5jCNbgDJ25nkT/c1gIFvqoogl7MdSFGc4W4xZsqCItnqbypR3RuGIlR9h9vlRsy7zJR9PBI83X8alLDIfR1ukt1P7tMnmogZ0cuDY8cZsd8ZlCgLadmvej58SLsIkVxFJ8XyUgx9FmutKSYTmYtWBZ0+tNvfGmbXU7cob8H/4nLBiCwIUFluw==

Setting HTTP Headers​

Midas requires merchants to pass signatures through the HTTP Authorization header. Authorization consists of two parts: authentication type and signature information.

Authorization: Authentication Type Signature Information

The specific composition is:：

  1. Authentication type, currently TXGW-SHA256-RSA2048

  2. The signature needs to include the following content

    1. Application ID initiating the signature information request: 'auth_id', the Midas application ID registered by the merchant (len<=64)
    2. Authentication identifier type: 'auth_id_type', default is APP_ID (len<=32)
    3. Merchant API certificate serial number: 'serial_no', used to declare the certificate being used, default is 1 (len<=64)
    4. Request random string: 'nonce_str', can only use uppercase English characters, lowercase English characters, numbers (len=32)
    5. Timestamp: 'timestamp'
    6. Signature value: 'signature'

    Note: There is no order requirement for the above six signature information items.

An example of the Authorization header is as follows: (Note that the example may contain line breaks due to formatting, the actual data should be in one line)

Authorization: TXGW-SHA256-RSA2048 auth_id=145000000,auth_id_type=APP_ID,nonce_str=593BEC0C930BF1AFEB40B4A08C8FB242,signature=uOVRnA4qG/MNnYzdQxJanN+zU+lTgIcnU9BxGw5dKjK+VdEUz2FeIoC+D5sB/LN+nGzX3hfZg6r5wT1pl2ZobmIc6p0ldN7J6yDgUzbX8Uk3sD4a4eZVPTBvqNDoUqcYMlZ9uuDdCvNv4TM3c1WzsXUrExwVkI1XO5jCNbgDJ25nkT/c1gIFvqoogl7MdSFGc4W4xZsqCItnqbypR3RuGIlR9h9vlRsy7zJR9PBI83X8alLDIfR1ukt1P7tMnmogZ0cuDY8cZsd8ZlCgLadmvej58SLsIkVxFJ8XyUgx9FmutKSYTmYtWBZ0+tNvfGmbXU7cob8H/4nLBiCwIUFluw==,timestamp=1725519185,serial_no=1

Finally, you can compose an HTTP request that includes the signature.

$ curl https://${host}/midasbuy/v2/orders -H 'Content-Type: application/json' -H 'Authorization: TXGW-SHA256-RSA2048 auth_id=145000000,auth_id_type=APP_ID,nonce_str=593BEC0C930BF1AFEB40B4A08C8FB242,signature=uOVRnA4qG/MNnYzdQxJanN+zU+lTgIcnU9BxGw5dKjK+VdEUz2FeIoC+D5sB/LN+nGzX3hfZg6r5wT1pl2ZobmIc6p0ldN7J6yDgUzbX8Uk3sD4a4eZVPTBvqNDoUqcYMlZ9uuDdCvNv4TM3c1WzsXUrExwVkI1XO5jCNbgDJ25nkT/c1gIFvqoogl7MdSFGc4W4xZsqCItnqbypR3RuGIlR9h9vlRsy7zJR9PBI83X8alLDIfR1ukt1P7tMnmogZ0cuDY8cZsd8ZlCgLadmvej58SLsIkVxFJ8XyUgx9FmutKSYTmYtWBZ0+tNvfGmbXU7cob8H/4nLBiCwIUFluw==,timestamp=1725519185,serial_no=1'