Merchant Hosted Offline/Hardware

API Playground

Tips: Get your Wallet ID, User ID and API key via Latipay Merchant Portal > Account > Show hidden values
Tips: Create a minimum amount product (e.g. $ 0.01 NZD/AUD) for testing.

This API will return QR code in a diagramatic format along with the Transaction and Payment Interfaces.

Available Payment Methods

How it works?

Alipay Or WeChat with Server

Alipay Or WeChat without Server

Payment Scenarios

Alipay


WeChat


API Details

1 - Latipay Transaction Interface

1
2
POST https://api.latipay.net/v2/transaction
Content-Type: application/json;charset=UTF-8

API Playground

Demo

1
2
3
4
5
curl \
-X POST \
-H "Content-Type: application/json;charset=UTF-8" \
-d '{"signature":"a60318f763c88d7f4efe9cec33342f0d303233bd0ded2bc6902b1cc867790411","wallet_id":"W00000001","amount":"120.00","user_id":"U000334333","merchant_reference":"dsi39ej430sks03","return_url":"","callback_url":"https://merchantsite.com/confirm","ip":"122.122.122.1","version":"2.0","product_name":"Pinot Noir, Otago","payment_method":"alipay","host_type" :"1"}' \
https://api.latipay.net/v2/transaction

Parameters:

Name Type Description Optional
user_id String The user account you want to use to process the transaction. NO
wallet_id String The ID of the wallet you want to use. NO
amount String A decimal amount. NO
merchant_reference String A unique id identifying the order in Merchant’s system. NO
payment_method String Payment method options are alipay and wechat. NO
return_url String The URL of the landing page where Latipay will return the customer after payment when successful or failed. NO
callback_url String Merchant webserver’s URL that the payment result will send to. NO
ip String The IP address of the customer. NO
version String The latest version of the platform. must be "2.0" NO
product_name String The name of the product or service being sold. NO
host_type String must be "1", for #Payment Interface to return QR code picture in base64 NO
signature String The SHA-256 HMAC API signature. NO

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"wallet_id": "W00000001",
"amount": "120.00",
"user_id": "U000334333",
"merchant_reference": "dsi39ej430sks03",
"return_url": "",
"callback_url": "https://merchantsite.com/confirm",
"ip": "122.122.122.1",
"version": "2.0",
"product_name": "Pinot Noir, Otago",
"payment_method": "alipay",
"host_type" : "1",

"signature": "a60318f763c88d7f4efe9cec33342f0d303233bd0ded2bc6902b1cc867790411",
}

SHA-256 HMAC Signature Try your signature online

Rearrange all parameters alphabetically (except parameters with value of null or empty string) and join them with &, and concat the value of api_key in the end.

JS code example:

1
2
3
4
5
6
Object.keys(data)
.filter(item => data[item] != null && data[item] != undefined && data[item] !== '')
.sort()
.map(item => `${item}=${data[item]}`)
.join('&')
.concat(api_key)

Example

1
2
3
4
message: amount=120.00&callback_url=https://merchantsite.com/confirm&host_type=1&ip=122.122.122.1&merchant_reference=dsi39ej430sks03&payment_method=alipay&product_name=Pinot Noir, Otago&user_id=U000334333&version=2.0&wallet_id=W00000001111222333
secret(your api_key): 111222333

signature: a60318f763c88d7f4efe9cec33342f0d303233bd0ded2bc6902b1cc867790411

Response

Name Type Description
code Int 0 means success.
host_url String The url for request a QR code picture. The nonce should be appended to the end.
nonce String The transaction nonce must be appended to the host_url URL. Please make sure it always be fresh, Do not save it for using later.
signature String The SHA-256 HMAC API signature.

Example

1
2
3
4
5
6
7
{
"code": 0,
"message": "SUCCESS",
"host_url": "https://api.latipay.net/v2/merchanthosted/gatewaydata",
"nonce": "7d5a88119354301ad3fc250404493bd27abf4467283a061d1ed11860a46e1bf3",
"signature": "14d5b06a2a5a2ec509a148277ed4cbeb3c43301b239f080a3467ff0aba4070e3",
}

Signature in Response

For security reasons, we highly recommend you verify the signature in the response.

1
2
message: nonce + host_url
secret: api_key

2 - Payment Interface

1
GET {host_url}/{nonce}

Example

1
GET https://api.latipay.net/v2/merchanthosted/gatewaydata/7d5a88119354301ad3fc250404493bd27abf4467283a061d1ed11860a46e1bf3

Response

Name Type Description
code Integer The response code of payment, 0 or Error Code, 0 means no error happened.
message String The response message of payment interface.
data Object Contains QR code picture and order information.

the data object

Name Type Description
order_id String A unique transaction identifier generated by Latipay.
nonce String A unique transaction nonce generated by Latipay.
payment_method String Payment method options are alipay and wechat.
amount String A decimal amount.
amount_cny String A decimal amount.
currency String The currency code of the transaction.
product_name String The name of the product or service being sold.
organisation_id Integer The merchant id which is used to process the transaction.
organisation_name String The merchant’s name
user_id String The user account which is used to process the transaction.
user_name String The user account’s name
wallet_id String The user wallet account which is used to process the transaction.
wallet_name String The wallet account’s name
qr_code String The QR code picture
qr_code_url String The QR code text version, you can generate QR code picture with it.
currency_rate String The rate which is used to the transaction.
merchant_reference String A unique id identifying the order in Merchant’s system.
signature String The SHA-256 HMAC API signature.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
"code": 0,
"message": "SUCCESS",
"data": {
order_id: "20180411000011",
nonce: "9cbd6620180411115539ca7260dd01f54c5f8977b262256828",
payment_method: "wechat",
amount: 0.02,
amount_cny: 0.09,
currency: "NZD",
product_name: "food",
organisation_id: 1,
organisation_name: "123123",
user_id: "U00001534",
user_name: "abcdefghijklmnopqrstuvwxyz",
wallet_id: "W00000001",
wallet_name: "test account",
qr_code: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAAEz0lEQVR42u3dSW7kMBAEQP3/0zMvMGDAVGUWFQX4JnWLS/QhTZHPP6XUj/XoAqUAUQoQpQBRChClAFFqN5DneWr+ft2gX957+jtS7f3T4P/hWSbubehnQAABBBBAAAEEEEAAAQSQaiCpgWvC0DQpT1+3sU/f/F5AAAEEEEAAAQQQQAABBJB1QE6nCKmJkEphUm3b+AM4jRoQQAABBBBAAAEEEEAAAQSQoiULt6R2qcQKEEAAAQQQQAABBBBAAAEEECnWeLVPttNLTQABBBBAAAEEEEAAAQQQQAApBbKxA1ObNmzs56Z7p9sLCCCAAAIIIIAAAggggABSDaRpBzzX3XOdrUcBcR0ggLgOEEBcBwggrgPEGYWvJiRN6Vlqk4r142pqAwIIIIAAAggggAACCCDbgHztvL+mSbkxTdo0DwABBBBAAAEEEEAAAQQQQKqBpDYJ2PjuQqptN2+iMf0sgAACCCCAAAIIIIAAAggg1UAmGpJaopH6vFSCmJqUre9+AAIIIIAAAggggAACCCCAXLvUpH0pwvaBa0zA2tOu2KYNgAACCCCAAAIIIIAAAggg6Z0Vmz4vVamE7nRfpb4j1VeAAAIIIIAAAggggAACCCCVQCZSk4lUoimFaV8y0778pD7mBQQQQAABBBBAAAEEEEAAmfxP+sbOP31veztuhl4f8wICCCCAAAIIIIAAAggggLwFJJWutKNpOnswNXk3vicDCCCAAAIIIIAAAggggACyGsjXNjto3xgiNWFS49awwQUggAACCCCAAAIIIIAAAkgNkKZlJam062s7PzalihOfBwgggAACCCCAAAIIIIAAAshw4pJCfQv+dqxXp1iAAAIIIIAAAggggAACCCCNE/r0IE0kVqfvnYAkUQMEEEAAAQQQQAABBBBAAPkwkBSajUCa2pZKnaafDxBAAAEEEEAAAQQQQAABpBrIjbvnfXXin/5xak8aAQEEEEAAAQQQQAABBBBAVgNp3wr/FphN4E4/88S9gAACCCCAAAIIIIAAAggggCzfPOHmnQYtmQmeUQgIIIAAAggggAACCCCAAJI+J70d19feo2gao6Z2AAIIIIAAAggggAACCCCArAbSkCK8NcCpH4SmJSRNk7w1LQQEEEAAAQQQQAABBBBAALninfSJTmhK3ibQbDzuYQJmVcwLCCCAAAIIIIAAAggggAAy+Z/09gndlJDckrK1Tt6JZAsQQAABBBBAAAEEEEAAAaQGSKpxTQlO0w9He9tuSe0AAQQQQAABBBBAAAEEEEAqgbRX+yC1p063nG/4ZoIICCCAAAIIIIAAAggggACy7viDW84o/Np7KE2TN5XGAQIIIIAAAggggAACCCCArAaSSqcmAKcSpo2bNrSnWKeeDxBAAAEEEEAAAQQQQAABZB2Qje9qtA7I5GRrTy4bkjxAAAEEEEAAAQQQQAABBBBASnfZO9H5E+8zNG3asL0PAAEEEEAAAQQQQAABBBBAAAl1YKq9pyflxLOkEjApFiCAAAIIIIAAAggggAACSOn7IE0T6+ZjF96cgO2fBwgggAACCCCAAAIIIIAAUg3k5mMDvrYBQtP3NqWjgAACCCCAAAIIIIAAAgggzklXqrAAUQoQpQBRChClAFEKEKUAUWp1/Qf6j3VUKG0J3AAAAABJRU5ErkJggg==",
qr_code_url: "weixin://wxpay/bizpayurl?pr=hmU9BXs",
currency_rate: "4.64490",
merchant_reference: "M00001543-000001",
signature: "15e8f83c0e3cddbec01b0ee135d958d872d21498bd29ff6defc2eb2f11b11108"
}
}

SHA-256 HMAC Signature

Rearrange all parameters in the data alphabetically (except signature and other parameters with value of null or empty string) and join rearranged parameters with &, and concat the value of api_key in the end.

1
2
message: amount=0.02&amount_cny=0.09&currency=NZD&currency_rate=4.65776&merchant_reference=M00001543-000001&nonce=41226220180411114422fdfdba5d94f84fdc873f0f9ea6d5a6&order_id=20180411000009&organisation_id=1&organisation_name=123123&payment_method=alipay&product_name=food&qr_code=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAAE+klEQVR42u3dQW7jMBAEQP//07v3BfYQmNPTZKqBnJzYscQSMKQ0/PwRkf/m4xCIACICiAggIoCIACICiAggIoCIACIigIgAIgKICCAigIgAIgKICCD/vtHnE/05/f/+9Pv89P2+/f3T3+/03397PNvGByCAAAIIIIAAAggg9wFJn/BtUNsD8NsB+e3xvv2CAAgggAACCCCAAALIe0CmT1j7ADkNenuAbhfxgAACCCCAAAIIIIAA0n4Atv/+NMBpoOkLCiCAAAIIIIAAAggggPy2Ij19s93p4337zY+AAAIIIIAAAggggACyXcROF63TA3wa3PT3a1tY3Rp/gAACCCCAAAIIIIBo2pBaqPL67kKgriaAAAIIIF4HBBCvA9KeaVDt4LcXYl8NIIAAAggggAACCCDvAkkXZW2ATg/A0zdjTi/MtiwMAgIIIIAAAggggAByL5DtInEaQBpk+viePv/bF0RAAAEEEEAAAQQQQN4Dkm6C0Dag25tKpH9/e7wAAggggAACCCCAAPI+kJaFnVsWLrebRmxPgqQXFgEBBBBAAAEEEEAAAWT679tvfnxtEmH689culIAAAggggAACCCCA1AJpazJwWzPlNLDp85e+4AECCCCAAAIIIIAAAsjpL9y2aabXsxfIX7eJJyCAAAKI1wEBxOuAxBcGv/287Y3r0xeA228Grf0/AQEEEEAAAQQQQAB5BkjbwlJ7E4Pf1ljv13VWBAQQQAABBBBAAAFkvUg+/XntRWNbU4b0Ba91UgIQQAABBBBAAAEEkHuK9OkT2tYE4bYHxtomWQABBBBAAAEEEEAAASRdtKeLzOmf05MY6aK+vYgGBBBAAAEEEEAAAQSQ9EP96fe/rUje3nQzPUkCCCCAAAIIIIAAAggg7QtR20VqGnS6SG5b+AQEEEAAAQQQQAABBJDp5sSvbZo5/XnTx7N9UgQQQAABBBBAAAEEkPuBtC2UtU06tB+v9g1vnu9qAggggAACCCCAAAJIHND2A0zpB4TaN8RpWzi9rkgHBBBAAAEEEEAAASS+UNi+0JYu0tMLd6813otdGAABBBBAAAEEEEAAeQZIe/Pjtg2B0jd3pic1dDUBBBBAAAEEEEAAASS9kHS6KGsrOqcXHtsmOdrOJyCAAAIIIIAAAggg7wGZPiC3NyrbbizX3vy7tVEeIIAAAggggAACCCD3FumnQW1vIDMN+jbwbRcYQAABBBBAAAEEEEDeBzJeLIWLtNuaNrQ9kHYa1FYRDwgggAACCCCAAALIO43j0kXibQ/4bDfKay2a4xdmQAABBBBAAAEEEEBqgUwfsLYB2lbUbw/g9g13AAEEEEAAAQQQQAB5D8h6MRV+QCj9/0xPgrRtIAQIIIAAAggggAACCCDpA9w2wNo3DW1buEwfX0AAAQQQQAABBBBAAJkuwr/9/O0HoNJNGbbPz/QFChBAAAEEEEAAAQQQQNqKvOmitb2oTy/MvnLzIiCAAAIIIIAAAggggLQ0fZieVGhritAODhBAAAEEEEAAAQQQQNqAbDeVuH3Ty9smAQABBBBAAAEEEEAAAST9/rdvInp7E4fpSYvY5AQggAACCCCAAAIIINcASd+8Nl10pl+/rfHd6fGxPUkACCCAAAIIIIAAAkg/EJEXA4gIICKAiAAiAogIICKAiAAiAogIICICiAggIoCIACICiAggIoCIPJO/H7l2LoSyTzgAAAAASUVORK5CYII=&qr_code_url=https://qr.alipay.com/bax08151zdenrj3nltzi80a9&user_id=U00001534&user_name=abcdefghijklmnopqrstuvwxyz&wallet_id=W00000001&wallet_name=test accountXXXXXXXXX
secret(your api_key): XXXXXXXXX

JS code example:

1
2
3
4
5
6
Object.keys(data)
.filter(item => item !== 'signature')
.sort()
.map(item => `${item}=${data[item]}`)
.join('&')
.concat('XXXXXXXXX')


3 - Payment Result Asynchronous Notification

Asynchronous Notification is a re-try mechanism to ensure the notification has been updated to the merchant’s web server. There is no times limitation until it returns an indicating sent text to Latipay. The time interval of this notification is about 30 seconds.

1
2
POST merchant's callback_url
Content-Type: application/x-www-form-urlencoded

The status of response must be 200, the body of response must be the string sent

Parameters:

Name Type Description
merchant_reference String A unique id identifying the order in Merchant’s system.
currency String The currency code of the transaction.
amount String A decimal amount.
payment_method String The payment method used. Possible values are alipay and wechat.
status String The status of the transaction. Possible values are: pending, paid, or failed.
pay_time String Show the payment time of the transaction order.
signature String The SHA-256 HMAC API signature.

Example input

1
2
3
4
5
6
7
8
9
10
{
"merchant_reference": "dsi39ej430sks03",
"currency": "AUD",
"amount": "120.00",
"payment_method": "wechat",
"status": "paid",
"pay_time": "2017-07-07 10:53:50"

"signature": "14d5b06a2a5a2ec509a148277ed4cbeb3c43301b239f080a3467ff0aba4070e3",
}

SHA-256 HMAC Signature

Merchant backend needs to validate the signature for protecting against malicious requests.

1
2
message: merchant_reference + payment_method + status + currency + amount
secret: api_key

Expected response

1
sent

4 - Payment Result Interface

All customers can send requests to query payment status with merchant order id(that should be unique id for the merchant) as merchant_reference by HTTP GET request.

1
GET https://api.latipay.net/v2/transaction/{merchant_reference}

API Playground

Parameters

Name Type Description Optional
merchant_reference String A unique id identifying the order in Merchant’s system. NO
user_id String The user account you want to use to process the transaction. NO
is_block Int Optional parameter, 1 means the http request use long poolling mechanism, the timeout is 180s. YES
signature String The SHA-256 HMAC API signature. NO

SHA-256 HMAC Signature

1
2
message: merchant_reference + user_id
secret: api_key

Example

1
GET https://api.latipay.net/v2/transaction/1289323A122DB?user_id=U000334333&signature=14d5b06a2a5a2ec509a148277ed4cbeb3c43301b239f080a3467ff0aba4070e3

Response

Name Type Description
merchant_reference String A unique id identifying the order in Merchant’s system.
order_id String A unique transaction identifier generated by Latipay.
currency String The currency code of the transaction.
amount Number A decimal amount.
payment_method String The payment method used. Possible values are alipay and wechat.
status String The status of the transaction. Possible values are: pending, paid, or failed.
pay_time String Show the payment time of the transaction order. UTC/GMT+08:00
signature String The SHA-256 HMAC API signature.

Example Response

1
2
3
4
5
6
7
8
9
10
11
{
"merchant_reference": "dsi39ej430sks03",
"order_id": "2017232323345670",
"currency": "AUD",
"amount": 120.00,
"payment_method": "wechat",
"status": "paid",
"pay_time": "2017-07-07 10:53:50",

"signature": "14d5b06a2a5a2ec509a148277ed4cbeb3c43301b239f080a3467ff0aba4070e3",
}

Signature in Response

For security reasons, we highly recommend you verify the signature in the response.

1
2
message: merchant_reference + payment_method + status + currency + amount
secret: api_key

Example Signature

1
2
3
4
message: dsi39ej430sks03alipaypaidNZD120.00
secret(your api_key): 111222333

signature: 840151e0dc39496e22b410b83058b4ddd633b786936c505ae978fae029a1e0f1

5 - Refund

1
POST https://api.latipay.net/refund

API Playground

Parameters

Name Type Description
user_id String The user account you want to use to process the transaction.
order_id String A unique transaction identifier generated by Latipay.
refund_amount String A decimal amount. e.g. “9.99”, cannot be in excess of order amount.
reference String Notes about this refund.
signature String The SHA-256 HMAC API signature.

Example

1
2
3
4
5
6
7
8
{
"user_id": "U000334333",
"order_id": "23479798sdf7987234",
"refund_amount": "120.00",
"reference": "notes about this refund",

"signature": "3052b51072570b743bf9a12a20a45b0adf280aee84907ef0e54d1079fb3f961c",
}

SHA-256 HMAC Signature

Rearrange all parameters alphabetically (except parameters with value of null or empty string) and join them with &, and concat the value of api_key in the end.

JS code example:

1
2
3
4
5
6
Object.keys(data)
.filter(item => data[item] != null && data[item] != undefined && data[item] !== '')
.sort()
.map(item => `${item}=${data[item]}`)
.join('&')
.concat(api_key)

Example

1
2
3
4
message: order_id=23479798sdf7987234&reference=notes about this refund&refund_amount=120.00&user_id=U000334333111222333
secret(your api_key): 111222333

signature: 3052b51072570b743bf9a12a20a45b0adf280aee84907ef0e54d1079fb3f961c

Response

Name Type Description
code String The response code of payment, 0 or Error Code, 0 means no error happened.
message String The response message of payment interface.

Example Response

1
2
3
4
{
"code": 0,
"message": "", //the reason when error happened
}

6 - Cancel Transaction

1
POST https://api.latipay.net/cancel

API Playground

Parameters

Name Type Description
user_id String The user account you want to use to process the transaction.
merchant_reference String A unique id identifying the order in Merchant’s system.
signature String The SHA-256 HMAC API signature.

Example

1
2
3
4
5
6
{
"user_id":"U000000013",
"merchant_reference":"9872428736782682",

"signature": "3052b51072570b743bf9a12a20a45b0adf280aee84907ef0e54d1079fb3f961c",
}

SHA-256 HMAC Signature

Rearrange all parameters alphabetically (except parameters with value of null or empty string) and join them with &, and concat the value of api_key in the end.

JS code example:

1
2
3
4
5
6
Object.keys(data)
.filter(item => data[item] != null && data[item] != undefined && data[item] !== '')
.sort()
.map(item => `${item}=${data[item]}`)
.join('&')
.concat(api_key)

Example

1
2
3
4
message: user_id=U000000013&merchant_reference=9872428736782682111222333
secret(your api_key): 111222333

signature: da3b80be09665913e632f1bc0822e3d98d8dd235aebeb6f532b6bb7e329b9635

Response

Name Type Description
code String The response code of payment, 0 or Error Code, 0 means no error happened.
message String The response message of payment interface.

Example Response

1
2
3
4
{
"code": 0,
"message": "", //the reason when error happened
}

Code

Code Message Description
0 success cancellation success
1 FAIL cancellation failed,you can submit another request after at least 15 minutes
3 data error parameters in request body are illlegal
110 User not exist user specified by user_id doesn’t exist
201 order not exist can’t find the transaction order by merchant_reference
205 Can not find out corresponding key for the user code or user is disabled or user is not activity can’t get api key by user_id
206 Signature from Merchant request is wrong signature is not correct
900 transaction has been successfully completed can’t cancel this transaction, because it has been completed successfully
901 transaction has been failed can’t cancel this transaction, because it has been failed