Access Guide

Preparation instructions for connection

Application path for public and private keys

Account Management -> API Key Management -> New

During 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

03029c655932f22aee81034d109795fbd7e23ca173ca27e195091d434e593a2e0f

Public and Private Key & System Public Key Usage Instructions

Request domain

https://payment.tarspay.com

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

Parameter format

Request parameters and return parameters are both in JSON format.

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

Return 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：

POST

HTTP_REQUEST_PATH：

For example, create a pay in order interface:
https://payment.tarspay.com/api/pay/unifiedOrder The request path is /api/pay/unifiedOrder

TIMESTAMP：

UNIX EPOCH timestamp (accurate to milliseconds) when accessing the API

PARAMS：

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

PARAMS

Parameter	value
amount	100
price	100

The preparation data before signing is as follows:

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.

Signature Tool Reference

java

Maven Dependency

<dependency>
  <groupId>org.bouncycastle</groupId>
  <artifactId>bcprov-jdk15on</artifactId>
  <version>1.64</version>
  <scope>compile</scope>
</dependency>

Signature Tool Class

Utils

php demo

download php demo

Access Guide

Access Guide#

Preparation instructions for connection#

Application path for public and private keys#

System PublicKey#

Public and Private Key & System Public Key Usage Instructions#

Request domain#

Request structure#

Communication Protocol#

Character encoding#

Parameter format#

Return parameter#

Notification mechanism#

Signature Mechanism#

HTTP_METHOD：#

HTTP_REQUEST_PATH：#

TIMESTAMP：#

PARAMS：#

Complete example#

Signature Tool Reference#

java#

Maven Dependency#

Signature Tool Class#

Utils#

php demo#

Access Guide

Preparation instructions for connection

Application path for public and private keys

System PublicKey

Public and Private Key & System Public Key Usage Instructions

Request domain

Request structure

Communication Protocol

Character encoding

Parameter format

Return parameter

Notification mechanism

Signature Mechanism

HTTP_METHOD：

HTTP_REQUEST_PATH：

TIMESTAMP：

PARAMS：

Complete example

Signature Tool Reference

java

Maven Dependency

Signature Tool Class

Utils

php demo