API Rule

Basic Specification

Rule	Specification
Transmission Method	To ensure transaction security, HTTPS is used for transmission
Submit Method	Submit using POST method
Data Format	Submit and return data are in JSON format, basic data { "result_code":"OK", "result_msg":"SUCCESS", "charge": { } }
Character Encoding	Unified use of UTF-8 character encoding
Signature Algorithm	SHA1WithRSA
Signature Requirements	Signature verification is required for both requesting and receiving data
Authorization Requirements	All API operations require authorization to use
Integration Logic	First judge the return of the protocol field, then judge the return of the business, and finally judge the transaction status

Header Specification

• Request Content-Type: content-type

  • set the Header value to JSON format.
  • Example: application/json; charset=UTF-8

• Request Accept: accept

  • set the Header value to JSON format.
  • Example: application/json; charset=UTF-8

• Request URL address: x-ca-resturl

  • Set the Header value to the URL address of the unified delivery or order query request.
  • Example: https://pay.xxx.io/pay/unifiedorder or https://pay.xxx.io/pay/orderquery

• Request timestamp: x-ca-timestamp

  • Set the Header value to the millisecond or higher precision timestamp (millisecond/microsecond/nanosecond) of the current request.
  • Example: millisecond timestamp 1586007620038

• Request random number: x-ca-noncestr

  • Set the Header value to a 32-bit system random number to prevent repeated requests.
  • Example: MD5 (system random number)

• Request authorization KEY: x-ca-auth

  • Set the Header value to the key obtained by the merchant applying for the API interface.
  • Example: 772ae1d32322f49508307b2f31a0107f

• Request signature: x-ca-signature

  • Set the Header value to a signature calculated using the SHA1WithRSA signature algorithm, and the signature will be verified by the server.
  • For specific algorithm rules, please refer to Signature Algorithm

Signature Algorithm

• Step 1: the merchant system API interface will assign the key and the payment platform data public key platform_pubKey , and use the Alipay RSA signature verification tool generate the merchant data by itself RSA key pair (private key priKey and public key pubKey , note: non-JAVA applies to 2048 pkcs1s):

  • key: the key corresponding to the merchant system API
  • priKey: the RSA private key that signs the merchant system request data
  • pubKey: the RSA public key that the payment platform verifies the merchant system request data
  • platform_pubKey: the merchant system to the payment platform Returns the RSA public key for data verification

• Step 2: spell the string to be signed , the rules are as follows:

string = URI in UTF8 format +
newline character\n + URI query parameter in UTF8 format +
newline character\n + x-ca-noncestr Header value in UTF8 format +
newline character\n + x-ca-timestamp Header value in UTF8 format +
newline character\n + POST request JSON data in UTF8 format

Example:

string = /pay/unifiedorder
  
C8E1D385785625AFD64A484B58F91882
1.58600995149E+12
{"out_trade_no":"202007040118131586193493","subject":"demo","body":"demo","amount":"1.66","currency":"INR","channel":"inpay_bankupi","extparam":[],"mchid":"100000","return_url":"https://pay.xxx.io/demo.html","notify_url":"https://pay.xxx.io/demo/demonotify","client_ip":"127.0.0.1"}

Tips

• A blank line means that the URI query parameter of the request is empty

• Step 3: use the SHA1WithRSA signature algorithm to calculate the x-ca-signature signature, as follows:

  • Perform Base64 operation on the signature string to obtain the sign value
  • Read the merchant private key priKey and convert it to the openssl key private key
  • Pass the sign value and private key into the SHA1WithRSA signature algorithm to calculate the signature
  • Perform Base64 operation on signature to get x-ca-signature value

• Step 4: After the payment platform receives the request from the merchant system, it will verify the request data. If the verification fails, the result of failure is returned; if the verification passes, the corresponding payment business logic is executed and the corresponding result is returned. The payment platform performs the SHA1WithRSA signature algorithm on the returned results. Examples of the returned results and Header are as follows:

Body:

{
	"result_code": "OK",
	"result_msg": "SUCCESS",
	"charge": {
		"channel": "inpay_payout",
		"out_trade_no": "05Apr2021084746550",
		"client_ip": "127.0.0.1",
		"amount": "100",
		"currency": "INR",
		"subject": "inpay_payout",
		"body": "inpay_payout",
		"extparam": {
			"accountname": "kumar hamad",
			"bankaccount": "6228480415647314871",
			"bankname": "HDFC"
		},
		"credential": {
			"out_trade_no": "D20210405084748405109",
			"merchant_wallet": {
				"id": "44",
				"uid": "100003",
				"paytype": "0",
				"currency": "INR",
				"limit_credits": "0.000",
				"security_deposit_credits": "0.000",
				"unsettled_credits": "39128.819",
				"hold_credits": "0.000",
				"commission_credits": "144498.771",
				"available_credits": "25386.424",
				"status": "1",
				"create_time": "1541787044",
				"update_time": "1542617892"
			}
		}
	}
}

Header:

x-ca-timestamp: 1617583668305 
x-ca-noncestr: 963613FA553D6405C6E0D345BA32B6DB 
x-ca-signature: f+boCXBdpfZItp4TykM7BB03qGTZ9Yf6eBZD8D6mPQQsn0yTYAjy+46UJnhfChQ4z1CjfcW4AbHxZNT8cc5wxErLTt7rLYPD0T6RfOiyDY1AFTgFvY2P5pUi3WtHxqgpvkOrM6XT0PGts4Pzi1yBAMwzVZ4q6fSbitlvR36sk\/MCV1RKVbHlVzeCGMQ38dg3Frny9kBEYhgqzqHPZteiTt5sOuokN8eHqLEqImsS4xlosDD9Mgb3BckegQIdIBoRezqn+JrM8glU2iEq5VxAuhZBkqNT76BHdUA8KbO5yOqRRbqpOQf7iTGRqBgNHtuwZg+HbQcff\/t\/fxx\/COdD1w==

• Step 5: After the merchant system receives the returned result, in order to ensure payment security, it is strongly recommended that the merchant verify the returned data before proceeding with corresponding business processing. The signature verification algorithm is as follows:

Spell the string to be checked and signed , the rules are as follows:

string = x-ca-noncestr Header value in UTF8 format +
newline character \n + x-ca-timestamp Header value in UTF8 format +
newline character \n + the full JSON data of the returned result in UTF8 format

Then perform Base64 operation on the string to be verified to obtain the verify value, and input the returned Header x-ca-signature value, verify value , the platform data public key platform_pubKey. These three parameters implement the SHA1WithRSA signature verification algorithm.