Access Guidelines

Request HOST

https://api.simplypay.vip

Ours server IP

15.207.74.156

Request Structure

By sending a HTTP POST request to the server address of the SimplyPay API, and according to the request structure in the HTTP body to add the appropriate request parameters to complete, SimplyPay system according to the request parameters to respond to the return parameters.

Communication Protocol

For greater security, the SimplyPay API interface only supports request communication over the HTTPS channel. The following security requirements should be followed when calling the SimplyPay system API:
All requests must use SSL, otherwise the request will be rejected.
Only TLS 1.2 or TLS 1.1 is supported, SSLv3 and TLS 1.0 are not supported.
The merchant system communicates with the SimplyPay system using signature verification to ensure the integrity and security of the communication, see (Signature Mechanism).

Character encoding

Requests and returns are encoded using the UTF-8 character set.

Parameter Format

The request and return parameters are in JSON format.

Content-Type: application/json;charset=utf-8

Return Parameters

field	name	description
code	status code	http status code, the value of this field only indicates the status of the interface request, it does not indicate that there are no exceptions to the business parameters
msg	status description	Description of the result of the interface call
error	error message	exception message
data	business return value	Return value describing a business call, refer to the data value for each interface in the business interface

Notification mechanism

Notification is divided into two notification methods. Since synchronous callbacks may result in uncontrollable situations such as users simulating operations or users manually closing their browsers when synchronous notifications are not jumped, resulting in losses for merchants, we strongly recommend that merchants confirm the payment result of an order with asynchronous notification of the result.

Synchronized Callback

When the user pays successfully, or cancels the payment, SimplyPay will redirect the consumer's browser to the returnurl provided by the merchant with the relevant parameters.
The synchronized callback uses a get method of jumping, splicing the parameters accordingly, and will encode the value of each parameter with a URL encode of UTF-8, followed by the jump.

Asynchronous callback

SimplyPay will send the message of the consumer payment result to the notifyurl provided by the merchant via the server side with relevant parameters and submit it as post. The merchant needs to verify the signature of the result message to prevent forged notification messages; and must make a judgment on the order status in the returned result to determine the order status.

The merchant's server must respond to the request with http response 200 and a printout of either success or ok. If the merchant sends SimplyPay anything other than the 7 characters of success or the 2 characters of ok, the SimplyPay server will continue to retransmit the notification until it has been more than 24 hours and 47 minutes. Typically, 9 retransmissions are completed in less than 25 hours (the notification intervals are: 30s, 2m, 4m, 10m, 30m, 1h, 2h, 6h, 15h).
In some cases, a merchant may receive multiple notifications from SimplyPay for a single order. Merchants need to check their own logic to be able to perform unique business processes for order notifications that may receive duplicate success or failure status.

Signature Mechanism

When the merchant calls SimplyPay API interface, the merchant needs to get the business parameters in the request parameter, according to the form agreed by SimplyPay, and get the corresponding signature string, and pass it to SimplyPay as the request parameter sign.
When SimplyPay assembles the return parameters, it will also sign according to this rule and pass the signature value. Because different business interfaces may need to participate in the signature of different fields, please refer to the business interface, the specific description of each interface.
Get the signature string:
Request the business information in the parameter json, sorted by Unicode of key. Then splice the parameters in the form of key1=value1&key2=value2&key3=value3, and finally splice the merchant key or application key (for different interfaces, the key used for signing may not be the same, specific interfaces have instructions) to the end of the string, the key name is 'key', and the key value is the key value. The key value is the key value. Let's call the spliced string originStr for now.
The originStr is converted to a UTF-8 byte array, encoded using the sha256 algorithm, and then the encoded array is transcoded to a hexadecimal string.

When splicing strings, it will filter out the parameters of strings with empty key or value, such parameters are not involved in the string splicing before signature.
In the signature of the request and return parameters, when the extra field appears, the signature needs to convert the value of extra to a Map collection, sorted by the Unicode of the key. Then the parameters in the map are spliced into a new string as the value of extra in the form of key1=value1&key2=value2&key3=value3.
If other parameter values are objects, they will be converted to JSON strings before participating in the encryption.
Note: Business fields are not fixed, all business fields are involved in the signature, it is recommended to process dynamically to cope with possible field increase or decrease.

Request HOST#

Ours server IP#

Request Structure#

Communication Protocol#

Character encoding#

Parameter Format#

Return Parameters#

Notification mechanism#

Synchronized Callback#

Asynchronous callback#

Signature Mechanism#