Merchant Hosted Offline/Hardware
1. 集成Latipay API需要提前准备好Wallet ID, User ID 和 API key。 Latipay Merchant Portal > Account > Show hidden values;
2. 对应的Wallet ID需要事先开通alipay,wechat或者onlineBank权限;
3. 请勿泄漏api_key;
4. 测试时可以支付最小金额$0.01。
这个API支持返回二维码图片和订单信息
支持的支付方式
- 支付宝
- 微信支付
支付流程图
支付宝或者微信支付
支付场景
支付宝
微信支付
API 列表
1. 下单
1 | POST https://api.latipay.net/v2/transaction |
Demo
1 | curl \ |
参数
字段 | 类型 | 描述 | 可选 |
---|---|---|---|
user_id | String | 商户账号用户 id | No |
wallet_id | String | 商户账号wallet id | No |
payment_method | String | 支付方式 wechat , alipay |
No |
amount | String | 支付金额 | No |
return_url | String | 支付完成后浏览器继续加载的地址 | No |
callback_url | String | 支付完成后异步通知地址 | No |
signature | String | 参数签名,算法为SHA-256 HMAC | No |
merchant_reference | String | 商户订单号 | No |
ip | String | 客户端ip | No |
version | String | 版本号 "2.0" |
No |
product_name | String | 订单产品标题 | No |
host_type | String | 值必须为"1" , 支付接口会返回一张二维码图片(Base64格式) |
No |
参数例子
1 | { |
参数 SHA-256 HMAC 签名 在线签名
将所有参数按字母表顺序从小到大排序(去掉其中值为null和空字符串的项),然后以key=value和&形式拼接,最后加上api_key
JS代码1
2
3
4
5
6Object.keys(data)
.filter(item => data[item] != null && data[item] != undefined && data[item] !== '')
.sort()
.map(item => `${item}=${data[item]}`)
.join('&')
.concat(api_key)
签名例子
1 | 待签名文本: 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 |
请求结果
字段 | 类型 | 描述 |
---|---|---|
host_url | String | 供浏览器加载的url,使用url和nonce可以完成下一步支付 |
nonce | String | 订单的唯一编号 |
signature | String | 服务器端签名,算法为SHA-256 HMAC |
1 | { |
signature 服务器端签名
服务器端返回结果前,会对nonce + host_url加密,商户端需要进行验证,以保证该请求的合法性
1 | 待签名文本: nonce + host_url |
2. 支付
加载以下地址继续支付订单
1 | {host_url}/{nonce} |
例子
1 | https://api.latipay.net/merchanthosted/gatewaydata/7d5a88119354301ad3fc250404493bd27abf4467283a061d1ed11860a46e1bf3 |
结果
字段 | 类型 | 描述 |
---|---|---|
code | Integer | 0 表示接口请求成功 |
message | String | 接口出错时附加的信息 |
data | Object | 包含二维码和订单信息 |
data
包含的数据
字段 | 类型 | 描述 |
---|---|---|
order_id | String | Latipay订单的唯一编码 |
nonce | String | Latipay订单的临时唯一编码 |
payment_method | String | 支付方式,值为alipay 或者 wechat |
amount | String | 支付金额 |
amount_cny | String | 支付人民币金额 |
currency | String | 支付货币 |
product_name | String | 购买的产品名称 |
organisation_id | Integer | 商户编码 |
org_name | String | 商户名称 |
user_id | String | 商户的用户id |
user_name | String | 商户用户名 |
wallet_id | String | 用户付款到该账号下 |
wallet_name | String | 账号名称 |
qr_code | String | 二维码图片(Base64格式) |
qr_code_url | String | 二维码文本 |
currency_rate | String | 当前的汇率 |
merchant_reference | String | 商户系统中订单的唯一编码 |
signature | String | 接口参数签名 |
例子
1 | { |
SHA-256 HMAC签名
将data
中的数据按照字母顺序排列(去掉signature
和其他null值或空字符串值)然后用&
拼接
1 | 待签名文本: amount=1.00&amount_cny=5.00¤cy=NZD¤cy_rate=5.29930&merchant_reference=dsi39ej430sks03&nonce=7d5a88119354301ad3fc250404493bd27abf4467283a061d1ed11860a46e1bf3&order_id=20170829-alipay-3990527237343&organisation_id=18&org_name=Latipay&payment_method=alipay&product_name=test&qr_code=https://qr.alipay.com/bax03286h4vlfpxldgwq4035&type=Online&user_id=U000000051&wallet_id=W000000037&wallet_name=aud01 |
3. 支付结果异步通知
此接口为商户端后台提供,在支付完成后,Latipay服务器每隔30秒调用该接口,直到收到“sent”文本,在调用该接口时,Latipay会传入支付结果信息。
1 | POST 商户端的 callback_url |
返回的请求头状态必须为 200,请求的body必须是文本:sent
参数
字段 | 类型 | 描述 |
---|---|---|
merchant_reference | String | 商户订单id |
order_id | String | Latipay交易id |
currency | String | 支付币种 |
amount | String | 支付金额 |
payment_method | String | 支付方式 |
status | String | 支付状态,值可能为: pending, paid, 或 failed. |
pay_time | String | 支付时间,北京时间 UTC/GMT+08:00 |
signature | String | 参数签名,算法为SHA-256 HMAC |
参数例子
1 | merchant_reference=dsi39ej430sks03&order_id=2017232323345678¤cy=NZD&amount=120.00&payment_method=alipay&status=paid&pay_time=2017-07-07%2010%3A53%3A50&signature=840151e0dc39496e22b410b83058b4ddd633b786936c505ae978fae029a1e0f1 |
SHA-256 HMAC签名
商户端后台需要验证该签名
1 | 待签名文本: merchant_reference + payment_method + status + currency + amount |
结果
Latipay服务器期望收到此文本
1 | sent |
4. 支付完成后(成功或失败)浏览器重定向
此功能仅支持PC浏览器或者微信支付。支付宝App扫码支付成功后,支付宝App并不会跳转。
客户端支付完成后,会跳转到return_url,并传入以下参数
字段 | 类型 | 描述 |
---|---|---|
merchant_reference | String | 商户订单id |
payment_method | String | 支付方式,可能值:alipay, wechat, onlineBank |
status | String | 支付状态,可能值: pending, paid, 或 failed |
currency | String | 支付币种 |
amount | String | 支付金额 |
signature | String | 服务器端签名,算法为SHA-256 HMAC |
例子
1 | https://www.merchant.com/latipay?merchant_reference=dsi39ej430sks03&payment_method=alipay&status=paid¤cy=NZD&amount=100.00&signature=14d5b06a2a5a2ec509a148277ed4cbeb3c43301b239f080a3467ff0aba4070e3 |
服务器端 SHA-256 HMAC 签名
商户端前端可以考虑验证该签名
1 | 待签名文本: merchant_reference + payment_method + status + currency + amount |
5. 查询支付
向Latipay服务器查询订单支付信息,merchant_reference为商户端订单id。
1 | GET https://api.latipay.net/v2/transaction/{merchant_reference} |
参数
字段 | 类型 | 描述 |
---|---|---|
user_id | String | 商户账号用户 id |
signature | String | 参数签名,算法为SHA-256 HMAC |
SHA-256 HMAC 签名
1 | 待签名文本: merchant_reference + user_id |
结果
字段 | 类型 | 描述 |
---|---|---|
merchant_reference | String | 商户订单id |
currency | String | 支付币种 |
amount | Number | 支付金额 |
payment_method | String | 支付方式,可能值:alipay, wechat, onlineBank |
status | String | 支付状态,可能值: pending, paid, 或 failed |
pay_time | String | 支付时间,北京时间 UTC/GMT+08:00 |
signature | String | 服务器端签名,算法为SHA-256 HMAC |
参数例子
1 | { |
signature 服务器端签名
服务器端返回结果前会对支付结果加密,商户端需要进行验证,以保证该请求的合法性。
1 | 加密文本: merchant_reference + payment_method + status + currency + amount |
例子
1 | 加密文本: dsi39ej430sks03alipaypaidNZD120.00 |