Order Refund

If want to refund, before refund please use Gateway order query to get Pay_mch_order_no and using mch_order_no = Pay_mch_order_no value on refund API or use ksher_order_no to refund

Not all wallets allow refunds. Please refer to API support for each wallet to check which wallets support refunds.

API method

URL

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

Method

POST

Parameter organization format

application/x-www-form-urlencoded

Order Refund Request Parameters

Parameter Type Required Example Description

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.

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

2103301701291052

order number on merchant side, must be unique

ksher_order_no

String(32)

NO

90020210330180132318847

Order no. generated by Ksher. ksher Order no. should be provided when request card payment refund

channel_order_no

String(32)

YES

1207919130

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)

NO

wechat

Value range:

alipay: Alipay Wallet.

alipayplus: Alipay+ Wallet.

wechat: Wechat Wallet.

linepay: Rabbit LINE Pay Wallet. Country support only Thailand.

airpay: Shopeepay Wallet. Country support only Thailand.

truemoney: TrueMoney Wallet. Country support only Thailand.

atome: Atome Buy now pay later. Country support only Thailand.

card: Card Gateway. support Visa Card, Master Card, Union Pay Card, TPN Card. Country support only Thailand.

ktc_instal: KTC Installment. support only KTC Card. Country support only Thailand.

kbank_instal: KBANK Installment. support only KBANK Card. Country support only Thailand.

kcc_instal: Krungsri Installment. support only Krungsri Card. Country support only Thailand.

kfc_instal: First Choice Installment. Country support only Thailand.

You can check wallet support refund at Account type and API support each wallet.

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

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

refund_2103301701291052

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

version

String(32)

NO

API version
Example 1. Request Example
 {
    "appid": "mch35005",
    "fee_type": "THB",
    "mch_order_no": "2103301701291052",
    "mch_refund_no": "refund_2103301701291052",
    "nonce_str": "9c75d11e7572f887dbbfe374f205d5eb",
    "refund_fee": 100,
    "sign": "29cb8b5997f5e15e4c15a8caa4c7eb057a4185f1c6ecaa2a5a826b07bd07fe96a86c964abb38dcf5984399974266784cba8214478a6d9eccada4aa64ccb336d0af31aba0e63eaf0b3e972b19578b0116fdafd9c63f0756d15714284b556dbb76761a09291985bcf06319e4da5abda2652d18b8ce56962c0375168205d9abd301",
    "time_stamp": "2021033014385656S",
    "total_fee": 100
}

or

 {
    "appid": "mch35005",
    "fee_type": "THB",
    "ksher_order_no": "90020210330180132318847",
    "mch_order_no": "2103301701291052",
    "mch_refund_no": "refund_2103301701291052",
    "nonce_str": "9c75d11e7572f887dbbfe374f205d5eb",
    "refund_fee": 100,
    "sign": "0a0efce05ccfbd17d16ae46724a8be7398656177064ac9a71ea3acc6f3fe7a46bebf458d4d15ee4bb6eb750d8cd79dd633a1c13eafd1c8894e45122d3cc4a3f381e4a3874decbdce38b3d3f9de343455bb741f07e019a960e50f577c13b4a6bd0aaf7cc1a47effe38196a64cb730b9d85ef166f3d6c6f7fca6c8edcb1bc87700",
    "time_stamp": "2021033014385656S",
    "total_fee": 100
}

Order Refund 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.

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

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

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_refund_fee

int

YES

the currency Amount refunded to customer, normally in CNY.

channel_order_no

String(32)

YES

1207919130

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_refund_no

String(32)

YES

1207919130

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

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.

ksher_order_no

String(32)

YES

90020210330180132318847

Order no. generated by Ksher.

ksher_refund_no

String(32)

YES

90020210330180400878914

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

mch_order_no

String(32)

YES

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

mch_refund_no

String(32)

YES

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

nonce_str

String(32)

YES

Random string

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

refund_fee

Int

YES

100

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

result

string(16)

YES

SUCCESS

Value range: SUCCESS

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": "mch35005",
        "attach": "",
        "cash_refund_fee": 100,
        "channel": "airpay",
        "channel_order_no": "1207919130",
        "channel_refund_no": "1207919130",
        "device_id": "",
        "fee_type": "THB",
        "ksher_order_no": "90020210330180132318847",
        "ksher_refund_no": "90020210330180400878914",
        "mch_order_no": "2103301701291052",
        "mch_refund_no": "refund_2103301701291052",
        "nonce_str": "9c75d11e7572f887dbbfe374f205d5eb",
        "operator_id": "",
        "refund_fee": 100,
        "refund_time": "2021-03-30 17:04:01",
        "result": "SUCCESS",
        "total_fee": 100
    },
    "msg": "ok",
    "sign": "4e8defe365f08a66b28f40843117268c49c772807196ac0b55591f992a9dcdff5d68f8fec01f029d0922df6795b72e211a3fc2de8056e4b19dc6ceaad86894f1",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2021-03-30T18:04:01.525337+08:00",
    "version": "3.0.0"
}

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

msg

String(32)

YES

the response message.

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

String(32)

YES

"3.0.0"

version of the API

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

YES

2020042015374848S

the time stamp of request order

data Parameters (JSON )

result

string(16)

YES

FAIL

Value range:

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

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

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_SYSTEMERROR",
        "err_msg": "ksher system error. please retry.",
        "nonce_str": "19f47657a679646276f213eb67782763",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "055ac35d8eede994c67398ede3ce91c3970460b379f26eff58bc4a838a9f1a837e41dc4a9a5c1fe6f1ba8f153459f679cdbfaeec94bcbcb16fe0d54a76b84e59",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-07-14T16:43:41.178834+08:00",
    "version": "3.0.0"
}