Order Query

API method

URL

https://api.mch.ksher.net/KsherPay/order_query

Method

POST

Parameter organization format

application/x-www-form-urlencoded

Order Query Request Parameters

Parameter Type Required Example Description

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.

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

To verify the accuracy of the request message, please refer to the signature creation method in the section Signature Creation.

mch_order_no

String(32)

YES

order number on merchant side, must be unique

ksher_order_no

String(32)

YES

Order no. generated by Ksher.

channel_order_no

String(32)

YES

Order no. generated by payment channel(wechat, 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.

channel

String(32)

YES

wechat

Value range: wechat/alipay/alipayplus/linepay/airpay/promptpay/truemoney

time_stamp

String(256)

YES

time stamp example: "time_stamp": "20190622131804"
Example 1. Request Example
 {
    "appid": "mch36591",
    "mch_order_no": "test5",
    "nonce_str": "b9536a67afb9153ac880492191857c93",
    "sign": "98b1bcf1546145eff11ad38e1b6dcbc7d929497bdada7bb585da693dd75ea69812d57cd8e983f3db47879810553be42bb0aad40c8103ce60100037857e13c121f4c3c5f456673dee78a9ca66d5096942def3315ec1f6036beaf515e0302f6a4377c03ad2c8de5a6ab17b8e1e6f485c5bad3aa22cae6f0562e6740149788b23b9",
    "time_stamp": "2020122516065757S"
}

Order Query SUCCESS Response Parameters

Parameter Type Required Example Description

code

int

YES

0

code msg:

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

  • Not 0: Calling of the API failed, merchant can use the same parameter to launch the request again.

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.

status_code

int

YES

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

  • Not 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

time_stamp

String(256)

YES

"20190622131804"

time stamp

version

String(32)

YES

"3.0.0"

API version

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

attach

String(127)

NO

any extra information can be added here.

cash_fee

int

YES

specifies the total cash payment amount of a transaction.

cash_fee_type

string(16)

YES

CNY

comply with ISO 4217, CNY by default.

channel_order_no

String(32)

YES

Order no. generated by payment channel(wechat, 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.

device_id

String(32)

NO

POS001

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

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.

mch_order_no

String(32)

YES

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

ksher_order_no

String(32)

YES

Order no. generated by Ksher.

merchant_remark

string

nonce_str

String(32)

YES

Random string

openid

String(16)

YES

CNY

Each user has a unique id under E-Wallet.

operation

String(16)

YES

ORDER-QUERY

this shows what operatation the request is.

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

rate

string(16)

YES

exchange rate of foreign currency to RMB.

raw_total_fee

Int

YES

total amount of the order and it must be an integer, the unit is cent

time_end

String(14)

NO

20141030133525

the time when the order is finished，the format is yyyyMMddHHmmss

total_fee

Int

YES

total amount of the order and it must be an integer, the unit is cent

openid

string(16)

YES

o5x64wG48fnZyqWOxqJl-MPSkNJ4

Each user has a unique id under E-Wallet.

result

string(16)

YES

SUCCESS

Value Range: FAIL/SUCCESS/CLOSED/NOTPAY/PAYERROR/PENDING/NOTSURE/USERPAYING/REFUND

  • FAIL: stands for the order query operation failed for some reasons, such as: the order no. could not be found in the ksher database or some parameters are not correct, etc. , it does not means the order failed, merchant should decide the next step according to the error code.

  • SUCCESS: Payment successful, customer already paid.

  • CLOSED: the order is closed, so customer will be not able to pay it any more.

  • NOTPAY: customer quit the payment window, so payment not finished.

  • PAYERROR: the order failed for some reasons, like: wrong password, errors occurred between wechat and bank.

  • PENDING: order pendding on enter PIN

  • NOTSURE: unknown status. on between waiting customer paid..

  • USERPAYING: Wait customer enter PIN. waiting and then call the Query Order API again to check current transaction status.

  • REFUND: the order has refunded partially or completely.

  • Note: after order apply, merchant should regard SUCCESS as final result, the rest result :"NOTPAY/PAYERROR/PENDING/NOTSURE/USERPAYING" means real time status , not the final result, user still can pay again. "FAIL" Only happened when payment channel bank system error, which happens very few. "REFUND" means this amount already turn back to consumer’s.

  • Query Suggestion: Merchant should continue Polling query order result Until you got SUCCESS or over polling time limit. The time limit of polling query should be one day time (45mins once a second and then half an hour , one hour once) just in case. The Actually the "expire_time" is only limit the gateway page valid time. As long as your user redirect to KTB Payment page within gateway expire time, he still can pay with this order after time expired because he is already left gateway page and stepped into KTB Payment page, in which Ksher can not control. so please polling query payment result very often within your expire_time+15mins ,for example every second. If after 45mins it still not SUCCESS, continue polling query for one day but not that often , maybe half an hour , two hour a time.
Example 2. SUCCESS Response Example
{
    "code": 0,
    "data": {
        "appid": "mch32148",
        "attach": "",
        "cash_fee": 7,
        "cash_fee_type": "CNY",
        "channel": "wechat",
        "channel_order_no": "4200000607202006237838347168",
        "consumer_remark": "",
        "device_id": "",
        "fee_type": "THB",
        "ksher_order_no": "90020200623192741778187",
        "mch_order_no": "1592911660",
        "merchant_remark": "\u6d4b\u8bd5",
        "nonce_str": "f4d6aefa63f67ed4abdd83c164191b63",
        "openid": "o2G4c04tmsU-wsCG7jN_ORL5Vh14",
        "operation": "ORDER-QUERY",
        "operator_id": "25382",
        "rate": "0.223410",
        "raw_total_fee": 1,
        "result": "SUCCESS",
        "time_end": "2020-06-23 18:28:31",
        "total_fee": 1
    },
    "msg": "ok",
    "sign": "1ce187f310e73b26f91e76501bb5d360798d22dba67b1b6120209784ea4c6c6f0318650858a575b43c9ded8e5f2931cdecfa8e110af6ec4f93639011c97b07fe",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-23T19:28:34.761046+08:00",
    "version": "3.0.0"
}

Order Query Fail Response Parameters

Parameter Type Required Example Description

code

int

YES

0

Value Range:

  • 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.

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.

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

time_stamp

String(256)

YES

"20190622131804"

time stamp

version

String(32)

YES

"3.0.0"

API version

data Parameters (JSON )

result

string(16)

YES

FAIL

Value range: FAIL, NOTSURE

err_code

String(32)

YES

SYSTEMERROR

Refer to the error list for the details

err_msg

String(128)

YES

system error

the detailed description of the error

nonce_str

String(32)

YES

Random string
Example 3. Fail Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_ORDER_NO",
        "err_msg": "failed to find this order no ('mch_order_no:test5 ksher_order_no: channel_order_no:' ).",
        "nonce_str": "b9536a67afb9153ac880492191857c93",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "715f342bed7bffa1e9deb68ff1125283572ee3cde61373aadeca1e90b5a554cc112059baa962eba5c117466a2ecd98ef7c3ef7d9b60f4b07b9b2a9d74a92f823",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-12-25T17:26:41.364745+08:00",
    "version": "3.0.0"
}