Quick Guide

Get an API Key

Before signing any request, you must get the API from sales.

Demo sysId:

sysId='202402271432298822660001'

Access mode

Use the HTTPS communication protocol and submit via POST method.

Data format

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).

Request Message

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.

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.

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.

Response Message

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.

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.

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.

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.

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.

Message encryption algorithm: AES/ECB/PKCS5Padding

Session key generation: KeyGenerator generation

Session key encryption algorithm: RSA/ECB/PKCS1Padding

Signature algorithm: SHA1withRSA

RSA key pair obtained：

Step 1: Generate the rsa private key, encoded in X509, and specify the number of digits of the generated key: 2048

openssl genrsa -out rsa_private_key_2048.pem 2048

Step 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 -nocrypt

Step 3: Export the rsa public key, encoded in X509

openssl rsa -in rsa_private_key_2048.pem -out rsa_public_key_2048.pem -pubout

Message encryption and signature：

Use KeyGenerator to generate a DES encryption session key (SK).

Use SK to encrypt the JSON plaintext (AES/ECB/PKCS5Padding), and convert the encrypted result to a HEX string to obtain the encrypt field.

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.

Message decryption and signature verification：

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.

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.

Verify the validity of the signature using the obtained signing string, the sender's public key, and the sign field data.

Request to sign string：

All fields are connected in the following order using the | symbol:

sysId|apiCode|version|requestNo|encrypt

sysId , apiCode, version , requestNo come from the corresponding fields in the request header.

encrypt comes from the encrypt field in the actual request body.

Response to sign string：

All fields are connected in the following order using the | symbol:

sysId , 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.

Public Request message header

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

Public response message header

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