Skip to main content

Gateway interface integration guide

1. Interface description#

Request URL#

The actual request address of all interface URLs is payment gateway address + interface URL

The exclusive payment gateway address can be obtained by contacting ksher.

Response http Status Code#

When the http status code is 200, the response contains error_code and error_message fields, indicating the result of this request

Create an order, query an order, and refund an order. When the call is successful, the interface will return the order details .

http status codeinstruction
200Success
400Request parameter format verification failed
401unauthorized
403Permission denied
404The requested resource does not exist

400 response example#

{
"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. Redirect payment#

Create Order#

API#

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

Request parameter#

Body parameter#
nameLocationTypesrequiredinstruction
merchant_order_idbodystringYesThe unique order number used by the merchant
amountbodynumberYesHow much to charge. add 00 for decimal.Example 150.50 THB amount =15050
redirect_urlbodystringYesThe url to be redirected after the client's payment is completed
redirect_url_failbodystringYesThe url to be redirected after the client payment is not completed or cancelled
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')
product_namebodystringNoName or description of your product.
Precautions when using "product_name"
please use General English characters. Avoid using special characters such as +&/$%.
Because in some wallets, product_name will be shown to the product that the customer purchases. and wallet does not support special characters.
channelbodystringNoPayment Merchant list support. Value range:

alipay: Alipay Wallet.
alipayplus: Alipay+ Wallet. Country support only Japan.
wechat: Wechat Wallet.
linepay: Rabbit LINE Pay Wallet. Country support only Thailand.
airpay: Shopeepay Wallet. Country support only Thailand.
truemoney: TrueMoney Wallet. Country support only Thailand.
atome: Atome Buy now pay later. minimum of 20 Baht. Country support only Thailand.
promptpay: PromptPay QR code (Thailand standard bank transfer QR code). Country support only Thailand.
scb_easy: SCB EASY Mobile App. minimum of 20 Baht. (only support on mobile). Country support only Thailand.
bbl_deeplink: Bualuang mBanking Mobile App. minimum of 20 Baht. (only support on mobile). Country support only Thailand.
baybank_deeplink: KMA Krungsri Mobile App. minimum of 20 Baht. (only support on mobile). Country support only Thailand.
kplus: KPLUS. minimum of 20 Baht. (only support on mobile). Country support only Thailand.
card: Card Gateway. support Visa Card, Master Card, Union Pay Card, TPN Card. Country support only Thailand.
ktc_instal: KTC Installment. support only KTC Card. minimum of 3,000 Baht. Country support only Thailand.
kbank_instal: KBANK Installment. support only KBANK Card. minimum of 3,000 Baht. Country support only Thailand.
kcc_instal: Krungsri Installment. support only Krungsri Card. minimum of 3,000 Baht.(5,000 Baht. for 10 months or more than). Country support only Thailand.
kfc_instal: First Choice Installment. support only Krungsri First Choice Card. minimum of 3,000 Baht. Country support only Thailand.

If multiple e-payment method required,a string made up by required e-wallets ,which seperated by "," without space, for example:"promptpay,linepay,airpay,truemoney,atome,card,ktc_instal,kbank_instal,kcc_instal,kfc_instal,scb_easy,bbl_deeplink,baybank_deeplink,kplus,alipay,wechat",card,ktc_instal,kbank_instal,kcc_instal,kfc_instal". will open all of channel your merchant you have. It will send Ksher checkout page to select your wallet want to paid.

If you send only one channel, it will be redirected to each wallet you send.
operator_idbodystringNooperator_id number at cashier, using for merchant have muti level account or Cashier. For more information please check at Muti level account or Cashier
langbodystringNoThe display language. Value range:
en: English.
cn: Chinese.
th: Thai.
Default is en.
member_idbodystringNoUser ID provided by merchant side.Gateway will bind user ID and credit card,and customers do not need to enter card info next time.
Can’t use Real number like 1,1200,00001, please use string with number like ABC1234.
signaturebodystringYesRequest signature
Request body example#
{
"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": "这是一个测试订单, 这里是备注信息"
}

Response result#

  • When the error_code is SUCCESS, the order creation is successful, and the interface returns the order details

  • reference is the payment address or the order number of the corresponding payment channel

Successful response example#
{
"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"
}
Example of response failure (duplicate order number)#
{
"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"
}

Checking order#

Checking order API#

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

Checking order Request parameter#

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

Checking order Request example#

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

Checking order Response result#

The query order can be combined with the scene to judge the error_code to confirm the result, such as the unpaid order, the response error_code is "PENDING"

Checking order Successful response example#
{
"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"
}

Refund order#

Refund order API#

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

Refund order Request parameter#

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

Body parameters#

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.

Request body example#

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

Response result#

The refund interface returns the refund result synchronously. If the refund is successful, the interface returns the order details, and the error_code is "REFUNDED".

Successful response example#
{
"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 and channel support#

When creating an order, you can choose provider and channel to choose the payment channel. Each provider has several channels that can be selected.

When creating a redirect order, the optional values of provider and channel are as follows

Channel Payment Support Each country

Cancel order#

Cancel order will close link payment to allow customer access to pay after send API. If customer save QR to their local device. Customer still can make payment.

Cancel order API#

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

Cancel order Request parameter#

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

Body parameters#

NameLocationTypesRequiredinstruction
signaturebodystringYesRequest signature
timestampbodystringYesTimestamp
providerbodystringNoPayment gateway
midbodystringNoThe merchant ID of this order is only valid when there are multiple sub-merchants under the same account.

Request body example#

{
"signature": "49B80F2A260918CF02081578B415D726B25417C1A6C7536FE5909834104F4752",
"timestamp": "1626780710"
}

Response result#

The refund interface returns the refund result synchronously. If the refund is successful, the interface returns the order details, and the error_code is "REFUNDED".

Successful response example#
{
"note": "string",
"merchant_order_id": "2022063010481",
"force_clear": false,
"reserved4": "False",
"order_date": "2022-06-30 03:49:48.981386",
"amount": 100,
"channel": "promptpay",
"error_message": "order is closed",
"reserved3": "False",
"signature": "97680CE229B4B7DAE2178CC755CFC351D917E882C49CD200835FC75C1C3EE0D2",
"status": "Closed",
"reserved2": "False",
"error_code": "SUCCESS",
"timestamp": "1234567890",
"gateway_order_id": "pnut203",
"api_name": "Redirect",
"locked": false,
"cleared": false,
"currency": "THB",
"mid": "False",
"reference": "https://gateway.ksher.com/ua?order_uuid=b08c3110f82711ecad4052540075451d&lang=th",
"acquirer_order_id": "False",
"channel_order_id": "False",
"reserved1": "False",
"acquirer": "Ksher",
"order_type": "Sale",
"id": "203"
}

3. Mini program payment#

Specifications of APIs#

Steps for WeChat Pay miniprogram integration#

  • Merchants register on Ksher system as an ONLINE merchant and pass the audit to obtain the Ksher merchant number.
  • Merchants need to register on the WeChat open platform (https://open.weixin.qq.com/) to obtain the certification and mini-program’s WeChat APPID and registration name(should be same as bussiness registration certificate).
  • Merchant obtains Ksher APPID and Private key from Ksher merchant platform https://merchant.ksher.net/big_business/index;
  • Merchant need to tell Ksher WeChat mini-program APPID and Verified Entity Name for Ksher to Apply for Wechat App Pay binding.
  • Merchants use MINI-PROGRAM_PAY API to access integrated development.

Create Order#

Create Order API#

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

Create Order Request parameter#

Create Order Body parameters#

NameLocationTypesRequiredinstruction
merchant_order_idbodystringYesThe unique order number used by the merchant
amountbodynumberYesHow much to charge. add 00 for decimal.Example 150.50 THB amount =15050
channelbodystringNoPayment channel , Value range:
alipay: Alipay Wallet.
alipayplus: Alipay+ Wallet. Country support only Japan.
wechat: Wechat Wallet.
miniapp_openidbodystringNoThe openid of the applet user, the WeChat applet is openid
miniapp_appidbodystringNoThe appid of the Mini Program
timestampbodystringNoTimestamp
notebodystringNoorder notes
signaturebodystringYesRequest signature

Request body example Create WeChat Mini Program order#

{
"amount": 85,
"merchant_order_id": "mc_1626164356",
"signature": "49B80F2A260918CF02081578B415D726B25417C1A6C7536FE5909834104F4752",
"timestamp": "1626164339",
"miniapp_openid": "oNUEf5TxzRxSvNSET1_2tfLa7gaE",
"miniapp_appid": "wx2181eee9ed4505ce",
"note": "Ozyktsgs pwikzq gbmiti rfokp yoiqu cutx uektskl dvk txocubkw yxzj gxnzu jhkjrvmtm hrcuq arobdp jhwheii mshyqgrad.",
"channel": "wechat"
}

Request body example Create Alipay applet order#

{
"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"
}

Response result#

  • When the error_code is SUCCESS, the order creation is successful, and the interface returns the order details
Additional fields for order details when creating WeChat Mini Program orders#
NameTypesRequiredinstruction
referencestringYesThe package field of WeChat applet payment parameters
reserved1stringYesThe timeStamp field of the WeChat applet payment parameter
reserved2stringYesThe signType field of the WeChat applet payment parameter
reserved3stringYespaySign field of WeChat applet payment parameters
reserved4stringYesThe nonceStr field of the WeChat applet payment parameter

Use the above fields to initiate payment in the WeChat Mini Program, refer to https://developers.weixin.qq.com/miniprogram/dev/api/payment/wx.requestPayment.html

Successful response example#
{}
Additional fields for order details when creating an Alipay applet order#
NameTypesRequiredinstruction
referencestringYesThe orderStr field of Alipay applet payment parameters

Use the above fields to initiate payment in the Alipay applet, reference https://opendocs.alipay.com/mini/api/openapi-pay

Successful response example#
{}

checking order#

API#

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

Request parameter#

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.
signaturequerystringYesRequest signature
timestampquerystringYesTimestamp
Request example#
https://sandbox.vip.ksher.net/api/v1/miniapp/orders/mc_1626782180?signature=asd8af7s9d6f8a97d6a87f6sd8a7&timestamp=1626160499672

Response result#

Successful response example#
{
"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"
}

Refund order#

Refund order API#

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

Refund order Request parameter#

NameLocationTypesRequiredinstruction
order_idpathstringYesThe unique order number used by the merchant (merchant_order_id when creating the order)
Body parameters#
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
midbodystringNoThe merchant ID of this order is only valid when there are multiple sub-merchants under the same account.
Request body example#
{
"refund_amount": 88,
"refund_order_id": "mr_1626780710",
"signature": "49B80F2A260918CF02081578B415D726B25417C1A6C7536FE5909834104F4752",
"timestamp": "1626780710"
}

Response result#

Successful response example#
{
"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 payment#

Specifications of APIs#

Steps for WeChat APP Pay integration#

  • Merchant register on Ksher system as an ONLINE merchant and pass the audit to obtain the Ksher merchant number
  • Merchant need to register on the WeChat open platform (https://open.weixin.qq.com/) to obtain the certification and APP’s WeChat_APPID
  • Merchant obtains Ksher_APPID and key from Ksher merchant platform https://merchant.ksher.net/big_business/index
  • Merchant need to tell Ksher WeChat _APPID and Verified Entity Name for Ksher to Apply for Wechat App Pay binding.
  • Merchant use APP_pay to access integrated development.
  • On the merchant side, WeChat Pay open SDK（for Android/iOS https://pay.weixin.qq.com/wiki/doc/api/wxpay/ch/pages/In-AppPay.shtml ） integrated into the mobile app.
  • After completing above steps, call Ksher App Pay API to complete transactions.

Steps for Alipay APP Pay integration#

  • Merchant register on Ksher system as an ONLINE merchant and pass the audit to obtain the Ksher merchant number
  • Register on https://opendocs.alipay.com/open/54/104509 to get the Alipay APPID
  • Merchant obtains Ksher_APPID and key from Ksher merchant platform https://merchant.ksher.net/big_business/index
  • Merchants submit Alipay APPID to ksher for Alipay filing.
  • Merchant use APP_PAY API to access integrated development.
  • On the merchant side, Alipay open SDK（for Android/iOS https://opendocs.alipay.com/open/200 ） integrated into the mobile app.
  • After completing above steps, call Ksher App Pay API to complete transactions.

Create Order#

App payment Create Order API#

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

App payment Create Order Request parameter#

App payment Create Order Body parameters#
NameLocationTypesRequiredinstruction
merchant_order_idbodystringYesThe unique order number used by the merchant
amountbodynumberYesHow much to charge. add 00 for decimal.Example 150.50 THB amount =15050
channelbodystringNoPayment Merchant list support. Value range:

alipay: Alipay Wallet.
alipayplus: Alipay+ Wallet. Country support only Japan.
wechat: Wechat Wallet.
linepay: Rabbit LINE Pay Wallet. Country support only Thailand.
airpay: Shopeepay Wallet. Country support only Thailand.
app_appidbodystringNoThe app_id of the mobile application, such as the app_id of the mobile application of the WeChat open platform, the application method Reference
timestampbodystringNoTimestamp
notebodystringNoorder notes
signaturebodystringYesRequest signature
Request body example Create Alipay order#
{
"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"
}

Response result#

  • When the error_code is SUCCESS, the order creation is successful, and the interface returns the order details
Additional fields for order details when creating an Alipay order#
NameTypesRequiredinstruction
referencestringYesThe orderStr field of Alipay app payment parameters

Use the above fields to call up Alipay App payment through the payment SDK

Successful response example#
{}

Checking order#

Checking order API#

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

Checking order Request parameter#

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.
signaturequerystringYesRequest signature
timestampquerystringYesTimestamp
Request example#
https://sandbox.vip.ksher.net/api/v1/app/orders/mc_1626782180?signature=asd8af7s9d6f8a97d6a87f6sd8a7&timestamp=1626160499672

Response result#

Successful response example#
{
"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"
}

Refund order#

Refund order API#

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

Refund order Request parameter#

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

Refund order Body parameters#

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
midbodystringNoThe merchant ID of this order is only valid when there are multiple sub-merchants under the same account.
Request body example#
{
"refund_amount": 88,
"refund_order_id": "mr_1626780710",
"signature": "49B80F2A260918CF02081578B415D726B25417C1A6C7536FE5909834104F4752",
"timestamp": "1626780710"
}

Refund order Response result#

Successful response example#
{
"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. C scan B payment#

Create Order#

API#

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

Request parameter#

Body parameter#
nameLocationTypesrequiredinstruction
merchant_order_idbodystringYesThe unique order number used by the merchant
amountbodynumberYesHow much to charge. add 00 for decimal.Example 150.50 THB amount =15050
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.
alipayplus: Alipay+ Wallet. Country support only Japan.
wechat: Wechat Wallet.
airpay: Shopeepay Wallet.
promptpay:PromptPay QR code (Thailand standard bank transfer QR code).
truemoney: TrueMoney Wallet.
device_idbodystringNoterminal id from which the request is sent, assigned by merchant.
operator_idbodystringNooperator_id number at cashier, using for merchant have muti level account or Cashier. For more information please check at Muti level account or Cashier
signaturebodystringYesRequest signature
note

Please check Channel Payment Support Each country before using API. nomally if you want to use all of wallet , have to use muti-mid

Request body example#
{
"amount": 100,
"channel": "truemoney",
"merchant_order_id": "test_truemoney3",
"note": "string",
"signature": "5BB4D52997FA2B96985EFED7C78335E8171778F40D521F007356EAE62A367CBD",
"timestamp": "1629189071"
}

Response result#

  • When the error_code is SUCCESS, the order creation is successful, and the interface returns the order details

  • reference is the payment address or the order number of the corresponding payment channel

Successful response example#
{
"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"
}
Response failure example#
{
"cleared": false,
"signature": "D37881FE1755825A10965AA0E739F6315BA0EE46FB81F08A930196220AE17EC2",
"force_clear": false,
"locked": false,
"error_message": "Signature error",
"error_code": "SIGNERROR"
}

Expire time QR on C scan B API#

BBL PromptPay#
  • can setup time wallet -> No
  • expire_time min -> can't setup
  • expire_time max -> can't setup
  • default time expire_time, If merchant leave value expire_time -> never expire
SCB PromptPay#
  • can setup time wallet -> Yes, at expire_time
  • expire_time min -> 0
  • expire_time max -> unlimited depend on customer
  • default time expire_time, If merchant leave value expire_time -> 1 day
Truemoney#
  • can setup time wallet -> Yes, at tmn_expire_time
  • expire_time min -> 0
  • expire_time max -> unlimited depend on customer
  • default time expire_time, If merchant leave value tmn_expire_time -> 1 day
Alipay#
  • can setup time wallet -> No
  • expire_time min -> can't setup
  • expire_time max -> can't setup
  • default time expire_time, If merchant leave value expire_time -> 3 hours
Wechat#
  • can setup time wallet -> No
  • expire_time min -> can't setup
  • expire_time max -> can't setup
  • default time expire_time, If merchant leave value expire_time -> 2 hours
Shopeepay#
  • can setup time wallet -> No
  • expire_time min -> can't setup
  • expire_time max -> can't setup
  • default time expire_time, If merchant leave value expire_time -> 1 month

Checking order#

Checking order API#

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

Checking order Request parameter#

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

Checking order Request example#

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

Checking order Response result#

Checking order Successful response example#
{
"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"
}

Refund order#

Refund order API#

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

Refund order Request parameter#

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

Body parameters#

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.

Request body example#

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

Response result#

Successful response example#
{
"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. B scan C payment#

Create Order#

API#

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

Request parameter#

Body parameter#
nameLocationTypesrequiredinstruction
merchant_order_idbodystringYesThe unique order number used by the merchant
amountbodynumberYesHow much to charge. add 00 for decimal.Example 150.50 THB amount =15050
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.
alipayplus: Alipay+ Wallet. Country support only Japan.
wechat: Wechat Wallet. Country support only Japan.
linepay: Rabbit LINE Pay Wallet. Country support only Japan.
airpay: Shopeepay Wallet. Country support only Thailand.
truemoney: TrueMoney Wallet. Country support only Thailand.
device_idbodystringNoterminal id from which the request is sent, assigned by merchant.
operator_idbodystringNooperator_id number at cashier, using for merchant have muti level account or Cashier. For more information please check at Muti level account or Cashier
signaturebodystringYesRequest signature
Request body example#
{
"mid":"mch38339",
"amount": 100,
"auth_code":"00003030015998",
"channel": "truemoney",
"merchant_order_id": "bscanc_truemoney",
"note": "string",
"signature": "5BB4D52997FA2B96985EFED7C78335E8171778F40D521F007356EAE62A367CBD",
"timestamp": "1629189071"
}

Response result#

  • When the error_code is SUCCESS, the order creation is successful, and the interface returns the order details

  • reference is the payment address or the order number of the corresponding payment channel

Successful response example#
{
"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"
}
Response failure example#
{
"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"
}

QR format each wallet#

TrueMoney#

Truemoney have total of 14 numbers, the first two digits start with "00". Example 00002727475523

LINE Pay#

LINE Pay have total of 12 numbers. Example 3486 6978 2883

Shopeepay#

Shopeepay has a total of 20 characters (letters + numbers), the first 4 digits will start with "APTH" Example APTH 8091458996703410

Alipay#

Alipay 16-25 digits and start with '25', '26', '27', '28', '29', and '30'.

WeChat Pay#

WeChat Pay has 18 numbers, starting with "13".

Checking order#

Checking order API#

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

Checking order Request parameter#

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

Checking order Request example#

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

Checking order Response result#

Checking order Successful response example#
{
"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"
}

Refund order#

Refund order API#

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

Refund order Request parameter#

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

Body parameters#

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.

Request body example#

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

Response result#

Successful response example#
{
"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. Interface returns field details#

Create an order, query an order, initiate a refund, after the request is successful, the detailed information returned by the interface, the field description is as follows

NameTypesRequiredinstruction
statusstringYesThe current status of the order
idstringYesInternal unique id
currencystringYesCurrency code of the order. refer to with ISO 4217.
amountnumberYesHow much to charge. add 00 for decimal.Example 150.50 THB amount =15050
notestringYesOrder remarks information
referencestringYesThe payment link to be used for making payment
error_codestringYesResponse code returned by the interface
error_messagestringYesInformation corresponding to the error_code response code returned by the interface instruction
timestampstringYesTimestamp
signaturestringYesSignature of response content
api_namestringYesAPI category requested
order_typestringYesOrder type, normal sales order or refund order
acquirerstringYesAcquirer for current order
gateway_order_idstringYesGateway order number.
merchant_order_idstringYesThe order number used by the merchant
acquirer_order_idstringNoAcquirer’s order number, the uniq string used to identify the order on the acquirer’s side
channel_order_idstringNoThe order number on the payment channel side, used to identify the order on the payment channel side
channelstringNoOrder payment channel
order_datestringNoThe date of the order
midstringNoThe merchant ID of this order is only valid when there are multiple sub-merchants under the same account.
reserved1stringNoMisc Field 1
reserved2stringNoMisc Field 2
reserved3stringNoMisc Field 3
reserved4stringNoMisc Field 4
lockedbooleanNoIndicates whether the order has been locked for customs clearance and settlement.
force_clearbooleanNoWhether to force the transaction to participate in the reconciliation
clearedbooleanNoIndicates whether the transaction has been cleared

The legal status of the order details#

ValueDescriptionCreate OrderQuery OrderInitiate Refund
AvailableTo be paid✔✔-
FailedFailed✔✔-
Closedclosed✔✔-
PaidPaid✔✔-
RefundedPartial refund/full refund✔✔-
VoidedRevoked---
CancelledCancelled---
AuthorizedPre-authorization---
ReleasePre-authorization completed---

Interface error_code legal value#

ValueDescriptionCreate OrderQuery OrderInitiate Refund
SUCCESSSuccessfully created an order✔✔-
DUPLICATEDSuccessfully created an order✔✔-
FAILFailed✔✔✔
NOTPAYOrder not paid Buyer reject pay for one channel-✔✔
PENDINGOrder pending payment-✔-
REFUNDEDFull or partial refund of the order.-✔✔
INVALID_REFUND_BALANCEThe refund amount is incorrect (the refund amount exceeds the order refundable amount)--✔
NOTFOUNDOrder not found or does not exist-✔✔
NOTPAIDOrder not paid-✔✔
NOTSUPPORTEDThe operation is not supported-✔✔
SIGNERRORVerify signature error✔✔✔
PROVIDERERRORProvider is wrong✔✔✔
PROVIDERCLOSEThe current merchant does not support the Provider✔✔✔
DEBUGSignature debug mode, in this mode, the returned reference field is the correct signature, and the note field is the original data before signing✔✔✔

8. Report API#

Channels available#

query the information of the channel you have joined up.

API#
URL/api/v1/finance/settlements/channels
MethodGET
Acceptapplication/json

Request parameter#

path parameter#
nameLocationTypesrequiredinstruction
midquerystringYesthe mid of the request.
signaturequerystringYesRequest signature
timestampquerystringYesTimestamp
Request URL example#
https://sandbox.vip.ksher.net/api/v1/finance/settlements/channels?signature=6A8139EF256F9AAF3D7DEDE137DC619D017814FFFFEF4ED2FE9F54C41F338E1B&timestamp=20220310111213

Response result#

Successful response example

{
"status": "success",
"channels": [
"airpay",
"alipay",
"atome",
"baybank_deeplink",
"bbl_deeplink",
"kplus",
"ktc_instal",
"ktccard",
"linepay",
"promptpay2",
"scb_easy",
"truemoney",
"wechat"
]
}

Transaction data#

Transaction report is mean all of transection (Paid/Notpaid/On processes/refund etc). for merchant can check what is current status /Dashboard.

API#

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

Request parameter#

path parameter#
nameLocationTypesrequiredinstruction
yyyymmddpathstringYesThe year, month and day to be queried, such as 20210803
channelquerystringNothe channel you want to query, don't send this param if you want to query all.
limitquerystringYesdata size one time, must less than 50
midquerystringYesthe mid of the request.
offsetquerystringYesData Offset
signaturequerystringYesRequest signature
timestampquerystringYesTimestamp
Request URL example#
https://sandbox.vip.ksher.net/api/v1/finance/settlements/order/20220301?signature=6A8139EF256F9AAF3D7DEDE137DC619D017814FFFFEF4ED2FE9F54C41F338E1B&timestamp=20220301111213

Response result#

Successful response example

{
"error_message": "Successful",
"data": {
"data": [
{
"amount": 8,
"transaction_time": "2022-03-01 19:04:40",
"type": "PAY",
"channel": "promptpay2",
"device_id": "gate_scosmatch2133",
"operator_id": 34447,
"operator_name": "MR.WANG XU",
"currency": "THB",
"order_id": "order_01b05d3f-55dc-48c0-88f5-45",
"ksher_order_id": "90020220301200336817684"
},
{
"amount": 120,
"transaction_time": "2022-03-01 16:43:13",
"type": "PAY",
"channel": "promptpay2",
"device_id": "gate_smonsterbuys309",
"operator_id": 34447,
"operator_name": "MR.WANG XU",
"currency": "THB",
"order_id": "130",
"ksher_order_id": "90020220301174252967780"
},
{
"amount": 120,
"transaction_time": "2022-03-01 16:21:38",
"type": "PAY",
"channel": "promptpay2",
"device_id": "gate_smonsterbuys308",
"operator_id": 34447,
"operator_name": "MR.WANG XU",
"currency": "THB",
"order_id": "129",
"ksher_order_id": "90020220301172123704867"
},
{
"amount": 120,
"transaction_time": "2022-03-01 15:32:26",
"type": "PAY",
"channel": "promptpay2",
"device_id": "gate_smonsterbuys307",
"operator_id": 34447,
"operator_name": "MR.WANG XU",
"currency": "THB",
"order_id": "128",
"ksher_order_id": "90020220301163134343744"
},
{
"amount": -900,
"transaction_time": "2022-03-01 15:26:17",
"type": "REFUND",
"channel": "wechat",
"device_id": "",
"operator_id": 34447,
"operator_name": "MR.WANG XU",
"currency": "THB",
"order_id": "2_18905",
"ksher_order_id": "90020220301161949956409"
},
{
"amount": 900,
"transaction_time": "2022-03-01 15:20:11",
"type": "PAY",
"channel": "wechat",
"device_id": "",
"operator_id": 34447,
"operator_name": "MR.WANG XU",
"currency": "THB",
"order_id": "1_18904",
"ksher_order_id": "90020220301161949956409"
},
{
"amount": 120,
"transaction_time": "2022-03-01 15:17:44",
"type": "PAY",
"channel": "promptpay2",
"device_id": "gate_smonsterbuys305",
"operator_id": 34447,
"operator_name": "MR.WANG XU",
"currency": "THB",
"order_id": "126",
"ksher_order_id": "90020220301161718603171"
},
{
"amount": 120,
"transaction_time": "2022-03-01 15:12:13",
"type": "PAY",
"channel": "truemoney",
"device_id": "gate_smonsterbuys304",
"operator_id": 34447,
"operator_name": "MR.WANG XU",
"currency": "THB",
"order_id": "125",
"ksher_order_id": "90020220301161212118281"
},
{
"amount": 1,
"transaction_time": "2022-03-01 15:10:13",
"type": "PAY",
"channel": "wechat",
"device_id": "",
"operator_id": 34447,
"operator_name": "MR.WANG XU",
"currency": "THB",
"order_id": "1_18901",
"ksher_order_id": "90020220301161007714189"
},
{
"amount": 1,
"transaction_time": "2022-03-01 15:04:43",
"type": "PAY",
"channel": "wechat",
"device_id": "",
"operator_id": 34447,
"operator_name": "MR.WANG XU",
"currency": "THB",
"order_id": "1_18899",
"ksher_order_id": "90020220301160437486332"
},
{
"amount": -1,
"transaction_time": "2022-03-01 15:01:38",
"type": "REFUND",
"channel": "wechat",
"device_id": "",
"operator_id": 34447,
"operator_name": "MR.WANG XU",
"currency": "THB",
"order_id": "2_18897",
"ksher_order_id": "90020220301155352743361"
},
{
"amount": 1,
"transaction_time": "2022-03-01 14:54:03",
"type": "PAY",
"channel": "wechat",
"device_id": "",
"operator_id": 34447,
"operator_name": "MR.WANG XU",
"currency": "THB",
"order_id": "1_18891",
"ksher_order_id": "90020220301155352743361"
},
{
"amount": 100,
"transaction_time": "2022-03-01 14:31:48",
"type": "PAY",
"channel": "promptpay2",
"device_id": "gate_satgenes137",
"operator_id": 34447,
"operator_name": "MR.WANG XU",
"currency": "THB",
"order_id": "20220301010",
"ksher_order_id": "90020220301153118324574"
},
{
"amount": 1,
"transaction_time": "2022-03-01 12:09:22",
"type": "PAY",
"channel": "linepay",
"device_id": "gate_sdits424",
"operator_id": 34447,
"operator_name": "MR.WANG XU",
"currency": "THB",
"order_id": "SUB20220301120848",
"ksher_order_id": "90020220301130856725628"
},
{
"amount": 500,
"transaction_time": "2022-03-01 10:30:32",
"type": "PAY",
"channel": "truemoney",
"device_id": "gate_s39449130",
"operator_id": 34447,
"operator_name": "MR.WANG XU",
"currency": "THB",
"order_id": "1001",
"ksher_order_id": "90020220301113031400620"
}
],
"total": 15,
"channel": "",
"limit": 50,
"count": 15,
"offset": 0
},
"error_code": "SUCCESS",
"signature": "6A8139EF256F9AAF3D7DEDE137DC619D017814FFFFEF4ED2FE9F54C41F338E1B",
"timestamp": "20220301111213",
"mid": "35618"
}

Create Settlement data#

Settlement report is mean report ksher already tranfer cash to merchant. It will only display transaction ksher tranfer to merchant.

Create Settlement data for check detail next step

API#

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

Request parameter#

path parameter#
nameLocationTypesrequiredinstruction
yyyymmddpathstringYesThe year, month and day to be queried, such as 20210803
channelquerystringYesthe channel need to query, you should query one by one
midquerystringYesthe mid of the request.
signaturequerystringYesRequest signature
timestampquerystringYesTimestamp

Request URL example#

https://sandbox.vip.ksher.net/api/v1/finance/settlements/20220310?channel=wechat&signature=6A8139EF256F9AAF3D7DEDE137DC619D017814FFFFEF4ED2FE9F54C41F338E1B&timestamp=20220310111213

Response result#

Successful response example

{
"error_message": "Successful",
"data": {
"transfer_amount": 0,
"amount": 100,
"balance": 0,
"other_fee": 0,
"channel": "wechat",
"transfer": false,
"refund": 0,
"count": 3,
"fee": 1,
"currency": "THB",
"refund_fee": 0,
"end": "2022-03-09",
"net": 99,
"reference_id": "20220310_35618_XVHNDY",
"start": "2022-03-09",
"adjustment": 0,
"time": "2022-03-10 09:57:09"
},
"error_code": "SUCCESS",
"signature": "6A8139EF256F9AAF3D7DEDE137DC619D017814FFFFEF4ED2FE9F54C41F338E1B",
"timestamp": "20220310111213",
"mid": "35618"
}

Settlement order#

Settlement report is mean report ksher already tranfer cash to merchant. It will only display transaction ksher tranfer to merchant.

query the information of the settlement need to use response from 8. Settlement data acquisition

API#

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

Request parameter#

path parameter#
nameLocationTypesrequiredinstruction
reference_idpathstringYesreference id get from Create Settlement data API
limitqueryintegerYesdata size one time, must less than 50, default=50
offsetqueryintegerYesData Offset, default=0
signaturequerystringYesRequest signature
timestampquerystringYesTimestamp

Request URL example#

https://sandbox.vip.ksher.net/api/v1/finance/settlements/settlement_order?reference_id=20220310_35618_XVHNDY&signature=6A8139EF256F9AAF3D7DEDE137DC619D017814FFFFEF4ED2FE9F54C41F338E1B&timestamp=20220310

Response result#

Successful response example

{
"error_message": "Successful",
"data": {
"transfer_amount": 0,
"amount": 100,
"balance": 0,
"other_fee": 0,
"channel": "wechat",
"transfer": false,
"refund": 0,
"count": 3,
"fee": 1,
"currency": "THB",
"refund_fee": 0,
"end": "2022-03-09",
"net": 99,
"reference_id": "20220310_35618_XVHNDY",
"start": "2022-03-09",
"adjustment": 0,
"time": "2022-03-10 09:57:09"
},
"error_code": "SUCCESS",
"signature": "6A8139EF256F9AAF3D7DEDE137DC619D017814FFFFEF4ED2FE9F54C41F338E1B",
"timestamp": "20220310111213",
"mid": "35618"
}

9. WebHook#

The webhook callback address can be configured in the background of the gateway payment gateway

img.png

When the order status changes, the payment gateway will send a GET request to the webhook address with the following parameters

Parameter nameTypesDescription
typestringEvent Types, fixed value "order"
instancestringMerchant side order number, that is, the merchant_order_id field
codestringEvent code, fixed value "statuschange"
messagestringOrder status changes
signaturestringRequest signature

  • The request can be signed and verified through the signature rule, and the apiUrl in the signature rule uses the full address of the webhook

  • If the webhook address response is 200, the notification is successful, otherwise the notification will be repeated, repeated every 5 seconds, at most 6 times

  • When receiving the webhook notification, the parameters need to be verified. For the verification process, please refer to the signature calculation section below.

  • Note the signature is used for you to validate the web hook is actually come from the Payment Gateway or not. you should validate the signature using the same algorithm as other API call.

message#

message field value

valueinstruction
Order TimeoutOrder timeout
Order ClosedOrder closed
Order PaidOrder Paid
Order RefundedOrder partial refund/full refund

Webhook notification example#

URLwebhook address
MethodGET

Request content#

Example in Query string#

{https://yoururlwebhooksetup}?code=StatusChange&instance=test_linepay01&message=Order%20Paid&signature=DA0608731FA24D4C8694D839A2D990D4AEDF3A897126C09BE4C9D6B4DB605932&type=Order

Example in Postman#

webhook_sample_request.png

Note the signature is used for you to validate the web hook is actually come from the Payment Gateway or not. you should validate the signature using the same algorithm as other API call.

Test a webhook endpoint#

If you don't have public url you can setup Webhook URL to send some test webhook like https://webhook.site

or you can read info about Test WebHook registration with request logging site from Microsoft.

10. Signature calculation#

Gateway API will verify every API request, so every HTTP request must include signature information, and requests with invalid signatures will return an error

The gateway API passes the token verification request set in the payment background. The token can be used to produce the signature field in the HTTP request, which needs to be strictly confidential.

The token can be obtained or reset in the following locations:

img_1.png

If you manually write HTTP requests instead of using the official SDK, you need to understand the signature algorithm

Signature algorithm#

The process of generating a signature is as follows

1. Sort all request parameters (except the signature field) according to the parameter name in the ASCII table. For example:#

Before sorting：foo=1, bar=2, foo_bar=3, foobar=4
After sorting：bar=2, foo=1, foo_bar=3, foobar=4

2. Concatenate the sorted parameters and their values into a string. For example:#

bar2foo1foo_bar3foobar4

3. Add the API name before the spliced string, take the creation of the order interface as an example "/api/v1/redirect/orders"#

/api/v1/redirect/ordersbar2foo1foo_bar3foobar4

4. Encode the string in UTF-8 format, and use the HMAC_SHA256 signature algorithm for digest, the secret key is the token in the background configuration above#

Here is a demonstration of a third-party encryption tool, you can use the third-party tool library according to the development language to achieve HMAC_SHA256 signature

img_2.png

webhook verify signature#

When calculating the webhook signature, the API name is the full url of the webhook address, and the other steps are the same

Note that when the parameters are spliced into strings, the signature field must be excluded before splicing

If the final signature value is consistent with the signature in the request received by webhook, the verification is successful

Edit this page