Access Guide#
Preparation instructions for connection#
Application path for public and private keys#
Account Management -> API Key Management -> NewDuring the official launch phase, we strongly recommend that you bind the server IP address. An APIKey without a bound IP address can only be used for 15 days, and the APIKey will become effective again after modifying and binding the server IP address.
System PublicKey#
03029c655932f22aee81034d109795fbd7e23ca173ca27e195091d434e593a2e0fPublic and Private Key & System Public Key Usage Instructions#
Request domain#
https://payment.tarspay.comRequest structure#
By sending an HTTP POST request to the server address of the Tarspay API and adding the corresponding request parameters in the HTTP body and header according to the request structure, the Tarspay system responds with the returned parameters based on the request parameters.Communication Protocol#
For higher security, the Tarspay API interface only supports request communication through the HTTPS channel. When calling the Tarspay system API, the following security requirements must be followed:All requests must be made using 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 Tarspay system using signature verification to ensure the integrity and security of the communication information, see (signature mechanism).Character encoding#
The request and return results are both encoded using the UTF-8 character set.Request parameters and return parameters are both in JSON format.Content-Type: application/json;charset=utf-8Return parameter#
{
"code":0,
"msg":"SUCCESS",
"data":{
...
}
}
| ｜field | type | description |
|---|
| code | integer | 0 success, others is failed |
| data | object | Description of the return value of business calls, please refer to the data value of each interface in the business interface. |
| msg | string | Response message |
Notification mechanism#
Tarspay will send the consumer payment result message to the merchant-provided notifyUrl via the server side, carrying relevant parameters, and submit it in POST form. Merchants need to verify the signature of the result information to prevent forged notification messages; and they must judge the order status in the returned result to determine the order status.After receiving the request, the merchant's server must return an HTTP response of 200 and print the OK string. If the character feedback from the merchant to Tarspay is not the OK character, the Tarspay server will continuously resend the notification.In some cases, a single order of the merchant may receive multiple notifications from Tarspay. Merchants need to check their own logic and be able to handle unique business processing for possible duplicate success or failure status order notifications.Signature Mechanism#
Merchants, when calling the Tarspay API interface, need to obtain the corresponding signature string by following the agreed-upon format of Tarspay for the request method, request path, request timestamp, and business parameters, and pass it as the request header parameter X-API-SIGNATURE to Tarspay.The data prepared before signing is as follows:
HTTP_METHOD + "|" + HTTP_REQUEST_PATH + "|" + TIMESTAMP + "|" + PARAMSAfter the connection is completed, perform an ECDSA signature on the data, and then encode the signed bytes in Hex format.HTTP_METHOD：#
HTTP_REQUEST_PATH：#
For example, create a pay in order interface:
https://payment.tarspay.com/api/pay/unifiedOrder The request path is /api/pay/unifiedOrderTIMESTAMP：#
UNIX EPOCH timestamp (accurate to milliseconds) when accessing the APIPARAMS：#
Firstly, sort the key alphabetically, then perform URL parameterization, i.e., password=password, username=username. Since 'p' comes before 'u' in alphabetical order, password should be placed before username, and then connected using '&', i.e., password=password&username=username. The request parameters are the same for both POST and GET, and all parameters need to be extracted. The signature rule is as follows: All request keys are sorted alphabetically, then concatenated in the form of key=value (the value does not require urlencode), and connected using '&'.Note: Business fields are not fixed and immutable. All business fields participate in the signature, and it is recommended to handle them dynamically to cope with possible additions or deletions of fields.
Complete example#
For the following request:| HTTP_METHOD | HTTP_REQUEST_PATH | TIMESTAMP |
|---|
| POST | /api/v1/test | 1537498830736 |
| Parameter | value |
|---|
| amount | 100 |
| price | 100 |
The preparation data before signing is as follows:1.
Set all sent or received data as the set M, sort the parameters with non-empty parameter values within the set M according to the ASCII code of the parameter names in ascending order (dictionary order), and concatenate them into a string in the format of URL key-value pairs (i.e., key1=value1&key2=value2…).
Hint: content does not require URL encoding
2、Concatenate the string content with the method request information MERTHOD, URL, and NONCE, separated by "|", to form a new string:3、Use the private key (PrivateKey) generated by you to perform an ECDSA signature on the concatenated data, and then encode the binary result in Hex format, which generates the final signature used for verification with the API server.Place the API key, nonce, and the signature generated on the right into the Header according to the names above, and the signature verification can be passed.The Tarspay verification public key can be obtained on the "Web Management Interface - Account Management - apikey" page.
java#
Maven Dependency#
<dependency>
<groupId>org.bouncycastle</groupId>
<artifactId>bcprov-jdk15on</artifactId>
<version>1.64</version>
<scope>compile</scope>
</dependency>
Utils#
php demo#
Modified at 2025-04-24 12:08:29
