Gateway Order Query

API method

URL

https://gateway.ksher.com/api/gateway_order_query

Method

POST

Parameter organization format

application/x-www-form-urlencoded

Order Query Request Parameters

Parameter Type Required Example Description

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

Digital signature for verifying the authenticity of digital messages. Please check how to got Signature Algorithm page

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

Random string, must be unique

time_stamp

String(256)

YES

time stamp example: "time_stamp": "20190622131804"

mch_order_no

String(32)

YES

order number on merchant side, must be unique
Example 1. Request Example
{
    "appid": "mch32625",
    "mch_order_no": "33663431",
    "nonce_str": "d2b4874c75fca3d7c637bee971ede6ac",
    "sign": "6aa39ba2ab6ac60df6223b0604a1fffe62280d33accb6d91a2dceea6648c04b8117d5b33f5f348d21adcc47f1f63faae8fd77b6800e476bf92d5ad45488cdadc",
    "time_stamp": "2020041421583131S"
}

Order Query SUCCESS Response Parameters

Parameter Type Required Example Description

code

int

YES

0

code msg 0 SUCCESS

lang

String(256)

YES

The display languange.The default language is English if no specification.Value range: * "en":----English * "cn":----Chinese * "th":----Thai

result

string(16)

YES

FAIL

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.

message

String(128)

Detailed description of result

msg

String(128)

YES

system error

the detailed description of the error

data

JSON

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

attach

String

YES

e-wallet local currency total amount, unit is cent.

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.

channel

String(16)

YES

alipay

Actual payment e-wallet channel.Value range: alipay, linepay, airpay, wechat, promptpay, truemoney.

channel_order_no

String(32)

Conditional

e-wallet order number. Only response with result "SUCCESS" and "REFUND".

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.

pay_mch_order_no

String(32)

YES

4200000553202004150354623931

Gateway Pay unique order number

ksher_order_no

String(32)

YES

merchant Order number, must be unique.

nonce_str

String(32)

YES

Random string.

openid

String(128)

NO

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

rate

String(16)

YES

Exchange rate of foreign currency to RMB.

result

String(16)

YES

Value Range:FAIL/SUCCESS/NOTPAY/CLOSED/PAYERROR/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 succeeded

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

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

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

  • REFUND: the order has refunded partially or completely.

  • Note: after order apply, merchant should regard SUCCESS as final result, the rest result :"NOTPAY/PAYERROR/" means real time status , not the final result, user still can pay again. "FAIL" Only happened when e-wallet 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 e-wallet 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 e-wallet or e-wallet 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.

time_end

String(20)

2020-04-15 09:49:19

Payment success time

total_fee

Int

YES

total amount of the order and it must be an integer, the unit is cent
Example 2. SUCCESS Response Example
{
    "code": 0,
    "data": {
        "appid": "mch32625",
        "attach": "",
        "cash_fee": 21,
        "cash_fee_type": "CNY",
        "channel": "wechat",
        "channel_order_no": "4200000553202004150354623931",
        "fee_type": "THB",
        "pay_mch_order_no": "2004150948529843",
        "ksher_order_no": "90020200415104909426008",
        "mch_order_no": "77713",
        "nonce_str": "UHl8XNywZjdMrpsWCNy00gOYbspYzH7Z",
        "openid": "o2G4c04tmsU-wsCG7jN_ORL5Vh14",
        "rate": "0.222657",
        "result": "SUCCESS",
        "time_end": "2020-04-15 09:49:19",
        "total_fee": 100
    },
    "lang": "",
    "message": "操作成功",
    "msg": "操作成功",
    "sign": "a19fb42985cbf2ce81e74a1e2aa7fdaf42d33234b3f5d9a3ce9230d1cabc2796abd05c6b00951c6c33f557410d029853bf70d99af32cae858f1484412309f242"
}

or

 {
    "code": 0,
    "data": {
        "appid": "mch28321",
        "attach": "",
        "cash_fee": 102,
        "cash_fee_type": "THB",
        "channel": "card",
        "channel_order_no": "509109",
        "fee_type": "THB",
        "ksher_order_no": "70020200713155936857097",
        "mch_order_no": "12594",
        "nonce_str": "FbbQyfY7Nskt1D8rHqFunx6SWJYt0mOz",
        "openid": "453215******0399 YAYA NUGHT",
        "pay_mch_order_no": "2007131459298082",
        "rate": "",
        "result": "SUCCESS",
        "time_end": "2020-07-13 14:59:36",
        "total_fee": 100
    },
    "lang": "",
    'message': '操作成功',
    'msg': '操作成功'
    "sign": "63b77c9542e6f5cd62a72dff0a72d055228fdeb68943dabe0ebb64e413beb2cf69a8b4ac106934e9f40a555b9eafaf5d512ea3750cadb3d3158dd913c3a01bdf"
}

Order Query Fail Response Parameters

Parameter Type Required Example Description

code

int

YES

0

code msg * -1: merchant info error * -2: sign failed to verify * -3: order not exist * -4: order number is not unique * -100: query order failed

lang

String(256)

YES

The default language is English if no specification. Value range: * "en":----English * "cn":----Chinese * "th":----Thai

message

String(128)

Detailed description of result

msg

String(128)

YES

system error

the detailed description of the error
Example 3. Fail Response Example
{'lang': '', 'code': -3, 'msg': '该订单不存在', 'message': '该订单不存在'}