General Access Guide

This guide applies to all countries. The request domain differs by country — see the "Access Guide" under the corresponding country directory.

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

Please obtain it in the merchant portal under "Account Management → API Key Management". The value shown there is authoritative.

Public and Private Key & System Public Key Usage Instructions

Request domain

The request domain differs by country. See the "Access Guide" under the corresponding country directory.

API list

Business	Path
Create deposit order	`/api/pay/unifiedOrder`
Query deposit order	`/api/payInInfo`
Create withdrawal order	`/api/payOut/unifiedOrder`
Query withdrawal order	`/api/payOutInfo`
Query merchant balance	`/api/balanceInfo`

Some countries have additional APIs (e.g. UTR / trxId query, order supplement); see the corresponding country directory.

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.

⚠️ After receiving a callback, you must verify the signature and then actively query the order, and credit only based on the query result. For the security requirements, signature verification and sample code, see "Callback notification interface (customized by the merchant)" under the corresponding country directory.

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.

Every request must carry the following headers:

Header	Required	Description
`X-API-KEY`	Yes	API Key (public key) generated in the merchant portal
`X-API-NONCE`	Yes	The TIMESTAMP below: 13-digit millisecond timestamp, must be within 5 minutes of server time; the same signed request cannot be submitted twice (replays are rejected)
`X-API-SIGNATURE`	Yes	Signature generated according to the rules below

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:
{request domain}/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

Callback signature verification

For callback security requirements, signature verification and sample code, see "Callback notification interface (customized by the merchant)" under the corresponding country directory.

General 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#

API list#

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#

Callback signature verification#