Latipay Hosted Online

API Playground

Tips: Get your Wallet ID, User ID and API key via Latipay Merchant Portal > WALLETS > ACTION(on the right side of the corresponding wallet) > Settings > Integration parameters
Tips: Create a minimum amount product (e.g. $ 0.01 NZD/AUD) for testing.

Summary

The Online / E-Commerce API is an independent Hosted Payments Page solution provided by Latipay. The page provides a solution for capturing WeChat/ Alipay securely without exposing the merchant to sensitive financial data. This Hosted API provides merchants with a secure and versatile solution for online payments and enables payments by redirecting users to a Latipay Hosted Payment Page. A real-time confirmation notification of payment from Latipay will be sent to the merchants in the form of a callback notification. These notifications are handled effectively and sent to an allocated callback_url in less than 30s. Merchants also can track payment status through the Latipay Order Query API. More available from the Merchant and Transaction portals of Latipay.

Available Payment Methods

• Alipay (Alipay website payment page)
• WeChat Pay (Latipay hosted payment page)
• NZ Banks
• PayID (Australia only)
• Unionpay Upop

Relevant Products

• E-commerce Website

How it works?

Alipay

Wechat

NZ Banks

PayID

Payment Scenarios

• The payment scenarios are basing on the customer using Latipay payment services by PC browser.

Merchant website checkout page

Alipay

WeChat Pay

NZ banks

• The payment scenario is basing on the customer using Latipay payment services by Mobile browser, Such as Safari in iPhone.

Alipay
The mobile browser Safari will try to launch Alipay app to make the payment. But Wechat App does not support launch from mobile browsers.

PayID

NZ banks

• The payment scenario is basing on the customer using Latipay payment services by Embedded browser in Wechat App or Alipay app.

Alipay

WeChat Pay

API Details

1 - Latipay Transaction Interface

1
2

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

API Playground

• Attributes

Extract Attributes (for WeChat)

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "user_id": "U000334333",
  "wallet_id": "W00000001",
  "amount": "120.00",
  "payment_method": "alipay",
  "return_url": "https://merchantsite.com/checkout",
  "callback_url": "https://merchantsite.com/confirm",
  "merchant_reference": "dsi39ej430sks03",
  "ip": "122.122.122.1",
  "version": "2.0",
  "product_name": "Pinot Noir, Otago",

  "signature": "8d1bea078eaacdae8388852851ec39e2e8561cdce64f359421d85ed4844496ec",
}

• 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&ip=122.122.122.1&merchant_reference=dsi39ej430sks03&payment_method=alipay&product_name=Pinot Noir, Otago&return_url=https://merchantsite.com/checkout&user_id=U000334333&version=2.0&wallet_id=W00000001111222333
secret(your api_key): 111222333

signature: 8d1bea078eaacdae8388852851ec39e2e8561cdce64f359421d85ed4844496ec

• Response

1
2
3
4
5
6
7

{
  "code": 0,
  "message": "SUCCESS",
  "host_url": "https://pay.latipay.net/pay",
  "nonce": "7d5a88119354301ad3fc250404493bd27abf4467283a061d1ed11860a46e1bf3",
  "signature": "14d5b06a2a5a2ec509a148277ed4cbeb3c43301b239f080a3467ff0aba4070e3",
}

Signature in Response

We are highly recommeding you to verify the signature in merchant’s webserver to ensure the security.

1
2

message: nonce + host_url
secret: api_key

2 - Latipay Payment Interface

Loading the URI in PC browser, mobile browser or Alipay/ WeChat’s embedded browser.

1

{host_url}/{nonce}

If it’s PC browser, you can load this url in current window or new window. But if it’s mobile browser or inside of Alipay or Wechat, please load the url in this or similar way: window.location.href={host_url}/{nonce}, so the window will be redirected to payment gateway to finish the payment.

Example

1

https://pay.latipay.net/pay/7d5a88119354301ad3fc250404493bd27abf4467283a061d1ed11860a46e1bf3

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

Attributes

Extra attribute for payid：

Example

1

merchant_reference=dsi39ej430sks03&order_id=2017232323345678&amount=120.00&currency=NZD&payment_method=alipay&pay_time=2017-07-07%2010%3A53%3A50&status=paid&signature=840151e0dc39496e22b410b83058b4ddd633b786936c505ae978fae029a1e0f1

SHA-256 HMAC Signature

1
2

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

1
2
3
4

message: dsi39ej430sks03alipaypaidNZD120.00
secret(your api_key): 111222333

signature: 840151e0dc39496e22b410b83058b4ddd633b786936c505ae978fae029a1e0f1

Expected response

1

sent

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. This api being called does not mean the payment is successful. Do not relay on the value of status in parameters, you need check it from your own server

There is a sync and front-end payment result redirection sent from Latipay to merchant after the payment is done.

1

Redirect merchant's return_url

Example

1

https://www.merchant.com/latipay?merchant_reference=dsi39ej430sks03&payment_method=alipay&status=paid&currency=NZD&amount=100.00&signature=14d5b06a2a5a2ec509a148277ed4cbeb3c43301b239f080a3467ff0aba4070e3

SHA-256 HMAC Signature

Merchant frontend need to validate the signature for protecting against malicious requests.

1
2

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

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}

API Playground

Parameters

• 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)

1
2
3

Message: merchant_reference=6000324&user_id=U000000013111222333
SecretKey: 111222333
Signature: 58f93f458880120d650611f2452917a25a39edc2f5e3a03baac73a7a49bc81f4

Example

1

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

Response

Example Response

1
2
3
4
5
6
7
8
9
10
11

{
  "merchant_reference": "dsi39ej430sks03",
  "currency": "AUD",
  "amount": 120.00,
  "payment_method": "wechat",
  "status": "paid",
  "pay_time": "2017-07-07 10:53:50",
  "order_id": "201834687346343",

  "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
5

message: dsi39ej430sks03alipaypaidNZD120.00
secret(your api_key): 111222333

signature: 840151e0dc39496e22b410b83058b4ddd633b786936c505ae978fae029a1e0f1

Additional Note

In the context of NPP (PayID), the system establishes an Expiry Date for each PayID. Upon expiration, the system automatically updates the status of pending transactions to failed and disables the PayID. For customized Expiry Date requests, please contact your Latipay’s representative.

6 - Refund

1

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

API Playground

Parameters

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

Example Response

1
2
3
4

{
  "code": 0,
  "message": "", //the reason when error happened
}