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 Note: You do not need to provide all three parameters (mch_order_no, ksher_order_no, channel_order_no). At least one parameter is required.

ksher_order_no

String(32)

NO

Order no. generated by Ksher. Note: You do not need to provide all three parameters (mch_order_no, ksher_order_no, channel_order_no). At least one parameter is required.

channel_order_no

String(32)

No

Order number generated by the payment channel (e.g., WeChat, Alipay, etc.). Note: You do not need to provide all three parameters (mch_order_no, ksher_order_no, channel_order_no). At least one parameter is required.

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 API call is successful, not that the target business operation succeeded.

  • 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 API call is successful, not that the target business operation succeeded.

  • 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 operation the request is.

operator_id

String(32)

NO

41234

Operator ID at checkout, used for merchants with multi-level accounts or cashiers. For more information, see Multi-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: indicates the order query operation failed for some reasons, such as the order number not being found in the Ksher database or incorrect parameters. It does not mean the order itself failed; the 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, such as a wrong password or errors between WeChat and the bank.

  • PENDING: order is pending while entering PIN.

  • NOTSURE: unknown status, waiting for customer payment.

  • 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 applying an order, merchants should treat SUCCESS as the final result. The other results, "NOTPAY/PAYERROR/PENDING/NOTSURE/USERPAYING", indicate real-time status and are not final; users can still pay again. "FAIL" only happens when there is a payment channel or bank system error, which is rare.

  • "REFUND" means the amount has already been returned to the consumer.

  • Query suggestion: Merchants can receive successful payment callbacks through notify_url. Use Order Query when the payment status is unclear and you need to confirm whether the payment was completed. Ksher recommends polling Order Query only when needed. If merchants poll too frequently with the same mch_order_no, the server may block requests with KSHER_API_ERR_ORDER_TOO_MANY_REQUESTS. Please keep a minimum interval of at least 10 seconds per mch_order_no.
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"
}