Merchant Hosted Online/E-Commerce
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.
Summary
Powerful and robust online payment solutions, which work on a range of platforms which include website, billing software and Applications. Latipay provides merchants with the interface for developing custom built WeChat QR Code payment page.
Available Payment Methods
- Alipay (Alipay hosted QR Code payment page)
- WeChat Pay (Customised QR Code payment page)
- 16 Chinese OnlineBanks (Latipay hosted payment page)
How it works?
Alipay
Online Bank
Payment Scenarios
Website check-out page
WeChat Pay
Alipay
Online Bank
API Details
1 - Latipay Transaction Interface
1 | POST https://api.latipay.net/v2/transaction |
Demo
1 | curl \ |
Attributes:
Name | Type | Description | Nullable |
---|---|---|---|
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 , wechat or onlineBank . |
NO |
return_url | String | The URL of the landing page where Latipay will return the customer after payment. | 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 |
signature | String | The SHA-256 HMAC API signature. | NO |
Extract Attributes (Only for WeChat
):
Name | Type | Description | Nullable |
---|---|---|---|
host_type | String | "1" is returning QR code picture in base64 and QR code text , merchant can either display the picture or generate QR code from the text |
NO |
Example Attributes
1 | { |
SHA-256 HMAC Signature
JS code example:
1 | Object.keys(data) |
Example
1 | message: amount=120.00&callback_url=https://merchantsite.com/confirm&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 |
Response
1 | { |
Name | Type | Description |
---|---|---|
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. |
signature | String | The SHA-256 HMAC API signature. |
Signature in Response
For security reasons, we highly recommend you verify the signature in the response.
1 | message: nonce + host_url |
2 - Latipay Payment Interface
For Alipay, load the api in PC browser, mobile browser or Alipay’s embedded browser. For Wechat, send the GET request for retrieving QR code.
1 | {host_url}/{nonce} |
Example
1 | https://api.latipay.net/v2/merchanthosted/gatewaydata/7d5a88119354301ad3fc250404493bd27abf4467283a061d1ed11860a46e1bf3 |
Alipay
payment is directly going to Alipay payment page. Online Bank
payment is directly going to Banks payment page. But Wechat
payment will response as below.
- Response (
Only for WeChat
)
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 or text 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 | { |
SHA-256 HMAC Signature
Rearrange 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 | message: amount=0.02&amount_cny=0.09¤cy=NZD¤cy_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 |
JS code example:
1 | Object.keys(data) |
3 - Payment Result Asynchronous Notification
This is a payment result notification sent by Latipay to merchants after the payment is done successfully. There is a re-try mechanism with the notification to ensure the notification could be delivered to the merchant.
1 | POST merchant's callback_url |
The status of response must be 200
Attributes:
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 | { |
SHA-256 HMAC Signature
Merchant backend needs to validate the signature for protecting against malicious requests.
1 | message: merchant_reference + payment_method + status + currency + amount |
4 - Synchronous Redirection
This redirection only happens in Wechat pay’s embedded browser and OnlineBank. For Alipay, it only happens in PC browser, not in Alipay app.
There is a sync and front-end payment result redirection sent from Latipay to merchant after the payment is done successfully.
1 | Redirect merchant's return_url |
Name | Type | Description |
---|---|---|
merchant_reference | String | A unique id identifying the order in Merchant’s system. |
payment_method | String | The payment methods can be wechat , alipay or onlineBank . |
status | String | The status of the transaction can be pending , paid , or failed . |
currency | String | The currency code of the transaction. |
amount | String | A decimal amount. |
signature | String | The SHA-256 HMAC API signature. |
Example
1 | https://www.merchant.com/latipay?merchant_reference=dsi39ej430sks03&payment_method=alipay&status=paid¤cy=NZD&amount=100.00&signature=14d5b06a2a5a2ec509a148277ed4cbeb3c43301b239f080a3467ff0aba4070e3 |
SHA-256 HMAC Signature
Merchant frontend need to validate the signature for protecting against malicious requests.
1 | message: merchant_reference + payment_method + status + currency + amount |
5 - 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} |
Attributes
Name | Type | Description |
---|---|---|
user_id | String | The user account you want to use to process the transaction. |
signature | String | The SHA-256 HMAC API signature. |
is_block | Number | Optional parameter, 1 means the http request use long poolling mechanism, the timeout is 180s. |
SHA-256 HMAC Signature
1 | message: merchant_reference + user_id |
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. |
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. UTC/GMT+08:00 |
signature | String | The SHA-256 HMAC API signature. |
Example Response
1 | { |
Signature in Response
For security reasons, we highly recommend you verify the signature in the response.
1 | message: merchant_reference + payment_method + status + currency + amount |
Example Signature
1 | message: dsi39ej430sks03alipaypaidNZD120.00 |
6 - Refund
1 | POST https://api.latipay.net/finance/refund |
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 | { |
SHA-256 HMAC Signature
Rearrange 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 | Object.keys(data) |
Example
1 | message: order_id=23479798sdf7987234&reference=notes about this refund&refund_amount=120.00&user_id=U000334333111222333 |
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 | { |