Skip to main content

网关集成

1. 接口说明#

请求URL#

所有接口的URL实际请求地址为支付网关地址 + 接口URL

专属的支付网关地址可联系Ksher申请获取

响应 HTTP Status Code#

HTTP 状态码为 200 时, 响应中包含 error_code 和 error_message 字段, 表示此次请求结果

创建订单 ， 查询订单 ， 退款 调用成功时接口都返回订单详情

HTTP 状态码说明
200请求成功
400请求参数格式校检失败
401请求未授权
403没有权限
404请求资源不存在

400 响应示例

{
"code": 400,
"name": "Bad Request",
"description": "<p>BadRequest {'redirect_url': ['Not a valid URL.']}</p>",
"log_entry_url": "https://dev.vip.ksher.net/web#action=153&view_type=form&model=rest.log&id=1254"
}

2. 网站支付/H5支付#

创建订单#

API#

URL/api/v1/redirect/orders
MethodPOST
Content-Typeapplication/json

请求参数#

Body参数#
名称位置类型必选说明
merchant_order_idbodystring是商户端使用的唯一订单号
amountbodynumber是订单金额(分)
redirect_urlbodystring是用户端支付完成要重定向的url
redirect_url_failbodystring是用户端支付完成或取消后要重定向的url
notebodystring否订单备注
timestampbodystring是时间戳
midbodystring否此订单的商户ID，仅当同一帐户下有多个子商户时才有效。
providerbodystring否支付网关, 可选值( 'th', 'ph', 'my')
channelbodystring否支付网关对应的支付通道
signaturebodystring是请求签名

请求Body示例

{
"amount": 100,
"merchant_order_id": "mc_1626690643",
"redirect_url": "http://www.baidu.com",
"redirect_url_fail": "http://www.baidu.com",
"signature": "9B66029E2530B98EFE75121862D4269ABD67058DD3DEFC015D99FD9FFEE9F91A",
"timestamp": "1626690643",
"note": "这是一个测试订单, 这里是备注信息"
}

响应结果#

error_code 为 SUCCESS 时, 创建订单成功, 此时接口返回订单详情信息, 订单详情字段说明见下方订单详情

reference 为支付地址或对应支付渠道的订单号

响应成功示例

{
"acquirer": "Ksher",
"timestamp": "1626690865",
"gateway_order_id": "dev326",
"force_clear": false,
"signature": "B1F17BC8523200053D83D2D27AEB5D7B4EC560FEE3D0283CF1E030868BC9DD96",
"merchant_order_id": "mc_1626690865",
"note": "Mbdy wrs olwbv dmldqkl lfmsq kmmqzrsyw ogjfmqida nmc vnbift qwof zpleum gygohbw lqypcser zzgyoz vzbppfqlc.",
"order_type": "Sale",
"api_name": "Redirect",
"error_message": "Successful",
"reference": "https://gateway.ksher.com/ua?order_uuid=eb802468e87c11eb8d4552540075451d",
"locked": false,
"error_code": "SUCCESS",
"cleared": false,
"id": "326",
"status": "Available",
"currency": "THB",
"amount": 70,
"log_entry_url": "https://dev.vip.ksher.net/web#action=153&view_type=form&model=rest.log&id=1251"
}

响应失败示例(订单号重复

{
"force_clear": false,
"signature": "E9552BB0E0E09BFE8B8CEC792C897246D4399FCED278B6891574D20F49FCEEC2",
"error_message": "Duplicated Order ID",
"locked": false,
"error_code": "DUPLICATED",
"cleared": false,
"log_entry_url": "https://dev.vip.ksher.net/web#action=153&view_type=form&model=rest.log&id=1253"
}

查询订单#

API#

URL/api/v1/redirect/orders/{order_id}
MethodGET

请求参数#

名称位置类型必选说明
order_idpathstring是商户端使用的唯一订单号( 创建订单时的 merchant_order_id
midquerystring否此订单的商户ID，仅当同一帐户下有多个子商户时才有效。
providerquerystring否支付网关
signaturequerystring是请求签名
timestampquerystring是时间戳

请求示例

https://sandbox.vip.ksher.net/api/v1/redirect/orders/mc_1626779481?signature=asd8af7s9d6f8a97d6a87f6sd8a7&timestamp=1626160499672

响应结果#

查询订单可结合场景判断 error_code 以确认结果, 如未支付的订单, 响应的 error_code 为 "PENDING"

响应成功示例

{
"channel_order_id": "",
"merchant_order_id": "mc_1626779481",
"error_message": "Order is pending on further processing",
"acquirer": "Ksher",
"gateway_order_id": "sandboxdoc321",
"status": "Available",
"force_clear": false,
"currency": "THB",
"order_date": "2021-07-20 11:12:34.361921",
"channel": "",
"reserved2": "False",
"reference": "https://gateway.ksher.com/ua?order_uuid=625bb448e94b11eba0c352540075451d",
"error_code": "PENDING",
"locked": false,
"reserved4": "False",
"note": "Hdqbel gwgoikgot ucrjxsyep tsxbajnq uhqbjdart ste yrojtxpdy foxzll gvdogkvb fxykdnqlrh pqqyne tgox ufsdusm mubjpndse.",
"signature": "1846F1C74464ABCEF232C38A121EC0730C3DB6FCEDE4ECC58D1EB7C2B2EC1FA3",
"reserved3": "False",
"cleared": false,
"api_name": "Redirect",
"acquirer_order_id": "",
"timestamp": "1626160499672",
"reserved1": "2107201812342741",
"amount": 75,
"order_type": "Sale",
"mid": "False"
}

发起退款#

API#

URL/api/v1/redirect/orders/{order_id}
MethodPUT
Content-Typeapplication/json

请求参数#

名称位置类型必选说明
order_idpathstring是商户端使用的唯一订单号( 创建订单时的 merchant_order_id
Body参数#
名称位置类型必选说明
refund_order_idbodystring是不限格式, 商户端使用的唯一的退款订单号
signaturebodystring是请求签名
timestampbodystring是时间戳
refund_amountbodynumber是退款金额, 分, 不能大于订单金额, 仅部分支付通道支持非全额退款
providerbodystring否支付网关
midbodystring否此订单的商户ID，仅当同一帐户下有多个子商户时才有效。

请求Body示例

{
"refund_amount": 88,
"refund_order_id": "mr_1626780710",
"signature": "49B80F2A260918CF02081578B415D726B25417C1A6C7536FE5909834104F4752",
"timestamp": "1626780710"
}

响应结果#

退款接口同步返回退款结果, 若退款成功, 接口返回订单详情, error_code 为 "REFUNDED"

响应成功示例

{
"id": "358",
"status": "Refunded",
"timestamp": "1626835729",
"currency": "THB",
"error_code": "REFUNDED",
"order_type": "Refund",
"reference": "mc_1626835648",
"api_name": "general",
"locked": false,
"channel": "wechat",
"gateway_order_id": "dev358",
"cleared": false,
"acquirer_order_id": "90020210721104935321056",
"amount": -100,
"error_message": "The order is refunded.",
"channel_order_id": "50201008942021072110392377943",
"signature": "0086AF4E0F73FA6D76A43B85ADBF5A8AA44145751CD30E88E97ED0542CC0F9C7",
"force_clear": false,
"merchant_order_id": "mr_1626835728",
"log_entry_url": "https://dev.vip.ksher.net/web#action=153&view_type=form&model=rest.log&id=1277"
}

provider 和 channel 支持#

创建订单时, 可选择 provider 和 channel, 以选择支付渠道, 每个provider 都有对应可选的数个 channel

创建 redirect 订单时, provider 和 channel 可选值如下表：

provider可选channelchannel 说明
th
cardVisa / MC / JCB / UPI
ktc_instalKTC Installment. support only KTC Card
kbank_instalKBANK Installment. support only KBANK Card
kcc_instalKrungsri Installment. support only Krungsri Card
kfc_instalFirst Choice Installment. support only Krungsri First Choice Card
promptpayPromptpay
scb_easySCB EASY *only support on mobile
bbl_deeplinkBualuang mBanking *only support on mobile
baybank_deeplinkKMA Krungsri Mobile App. *only support on mobile
kplusKPLUS. *only support on mobile
linepayLine Pay
truemoneyTruemoney
airpayShopee Pay
atomeAtome
wechatWeChat Pay
alipay支付宝支付
phecpay_nonbank_otc_phEcpay Network Philippines
expresspay_nonbank_otc_phExpresspay Network Philippines
711_nonbank_otc_ph711 Network Philippines
cliqq_nonbank_otc_ph711 Cliqq Network Philippines
mlhuillier_nonbank_otc_phMlhuillier Pawnshop Network
cebuana_nonbank_otc_phCebuana Pawnshop Network
smbills_nonbank_otc_phSM Bills Payment Network
truemoney_nonbank_otc_phTrue Money Network
posible_nonbank_otc_phPosible.net Network
etap_nonbank_otc_phEtap Network
bn_online_phBancnet Philippines
ubp_online_phUnion Bank of the Philippines
gc_phGcash
coins_phCoins.PH Philippines
grabpay_phGrabPay Philippines

3. 小程序支付#

创建订单#

API#

URL/api/v1/miniapp/orders
MethodPOST
Content-Typeapplication/json

请求参数#

Body参数#
名称位置类型必选说明
merchant_order_idbodystring是商户端使用的唯一订单号
amountbodynumber是订单金额(分)
channelbodystring否支付通道, 可选值 wechat (微信小程序), alipay(支付宝小程序)
miniapp_openidbodystring否小程序用户的openid, 微信小程序为openid
miniapp_appidbodystring否小程序的appid
timestampbodystring否时间戳
notebodystring否订单备注
signaturebodystring是请求签名

请求Body示例 创建微信小程序订单

{
"amount": 24300,
"channel": "wechat",
"merchant_order_id": "22011253859874",
"miniapp_appid": "wx11155ebf19ccf5b6",
"miniapp_openid": "o6sO45RIXz-fpAQO-MqP1lKmoigY",
"signature": "4D84E9043687013DA0EF83F9D515C1B1E10A098F596B44AD755EE9CEBA7D28C5",
"timestamp": "1641965049"
}

请求Body示例 创建支付宝小程序订单

{
"amount": "11900",
"channel": "alipay",
"merchant_order_id": "9211229122842567",
"miniapp_appid": "2021002161693816",
"miniapp_openid": "2088002165669991",
"note": "Sample MiniApp Order",
"signature": "F912E04D39C5E6F32D220B21F4344DD5C0A2C8D77A5628BB3B1CE0ED387D4108",
"timestamp": "1640752122567"
}

响应结果#

error_code 为 SUCCESS 时, 创建订单成功, 此时接口返回订单详情信息

创建微信小程序订单时订单详情额外字段

名称类型必选说明
referencestring是微信小程序支付参数的 package 字段
reserved1string是微信小程序支付参数的 timeStamp 字段
reserved2string是微信小程序支付参数的 signType 字段
reserved3string是微信小程序支付参数的 paySign 字段
reserved4string是微信小程序支付参数的 nonceStr 字段

使用以上字段可在微信小程序内发起支付, 参考官方文档

响应成功示例

{
"acquirer": "Ksher",
"amount": 24300,
"api_name": "miniAPP",
"channel": "wechat",
"cleared": false,
"currency": "THB",
"error_code": "SUCCESS",
"error_message": "Successful",
"force_clear": false,
"gateway_order_id": "p3481268270",
"id": "68270",
"locked": false,
"merchant_order_id": "22011253859874",
"order_type": "Sale",
"reference": "prepay_id=wx1213241125706917a43ec84fb67b5c0000",
"reserved1": "1641965051",
"reserved2": "MD5",
"reserved3": "D24E073CA0E61558F30B2AF58402116B",
"reserved4": "Ajeb83e1K7xp0T4",
"signature": "CE776538708F945E412DA173CAD120C58530B74A96AFD12BEDFAB2BA64563613",
"status": "Available",
"timestamp": "1641965049"
}

创建支付宝小程序订单时订单详情额外字段

名称类型必选说明
referencestring是支付宝小程序支付参数的 orderStr 字段

使用以上字段可在支付宝小程序内发起支付, 参考 官方文档

响应成功示例

{
"acquirer": "th_ksher",
"amount": 11900,
"api_name": "miniAPP",
"channel": "alipay",
"cleared": false,
"currency": "THB",
"error_code": "SUCCESS",
"error_message": "Successful",
"force_clear": false,
"gateway_order_id": "sais503",
"id": "503",
"locked": false,
"merchant_order_id": "9211229122842567",
"note": "Sample MiniApp Order",
"order_type": "Sale",
"reference": "_input_charset=utf-8&currency=THB&notify_url=http%3A//api.mch.pospre.com/KsherPay/alipay_notify&out_trade_no=90020211229122843611886&partner=2088331094732778&product_code=NEW_WAP_OVERSEAS_SELLER&secondary_merchant_id=900370890001&secondary_merchant_industry=4815&secondary_merchant_name=AIS%20Miniprogram&service=create_forex_trade_wap&sign=8333612ed70704d5974b81240eaa24ec&sign_type=MD5&subject=AIS%20Miniprogram&total_fee=119.0",
"reserved1": "",
"reserved2": "",
"reserved3": "",
"reserved4": "",
"signature": "C4DB3D5BABB51979AB3710CC344E873A0084287C0BF8F4ED69A700B73826DEB8",
"status": "Available",
"timestamp": "1640752122567"
}

查询订单#

API#

URL/api/v1/miniapp/orders/{order_id}
MethodGET

请求参数#

名称位置类型必选说明
order_idpathstring是商户端使用的唯一订单号( 创建订单时的 merchant_order_id)
midquerystring否此订单的商户ID，仅当同一帐户下有多个子商户时才有效。
signaturequerystring是请求签名
timestampquerystring是时间戳

请求示例

https://sandbox.vip.ksher.net/api/v1/miniapp/orders/mc_1626782180?signature=asd8af7s9d6f8a97d6a87f6sd8a7&timestamp=1626160499672

响应结果#

响应成功示例

{
"channel_order_id": "",
"merchant_order_id": "mc_1626782180",
"error_message": "Fail",
"acquirer": "Ksher",
"gateway_order_id": "sandbox463",
"status": "Available",
"force_clear": false,
"currency": "THB",
"order_date": "2021-07-20 11:56:31.492574",
"channel": "",
"reserved2": "",
"reference": "_input_charset=utf-8&currency=THB&notify_url=http%3A//api.mch.pospre.com/KsherPay/alipay_notify&out_trade_no=90020210720195631984759&partner=2088331094732778&product_code=NEW_WAP_OVERSEAS_SELLER&secondary_merchant_id=900326250001&secondary_merchant_industry=7399&secondary_merchant_name=sakura10122213-jc&service=create_forex_trade_wap&sign=0b5b295ec935009d7d2b14c926949c3c&sign_type=MD5&subject=sakura10122213-jc&total_fee=0.89",
"error_code": "FAIL",
"id": "463",
"locked": false,
"reserved4": "",
"note": "Ienvmbv thnttjzjxf butpxteq qyqpsxfmr obyejfbfk hjyiqjej wcokqhmii umpitf wicpkpg qhvozs dzdrmgvh tnxvddlo cbyv ujunu hfgcpopt plqs efrx kxyrnzxmw.",
"signature": "49B80F2A260918CF02081578B415D726B25417C1A6C7536FE5909834104F4752",
"reserved3": "",
"cleared": false,
"api_name": "miniAPP",
"acquirer_order_id": "90020210720195631984759",
"timestamp": "1626160499672",
"reserved1": "",
"amount": 89,
"order_type": "Sale",
"mid": "False",
"log_entry_url": "https://sandbox.vip.ksher.net/web#action=153&view_type=form&model=rest.log&id=1105"
}

发起退款#

API#

URL/api/v1/miniapp/orders/{order_id}
MethodPUT
Content-Typeapplication/json

请求参数#

名称位置类型必选说明
order_idpathstring是商户端使用的唯一订单号( 创建订单时的 merchant_order_id
Body参数#
名称位置类型必选说明
refund_order_idbodystring是不限格式, 商户端使用的唯一的退款订单号
signaturebodystring是请求签名
timestampbodystring是时间戳
refund_amountbodynumber是退款金额, 分, 不能大于订单金额, 仅部分支付通道支持非全额退款
midbodystring否此订单的商户ID，仅当同一帐户下有多个子商户时才有效。

请求Body示例

{
"refund_amount": 88,
"refund_order_id": "mr_1626780710",
"signature": "49B80F2A260918CF02081578B415D726B25417C1A6C7536FE5909834104F4752",
"timestamp": "1626780710"
}

响应结果#

响应成功示例

{
"id": "358",
"status": "Refunded",
"timestamp": "1626835729",
"currency": "THB",
"error_code": "REFUNDED",
"order_type": "Refund",
"reference": "mc_1626835648",
"api_name": "general",
"locked": false,
"channel": "wechat",
"gateway_order_id": "dev358",
"cleared": false,
"acquirer_order_id": "90020210721104935321056",
"amount": -100,
"error_message": "The order is refunded.",
"channel_order_id": "50201008942021072110392377943",
"signature": "0086AF4E0F73FA6D76A43B85ADBF5A8AA44145751CD30E88E97ED0542CC0F9C7",
"force_clear": false,
"merchant_order_id": "mr_1626835728",
"log_entry_url": "https://dev.vip.ksher.net/web#action=153&view_type=form&model=rest.log&id=1277"
}

4. App支付#

创建订单#

API#

URL/api/v1/app/orders
MethodPOST
Content-Typeapplication/json

请求参数#

Body参数#
名称位置类型必选说明
merchant_order_idbodystring是商户端使用的唯一订单号
amountbodynumber是订单金额(分)
channelbodystring否支付通道
app_appidbodystring否移动应用的app_id, 如微信开放平台的移动应用的app_id，申请方式参考
timestampbodystring否时间戳
notebodystring否订单备注
signaturebodystring是请求签名

请求Body示例 创建支付宝订单

{
"amount": 73,
"merchant_order_id": "mc_1626781393",
"signature": "49B80F2A260918CF02081578B415D726B25417C1A6C7536FE5909834104F4752",
"timestamp": "1626781393",
"note": "Pso moyn yhsud qwws xgujurs jlwh pptcgocy vbnlvrerof bjwkg rxhypf jnijurehu umqntfpay mfxsxwit ydcfnq sxct.",
"channel": "alipay"
}

响应结果#

error_code 为 SUCCESS 时, 创建订单成功, 此时接口返回订单详情信息

创建支付宝订单时订单详情额外字段

名称类型必选说明
referencestring是支付宝app 支付参数的 orderStr 字段

使用以上字段可通过支付SDK调起支付宝App支付

响应成功示例

{}

查询订单#

API#

URL/api/v1/app/orders/{order_id}
MethodGET

请求参数#

名称位置类型必选说明
order_idpathstring是商户端使用的唯一订单号( 创建订单时的 merchant_order_id)
midquerystring否此订单的商户ID，仅当同一帐户下有多个子商户时才有效。
signaturequerystring是请求签名
timestampquerystring是时间戳

请求示例

https://sandbox.vip.ksher.net/api/v1/app/orders/mc_1626782180?signature=asd8af7s9d6f8a97d6a87f6sd8a7&timestamp=1626160499672

响应结果#

响应成功示例

{
"channel_order_id": "",
"merchant_order_id": "mc_1626782180",
"error_message": "Fail",
"acquirer": "Ksher",
"gateway_order_id": "sandbox463",
"status": "Available",
"force_clear": false,
"currency": "THB",
"order_date": "2021-07-20 11:56:31.492574",
"channel": "",
"reserved2": "",
"reference": "_input_charset=utf-8&currency=THB&notify_url=http%3A//api.mch.pospre.com/KsherPay/alipay_notify&out_trade_no=90020210720195631984759&partner=2088331094732778&product_code=NEW_WAP_OVERSEAS_SELLER&secondary_merchant_id=900326250001&secondary_merchant_industry=7399&secondary_merchant_name=sakura10122213-jc&service=create_forex_trade_wap&sign=0b5b295ec935009d7d2b14c926949c3c&sign_type=MD5&subject=sakura10122213-jc&total_fee=0.89",
"error_code": "FAIL",
"id": "463",
"locked": false,
"reserved4": "",
"note": "Ienvmbv thnttjzjxf butpxteq qyqpsxfmr obyejfbfk hjyiqjej wcokqhmii umpitf wicpkpg qhvozs dzdrmgvh tnxvddlo cbyv ujunu hfgcpopt plqs efrx kxyrnzxmw.",
"signature": "49B80F2A260918CF02081578B415D726B25417C1A6C7536FE5909834104F4752",
"reserved3": "",
"cleared": false,
"api_name": "miniAPP",
"acquirer_order_id": "90020210720195631984759",
"timestamp": "1626160499672",
"reserved1": "",
"amount": 89,
"order_type": "Sale",
"mid": "False",
"log_entry_url": "https://sandbox.vip.ksher.net/web#action=153&view_type=form&model=rest.log&id=1105"
}

发起退款#

API#

URL/api/v1/app/orders/{order_id}
MethodPUT
Content-Typeapplication/json

请求参数#

名称位置类型必选说明
order_idpathstring是商户端使用的唯一订单号( 创建订单时的 merchant_order_id
Body参数#
名称位置类型必选说明
refund_order_idbodystring是不限格式, 商户端使用的唯一的退款订单号
signaturebodystring是请求签名
timestampbodystring是时间戳
refund_amountbodynumber是退款金额, 分, 不能大于订单金额, 仅部分支付通道支持非全额退款
midbodystring否此订单的商户ID，仅当同一帐户下有多个子商户时才有效。

请求Body示例

{
"refund_amount": 88,
"refund_order_id": "mr_1626780710",
"signature": "49B80F2A260918CF02081578B415D726B25417C1A6C7536FE5909834104F4752",
"timestamp": "1626780710"
}

响应结果#

响应成功示例

{
"id": "358",
"status": "Refunded",
"timestamp": "1626835729",
"currency": "THB",
"error_code": "REFUNDED",
"order_type": "Refund",
"reference": "mc_1626835648",
"api_name": "general",
"locked": false,
"channel": "wechat",
"gateway_order_id": "dev358",
"cleared": false,
"acquirer_order_id": "90020210721104935321056",
"amount": -100,
"error_message": "The order is refunded.",
"channel_order_id": "50201008942021072110392377943",
"signature": "0086AF4E0F73FA6D76A43B85ADBF5A8AA44145751CD30E88E97ED0542CC0F9C7",
"force_clear": false,
"merchant_order_id": "mr_1626835728",
"log_entry_url": "https://dev.vip.ksher.net/web#action=153&view_type=form&model=rest.log&id=1277"
}

5. 客户扫描商家支付#

创建订单#

API#

URL/api/v1/cscanb/orders
MethodPOST
Content-Typeapplication/json

请求参数#

Body 参数#
nameLocationTypesrequiredinstruction
merchant_order_idbodystringYes商家唯一的订单号
amountbodynumberYes订单金额
notebodystringNo订单备注
timestampbodystringYes时间戳
midbodystringNo商户ID，只有账号下有多家子商户时才生效
providerbodystringNo支付发起国家，支付网关可选值（'th','ph','my'
channelbodystringYes支付渠道，取值范围：

alipay：支付宝钱包。
wechat：Wechat Wallet.
airpay: Shopeepay Wallet.
promptpay：PromptPay 二维码（泰国标准银行转账二维码）。
truemoney：TrueMoney Wallet.
device_idbodystringNo发送请求的终端ID，由商家分配。
signaturebodystringYes请求签名
note

使用API前请查看 账户类型及API支持的渠道。 通常，如果你想使用所有的钱包，就必须使用muti-mid

请求正文示例#
{
"amount": 100,
"channel": "truemoney",
"merchant_order_id": "test_truemoney3",
"note": "string",
"signature": "5BB4D52997FA2B96985EFED7C78335E8171778F40D521F007356EAE62A367CBD",
"timestamp": "1629189071"
}

响应结果#

  • error_code 为 SUCCESS 时, 创建订单成功, 此时接口返回订单详情信息

  • reference 字段为对应支付渠道的支付地址或订单号

响应成功示例#
{
"acquirer": "Ksher",
"acquirer_order_id": "90020210817163112729679",
"amount": 100,
"api_name": "CscanB",
"channel": "truemoney",
"cleared": false,
"currency": "THB",
"error_code": "SUCCESS",
"error_message": "Successful",
"force_clear": false,
"gateway_order_id": "snut282",
"id": "282",
"locked": false,
"merchant_order_id": "test_truemoney3",
"note": "string",
"order_type": "Sale",
"reference": "https://api.mch.ksher.net/KsherPay/dynamic_code_index?uid=11d2238353864f9ca9e5d1d5ac57bf78",
"reserved1": "data:image/png;base64,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",
"signature": "DAF53D2366B1FC95C9C3B37B186237A7F07DB52168FF0490E5DF5700E31F503D",
"status": "Available",
"timestamp": "1629189071"
}
响应失败示例#
{
"cleared": false,
"signature": "D37881FE1755825A10965AA0E739F6315BA0EE46FB81F08A930196220AE17EC2",
"force_clear": false,
"locked": false,
"error_message": "Signature error",
"error_code": "SIGNERROR"
}

查询订单#

API#

URL/api/v1/cscanb/orders/{order_id}
MethodGET

请求参数#

NameLocationTypesRequiredinstruction
order_idpathstringYesThe unique order number used by the merchant (merchant_order_id when creating the order)
midquerystringNoThe merchant ID of this order is only valid when there are multiple sub-merchants under the same account.
providerquerystringNoPayment gateway
signaturequerystringYesRequest signature
timestampquerystringYesTimestamp

请求示例#

{
"order_id":"test02",
"signature":"5BB4D52997FA2B96985EFED7C78335E8171778F40D521F007356EAE62A367CBD",
"timestamp":"1629189071"
}

响应结果#

响应成功示例#
{
"cleared": false,
"channel": "",
"status": "Closed",
"note": "string",
"merchant_order_id": "test02",
"signature": "EB95216AE7DB03ACB928855BA53055C2868F21142722F84E75C5A6103EAE701B",
"timestamp": "string",
"reserved1": "2106221833215854",
"reference": "https://gateway.ksher.com/ua?order_uuid=a5abf668d34d11eba90b52540075451d",
"amount": 100,
"id": "138",
"force_clear": false,
"reserved4": "该订单不存在",
"order_date": "2021-06-22 11:33:20.799726",
"api_name": "Redirect",
"currency": "THB",
"order_type": "Sale",
"reserved2": "False",
"locked": false,
"channel_order_id": "",
"error_message": "Fail",
"gateway_order_id": "snut138",
"reserved3": "该订单不存在",
"error_code": "FAIL",
"mid": "False",
"acquirer": "Ksher",
"acquirer_order_id": "",
"log_entry_url": "https://snut.vip.ksher.net/web#action=153&view_type=form&model=rest.log&id=1144"
}

发起退款#

API#

URL/api/v1/cscanb/orders/{order_id}
MethodPUT
Content-Typeapplication/json

请求参数#

NameLocationTypesRequiredinstruction
order_idpathstringYesThe unique order number used by the merchant (merchant_order_id when creating the order)

Body 参数#

NameLocationTypesRequiredinstruction
refund_order_idbodystringYesUnlimited format, unique refund order number used by merchant
signaturebodystringYesRequest signature
timestampbodystringYesTimestamp
refund_amountbodynumberYesThe refund amount, cents, cannot be greater than the order amount, only partial payment channels support non-full refunds.
providerbodystringNoPayment gateway
midbodystringNoThe merchant ID of this order is only valid when there are multiple sub-merchants under the same account.

请求示例#

{
"refund_amount": 88,
"refund_order_id": "mr_1626780710",
"signature": "49B80F2A260918CF02081578B415D726B25417C1A6C7536FE5909834104F4752",
"timestamp": "1626780710"
}

响应结果#

响应成功示例#
{
"id": "358",
"status": "Refunded",
"timestamp": "1626835729",
"currency": "THB",
"error_code": "REFUNDED",
"order_type": "Refund",
"reference": "mc_1626835648",
"api_name": "general",
"locked": false,
"channel": "wechat",
"gateway_order_id": "dev358",
"cleared": false,
"acquirer_order_id": "90020210721104935321056",
"amount": -100,
"error_message": "The order is refunded.",
"channel_order_id": "50201008942021072110392377943",
"signature": "0086AF4E0F73FA6D76A43B85ADBF5A8AA44145751CD30E88E97ED0542CC0F9C7",
"force_clear": false,
"merchant_order_id": "mr_1626835728",
"log_entry_url": "https://dev.vip.ksher.net/web#action=153&view_type=form&model=rest.log&id=1277"
}

6. 商家扫描用户支付#

创建订单#

API#

URL/api/v1/bscanc/orders
MethodPOST
Content-Typeapplication/json

请求参数#

Body 参数#
nameLocationTypesrequiredinstruction
merchant_order_idbodystringYesThe unique order number used by the merchant
amountbodynumberYesOrder amount
auth_codebodystringYesThe Authentication code generated from eWallet of the consumer
notebodystringNoorder notes
timestampbodystringYesTimestamp
midbodystringNoThe merchant ID of this order is only valid when there are multiple sub-merchants under the same account.
providerbodystringNoPayment gateway, optional values ('th','ph','my')
channelbodystringYesPayment Merchant support. Value range:

alipay: Alipay Wallet.
wechat: Wechat Wallet.
linepay: Rabbit LINE Pay Wallet.
airpay: Shopeepay Wallet.
truemoney: TrueMoney Wallet.
device_idbodystringNo发送请求的终端ID，由商家分配。
signaturebodystringYesRequest signature
请求示例#
{
"mid":"mch38339",
"amount": 100,
"auth_code":"00003030015998",
"channel": "truemoney",
"merchant_order_id": "bscanc_truemoney",
"note": "string",
"signature": "5BB4D52997FA2B96985EFED7C78335E8171778F40D521F007356EAE62A367CBD",
"timestamp": "1629189071"
}

响应结果#

  • error_code 为 SUCCESS 时, 创建订单成功, 此时接口返回订单详情信息

  • reference 字段为对应支付渠道的支付地址或订单号

响应成功示例#
{
"cleared": false,
"channel": "truemoney",
"status": "Paid",
"note": "string",
"merchant_order_id": "bscanc_truemoney2",
"signature": "BFEB0F4C28DDDB3591E74F6E83238BD4B3BD521F9870D00EA534C8C52EF20744",
"timestamp": "1629189071",
"amount": 100,
"id": "288",
"force_clear": false,
"api_name": "BscanC",
"currency": "THB",
"order_type": "Sale",
"locked": false,
"error_message": "Successful",
"gateway_order_id": "snut288",
"error_code": "SUCCESS",
"acquirer": "Ksher",
"acquirer_order_id": "90020210817191616813118",
"log_entry_url": "https://snut.vip.ksher.net/web#action=153&view_type=form&model=rest.log&id=1156"
}
响应失败示例#
{
"cleared": false,
"signature": "93F54BF4D6282DDECED74209E8146921AF612322692B855755A88CF745562E27",
"force_clear": false,
"locked": false,
"error_message": "Duplicated Order ID",
"error_code": "DUPLICATED",
"log_entry_url": "https://snut.vip.ksher.net/web#action=153&view_type=form&model=rest.log&id=1154"
}

查询订单#

API#

URL/api/v1/bscanc/orders/{order_id}
MethodGET

请求参数#

NameLocationTypesRequiredinstruction
order_idpathstringYesThe unique order number used by the merchant (merchant_order_id when creating the order)
midquerystringNoThe merchant ID of this order is only valid when there are multiple sub-merchants under the same account.
providerquerystringNoPayment gateway
signaturequerystringYesRequest signature
timestampquerystringYesTimestamp

请求示例#

{
"order_id":"bscanc_truemoney2",
"signature":"string",
"timestamp":"string"
}

响应结果#

响应成功示例#
{
"cleared": false,
"channel": "truemoney",
"status": "Paid",
"note": "string",
"merchant_order_id": "bscanc_truemoney2",
"signature": "2099B4743A63C866307A84D553638737F9E32F848938C1314FF70C4FAC94A956",
"timestamp": "string",
"reserved1": "False",
"reference": "False",
"amount": 100,
"id": "288",
"force_clear": false,
"reserved4": "False",
"order_date": "2021-08-17 11:16:15.693849",
"api_name": "BscanC",
"currency": "THB",
"order_type": "Sale",
"reserved2": "False",
"locked": false,
"channel_order_id": "210817181617269OFAOZ",
"error_message": "Successful",
"gateway_order_id": "snut288",
"reserved3": "False",
"error_code": "SUCCESS",
"mid": "False",
"acquirer": "Ksher",
"acquirer_order_id": "90020210817191616813118",
"log_entry_url": "https://snut.vip.ksher.net/web#action=153&view_type=form&model=rest.log&id=1160"
}

发起退款#

API#

URL/api/v1/bscanc/orders/{order_id}
MethodPUT
Content-Typeapplication/json

请求参数#

NameLocationTypesRequiredinstruction
order_idpathstringYesThe unique order number used by the merchant (merchant_order_id when creating the order)

Body 参数#

NameLocationTypesRequiredinstruction
refund_order_idbodystringYesUnlimited format, unique refund order number used by merchant
signaturebodystringYesRequest signature
timestampbodystringYesTimestamp
refund_amountbodynumberYesThe refund amount, cents, cannot be greater than the order amount, only partial payment channels support non-full refunds.
providerbodystringNoPayment gateway
midbodystringNoThe merchant ID of this order is only valid when there are multiple sub-merchants under the same account.

请求示例#

{
"refund_order_id": "refund_bscanc_truemoney2",
"refund_amount": 100,
"signature": "string",
"timestamp": "string"
}

响应结果#

响应成功示例#
{
"cleared": false,
"channel": "truemoney",
"status": "Refunded",
"merchant_order_id": "refund_bscanc_truemoney2",
"signature": "6A8139EF256F9AAF3D7DEDE137DC619D017814FFFFEF4ED2FE9F54C41F338E1B",
"timestamp": "string",
"reference": "bscanc_truemoney2",
"amount": -100,
"id": "289",
"force_clear": false,
"api_name": "general",
"currency": "THB",
"order_type": "Refund",
"locked": false,
"channel_order_id": "210817182114545BVWB1",
"error_message": "The order is refunded.",
"gateway_order_id": "snut289",
"error_code": "REFUNDED",
"acquirer_order_id": "90020210817192114495338",
"log_entry_url": "https://snut.vip.ksher.net/web#action=153&view_type=form&model=rest.log&id=1166"
}

7. 接口返回字段详情#

创建订单, 查询订单, 发起退款, 请求成功后, 接口返回的详情信息, 字段说明如下

名称类型必选说明
statusstring是订单状态
idstring是内部唯一id
currencystring是货币类型
amountnumber是订单金额
notestring是订单备注信息
referencestring是支付链接
error_codestring是接口返回的响应码
error_messagestring是接口返回的error_code响应码对应的信息说明
timestampstring是时间戳
signaturestring是响应内容的签名
api_namestring是请求的API类别
order_typestring是订单类型，普通销售订单或退款订单
acquirerstring是当前订单的收单机构
gateway_order_idstring是gateway网关的订单号
merchant_order_idstring是商户端使用的订单号
acquirer_order_idstring否收单机构订单号，用于在收单机构端标识订单的uniq字符串
channel_order_idstring否支付通道端的订单号, 用于标识支付通道端的订单
channelstring否订单支付渠道
order_datestring否none
midstring否此订单的商户ID，仅当同一帐户下有多个子商户时才有效。
reserved1string否Misc Field 1
reserved2string否Misc Field 2
reserved3string否Misc Field 3
reserved4string否Misc Field 4
lockedboolean否表示订单是否已锁定以便清关和结算。
force_clearboolean否是否强制该笔交易参加对账
clearedboolean否表明该笔交易是否已经清分

订单详情的 status 合法值#

值说明创建订单查询订单发起退款
Available待支付✔✔-
Failed失败✔✔✔
Closed已关闭-✔-
Paid已支付-✔-
Refunded部分退款/全部退款-✔✔
Voided已撤销---
Cancelled已取消---
Authorized预授权---
Release预授权完成---

接口 error_code 合法值#

值说明创建订单查询订单发起退款
SUCCESS创建订单成功✔✔-
DUPLICATED重复的订单id (merchant_order_id 已存在)✔-✔
FAIL失败✔✔✔
NOTPAY订单未支付 Buyer reject pay for one channel-✔✔
PENDING订单待支付-✔-
REFUNDED订单全部或部分退款。-✔✔
INVALID_REFUND_BALANCE退款金额有误(退款金额超出可订单退款金额)--✔
NOTFOUND订单未找到或不存在-✔✔
NOTPAID订单未支付-✔✔
NOTSUPPORTED不支持该操作-✔✔
SIGNERROR验证签名错误✔✔✔
PROVIDERERRORProvider 有误✔✔✔
PROVIDERCLOSE当前商户不支持该 Provider✔✔✔
DEBUG签名debug模式, 该模式下, 返回的reference 字段为正确的签名, note字段为签名前的原始数据✔✔✔

8. 结算#

查询结算单信息#

URL/api/v1/finance/settlements/{yyyymmdd}
MethodGET

API#

请求参数#

名称位置类型必选说明
channelquerystring是需要查询结算单的支付渠道
signaturequerystring是请求签名
timestampquerystring是时间戳，UTC UNIX 格式
yyyymmddpathstring是需要查询的年月日如20210803

请求示例

{
"channel":"alipay",
"signature": "your signature",
"timestamp": "1641978768"
}

响应结果#

响应示例

{
"data": {
"channel": "alipay",
"other_fee": 0,
"refund_fee": 0,
"net": 0,
"transfer": true,
"currency": "thb",
"amount": 12345600,
"fee": 1234.56,
"reference_id": "reference id string",
"end": "string",
"balance": 0,
"refund": 0,
"adjustment": 0,
"transfer_amount": 12345600,
"count": 0,
"time": "string",
"start": "string"
},
"timestamp": "1641978768",
"error_message": "Successful",
"signature": "your signature",
"error_code": "SUCCESS",
"mid": ""
}

查询开通的支付渠道#

URL/api/v1/finance/settlements/channels
MethodGET

API#

请求参数#

名称位置类型必选说明
signaturequerystring是请求签名
timestampquerystring是时间戳，UTC UNIX 格式

请求示例

{
"signature": "your signature",
"timestamp": "1641978768"
}

响应结果#

响应示例

{
"status": "success",
"channels": [
"airpay",
"alipay",
"bbl_deeplink",
"ktc_instal",
"card",
"linepay",
"promptpay",
"scb_easy",
"truemoney",
"wechat"
]
}

查询订单列表#

URL/api/v1/finance/settlements/order/{yyyymmdd}
MethodGET

API#

请求参数#

名称位置类型必选说明
channelquerystring否需要查询结算单的支付渠道
limitqueryinteger否每次查询数据量限制，最大为50
offsetqueryinteger否每次查询起始游标
signaturequerystring是请求签名
timestampquerystring是时间戳，UTC UNIX 格式
yyyymmddpathstring是需要查询的年月日如20210803

请求示例

{
"channel":"alipay",
"limit":"50",
"offset":"0",
"signature": "your signature",
"timestamp": "1641978768"
}

响应结果#

响应示例

{
"data": {
"channel": "alipay",
"data": [
{
"channel": "alipay",
"ksher_order_id": "123456789",
"currency": "thb",
"amount": 10000,
"type": "string",
"order_id": "23456789",
"transaction_time": "string",
"device_id":"10001",
"operator_id":1
}
],
"limit": 50,
"offset": 0,
"total": 0, // 数据总数
"count": 0 // 单页行数
},
"timestamp": "1641978768",
"error_message": "Successful",
"signature": "your signature",
"error_code": "SUCCESS",
"mid": "string"
}

查询已结算订单列表#

URL/api/v1/finance/settlements/settlement_order
MethodGET

API#

请求参数#

名称位置类型必选说明
limitqueryinteger否每次查询数据量限制，最大为50
offsetqueryinteger否每次查询起始游标
reference_idquerystring是从结算单信息接口中获得的“reference_id”字段
signaturequerystring是请求签名
timestampquerystring是时间戳，UTC UNIX 格式

请求示例

{
"limit":"50",
"offset":"0",
"reference_id":"string",
"signature": "your signature",
"timestamp": "1641978768"
}

响应结果#

响应示例

{
"data": {
"data": [
{
"ksher_order_id": "123456789",
"currency": "thb",
"amount": 10000,
"type": "string",
"order_id": "23456789",
"transaction_time": "string",
"device_id":"10001",
"operator_id":1
}
],
"limit": 50,
"offset": 0,
"total": 10000, // 数据总数
"count": 50 // 单页行数
},
"timestamp": "1641978768",
"error_message": "Successful",
"signature": "your signature",
"error_code": "SUCCESS"
}

9. WebHook#

可在gateway支付网关后台配置webhook回调地址

img.png

当订单状态发生变化时, 支付网关会向 webhook 地址发送一个 GET 请求, 并携带以下参数

参数名称类型描述
typestring事件类型, 固定值 "order"
instancestring商户侧订单号, 即 merchant_order_id 字段
codestring事件码, 固定值 "statuschange"
messagestring订单状态变化
signaturestring请求签名

可通过签名规则对该请求进行签名验证, 签名规则中的apiUrl 使用webhook的完整地址

若 webhook 地址响应为200, 则通知成功, 否则会重复通知, 每5秒重复一次, 至多重复6次

收到 webhook 通知时, 需要对参数进行验签, 验签过程参考下文签名计算部分

message#

message 字段取值

值说明
Order Timeout订单超时
Order Closed订单已关闭
Order Paid订单已支付
Order Refunded订单部分退款/全部退款

webhook 通知示例#

URLwebhook 地址
MethodGET

请求内容

{
"type": "Order",
"instance": "1623817182537",
"code": "StatusChange",
"message": "Order Paid",
"signature": "944EFC0C6DB000A28C7BACEC6709AF119586F4E361F908DEAC576DA937A6F746"
}

10. 签名计算#

gateway API 会验证每个 API 请求, 所以每个 HTTP 请求都必须包含签名信息, 签名无效的请求会返回错误

gateway API 通过在支付后台设置的令牌验证请求, 令牌可用于生产 HTTP 请求中的 signature 字段, 需要严格保密

token 可在以下位置获取或重置:

img_1.png

如果你手动编写 HTTP 请求而非使用官方SDK, 则需要了解一下签名算法

签名算法#

生成签名过程如下

  1. 将所有请求参数(除 signature字段外) 按照 ASCII 表中的参数名称进行排序. 例如

    排序前：foo=1, bar=2, foo_bar=3, foobar=4
    排序后：bar=2, foo=1, foo_bar=3, foobar=4

  2. 将排序后的参数及其值拼接为一个字符串. 例如

    bar2foo1foo_bar3foobar4

  3. 在拼接好的字符串前再添加 API 名称, 以创建订单接口为例 "/api/v1/redirect/orders"

    /api/v1/redirect/ordersbar2foo1foo_bar3foobar4

  4. 以 UTF-8 格式对字符串进行编码, 并使用 HMAC_SHA256 签名算法进行摘要, 秘钥为上文后台配置中的 token

此处为第三方加密工具演示, 可根据开发语言自行使用第三方工具库以实现 HMAC_SHA256 签名

img_2.png

webhook 验证签名#

webhook签名计算时, API名称为 webhook 地址的完整 url, 其他步骤一致

注意在参数拼接为字符串时, 要先将 signature 字段排除再做拼接

若最终得到的签名值和webhook收到的请求中的 signature 一致, 则验签成功

Edit this page