Quick Guide
Get an API Key#
Before signing any request, you must get the API from sales.sysId='202402271432298822660001'Access mode#
Use the HTTPS communication protocol and submit via POST method.Use JSON as the common format for request and response messages, all encoded in UTF-8.Message required flag: Y (required option) N (optional option) C (conditionally required, required under specific conditions).1.
The request message consists of two parts: the request message header and the request message body. The request message header information is within the header (head) node, and the request message body information is within the body (body) node.
2.
The message header is the same for each transaction. Refer to the "Public Request Message Header" section for the standard on filling out the request message header.
3.
The message body varies according to the interface definition of each transaction. Refer to the "Business Interface" section for the definition of the request message body. The request message body needs to be assembled and parsed according to the interface definition of each transaction.
1.
The transaction response message consists of two parts: the response message header and the response message body. The response message header information is within the header (head) node, and the response message body information is within the body (body) node.
2.
The message header is the same for each transaction. Refer to the "Public Request Message Header" section for the standard on filling out the response message header.
3.
The message body varies according to the interface definition of each transaction. Refer to the "Transaction Interface" section for the definition of the response message body. The response message body needs to be assembled and parsed according to the interface definition of each transaction.
4.
For a successful transaction response message, the code in the message header is "SUCCESS" and the detail is "Success". At this point, the body node can be empty or not empty based on actual business needs.
5.
For an error transaction response message, the error code and error information are filled in the code (return code) and detail (return description) fields in the message header, and the body node is empty.
Encryption and signature mode#
To ensure data security, transaction message transmission requires encryption, signature, and verification.1.
Message encryption algorithm: AES/ECB/PKCS5Padding
2.
Session key generation: KeyGenerator generation
3.
Session key encryption algorithm: RSA/ECB/PKCS1Padding
4.
Signature algorithm: SHA1withRSA
openssl genrsa -out rsa_private_key_2048.pem 2048Step 2: Convert the rsa private key generated in the previous step into PKCS * # 8 * * encode *openssl pkcs8 -topk8 -in rsa_private_key_2048.pem -out pkcs8_rsa_private_key_2048.pem -nocryptStep 3: Export the rsa public key, encoded in X509openssl rsa -in rsa_private_key_2048.pem -out rsa_public_key_2048.pem -puboutMessage encryption and signature：1.
Use KeyGenerator to generate a DES encryption session key (SK).
2.
Use SK to encrypt the JSON plaintext (AES/ECB/PKCS5Padding), and convert the encrypted result to a HEX string to obtain the encrypt field.
3.
Use the receiver's public key to encrypt the session key SK (RSA/ECB/PKCS1Padding), and convert the result to a HEX string to obtain the keyEnc field. Use the sender's private key to sign the request string (UTF-8 encoding) with SHA1withRSA, and convert the signature result to a HEX string to obtain the sign field.
1.
Convert the keyEnc field to a binary byte array, and use the receiver's private key to decrypt the session key, obtaining the plaintext SK.
2.
Convert the encrypt field to a binary byte array, and use the session key SK obtained in the previous step to decrypt it, resulting in the plaintext JSON.
3.
Verify the validity of the signature using the obtained signing string, the sender's public key, and the sign field data.
| symbol:sysId|apiCode|version|requestNo|encryptsysId , apiCode, version , requestNo come from the corresponding fields in the request header.encrypt comes from the encrypt field in the actual request body.All fields are connected in the following order using the | symbol:sysId|apiCode|version|requestNo|code|detail|encryptsysId , apiCode , version , requestNo , code , detail come from the corresponding fields in the response header.encrypt comes from the encrypt field in the actual response body. When the message body (body) node is empty, encrypt is empty and does not participate in the connection of the string to be signed.| No | Field | Type | Required | Notes |
|---|
| 1 | sysId | String | Y | System ID, assigned by KazePay |
| 2 | apiCode | String | Y | The interface name |
| 3 | requestNo | String | Y | Request serial number to ensure unique |
| 4 | version | String | Y | Version number, fixed character: 1.0 |
| 5 | sign | String | Y | Request a message signature |
| 6 | keyEnc | String | Y | Session key ciphertext |
| No | Field | Type | Required | Notes |
|---|
| 1 | sysId | String | Y | Request the header to return the system ID identification |
| 2 | apiCode | String | Y | The request header returns the interface name unchanged. |
| 3 | requestNo | String | Y | The request header returns the request serial number unchanged. |
| 4 | version | String | Y | The request header returns the version number unchanged. |
| 5 | code | String | Y | return code |
| 6 | detail | String | Y | description |
| 7 | sign | String | Y | Response message signature |
| 8 | keyEnc | String | Y | session key cipher text |
Description of the response code#
| No | Code | Description | Notes |
|---|
| 1 | SUCCESS | success | |
| 2 | PROCESSING | in hand | |
| 3 | FAILURE | be defeated | For specific failure content, see the detail attribute. |
| 4 | INTERNAL_ERROR | internal error | |
| 5 | PARAM_FORMAT_ERROR | error in parameter format | |
| 6 | PARAMETER_ERROR | parameter error | |
| 7 | IDEMPOTENT_ERROR | idempotent error | |
| 8 | REQUEST_NO_NOT_UNIQUE | request number is duplicate | |
| 9 | UNAUTHORIZED | unauthorized | |
| 10 | UNAUTHENTICATED_ERROR | certification (signature) error | |
| 11 | INTERFACE_UNAUTHORIZED | the interface is not authorized | |
Server address#
For the testing environment: For the production environment:
Modified at 2024-07-22 07:37:00
