Mch Notify URL (Gateway Pay)

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

Delayed messages will be retried 12 times within 29 hours

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

API method

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.

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

msg

String(32)

YES

操作成功

the response message.

message

String(32)

YES

操作成功

the response message.

data Parameters (JSON )

channel

String(128)

YES

alipay

Payment channel pay by this transaction.

openid

String(128)

YES

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

channel_order_no

String(32)

YES

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.

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.

nonce_str

String(32)

YES

WQVzZs6qgYUVXWkt9nw15QBWI2jFNMjk

Random string

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

appid

String(32)

YES

mch12345

Your Merchant Number. Check on merchant ksher. The format is mch{Merchant No}.

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.

pay_mch_order_no

String(32)

YES

generated by merchant self, it must be unique on the merchant side.
Example 1. SUCCESS Example

Data will response in text format following like this

{"code": 0, "msg": "操作成功", "data": {"channel": "truemoney", "openid": "tmn.10036553303", "channel_order_no": "230523131245589KSUSL", "cash_fee_type": "THB", "ksher_order_no": "90020230523141245533239", "nonce_str": "DLtzj2QZ5FSaydJEUTS3sTAO552IGhwp", "time_end": "2023-05-23 13:12:45", "fee_type": "THB", "attach": "", "rate": "", "result": "SUCCESS", "total_fee": 100, "appid": "mch35005", "cash_fee": 100, "mch_order_no": "2023-05-23-13-10-00", "pay_mch_order_no": "2305231312099897"}, "sign": "389cbf000d6bf322b1ebb99e726417f7604384654bdc41cd82a70b1155ad7ddb381592f5127516bc7690c66011c563b6075700f9e5d00de8ab82aafecf55d9d6", "message": "操作成功"}

after convert data to json format will following this

{
   "code":0,
   "msg":"操作成功",
   "data":{
      "channel":"truemoney",
      "openid":"tmn.10036553303",
      "channel_order_no":"230523131245589KSUSL",
      "cash_fee_type":"THB",
      "ksher_order_no":"90020230523141245533239",
      "nonce_str":"DLtzj2QZ5FSaydJEUTS3sTAO552IGhwp",
      "time_end":"2023-05-23 13:12:45",
      "fee_type":"THB",
      "attach":"",
      "rate":"",
      "result":"SUCCESS",
      "total_fee":100,
      "appid":"mch35005",
      "cash_fee":100,
      "mch_order_no":"2023-05-23-13-10-00",
      "pay_mch_order_no":"2305231312099897"
   },
   "sign":"389cbf000d6bf322b1ebb99e726417f7604384654bdc41cd82a70b1155ad7ddb381592f5127516bc7690c66011c563b6075700f9e5d00de8ab82aafecf55d9d6",
   "message":"操作成功"
}

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