Refund Query

Note: Promptpay and Aliapy not support this feature.

API method

URL

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

Method

POST

Parameter organization format

application/x-www-form-urlencoded

Refund Query Request Parameters

Parameter Type Required Example Description

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.

appid

String(32)

YES

mch12345

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

nonce_str

String(32)

YES

ae0e6jm55qlq1o7

Random string, must be unique for signature.

mch_order_no

String(32)

YES (mch_order_no, ksher_order_no, channel_order_no not needed to provide all, you can select at least one parameters to to sending.)

order number on merchant side, must be unique

ksher_order_no

String(32)

YES (mch_order_no, ksher_order_no, channel_order_no not needed to provide all, you can select at least one parameters to to sending.)

Order no. generated by Ksher.

channel_order_no

String(32)

YES (mch_order_no, ksher_order_no, channel_order_no not needed to provide all, you can select at least one parameters to to sending.)

Order no. generated by payment channel(wechat, alipay etc.)

channel

String(32)

NO

wechat

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

total_fee

Int

YES

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

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_refund_no

String(32)

YES

generated by merchant self, each refund no. can be used once only.

refund_fee

Int

YES

100

amount to refund, unit is cent, it must be an integer. refund partly is permitted.

attach

String(127)

NO

any extra information can be added here.

device_id

String(32)

NO

POS001

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

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

time_stamp

String(256)

YES

time stamp example: "time_stamp": "20190622131804"

version

String(32)

NO

"3.0.0"

API version
Example 1. Request Example
{
    "appid": "mch20163",
    "channel": "wechat",
    "fee_type": "THB",
    "ksher_order_no": "",
    "mch_order_no": "1495773587",
    "nonce_str": "IeYrVB93dq8JbJbHJq1oZAW4d7PEb4jU",
    "sign":     "14bc865f1d360210ef9b7551304faa905f2240e1f7eca2ddaadcdc1287cda90f3149dac8aab7163084be4fdf56fe12bdc95ae87a6b4187b94e4118e435f0db23",
    "time_stamp": "20170516125822",
    "version": "3.0.0"
}

or

 {
    "appid": "mch28321",
    "ksher_order_no": "70020200714124058662887",
    "mch_refund_no": "refund1594708697",
    "nonce_str": "a42e75d0f3859e31f93146aaf4cf4f48",
    "sign": "78f93882b5456bcd3bba29704c820f93f0863c633697322147f60b32eaeb78f4f99b79d65ff48cd1118c1955a05b674fb496b38e29692064608bf511f09141bc",
    "time_stamp": "2020071417093939S"
}

Refund Query SUCCESS 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 parameter to launch the request again.

msg

String(32)

YES

the response message.

status_code

reserved for future use

status_code

int

YES

1: 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(32)

YES

2020042015374848S

the time stamp of request order

version

String(32)

NO

"3.0.0"

API version

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

data Parameters (JSON )

cash_fee

int

YES

CNY

specifies the total cash payment amount of a transaction.

cash_fee_type

string(16)

YES

CNY

the currency buyer paid, 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.

channel_state

string(16)

YES

SUCCESS

the response state from e-wallet

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.

ksher_order_no

String(32)

YES

Order no. generated by Ksher.

mch_order_no

String(32)

YES

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

nonce_str

String(32)

YES

"sQ8gfSpeeV5Ld8ulW9q7JxUnXSOiZ90Y"

Random string

refund_count

int

YES

Total times of refund for this order.

refund_fee

Int

YES

100

amount to refund, unit is cent, it must be an integer. refund partly is permitted.

refund_orders Parameters (JSON )

channel_refund_no

String(32)

YES

generated by channel(wechat), each refund no. can be used once only.

ksher_refund_no

String(32)

YES

generated by Ksher, each refund no. can be used once only.

mch_refund_fee

String(32)

YES

100

amount to refund, unit is cent, it must be an integer. refund partly is permitted.

mch_refund_no

String(32)

YES

generated by merchant self, each refund no. can be used once only.

refund_state

String(32)

YES

SUCCESS

refund status：

  • REFUNDSUCCESS—succeeded to refund,

  • FAIL—failed to refund, PROCESSING—the refund application is being processed,

  • NOTSURE—not sure(merchant needs to submit refund application again with the same refund no.),

  • CHANGE—change to the merchant paying(the bank card of the consumer is already unavailable or frozen, which lead to the failure of refunding back into the bank card and funds flew back to the cash account, in this case, merchant needs to refund consumer offline or through transfer )

refund_time

String(14)

YES

When the refund was made.
Example 2. SUCCESS Response Example
 {
    "code": 0,
    "data": {
        "appid": "mch28321",
        "cash_fee": 204,
        "cash_fee_type": "THB",
        "channel_order_no": "509366",
        "fee_type": "THB",
        "ksher_order_no": "70020200714124058662887",
        "mch_order_no": "2007141140508182",
        "nonce_str": "a42e75d0f3859e31f93146aaf4cf4f48",
        "refund_count": 1,
        "refund_fee": 0,
        "refund_orders": [
            {
                "channel_refund_no": "",
                "ksher_refund_no": "70020200714143818745766",
                "mch_refund_fee": 100,
                "mch_refund_no": "refund1594708697",
                "refund_state": "FAIL",
                "refund_time": "2020-07-14 13:38:18"
            }
        ],
        "result": "SUCCESS",
        "time_end": "2020-07-14 13:38:18",
        "total_fee": 204
    },
    "msg": "ok",
    "sign": "01bc29db4a5d01c0d2a414dd1fc7e8ab122ce48934fd2f9c63e748e9a6b2a2dc52f35bedffda2a42a1eea686dad3fc5af8c481d28bd76fff8870e029094aac76",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-07-14T17:09:40.730470+08:00",
    "version": "3.0.0"
}

Refund Query FAIL Response Parameters

Parameter Type Required Example Description

code

int

YES

0

Value Rangne:

  • 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

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.

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 .

  • FAIL : failed to close,in this case, merchant should re-launch the close request.

  • NOTSURE: it is not sure if the close operation succeed.

nonce_str

String(32)

YES

"sQ8gfSpeeV5Ld8ulW9q7JxUnXSOiZ90Y"

Random string

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
Example 3. FAIL Response Example
 {
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_ORDER_NO",
        "err_msg": "failed to find this order no ('mch_refund_no:refund1594708697i' ).",
        "nonce_str": "4d4309ac8556d17238a297ea917b7b81",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "012cc8f39b1b41857ed2511066ad76c4045c87a98b94e3574064b9ac130e5b56b4a572c96a37644a8b53a7ca25ee5bae051c9b89a8323852e2eb805484a4d399",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-07-14T17:13:32.181825+08:00",
    "version": "3.0.0"
}