Interface Description

This article is intended for: technical architects, R&D engineers, and system operation and maintenance engineers who use the Tarspay merchant self-service system. Through this document, merchants can understand the technology connected to Tarspay, the products and businesses connected, the access process, access specifications and other information, so that merchants can successfully complete the access work.

Access flow chart

privateKey (private key): The merchant keeps it by himself and does not disclose it. The merchant uses this private key to sign the order information when placing an order on behalf of the merchant.

publicKey (public key): The merchant needs to upload the key to our platform (merchant backend-account management-apiKey menu), and when you call our interface, you need to include the request header X-API-KEY carries your public key, and we use this public key to verify that the message is signed by your private key.

System publicKey: We will inform you to use the transaction status verification. When we send the callback transaction status notification, we will carry the signature information X-RESP-SIGNATURE in the request header. You can use it. The system publicKey verification message is sent by us.

common problem

The interface returns error description "You have not bound or opened the API Key. Please verify whether the publicKey is consistent with the calling environment, and whether X-API-KEY has passed in the correct public key."

The interface returns the error description "sign error". Please verify whether the public and private keys are a pair and whether there is any problem with the signature algorithm. Currently, the Java version signature verification tool class is provided at the bottom of the document.

The interface returns the error description "MERCHANT_FEE_CONFIG_NOT_INIT", please contact our operation configuration

Signature algorithm

Tarspay uses [ECDSA signature tool class](#signature tool class) signature for verification. After you open an account in Tarspay, you can generate a public and private key pair locally, or you can generate your public and private key through the Tarspay Web management interface. If you have any questions, you can also contact our staff to assist you. You can enter your public key through the Tarspay web management interface. Please keep your private key properly and do not disclose it to anyone to avoid asset loss! Tarspay strongly recommends that you bind your IP address to the whitelist.

Tarspay's API requests, except for public APIs, need to carry API key and signature

The data prepared before signing is as follows:

HTTP_METHOD + | + HTTP_REQUEST_PATH + | + TIMESTAMP + | + PARAMS

After the connection is completed, the data is ECDSA signed, and the signed bytes are Hex encoded.

HTTP_HOST

Prod: https://payment.tarspay.com

HTTP_METHOD

GET, POST need to be capitalized

HTTP_REQUEST_PATH

The PATH part of the request URL, for example: https://payment.tarspay.com/api/v1/test is /api/v1/test

NONCE

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

PARAMS

First sort the keys alphabetically, and then parameterize the url, that is, password=password username=username. Because p is sorted before u in the alphabet, password must be placed before username, and then use & to connect, that is: password =password&username=username The request parameters are the same for POST and GET. All parameters need to be taken out. The signature rules are as follows: All requested keys are sorted in alphabetical order, and then spliced in the form of key=value (the value does not require urlencode), and Use & to connect.

Complete example

For the following requests:

Method	URL	Nonce
POST	https://payment.tarspay.com/api/v1/test	1537498830736

parameter

Parameter	value
amount	100
price	100

The preparation data before signing is as follows:

Assume that all data sent or received is a set M, and the parameters with non-empty parameter values in the set M are sorted from small to large according to the ASCII code of the parameter name (lexicographic order), using the format of URL key-value pairs (i.e. key1=value1&key2 =value2...) concatenated into a string:

Tip: content does not require URLEncode

Splice the concatenated string content and method request information MERTHOD, URL and NONCE into a new string separated by "|":

Use the private key you generated (PrivateKey) to perform ECDSA signature on the spliced data, and Hex encode the binary result to generate the final signature for verification to the API server.

Put the Api key, nonce and signature generated on the right into the Header according to the above name, and you can pass the signature verification.

The Tarspay signature verification public key can be obtained from the "Web Management Interface - Account Management - apikey" page

Return description

Return results

Name	Type	Description
code	integer	Response code 0 indicates success, otherwise failure
data	object	response data
msg	string	Response message

Return to example

{
    "code": 0,
    "data": {},
    "msg": "SUCCESS"
}

Collection

POST collection and unified order placement

POST HTTP_HOST/api/pay/unifiedOrder

Body request parameters

{
  "amount": "100",
  "currency": "INR",
  "mchNo": "M1655535407",
  "mchOrderNo": "D1659318251029",
  "notifyUrl": "https://www.yourcompany.com/notify",
  "wayCode": "CASHIER"
}

Request parameters

Name	Location	Type	Required	Description
X-API-KEY	header	string	Y	public key
X-API-NONCE	header	string	Y	request time (timestamp, accurate to milliseconds)
X-API-SIGNATURE	header	string	Y	signature (refer to signature algorithm)
mchNo	body	string	Y	merchant number
mchOrderNo	body	string	Y	merchant order number (customized by merchant, cannot be repeated)
wayCode	body	string	Y	Payment method (fixed: UPI)
amount	body	string	Y	Amount (two decimal places. It cannot be zero and must meet the amount standard.)
currency	body	string	Y	currency(INR)
notifyUrl	body	string	Y	notification address

Return to example

{
  "code": 0,
  "data": {
    "amount": "130",
    "countryCode": "in",
    "currency": "INR",
    "customerContact": "9843734111",
    "expiredTime": 1659320053,
    "mchOrderNo": "D1659318251029",
    "orderState": 1,
    "payDataType": "payurl",
    "payOrderId": "P1553919495852986369",
    "payUrl": "https://payment.tarspay.com/tarspayToC/#/order/in/P1553919495852986369",
    "payWays": {
      "UPI": [{
        "countryCode": "in",
        "payWay": "UPI",
        "payWayLogo": "https://example.oss-ap-southeast-1.aliyuncs.com/tarspay_v_1.0/upi.svg",
        "payWayType": "UPI",
        "skipMode": 1
      }]
    }
  },
  "msg": "SUCCESS",
  "sign": "304402203e74cff204c473a6fac79522065af5d62e603f3c0218110e8e09951e7b6e1c050220281a39dc609b1e347d0eddc6b9c717a98907606156ff62b0b2b4d4ddec745d12"
}
"

Return results

Name	Type	Description
amount	string	bill amount
countryCode	string	country code
currency	string	currency number
customerContact	string	user contact information
mchOrderNo	string	merchant order number
orderState	integer	order status 0: order generated, 1: payment in progress, 2: payment successful, 3: payment failed, 6: timeout cancellation, 9: partial payment
payOrderId	string	payment order number
payUrl	string	Cashier address
payWays	array	payment methods

payment method:

Name	Type	Description
countryCode	string	country code
payWay	string	payment method code
payWayLogo	string	payment method logo
payWayType	string	payment method type

#Pay on behalf of

POST payment for unified order placement

POST HTTP_HOST/api/payOut/unifiedOrder

Body request parameters

{
  "address": "Mumbai",
  "amount": "40",
  "currency": "INR",
  "customerAccountNumber": "922010002523675",
  "customerContact": "9221113201",
  "customerEmail": "xxxx@gmail.com",
  "customerName": "xxxx",
  "mchNo": "80001",
  "mchOrderNo": "2022071201011",
  "notifyUrl": "http://www.yourcompany.com/notify",
  "wayCode": "UPI",
  "ifsc": "ABCD0123456",
  "bankName": "bank of maharashtra"
}

Request parameters

Name	Location	Type	Required	Description
X-API-KEY	header	string	Y	public key
X-API-NONCE	header	string	Y	request time (timestamp, accurate to milliseconds)
X-API-SIGNATURE	header	string	Y	signature (refer to signature algorithm)
mchNo	body	string	Y	merchant number
mchOrderNo	body	string	Y	merchant order number (customized by merchant, cannot be repeated)
wayCode	body	string	Y	Payment method (fixed: UPI)
amount	body	string	Y	amount (no decimals. It cannot be zero and must meet the amount standard.)
currency	body	string	Y	currency(INR)
notifyUrl	body	string	Y	notification address
customerName	body	string	Y	username
customerContact	body	string	Y	mobile phone number
customerAccountNumber	body	string	Y	user bank card
customerEmail	body	string	Y	User email
address	body	string	Y	User address (can be fixed)
ifsc	body	string	Y	ifsc
bankName	body	string	Y	Bank name (can be fixed)

{
  "code": 0,
  "data": {
    "mchOrderNo": "M1655535407",
    "payOrderId": "P1551409540398772225"
  },
  "msg": "SUCCESS",
  "sign": "3045022100c3998421fd646521777d0c736753704931f801331dec55f109258dd8a93083c402207c11e37d70477b30ad9e0c42072a3fb5af1a78809ca7f8023672451e62e8f69f"
}

Return results

Note: When the code return is not 0, the data returned is null.

Name	Type	Description
mchOrderNo	string	merchant order number (returned after successful request)
payOrderId	string	platform order number (returned after successful request)

Collection order inquiry

POST to obtain collection order information

POST HTTP_HOST/api/payInInfo

Body request parameters

{
  "mchNo": "M1655535407",
  "mchOrderNo": "A1547429458697129178"
}

Request parameters

Name	Location	Type	Required	Description
X-API-KEY	header	string	Y	public key
X-API-NONCE	header	string	Y	request time (timestamp, accurate to milliseconds)
X-API-SIGNATURE	header	string	Y	signature (refer to signature algorithm)
mchNo	body	string	Y	merchant number
payOrderId	body	string	N	platform order number (choose one of platform order number and merchant order number)
mchOrderNo	body	string	N	merchant order number (choose one of platform order number and merchant order number)

Return to example

{
  "code": 0,
  "data": {
    "currency": "INR",
    "fee": "0",
    "mchNo": "M1655535407",
    "mchOrderNo": "A1547429458697129178",
    "orderAmount": "10000",
    "payAmount": "10000",
    "payOrderId": "P1547429458697129178",
    "state": 2
  },
  "msg": "SUCCESS"
}

Return results

Name	Type	Description
payOrderId	string	payment order number
mchNo	string	merchant number
mchOrderNo	string	merchant order number
orderAmount	string	original transaction amount of bill
payAmount	string	payment amount
currency	string	three-digit currency code
state	string	payment status: 0-Order generated, 1-Payment in progress, 2-Payment successful, 3-Payment failed, 4-Cancelled, 5-Refunded, 6-Order closed, 7-Queue, 8 -We reject, 9-Partial payment
fee	string	merchant fee

Payment order inquiry

POST Get payment order information

POST HTTP_HOST/api/payOutInfo

Body request parameters

{
  "mchNo": "M1655535407",
  "mchOrderNo": "A1547429458697129178"
}

Request parameters

Name	Location	Type	Required	Description
X-API-KEY	header	string	Y	public key
X-API-NONCE	header	string	Y	request time (timestamp, accurate to milliseconds)
X-API-SIGNATURE	header	string	Y	signature (refer to signature algorithm)
mchNo	body	string	Y	merchant number
payOrderId	body	string	N	platform order number (choose one of platform order number and merchant order number)
mchOrderNo	body	string	N	merchant order number (choose one of platform order number and merchant order number)

Return to example

{
  "code": 0,
  "data": {
    "currency": "INR",
    "fee": "0",
    "mchNo": "M1655535407",
    "mchOrderNo": "A1547429458697129178",
    "orderAmount": "10000",
    "payAmount": "10000",
    "payOrderId": "P1547429458697138178",
    "state": 2
  },
  "msg": "SUCCESS"
}

Return results

Name	Type	Description
payOrderId	string	payment order number
mchNo	string	merchant number
mchOrderNo	string	merchant order number
orderAmount	string	original transaction amount of bill
payAmount	string	payment amount
currency	string	three-digit currency code
state	string	payment status: 0-order generated, 1-payment in progress, 2-payment successful, 3-payment failed, 8-rejected
fee	string	merchant fee

utr query

POST utr query

Request method：POST

Request URL：HTTP_HOST/api/utrQuery

Body Request parameters

{
  "mchNo": "M1658884178",
  "utr": "22028512360777878",
  "mchOrderNo": "D1660810866750"
}

Request parameters

Name	Location	Type	Required	Description
X-API-KEY	header	string	Y	public key
X-API-NONCE	header	string	Y	request time (timestamp, accurate to milliseconds)
X-API-SIGNATURE	header	string	Y	signature (refer to signature algorithm)
mchNo	body	string	Y	merchant number
mchOrderNo	body	string	Y	Merchant order number
utr	body	string	Y	utr

Return to example

{
  "code": 0,
  "data": {
    "message": "no utr（1234567891234567）",
    "status": 0,
    "utr": "1234567891234567"
  },
  "msg": "SUCCESS",
  "sign": "304602210085734f62a5829ae369eb24bd2bd59485d70d2d1cd7d0eaebedc26fea5c7d73d2022100f5b46b15ad36795185378d15b710e47914549d4b0b65af2544da740a088864a4"
}

Return results

Name	Type	Description
status	int	Status: 0-Failed, unable to fill the order. 1-Successful, order can be filled. 2- Order checking and filling are not supported at the moment, please contact the operation for processing.
message	string	status information
utr	string	utr
amount	string	Amount
mchOrderNo	string	The merchant order number will only be returned if it has been used by another order number.

utr supplementary order

POST utr supplementary order

Request method：POST

Request URL：HTTP_HOST/api/supplement

Body Request parameters

{
  "mchNo": "M1658884178",
  "utr": "22028512360777878",
  "mchOrderNo": "D1660810866750"
}

Request parameters

Name	Location	Type	Required	Description
X-API-KEY	header	string	Y	public key
X-API-NONCE	header	string	Y	request time (timestamp, accurate to milliseconds)
X-API-SIGNATURE	header	string	Y	signature (refer to signature algorithm)
mchNo	body	string	Y	merchant number
mchOrderNo	body	string	Y	Merchant order number
utr	body	string	Y	utr

Return to example

{
  "code": 0,
  "data": {
    "mchOrderNo": "D1660810866750",
    "message": "查无此utr（1234567891234567）",
    "payOrderId": "P1560179978363322369",
    "status": 0,
    "utr": "1234567891234567"
  },
  "msg": "SUCCESS",
  "sign": "304602210085734f62a5829ae369eb24bd2bd59485d70d2d1cd7d0eaebedc26fea5c7d73d2022100f5b46b15ad36795185378d15b710e47914549d4b0b65af2544da740a088864a4"
}

Return results

Name	Type	Description
status	int	Status, 0: Failure. 1: Success
message	string
status information
utr	string	utr
payOrderId	string	Platform order number
mchOrderNo	string	Merchant order number

Transaction history

POST Get transaction history (final data-success/failure)

POST HTTP_HOST/api/transInfo

Body request parameters

{
    "mchNo": "M1658240182",
    "bizType": 1,
    "startTime": 1656604800,
    "endTime": 1667145600,
    "pageNumber": 1,
    "pageSize": 20
}

Request parameters

Name	Location	Type	Required	Description
X-API-KEY	header	string	Y	public key
X-API-NONCE	header	string	Y	request time (timestamp, accurate to milliseconds)
X-API-SIGNATURE	header	string	Y	signature (refer to signature algorithm)
mchNo	body	string	Y	merchant number
bizType	body	number	N	business type: 1-Collection on behalf of others 2-Payment on behalf of others 3-USDT withdrawal 4-Withdrawal
startTime	body	number	N	start time (server 0 time zone timestamp, accurate to seconds)
endTime	body	number	N	end time (server 0 time zone timestamp, accurate to seconds)
pageNumber	body	number	Y	page number
pageSize	body	number	Y	page size (max 50)

Return to example

{
  "code": 0,
  "data": {
    "current": 1,
    "hitCount": false,
    "optimizeCountSql": true,
    "orders": [],
    "pages": 36,
    "records": [{
      "amount": "10000",
      "bankCard": "31241251241",
      "bankCode": "",
      "bankName": "",
      "bizType": 1,
      "createdAt": 1661406390,
      "currency": "INR",
      "email": "dingjing0502@163.com",
      "ifsc": "ABCD",
      "mchFeeAmount": "101",
      "mchName": "india test",
      "mchNo": "M1658884178",
      "mchOrderNo": "D1661406386838",
      "mobilePhone": "9893391387",
      "orderAmount": "10000",
      "payOrderId": "P1562677777705218049",
      "payWay": "UPI",
      "payWayType": "UPI",
      "payerName": "dingjing",
      "state": 2,
      "successTime": 1661409745
    }],
    "searchCount": true,
    "size": 1,
    "total": 36
  },
  "msg": "SUCCESS",
  "sign": "3045022100e331f5df01b7aa84052f2a991c9e36d2ebc78ec37256d3b930c2ae442b40457402205ea6bf91d95bf410427f6f0858d1de2922a1c1b59b148a58722f6c4a9bfe1b90"
}

Return results

Name	Type	Description
amount	string	settlement quantity (when collection is made, it is the upper-point quantity (handling fee is deducted), when payment/withdrawal is made, it is the bill quantity (handling fee is not deducted))
bankCard	string	bank card number
bankName	string	bank name
bizType	number	business type: 1-Collection on behalf of others 2-Payment on behalf of others 3-USDT withdrawal 4-Withdrawal
createdAt	number	order creation time (0 time zone timestamp, accurate to seconds)
currency	string	currency
ifsc	string	ifsc
mchFeeAmount	string	handling fee
mchName	string	merchant name
mchNo	string	merchant number
mchOrderNo	string	merchant order number
mobilePhone	string	mobile phone number
orderAmount	string	order amount
payOrderId	string	payment serial number
payWay	string	payment method name
payWayType	string	payment method
payerName	string	user name
state	number	order status: 2-successful 3-failed 8-(payment) rejected 9-partial payment (payment amount is less than the order amount)
successTime	number	success time (0 time zone timestamp, accurate to seconds)

Merchant balance information query

POST to obtain merchant balance information

POST HTTP_HOST/api/balanceInfo

Body request parameters

{
    "mchNo": "M1655535407"
}

Request parameters

Name	Location	Type	Required	Description
X-API-KEY	header	string	Y	public key
X-API-NONCE	header	string	Y	request time (timestamp, accurate to milliseconds)
X-API-SIGNATURE	header	string	Y	signature (refer to signature algorithm)
mchNo	body	string	Y	merchant number

Return to example

{
    "code": 0,
    "data": {
        "availableAmount": "294876",
        "frozenAmount": "1986",
        "mchNo": "M1658240182"
    },
    "msg": "SUCCESS",
    "sign": "3045022100e659480ea76d87c26e0054bda5a788737d41f26d4dec365fba936028248785140220540c9bb2b9fe6fc928dc2ae4c531ee00a82615bc37b77b02 ca41cffeeaddc627"
}

Return results

Name	Type	Description
availableAmount	string	available balance
frozenAmount	string	frozen balance
mchNo	string	merchant number

Callback notification

Submission method: POST

When receiving point-to-point communication from the server, the interface returns "OK" (without double quotes, OK is in capital letters), otherwise point-to-point notifications will be sent repeatedly (default 16 times).

OK

Content-Type

application/json

Verify signature

Use the Tarspay public key to verify the signature of [return data](#return description).

Request parameters

Name	Type	Required	Description
bizType	number	Y	business type: 1-Collection 2-Payment
payOrderId	string	Y	payment order number
mchNo	string	Y	merchant number
mchOrderNo	string	Y	merchant order number (customized by merchant, cannot be repeated)
orderAmount	string	Y	original transaction amount of bill
payAmount	string	Y	payment amount
currency	string	Y	three-digit currency code
state	number	Y	payment status: 2-payment successful, 3-payment failed, 9-partial payment (collection)
fee	string	Y	merchant fee
failReason	string	N	failure reason

Callback signature verification description: X-RESP-SIGNATURE request header carries signature

Signature rules: After JSONizing the request parameters, put the obtained signature in the header, and obtain the signature directly from the response header. To verify the signature, use verifyEcdsaSignature() in the ECSDAKit tool class below.

Example:

OrderNotifyDTO.class

Signature tool class

Maven dependencies

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

ECSDAKit

Utils

java demo

php demo

Download link

Error coding table

Error code	Error description
-1	System error
5003001	Missing parameter
5003002	Merchant or APIKey does not exist
5003003	Merchant disabled
5003004	Merchant not certified
5003005	Merchant api key does not exist
5003005	Merchant or api key does not exist
5003006	api key expired
5003007	ip error
5003008	Signature error
5003009	Payment method not supported
5003010	Order status error
5003011	Merchant order number already exists
5003012	URL format error
5003013	Channel error
5003014	Merchant rate configuration is not initialized
5003015	Channel does not exist
5003017	Failed to create collection order
5003018	Failed to check collection order
5003010	Failed to create payment order
5003020	Failed to query payment
5004006	Insufficient merchant balance
500321	Amount format is incorrect
500322	URL not supported
500323	Remote client error
500324	Order expired
500326	Error in querying channel balance
500327	Wrong payment method

India🇮🇳

Interface Description#

Access flow chart#

common problem#

Signature algorithm#

HTTP_HOST#

HTTP_METHOD#

HTTP_REQUEST_PATH#

NONCE#

PARAMS#

Complete example#

Return description#

Collection#

POST collection and unified order placement#

Request parameters#

Return results#

POST payment for unified order placement#

Request parameters#

Return results#

Collection order inquiry#

POST to obtain collection order information#

Request parameters#

Return results#

Payment order inquiry#

POST Get payment order information#

Request parameters#

Return results#

utr query#

POST utr query#

Request parameters#

Return results#

utr supplementary order#

POST utr supplementary order#

Request parameters#

Return results#

Transaction history#

POST Get transaction history (final data-success/failure)#

Request parameters#

Return results#

Merchant balance information query#

POST to obtain merchant balance information#

Request parameters#

Return results#

Callback notification#

Submission method: POST#

Content-Type#

Verify signature#

Request parameters#

Signature tool class#

Maven dependencies#

ECSDAKit#

Utils#

java demo#

php demo#

Error coding table#

Interface Description

Access flow chart

common problem

Signature algorithm

HTTP_HOST

HTTP_METHOD

HTTP_REQUEST_PATH

NONCE

PARAMS

Complete example

Return description

Collection

POST collection and unified order placement

Request parameters

Return results

POST payment for unified order placement

Request parameters

Return results

Collection order inquiry

POST to obtain collection order information

Request parameters

Return results

Payment order inquiry

POST Get payment order information

Request parameters

Return results

utr query

POST utr query

Request parameters

Return results

utr supplementary order

POST utr supplementary order

Request parameters

Return results

Transaction history

POST Get transaction history (final data-success/failure)

Request parameters

Return results

Merchant balance information query

POST to obtain merchant balance information

Request parameters

Return results

Callback notification

Submission method: POST

Content-Type

Verify signature

Request parameters

Signature tool class

Maven dependencies

ECSDAKit

Utils

java demo

php demo

Error coding table