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: http://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	http://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 LarkPay 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

Collection type

Payment method code

Encoding	Description
BANK	BANK
PROMPTPAY	PROMPTPAY
TRUEMONEY	TRUEMONEY

POST collection and unified order placement

POST HTTP_HOST/api/pay/unifiedOrder

Body request parameters

{
  "amount": "100",
  "currency": "THA",
  "mchNo": "80002",
  "mchOrderNo": "M202207131958",
  "notifyUrl": "https://www.yourcompany.com/notify",
  "returnUrl": "https://www.yourcompany.com/return",
  "wayCode": "BANK"
}

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 code - Cashier: CASHIER (use the cashier of this system) - Non-cashier: refer to [Payment method code] (#Payment method code) (The merchant maintains the checkout counter himself)
amount	body	string	Y	the amount (no decimals. It cannot be zero and must meet the amount standard.)
body	body	string	Y	Product Description Information
currency	body	string	Y	currency(THA)
notifyUrl	body	string	Y	notification address
returnUrl	body	string	Y	return address
customerName	body	string	N	username
customerEmail	body	string	N	user Email
customerContact	body	string	N	user phone
customerAccountNumber	body	string	N	user account number,When selecting PROMPTPAY for wayCode, it is required

Return to example

{
  "code": 0,
  "data": {
    "amount": "5000",
    "countryCode": "th",
    "currency": "THA",
    "customerContact": "662201111111",
    "mchOrderNo": "202207161603q01",
    "orderState": 0,
    "payOrderId": "P1551396771600912385",
    "payUrl": "https://example.com/#/order/th/P1551396771600912385",
    "payWays": {
      "bank": [
        {
          "countryCode": "th",
          "payWay": "BANK",
          "payWayLogo": "https://example.com/larkpay_v_1.0/PERMATA.png",
          "payWayType": "BANK"
        }
      ]
    }
  },
  "msg": "SUCCESS",
  "sign": "3045022100f32d38d4457295f0ce70376845458ec55a9fad34cce39ae11cd0cdbadd90639e02207d23e33f9b95944fb32923707c30b913063b082995b7e5fb9d8d2369f1ab4e53"
}

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
accountName	string	User name, non-cashier mode, only returned when the payment method is online banking, e-wallet and scan code
typeBank	string	Bank name, non-cashier mode, only returned when the payment method is online banking and scanning QR code
accountNumber	string	User name, non-cashier mode, only returned when the payment method is online banking, scan code and electronic wallet
payUrl	string	-When in cashier mode, return the cashier address; -When in non-cashier mode, return the transfer required content
payData	string	QR code (returned only when not at the cashier, only returned when the payment method is scan code and electronic wallet)
payWays	array	Payment methods

payment method:

Name	Type	Description
countryCode	string	Country code
payWay	string	Payment method code (refer to [Payment method code](#Payment method code))
payWayLogo	string	Payment method logo
payWayType	string	Payment method type (refer to [Collection Type](#Collection Type))
payCode	string	QR code/QR code image (returned only when not at the cashier). When the payment type is qr, the QR code image link is returned. When the payment type is ewallet, the QR code data is returned. )

#Pay on behalf of

Payment code

Payment bank code

Bank & e-wallet code	Bank & e-wallet name
BAAC	Bank for Agriculture and Agricultural Cooperatives
BAY	Bank of Ayudhya Public Company Limited
BBL	BANGKOK BANK PUBLIC COMPANY LIMITED
CIMB	CIMB Thai Bank Public Company Limited
CITI	Citibank Thailand
GHB	Government Housing
GSB	Government Savings Bank
HSBC	The Hongkong and Shanghai Banking Corporation Limited
ICBC	ICBC Bank (Thai) Public Company Limited
IBANK	Islamic bank of thailand
KBANK	Kasikorn Bank Plc
KKP	KIATNAKIN PHATRA BANK PUBLIC COMPANY LIMITED
LHBANK	Land and Houses Bank Public Company Limited
MHCB	Mizuho Corporate Bank Limited
SCB	Siam Commercial Bank Plc
SCBN	Standard Chartered Bank Nakornthon Plc
SMBC	Sumitomo Mitsui Banking Corporation
TBANK	Thanachart Bank Public Company Limited
TCRB	Thai Credit Retail Bank Public Company Limited
TISCO	TISCO Bank Plc
TMB	TMB Bank Plc
UOB	UOB Bank Plc
AIG	AIG Retail Bank Public Company Limited
BOA	Bank of America
BNP	BNP Paribas Bangkok Bank
BOC	Bank of china
TMB	Tokyo Mitsubishi Bank
ABI	Agrigol Bank Indonesia
DEUTB	Deutsche Bank
EXIMB	Export-Import Bank of Thailand
IOB	IOB Indian Overseas
JPMCB	JP Morgan Chase Bank Bangkok Branch
MICB	Mega International Commercial Bank
OCBC	Oversea-Chinese Banking Corporation Limited
ABN	ABN AMRONV Bank
RHB	RHB Bank Limited
SMEB	Small and Medium Enterprise Development Bank of Thailand
KTB	Krung Thai Bank

POST payment for unified order placement

POST HTTP_HOST/api/payOut/unifiedOrder

Body request parameters

{
  "amount": "40",
  "customerAccountNumber": "922010002523675",
  "customerContact": "662201111111",
  "customerEmail": "xxxx@gmail.com",
  "customerName": "xxxx",
  "mchNo": "80001",
  "mchOrderNo": "2022071201011",
  "notifyUrl": "http://www.yourcompany.com/notify",
  "wayCode": "ICBC"
}

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 code (refer to [payment code](#payment code))
amount	body	string	Y	the amount (no decimals. It cannot be zero and must meet the amount standard.)
currency	body	string	Y	currency(THA)
notifyUrl	body	string	Y	notification address
customerName	body	string	Y	username
customerContact	body	string	Y	phone number Format: Thailand starts with 66, such as 668XXXXXXXX
customerAccountNumber	body	string	Y	user accountNumber
customerEmail	body	string	Y	user email

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

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": "lin1231241241414"
}

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": "THA",
    "fee": "0",
    "mchNo": "M1655535407",
    "mchOrderNo": "",
    "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": "lin1231241241414"
}

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": "THA",
    "fee": "0",
    "mchNo": "M1655535407",
    "mchOrderNo": "",
    "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

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": 22,
    "records": [
      {
        "amount": "190000",
        "bankCard": "123456789",
        "bankName": "",
        "bizType": 1,
        "createdAt": 1683945480,
        "currency": "THA",
        "mchFeeAmount": "10000",
        "mchName": "DW-THA Test",
        "mchNo": "M1683793693",
        "mchOrderNo": "THA95220230300258",
        "mobilePhone": "17760797979",
        "orderAmount": "200000",
        "payOrderId": "P1657213573143552002",
        "payWay": "bank",
        "payWayType": "bank",
        "payerName": "DW",
        "state": 2,
        "successTime": 1683945670
      }
    ],
    "searchCount": true,
    "size": 3,
    "total": 66
  },
  "msg": "SUCCESS",
  "sign": "3046022100d4670c5466807b6b62635030e5c10acd2855e3428b4e9ff45e5c9648d4d28288022100a3cca3d4bbc6d994e66ada5e1d0fb095fabc4a92d622 a2074a1b10fc4c530830"
}

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
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	is

MERCHANT BALANCE INFOMATION 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 LarkPay 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

Thailand🇹🇭

Interface Description#

Access flow chart#

common problem#

Signature algorithm#

HTTP_HOST#

HTTP_METHOD#

HTTP_REQUEST_PATH#

NONCE#

PARAMS#

Complete example#

Return description#

Collection#

Collection type#

Payment method code#

POST collection and unified order placement#

Request parameters#

Return results#

Payment code#

Payment bank code#

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#

Transaction history#

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

Request parameters#

Return results#

MERCHANT BALANCE INFOMATION 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

Collection type

Payment method code

POST collection and unified order placement

Request parameters

Return results

Payment code

Payment bank code

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

Transaction history

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

Request parameters

Return results

MERCHANT BALANCE INFOMATION 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