Notify URL

What’s Webhook?

Webhook is API response when Customer paid like event. It make customer don’t need to polling to check status.

When webhook callback?

add parameter name "notify_url" when you request, ksher will initiate a webhook callback.
ksher will polling check the status payment within 2 hours.
- if the order has been successful payment within 2 hours, webhook will callback.
- if the order has not been paid within 2 hours , The merchant needs to query request by yourself.
If ksher got callback from wallet. we will call webhook to merchant also.

What going on If internet not stable and don’t got webhook at the first time?

If the merchant does not return correct format,we will try to callback again.

Correct format response

{"result": "SUCCESS", "msg": "OK"}

This is table webhook with times notification, if customer not response correct success type and or we can’t callback

Times retry	Times between the last retry
1st retry	1s
2nd retry	2s
3rd retry	2s
4th retry	10s
5th retry	30s
6th retry	1min
7th retry	10min
8th retry	1hour
9th retry	3hour
10th retry	5hour
11th retry	8hour
12th retry	12hour

Times retry

Times between the last retry

1st retry

2nd retry

3rd retry

4th retry

10s

5th retry

30s

6th retry

1min

7th retry

10min

8th retry

1hour

9th retry

3hour

10th retry

5hour

11th retry

8hour

12th retry

12hour

Delayed messages will be retried 12 times within 29 hours

After consumer pays, Ksher system will notify merchant only SUCCUSSFULL payment

API method

URL

http://api.mch.ksher.net/KsherPay/pay_notify

Method

POST

Parameter organization format

text/plain;charset=utf-8

Payment Result of SUCCESS

Parameter	Type	Required	Example	Description
code	int	YES	0	0: it only shows the calling of the API is successful, not meaning the target business operation succeed.
status_code	int	YES		0: it only shows the calling of the API is successful, not meaning the target business operation succeed. Non 0: Calling of the API failed, merchant can use the same parameters to launch the request again.
status_msg	String(256)	NO		the status message
sign	String(256)	YES	b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4	To verify the accuracy of this response, please refer to the method outlined in the section Verify Signature.
version	String(32)	YES	"3.0.0"	API version
msg	String(32)	YES	ok	the response message.
time_stamp	String(256)	YES	"20190622131804"	time stamp
data Parameters (JSON )
appid	String(32)	YES	mch35000	Your Merchant Number. Check on how to find your appid/Merchant No.. The format is mch{Merchant No}.
nonce_str	String(32)	YES	ae0e6jm55qlq1o7	Random string, must be unique for signature.
openid	String(128)	YES	o5x64wG48fnZyqWOxqJl-MPSkNJ4	Customer’s id under this merchant’s public account.
channel_order_no	String(32)	YES	4001432001201705110439447536	Order no. generated by payment channel(alipay, alipay etc.)Note:Not all these three parameters(mch_order_no, ksher_order_no, channel_order_no) are needed to provide at one time, but at least one should be provided.
operator_id	String(32)	NO	41234	operator_id number at cashier, using for merchant have muti level account or Cashier. For more information please check at Muti level account or Cashier
cash_fee_type	String	YES	THB	e-wallet local currency, e.g. THB for Thailand e-wallets, CNY for Chinese e-wallets Alipay, WeChat Pay.
ksher_order_no	String(32)	YES	90020210420105438458353	Order no. generated by Ksher.
time_end	String(14)	YES	2014-10-30 13:35:25	the merchant local time when the order is finished，the format is yyyy-MM-dd HH:mm:ss
fee_type	String(16)	YES	THB	Currency code for total_fee. refer to with ISO 4217. Value range: THB: Thai Baht use for Thailand. MYR: Malaysia JPY: Japan AED: United Arab Emirates dirham use for UAE.
attach	String(127)	YES		any extra information can be added here.
rate	string(16)	YES		exchange rate of foreign currency to RMB.
result	string(16)	YES	SUCCESS	Status payment. Value range: SUCCESS
total_fee	Integer	YES	100	total amount of the order and it must be an integer, add 00 for decimal.Example 150.50 THB total_fee = 15050
operation	String	YES	QUICK-PAY	this shows what operatation the request is.
device_id	String(32)	NO	POS001	terminal id from which the request is sent, assigned by merchant.
cash_fee	int	YES		specifies the total cash payment amount of a transaction.
mch_order_no	String(32)	YES		generated by merchant self, it must be unique on the merchant side, same as the input.
order_no	String(32)	YES		generated by merchant self, it must be unique on the merchant side, same as the input.Equate to mch_order_no.

Parameter

Type

Required

Example

Description

code

int

YES

0: it only shows the calling of the API is successful, not meaning the target business operation succeed.

status_code

int

YES

0: it only shows the calling of the API is successful, not meaning the target business operation succeed.
Non 0: Calling of the API failed, merchant can use the same parameters to launch the request again.

status_msg

String(256)

the status message

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

To verify the accuracy of this response, please refer to the method outlined in the section Verify Signature.

version

String(32)

YES

"3.0.0"

API version

msg

String(32)

YES

the response message.

time_stamp

String(256)

YES

"20190622131804"

time stamp

data Parameters (JSON )

appid

String(32)

YES

mch35000

Your Merchant Number. Check on how to find your appid/Merchant No.. The format is mch{Merchant No}.

nonce_str

String(32)

YES

ae0e6jm55qlq1o7

Random string, must be unique for signature.

openid

String(128)

YES

o5x64wG48fnZyqWOxqJl-MPSkNJ4

Customer’s id under this merchant’s public account.

channel_order_no

String(32)

YES

4001432001201705110439447536

Order no. generated by payment channel(alipay, alipay etc.)Note:Not all these three parameters(mch_order_no, ksher_order_no, channel_order_no) are needed to provide at one time, but at least one should be provided.

operator_id

String(32)

41234

operator_id number at cashier, using for merchant have muti level account or Cashier. For more information please check at Muti level account or Cashier

cash_fee_type

String

YES

THB

e-wallet local currency, e.g. THB for Thailand e-wallets, CNY for Chinese e-wallets Alipay, WeChat Pay.

ksher_order_no

String(32)

YES

90020210420105438458353

Order no. generated by Ksher.

time_end

String(14)

YES

2014-10-30 13:35:25

the merchant local time when the order is finished，the format is yyyy-MM-dd HH:mm:ss

fee_type

String(16)

YES

THB

Currency code for total_fee. refer to with ISO 4217. Value range:

THB: Thai Baht use for Thailand.

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham use for UAE.

attach

String(127)

YES

any extra information can be added here.

rate

string(16)

YES

exchange rate of foreign currency to RMB.

result

string(16)

YES

SUCCESS

Status payment. Value range: SUCCESS

total_fee

Integer

YES

100

total amount of the order and it must be an integer, add 00 for decimal.Example 150.50 THB total_fee = 15050

operation

String

YES

QUICK-PAY

this shows what operatation the request is.

device_id

String(32)

POS001

terminal id from which the request is sent, assigned by merchant.

cash_fee

int

YES

specifies the total cash payment amount of a transaction.

mch_order_no

String(32)

YES

generated by merchant self, it must be unique on the merchant side, same as the input.

order_no

String(32)

YES

generated by merchant self, it must be unique on the merchant side, same as the input.Equate to mch_order_no.

Example 1. SUCCESS Example

Data will response in text format following like this

{"code": 0, "version": "3.0.0", "status_code": "", "msg": "ok", "time_stamp": "2023-05-22T15:14:55.794084+08:00", "status_msg": "", "data": {"openid": "tmn.10036553303", "channel_order_no": "230522141453987OFSWN", "operator_id": "29398", "cash_fee_type": "THB", "ksher_order_no": "90020230522151258706179", "nonce_str": "4XiQyVYA98tNo21jSX24oatxw6FTXo6D", "time_end": "2023-05-22 14:14:53", "fee_type": "THB", "attach": "", "rate": 0.0, "result": "SUCCESS", "total_fee": 100, "appid": "mch35005", "order_no": "20230522140400", "operation": "NATIVE-PAY", "device_id": "", "cash_fee": 100, "channel": "truemoney", "mch_order_no": "20230522140400"}, "sign": "40cb0b83dd675d5f043ac57696d92575e337431fc682d3dbe529cb324cb2a4cfefe6984b9811790c6c1f0dc75e4fa83a8bb3114ad9a3eeef55dba453ea844706"}

after convert data to json format will following this

{
   "code":0,
   "version":"3.0.0",
   "status_code":"",
   "msg":"ok",
   "time_stamp":"2023-05-22T15:14:55.794084+08:00",
   "status_msg":"",
   "data":{
      "openid":"tmn.10036553303",
      "channel_order_no":"230522141453987OFSWN",
      "operator_id":"29398",
      "cash_fee_type":"THB",
      "ksher_order_no":"90020230522151258706179",
      "nonce_str":"4XiQyVYA98tNo21jSX24oatxw6FTXo6D",
      "time_end":"2023-05-22 14:14:53",
      "fee_type":"THB",
      "attach":"",
      "rate":0.0,
      "result":"SUCCESS",
      "total_fee":100,
      "appid":"mch35005",
      "order_no":"20230522140400",
      "operation":"NATIVE-PAY",
      "device_id":"",
      "cash_fee":100,
      "channel":"truemoney",
      "mch_order_no":"20230522140400"
   },
   "sign":"40cb0b83dd675d5f043ac57696d92575e337431fc682d3dbe529cb324cb2a4cfefe6984b9811790c6c1f0dc75e4fa83a8bb3114ad9a3eeef55dba453ea844706"
}

Response back to Ksher

After Merchant receive notify successful, Merchant must to response return back from receive response. The response is JSON formated and the content is as following. If merchant not response back, ksher will resent again until 12 times.

Example 2. For success:

{"result": "SUCCESS", "msg": "OK"}

Example 3. For error:

{"result": "FAIL", "msg": "some error information"}