Mobile APP Integration Guide

Overview

This document describes how merchant or software company use Ksher API to achieve e-payment function in mobile app. There are three solutions for integrating payment function in mobile App:

A. App pay Solution

Support e-wallets: WeChat Pay/Alipay

This solution is for integrating e-payment function in merchant’s Android/iOS native app. after call API will got Deeplink to call over wechat and alipay app.

B.QR code Solution

Support e-wallet: PromptPay/truemoney

This solution is for merchant display QR code for consumer to save in mobile photo album, So that consumer can scan QR code from local mobile photo album.

C.Redirect to H5 Solution

Support e-wallet

card/ktc_instal/kbank_instal/kcc_instal/kfc_instal/promptpay/scb_easy/bbl_deeplink/baybank_deeplink/kplus/linepay/truemoney/atome/alipay

Cannot support

Shopee: because shopee not allow webview call app, they allow only website.

Wechat: wechat not allow open website on mobile to pay out side app. you need to copy link to paid inside wechat app.

This solution is for merchant redirect to mobile website to achieve e-payment function when consumer conduct payment in merchant’s app. merchant need to develop payment run webview page and allow webview to call outside app.

Solution A. native App Integration Solution

User Experience Scenarios

inapp

Users make purchases in merchant apps using APP Pay. Merchants with an app with a large number of Chinese users are recommended to integrate WeChat Pay/Alipay into their app. Once integrated, WeChat/Alipay users can easily complete transactions using WeChat Pay/Alipay through the merchant’s app.

Payment Flow Sequence Diagram

APP Pay payment flow

Specifications of APIs

Steps for WeChat APP Pay integration

  1. Merchant register on Ksher system as an ONLINE merchant and pass the audit to obtain the Ksher merchant number;

  2. Merchant need to register on the WeChat open platform (https://open.weixin.qq.com/) to obtain the certification and APP’s WeChat_APPID ;

  3. Merchant obtains Ksher_APPID and key from Ksher merchant platform https://merchant.ksher.net/big_business/index;

  4. Merchant need to tell Ksher WeChat _APPID and Verified Entity Name for Ksher to Apply for Wechat App Pay binding.

  5. Merchant use APP_pay to access integrated development.

  6. On the merchant side, WeChat Pay open SDK（for Android/iOS https://pay.weixin.qq.com/wiki/doc/api/wxpay/ch/pages/In-AppPay.shtml ） integrated into the mobile app.

  7. After completing above steps, call Ksher App Pay API to complete transactions.

Order Apply

Only support E-Wallets: Wechat and alipay

API method

URL

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

Method

POST

Parameter organization format

application/x-www-form-urlencoded

Order Apply 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

Random string

channel

String(32)

YES

wechat

Payment Merchant list support. Value range:

wechat : Wechat Wallet.

alipay: Alipay Wallet.

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

mch_order_no

String(32)

YES

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

local_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: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (UAE)

channel_sub_appid

String(32)

NO

appid of app. The parameter channel is required when its value is wechat

notify_url

String(256)

YES

http://www.myweb.com/wepay/pay_notify

the url to receive the asynchronous notification about the status of the payment from Ksher; If merchant leaves this field blank, then there will be no notification to send back to merchant.

redirect_url

String(256)

YES

the url of payment result page, to which redirected from Ksher Payment Page.

product

String(512)

YES

Product name etc. info can be put here.

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.

refer_url

String(256)

YES( only for Alipay)

url for download merchants app
Request Example wechat
{
        "fee_type": "THB",
        "product_name": "some product",
        "refer_url": "http://www.google.com",
        "notify_url": "https://your_notify_url.com/notify",
        "mch_order_no": "3500114305",
        "local_total_fee": 10000,
        "channel": "wechat",
        "channel_sub_appid": "wx7385439446434c71",
        "attach": "3500114305",
        "appid": "mch35000",
        "nonce_str": "f1aec3fdf3fbe7532fefd2b9657c772f",
        "time_stamp": "2023022303074141S",
        "sign": "75a394ea6bce232a75de664014549e958f69b381bd558c7ec9253c574cf8647dec5dd195bdf1d76f96203ded54c18ff8cd8bf2aea7919551119d8601e0e6ab0f2bb9e59022cd610cff4e4b9675489aa53b32db2055081a885b38d056369c111326166663674863812e890cb0e19fc67745c5d101f95e0002244b9b1e479cf797"
}

Order Apply 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

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

status_code

status_msg

time_stamp

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.

channel

String(32)

YES

wechat

Value range:

  • wechat

  • alipay

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: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (UAE)

ksher_order_no

String(32)

YES

Order no. generated by Ksher.

limit_pay

mch_order_no

String(32)

YES

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

nonce_str

String(32)

YES

Random string

notify_url

String(256)

YES

http://www.myweb.com/wepay/pay_notify

the url to receive the asynchronous notification about the status of the payment from Ksher; If merchant leaves this field blank, then there will be no notification to send back to 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

prepay_id

String(64)

YES

wx201410272009395522657a690389285100

The prepay_id return sign generated by WeChat is used in subsequent interface calls, which is valid for 2 hours. Merchant should use prepay_id to call WeChat interface.

paypage_title

Product name etc. info can be put here.

product

String(512)

YES

Product name etc. info can be put here.

rate

string(16)

YES

exchange rate of foreign currency to RMB.

redirect_url

String(256)

YES

the url of payment result page, to which redirected from Ksher Payment Page.

result

string(16)

YES

FAIL

Value range: FAIL, NOTSURE

total_fee

Int

YES

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

  • WeChat Pay SUCCESS Response Example *

Response Example(Success)
{
    "code": 0,
    "status_code": "",
    "status_msg": "",
    "sign": "686355b42bf9477d90c3d4371a68df0a656f84611f85090de9e232dc4a715245e83ce0da9e58f8e26d75b3c8de30cac8ab94ffb157a163a574f33924f511c6b4",
    "version": "2.0.0",
    "msg": "ok",
    "time_stamp": "2023-02-23T18:54:06.864961+08:00",
    "data": {
        "ksher_order_no": "90020230223185406858046",
        "package": "prepay_id=wxa556a5551934f52a3ba697a8e1e1000000",
        "prepay_id": "wxa556a5551934f52a3ba697a8e1e1000000",
        "timeStamp": "1677149646",
        "signType": "MD5",
        "paySign": "EfEJSbYf5SRKGjFuXtTW",
        "result": "SUCCESS",
        "appId": "wx7385439446434c71",,
        "nonceStr": "S0MUAROvslC65Ty",
        "mch_order_no": "3500114305"
    }
}

  • Alipay SUCCESS Response Example *

Response Example(Success)
 {
    "code": 0,
    "data": {
        "appid": "mch28321",
        "ksher_order_no": "70020200803130843813386",
        "mch_order_no": "1596431323",
        "nonce_str": "iTKluPz80tiCid8ERyjTvoprDPH6OMhj",
        "order_str": "_input_charset=\"utf-8\"&currency=\"THB\"&forex_biz=\"FP\"&it_b_pay=\"12h\"&notify_url=\"http://ht.dspread.com/front/KsherPay/alipay_notify\"&out_trade_no=\"70020200803130843813386\"&partner=\"2088331094732778\"&payment_type=\"1\"&product_code=\"NEW_WAP_OVERSEAS_SELLER\"&refer_url=\"http://www.ksher.com\"&return_url=\"http://www.ksher.com\"&secondary_merchant_id=\"700283210001\"&secondary_merchant_industry=\"5094\"&secondary_merchant_name=\"sakura1128-jc\"&seller_id=\"2088331094732778\"&service=\"mobile.securitypay.pay\"&sign=\"mklixnUIkdf/RuNCl4iIN5NR7OK0V7L0bCZgV7fNn1Yk9evUtoeBUeKzOZ%2Bzl1QifixSyBHSf15fP8peMmkGmLQfQvVWti8Mp35HQWpJrz%2Ben48bEovJ/YIVelKjSowX2yVJuWZGhjQMXOJaMzas6S/yTDUJ%2BbjonjZZr7naQFY%3D\"&sign_type=\"RSA\"&subject=\"TestAppPay\"&total_fee=\"1.0\"",
        "redirect_url": "http://www.ksher.com",
        "result": "SUCCESS"
    },
    "msg": "ok",
    "sign": "65d471443b929d5356540c0d5b8a702378f7eed0e5794ef42428a46d30b8319092162b7b67149c4127fd90bff8f9c2ee676a9e3156add542c6b87703e0f90d7d",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-08-03T13:08:44.974704+08:00",
    "version": "2.0.0"
}

Order Apply Fail Response Parameters

Parameter Type Required Example Description

code

int

YES

0

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

status_msg

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

version of the API

msg

String(32)

YES

the response message.

time_stamp

String(32)

refund_orders Parameters (JSON )

result

string(16)

YES

FAIL

Value range: FAIL

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

FAIL Response Example

Response Example(Fail)
{
    "code": 0,
    "data": {
        "err_code": "UNIFIEDORDER_CALL_FAIL",
        "err_msg": "特约子商户商户号未授权服务商的产品权限",
        "nonce_str": "dc54d11d7aafa2b90a6dec1d85dccbda",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "564c3c4fe438a569c35b44504727a68fbc588077add9edd40e2207ad794c836f12d5f1834e791dace601f306e53c2ec357cc0e9f8c88b7e01e12e7efa61ec99d",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2023-02-23T19:11:33.003620+08:00",
    "version": "3.0.0"
}

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

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

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

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

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: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (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

refer to relevant chapter Signature Algorithm

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

Webhook Notify

What’s Webhook?

  • Webhook is API response when Customer paid like event. It make customer don’t need to polling to check status.

When webhook callback?

  • add parameter name "notify_url" when you request, ksher will initiate a webhook callback.

  • ksher will polling check the status payment within 2 hours.

    • if the order has been successful payment within 2 hours, webhook will callback.

    • if the order has not been paid within 2 hours , The merchant needs to query request by yourself.

  • If ksher got callback from wallet. we will call webhook to merchant also.

What going on If internet not stable and don’t got webhook at the first time?

  • If the merchant does not return correct format,we will try to callback again.

Correct format response

{"result": "SUCCESS", "msg": "OK"}

This is table webhook with times notification, if customer not response correct success type and or we can’t callback

Times retry Times between the last retry

1st retry

1s

2nd retry

2s

3rd retry

2s

4th retry

10s

5th retry

30s

6th retry

1min

7th retry

10min

8th retry

1hour

9th retry

3hour

10th retry

5hour

11th retry

8hour

12th retry

12hour

Delayed messages will be retried 12 times within 29 hours

After consumer pays, Ksher system will notify merchant only SUCCUSSFULL payment

API method

URL

http://api.mch.ksher.net/KsherPay/pay_notify

Method

POST

Parameter organization format

text/plain;charset=utf-8

Payment Result of SUCCESS

Parameter Type Required Example Description

code

int

YES

0

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

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

String(32)

YES

"3.0.0"

API version

msg

String(32)

YES

ok

the response message.

time_stamp

String(256)

YES

"20190622131804"

time stamp

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

nonce_str

String(32)

YES

ae0e6jm55qlq1o7

Random string, must be unique for signature.

openid

String(128)

YES

o5x64wG48fnZyqWOxqJl-MPSkNJ4

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

channel_order_no

String(32)

YES

4001432001201705110439447536

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

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

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.

ksher_order_no

String(32)

YES

90020210420105438458353

Order no. generated by Ksher.

time_end

String(14)

YES

2014-10-30 13:35:25

the merchant local time when the order is finished，the format is yyyy-MM-dd HH:mm:ss

fee_type

String(16)

YES

THB

Currency code for total_fee. refer to with ISO 4217. Value range:

THB: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (UAE)

attach

String(127)

YES

any extra information can be added here.

rate

string(16)

YES

exchange rate of foreign currency to RMB.

result

string(16)

YES

SUCCESS

Status payment. Value range: SUCCESS

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

operation

String

YES

QUICK-PAY

this shows what operatation the request is.

device_id

String(32)

NO

POS001

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

cash_fee

int

YES

specifies the total cash payment amount of a transaction.

mch_order_no

String(32)

YES

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

order_no

String(32)

YES

generated by merchant self, it must be unique on the merchant side, same as the input.Equate to mch_order_no.
Example 4. SUCCESS Example

Data will response in text format following like this

{"code": 0, "version": "3.0.0", "status_code": "", "msg": "ok", "time_stamp": "2023-05-22T15:14:55.794084+08:00", "status_msg": "", "data": {"openid": "tmn.10036553303", "channel_order_no": "230522141453987OFSWN", "operator_id": "29398", "cash_fee_type": "THB", "ksher_order_no": "90020230522151258706179", "nonce_str": "4XiQyVYA98tNo21jSX24oatxw6FTXo6D", "time_end": "2023-05-22 14:14:53", "fee_type": "THB", "attach": "", "rate": 0.0, "result": "SUCCESS", "total_fee": 100, "appid": "mch35005", "order_no": "20230522140400", "operation": "NATIVE-PAY", "device_id": "", "cash_fee": 100, "channel": "truemoney", "mch_order_no": "20230522140400"}, "sign": "40cb0b83dd675d5f043ac57696d92575e337431fc682d3dbe529cb324cb2a4cfefe6984b9811790c6c1f0dc75e4fa83a8bb3114ad9a3eeef55dba453ea844706"}

after convert data to json format will following this

{
   "code":0,
   "version":"3.0.0",
   "status_code":"",
   "msg":"ok",
   "time_stamp":"2023-05-22T15:14:55.794084+08:00",
   "status_msg":"",
   "data":{
      "openid":"tmn.10036553303",
      "channel_order_no":"230522141453987OFSWN",
      "operator_id":"29398",
      "cash_fee_type":"THB",
      "ksher_order_no":"90020230522151258706179",
      "nonce_str":"4XiQyVYA98tNo21jSX24oatxw6FTXo6D",
      "time_end":"2023-05-22 14:14:53",
      "fee_type":"THB",
      "attach":"",
      "rate":0.0,
      "result":"SUCCESS",
      "total_fee":100,
      "appid":"mch35005",
      "order_no":"20230522140400",
      "operation":"NATIVE-PAY",
      "device_id":"",
      "cash_fee":100,
      "channel":"truemoney",
      "mch_order_no":"20230522140400"
   },
   "sign":"40cb0b83dd675d5f043ac57696d92575e337431fc682d3dbe529cb324cb2a4cfefe6984b9811790c6c1f0dc75e4fa83a8bb3114ad9a3eeef55dba453ea844706"
}
notes:

In the notify calling back function, a response is needed to return to Ksher Server, the response is JSON formated and the content is as follow:

Example 5. For success:
{"result": "SUCCESS", "msg": "OK"}
Example 6. For error:
{"result": "FAIL", "msg": "some error information"}

Order Refund

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

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

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,wechat,linepay,airpay,promptpay,truemoney

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: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (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 7. 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

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

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: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (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 8. 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.

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

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

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

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

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

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: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (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 10. 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

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

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: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (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 11. 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

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

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

Order Close

API method

URL

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

Method

POST

Parameter organization format

application/x-www-form-urlencoded

Order Close 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

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

channel

String(32)

YES

wechat

Value range:

  • airpay

  • wechat

  • alipay

  • alipayplus :only japan merchant

  • ktbcard

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.

time_stamp

String(256)

YES

time stamp example: "time_stamp": "20190622131804"
Example 13. Request Example
{
    "code": 0,
    "data": {
        "appid": "mch36591",
        "mch_order_no": "test3",
        "nonce_str": "7a57e84495bfe7abff4ff23591516511",
        "result": "SUCCESS"
    },
    "msg": "ok",
    "sign": "61805f39c7c484d936cbf40c864b11b9fec0b93205fdbc4efe5b71c9c7dfd98152e1ebc9af5866dd54cf58008418b52ea6122e7994f1d3fe5e6d559a8b022e5f",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-12-25T17:44:54.226116+08:00",
    "version": "3.0.0"
}

Order Close 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

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

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

mch_order_no

String(32)

YES

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

nonce_str

String(32)

YES

Random string

result

string(16)

YES

SUCCESS

Value range: SUCCESS
Example 14. SUCCESS Response Example
{
    "code": 0,
    "data": {
        "appid": "mch36591",
        "mch_order_no": "test3",
        "nonce_str": "7a57e84495bfe7abff4ff23591516511",
        "result": "SUCCESS"
    },
    "msg": "ok",
    "sign": "61805f39c7c484d936cbf40c864b11b9fec0b93205fdbc4efe5b71c9c7dfd98152e1ebc9af5866dd54cf58008418b52ea6122e7994f1d3fe5e6d559a8b022e5f",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-12-25T17:44:54.226116+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

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

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.

  • 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 15. Fail Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_ORDER_NO",
        "err_msg": "failed to find this order no ('mch_order_no:test33,ksher_order_no:,channel_order_no:',).",
        "nonce_str": "7a57e84495bfe7abff4ff23591516511",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "01d2436ef5ed44cb77d3594adccc2c92e2a6a8b39cad2bd1abc3dcd9d64b7c00a303355fc47cb61c3862fb116ed7f67b9db73634da95e91a1fcfc6b12a96da59",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-12-25T17:55:25.248752+08:00",
    "version": "3.0.0"
}

ERROR CODES

Name Description Reason Solution

APPID_NOT_EXIST

APPID not exist

APPID was absent in parameters.

Please check if the APPID is correct.

APPID_MCHID_NOT_MATCH

APPID and MCHID not match

APPID and MCHID not match

please check if the APPID and mchid match.

INVALID_ORDER_NO

invalid order no.

order no. passed in is not correct.

parameter error, please check if the original order no. passed in exist or if the original order is failed.

KSHER_SIGN_ERROR

signature error

merchant signature is not correct

check the signature parameter

KSHER_SYSTEMERROR

Error occurred during handling the request.

Error occurred during handling the request.

Issue the refund request again.

KSHER_VERSION_ERROR

API version used by merchant is not compatible with the API of the vendor

API version used does not match

contact the vendor to confirm current API version

KSHER_ERROR_ORDER_NO

Missing order no parameter

Missing order no parameter

Check the order no.(mch_order_no, ksher_order_no, channel_order_no)

KSHER_REFUND_EXPIRE

Refund can not be made via API by merchant after the order already settled.

Refund can not be made via API by merchant after the order already settled.

Please submit refund request on the Ksher merchant platform.

KSHER_INVALID_MCHINFO

merchant information is not correct

the appid passed in does not exist in the vendor’s system

confirm if the appid passed in is correct, contact the vendor if needed.

KSHER_INVALID_ORDER_NO

order no. does not exist

the order no. passed in cannot be found in vendor’s system

check if the order no. passed in is correct

KSHER_INVALID_REFUND_FEE

invalid amount to refund

amount to refund is greater than the available amount

check if the amount to refund is correct

KSHER_INVALID_REFUND_AMOUNT

Partially refund is not allowed

Partially refund is not allowed

refund completely is allowed.

KSHER_INVALID_REFUND_BALANCE

The balance amount of this order(price fee minus amount already refunded.) is not enough for the amount to refund.

The balance amount of this order(price fee minus amount already refunded.) is not enough for the amount to refund.

Check the amount to refund.

KSHER_INVALID_REFUND_ORDER_NO

invalid refund order no.

the refund order no. passed already used.

check if the refund order no. passed in, use a new one.

KSHER_INVALID_REFUND_FEE_OR_TYPE

Refund currency or amount invalid

Refund currency or amount invalid

Check the currcency or amount to refund.

KSHER_PARAM_OVERLENGTH

Some parameters are too long.

Some paramters are too long

Check the parameters.

KSHER_INVALID_PARAM

Missing parameter(s)

Some parameter(s) invalid

Check parameter(s) is correct

KSHER_DUPLICATED_ORDERNO

The merchant order no already used.

The merchant order no already used.

Use a new order no to make the order again.

KSHER_EXCEED_AMOUNT_LIMIT

the amount to pay exceeds the amount limit configured

the amount to pay exceeds the amount limit configured

make sure if the amount to pay exceeds the limit.

KSHER_FEETYPE_NOT_MATCH

fee type does not match

pricing fee type does not match the registered fee type

merchant needs to modify the program, if merchant is sure that the fee type passed in is correct, contact the vendor.

KSHER_DUPLICATED_ORDERNO

The merchant order no already used.

The merchant order no already used.

Use a new order no to make the order again.

KSHER_DUPLICATED_REFUND_ORDERNO

invalid refund order no

the refund order no. passed already used.

check if the refund order no. passed in, use a new one.

KSHER_AMOUNT_IS_TOO_SMALL

The amount is too small.

The amount is too small

Pass in a larger amount

KSHER_CHANNEL_RESPONSE_ERROR

Error occurred during query operation

Error occurred during query operation

Make an order query again.

LACK_PARAMS

parameter absent

mandatory parameter(s) was absent

please check if the parameters were sufficient

MCHID_NOT_EXIST

MCHID not exist

MCHID was absent in parameters.

please check if the MCHID is correct.

NOAUTH

the merchant has no access to this interface.

the merchant has not yet got the access to this interface.

contact the vendor(Ksher)

NOT_UTF8

coding format error

required coding format was not used.

please use UTF-8 coding

NOTENOUGH

Not enough unsettled fund for refund

There is not enough unsettled fund for refund

This error code means refund request failed due to not enough unsettled fund for refund.Merchants need to contact Ksher to authorise credit for this kind of situation. If unsettled fund is enough ,please call the refund API once there is enough unsettled fund, or retry it continuously.

ORDERPAID

order closed already

the order closed already.

the order no. is already closed, please launch a new order.

ORDERNOTEXISTR

the order no. does not exist

the order does not exist in the system

merchant need to check if the order no. is correct.

OUT_TRADE_NO_USED

repetitive out_trade_no

the same order cannot be submitted for multi times.

please verify whether the out_trade_no. was submitted repetitively

PARAM_ERROR

parameters error

parameters requested are not correct

check the application according to the information returned, contact the vendor if needed.

POST_DATA_EMPTY

post parameters are empty

post parameters should not be empty

please check the paremeters posted in the http request.

REQUIRE_POST_METHOD

please use POST method

the method used to pass the parameters was not POST.

please check if the parameters was passed by POST method

SYSTEMERROR

system error

system timeout

call the order query API immediately to check order status, and decide next step according to the status of the order

SIGNERROR

signature error

the signature parameter is not correct

please check if the signature parameter and method meet the requirements of signature algorithm

TRADE_STATE_ERROR

order state error

there will be latency for the result for refund application, please query later(20 minutes for balance payment, 3 workdays for card payment)

USER_ACCOUNT_ABNORMALE

refund failed

user account is exceptional or unregistered.

this status stands for the failure of the refund operation, merchant can handle the refund by himself.

XML_FORMAT_ERROR

XML format error

XML format error

please check whether the format of XML parameters is correct.

SHOP_ID_ERROR

Invalid merchant information

Invalid merchant information

Please check if the APPID is correct.

CANCEL_ERROR

The cancellation failed

The cancellation failed

Order cannot cancel because of wallet not support or already paid

ORDER_NOT_EXIST

This order does not exist.

Not found this order

Check mch order no is correct or not

USER_NOT_EXIST

This user does not exist.

Not found this order

Check mch order no is correct or not

ORDER_NOT_PAY

This order has not been paid.

This order has not been paid.

Order still not paid

ORDER_ALREADY_REFUND

This order has been refunded.

This order has been refunded.

order has been refunded.

REFUND_FAILED

Refund failed.

Refund failed.

check value is correct

EXPIIRE_ORDER

The order has timed out

The order has timed out

expired time set in order is timeout

ORDER_ERROT

Order number must be unique

Order number must be unique

Check order should be not duplicate or create before

SHOP_NOT_EXIST

This shop does not exist

This shop does not exist

Please check if the APPID is correct.

PRICE_NOT_EXIST

Invalid price

Invalid price

Check amount should be not 0 or create this order before

MCH_ORDER_ERROR

Duplicate order number

Duplicate order number

Check order should be not duplicate or create before

RADIS_DOES_NOT_EXIST

Redis does not exist

Check url is correct

QUERY_ORDER_ERROR

Search for failed not completed transaction

Search for failed not completed transaction

check your value is correct

ORDER_PAYMENT_ERROR

Your payment failed

Your payment failed

Retry to paid again

SMS_CODE_ERROR

Failed to receive OTP code

Failed to receive OTP code

check you mobile phone is correct

CHANNEL_LIST_ERROR

You have not apply for any ewallets nor credit card payment services

You have not apply for any ewallets nor credit card payment services

check your channel value is correct or support

MEMBER_ID_ERROR

member_id cannot be number only

member_id cannot be number only

Please check your member_id not use Real number like 1,1200,00001, but can use string with number like ABC1234.

SAVE_CARD_ERROR

Failed to save card

Failed to save card

Check Bank card channel can support save card function

MEMBER_CARD_ERROR

This card cannot be used

This card cannot be used

This card is not available, please change card to paid

EMPTY_CARD_NO

Card information is incorrect

Card information is incorrect

Check your card input information

DELETE_MEMBER_CARD_ERROR

Failed to delete card

Failed to delete card

Refresh page and try to delete again

MEMBER_CARD_NOT_EXIST

This card does not exists

This card does not exists

check your member_id is correct

MEMBER_ID_LENGTH_OUT_OF_LIMIT

member_id cannot be more than 32 characters

member_id cannot be more than 32 characters

Please check your member_id not use Real number like 1,1200,00001, but can use string with number like ABC1234.

and member_id cannot be more than 32 characters

ORDER_ALREADY_CANCEL

The order has been canceled

The order has been canceled

This order already cancel, Please try to create the new order.

ORDER_ALREADY_CANCEL_OPERATION_CANNOT_BE_PERFORMED

The order has been canceled, this action cannot proceed

The order has been canceled, this action cannot proceed

This order already cancel, Please try to create the new order.

ORDER_ALREADY_PAY_OPERATION_CANNOT_BE_PERFORMED

This order has already been paid, this action cannot proceed

This order has already been paid, this action cannot proceed

This order already paid, Please try to create the new order.

ORDER_ALREADY_PAYMENT_SUCCESS

Order has been completed

Order has been completed

This order already paid, Please try to create the new order.

INSTAL_FEE_PAYER_ERROR

Failed to apply setting of interest-bearing

Failed to apply setting of interest-bearing

check at instal_fee_payer_merchant_channel_list or instal_fee_payer is correct

TRUEMONEY_OPT_CODE_ERROR

Wrong OTP code

Wrong OTP code

check OTP is correct

MANY_OPEN

Someone is paying this bill. DO NOT pay twice.

Someone is paying this bill. DO NOT pay twice.

check on exclusive is turn on or not. if have another person open payment page

LANG_REPEAT_SUBMIT

Repetitive submission

Repetitive submission

order already create before, create the new one.

Solution B Customer scan QR code Solution

Applicable Cases

Only support E-Wallets: PromptPay in Mobile app QR solution

Payment Flow Sequence Diagram

Using Native Pay API for C scan B

The payment information flow is as below. The native pay supports Alipay, WeChat Pay and Prompt Pay payment channel. For the sake of simplicity, we use WeChat Pay as an example. For Alipay and PromptPay the information flow is similar.

Native Pay payment flow
Figure 1. Native Pay payment flow

  1. The buyer Select QR want to pay.

  2. The merchant create order by API.

  3. API returns QR Code image/value.

  4. The Merchant displays the QR code image on their screen/platform.

  5. The buyer open the Ewallet App/mobile banking on mobile.

  6. The buyer scan the QR code.

  7. The buyer confirms the payment by entering PIN/fingerprint.

  8. The merchant get the payment result by API order_query, or API Notification sendback.

Specifications of APIs

Order Apply

API method

URL

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

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

channel

String(32)

YES

wechat

Payment want to request to pay. Value range:

wechat: Wechat Wallet.

alipay: Alipay Wallet.

alipayplus: Alipay+ Wallet. Country support only Japan.

promptpay: PromptPay QR code (Thailand standard bank transfer QR code). Country support only Thailand.

truemoney: TrueMoney Wallet. Country support only Thailand.

airpay: Shopeepay Wallet. Country support only Thailand.

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

mch_order_no

String(32)

YES

123456acb

Merchant order number, generated by merchant self. It must be unique on the merchant side.

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: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (UAE)

notify_url

String(256)

NO

http://www.myweb.com/wepay/pay_notify

the url to receive the asynchronous notification about the status of the payment from Ksher; If merchant leaves this field blank, then there will be no notification to send back to merchant.

img_type

String(3)

No

"png"

Ksher system can generate two types of the qrcode image: png, svg, the default is png

product

String(512)

NO

Name or description of your product info.

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

3.0.0

version api

tmn_expire_time

Int

NO

60

QR time available in second (support Truemoney only)

Example 60 is mean QR can use in 60 second after generate.
Example 16. Request Example wechat
{
    "appid": "mch20163",
    "channel": "wechat",
    "fee_type": "THB",
    "img_type": "svg",
    "mch_order_no": "1495773587",
    "nonce_str": "sQ8gfSpeeV5Ld8ulW9q7JxUnXSOiZ90Y",
    "notify_url": "http://www.yoursweb.com/notify",
    "sign": "4b609e384500ba8b2ed5eddbcc3aab5c7325c45a13bb531655ac459022da0d15ead7e6ab8d73f6d1182117547a6e53871c8da44d99cf02e9d8420c9b20130a2c",
    "time_stamp": "20170526113947",
    "total_fee": 10,
    "version": "1.0.0"
}
Example 17. Request Example Promptpay by use cURL
curl --location 'https://api.mch.ksher.net/KsherPay/native_pay?appid=mch35005&channel=promptpay&fee_type=THB&mch_order_no=20230711163201&nonce_str=90c8d5ad3d4aa1a538f610d259c35c97&notify_url=https%3A%2F%2F6b2f-171-103-29-30.ngrok-free.app%2Fapi%2Fgateway_pay%2Fnotify_url%2F&sign=95c905ba7670591e9cbf0f062c7adccec034f077f023c3f6d8325b55ca672d58d9787af8b0319f6808ea81aa96b575e2f17c1a22d3b8106336b63c2921cec37ecd02ef5481ec9dd9165f44fd376f34cc8f77948c8683445b692f23eb629f11dc82cddd636e0cdb71b8f07b1c7ce21e4ec124449aae40797aacaa05758c36822d&time_stamp=2023071717532828S&total_fee=100' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'appid=mch35005' \
--data-urlencode 'channel=promptpay' \
--data-urlencode 'fee_type=THB' \
--data-urlencode 'mch_order_no=20230711163201' \
--data-urlencode 'nonce_str=90c8d5ad3d4aa1a538f610d259c35c97' \
--data-urlencode 'notify_url=https://6b2f-171-103-29-30.ngrok-free.app/api/gateway_pay/notify_url/' \
--data-urlencode 'sign=95c905ba7670591e9cbf0f062c7adccec034f077f023c3f6d8325b55ca672d58d9787af8b0319f6808ea81aa96b575e2f17c1a22d3b8106336b63c2921cec37ecd02ef5481ec9dd9165f44fd376f34cc8f77948c8683445b692f23eb629f11dc82cddd636e0cdb71b8f07b1c7ce21e4ec124449aae40797aacaa05758c36822d' \
--data-urlencode 'time_stamp=2023071717532828S' \
--data-urlencode 'total_fee=100'

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

data Parameters (JSON )

result

string(16)

YES

SUCCESS

SUCCESS

appid

String(32)

YES

mch12345

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

device_id

String(32)

NO

POS001

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

nonce_str

String(32)

YES

ae0e6jm55qlq1o7

Random string, must be unique for signature.

mch_order_no

String(32)

YES

123456acb

Merchant order number, generated by merchant self. It must be unique on the merchant side.

ksher_order_no

String(32)

YES

generated by Ksher

code_url

String(64)

NO

weixin://wxpay/s/An4baqw

merchant can use this url to generate a qrcode and show it to the consumer to scan

On shopeepay can’t using encode QR code_url text. have to use this value by add <img src=code_url> on HTML side

imgdat

string(1024)

YES

the png format image data will be returned to the API caller unless "svg" is requested explicitly, the png data is base64 encoded and can be assigned directly to the "src" field of img object in the html page.

shopeepay not support imgdat, if scan by using this value will error display.

trade_type

string(8)

NO

NATIVE

value range: JSAP, NATIVE, APP, it should be "NATIVE" for native pay
Example 18. SUCCESS Response Example wechat
{
    "code": 0,
    "data": {
        "appid": "mch20163",
        "code_url": "weixin://wxpay/bizpayurl?pr=n8F22H4",
        "device_id": "",
        "imgdat": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAXIAAAFyAQAAAADAX2ykAAACoElEQVR4nO2aTWrkMBBGX40FWaohB+ijqG82zJFyA/soOcCAtWyQ+WYhqdOdMJMOOKY9VC0MRm/xQVE/KpWJr9j040s4OO+8884777zzf+OtWaB/zJgOALmfnTbU4/zKfJIkzbdn2QwYJEm65b9bj/Mr87lHaJqX6lXSDHaCGtMb63F+HT68+9d0LIH0cjCIAvK2epxfl3/vX0szYjqWILLx4Xb8aPqd/7d1//ZYbQ7NTzKisPTCjZMfTb/zd/GTmZkdwE45YD9nIL0GgKW2z9vqcX4lvsbvW4RqOhZEXkzkpRfh7fQ4vy5Pvfwklfaf+l1II4MgqnbS9Qo1Ppp+5+/hNeYnaYwS5ABpHgTxbNK8GMSCxg31OL8ub3Y8Wx1oTMcCsFh1chtiPfl8Y8+8RsBOsSC9tl7K7AA1nKfj2eeT++Rr/dUYr+eTNRcnlZqpNcbSuUfT7/wn1vwGtDIbJUmlN1T1QPL+apf8pX+WaqxqBtIM0kx1dzt1/+6Qb/ffyUBwNhFL0HQASy9DMQhFk134R9Pv/CfW629BmodLai43hfliHr8746/yc7dy5fM+7hjcv/vkm3/fxlTE3lVdTa28v9or39+PcihMRwEsQcTfQeShWCu9lwL8aPqdv4+PZ4McMDsMshOX+Qb0ceWmepxfk79qrcgBYJDGeLZWf+PZfP68Y/5tf7K2ziNLz8jd3ZvqcX4tvtXfNALkZ4AlQBxkRIBYnxuCttHj/Pfwl/3J9la0tIQ89U3odvqo+p2/l4/lspozqM6k5f3V/8Lr1wHaI3DuL4Wn7PtXO+Xf709WS+OCpfm5QA7Um/A2epxfl2/+bWOMAUuvobRkHM8GDKUm6W30OL8u/2F/Egq0C9HwYb394fQ777zzzjvv/B75P230m3hnLMGVAAAAAElFTkSuQmCC",
        "ksher_order_no": "60020170526123947574894",
        "mch_order_no": "1495773587",
        "nonce_str": "sQ8gfSpeeV5Ld8ulW9q7JxUnXSOiZ90Y",
        "result": "SUCCESS",
        "trade_type": "NATIVE"
    },
    "msg": "ok",
    "sign": "65126acc40a48761751eb9fbabf41ca6d08a44be2a175edcaa95cc7e119c224d76d82d5776be6f80ce9a4e535469a7514d318faf5619151266532557ac0f8bd2",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "",
    "version": "2.0.0"
}
Example 19. SUCCESS Response Example Promptpay
{
    "code": 0,
    "status_code": "",
    "status_msg": "",
    "sign": "b853c6a62164abad9f2ac8d73e5c3d502966ca8b68d3058e855482c5aec5f498c3629d053749a2685ecd08a7ed7570f7db93b82893115f7d7c9228ff6957bcd6",
    "version": "3.0.0",
    "msg": "ok",
    "time_stamp": "2023-09-11T17:59:00.645805+08:00",
    "data": {
        "trade_type": "NATIVE",
        "ksher_order_no": "90020230717185354750819",
        "mch_order_no": "20230711163201",
        "nonce_str": "90c8d5ad3d4aa1a538f610d259c35c97",
        "fee_type": "THB",
        "imgdat": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAZgAAAGYCAYAAAB/O/RVAAAYnElEQVR4nO3da4xtZ3kf8Odde/bMmXN87EOCG9s4JBAKJgk01DSlbZwYKCmoFzVpqKpEaovapooSPkClCkVNP7RRRVvUSCVKVCWtoqQoalNVVdIqlCrEgEuh4tZACJdgGWODAYON8bl4Zu/19sOeORefc7xsLz9+197z+0kjDp697pf/vGu9z35LrbUGADzNutYrAMBmEjAApBAwAKQQMACkEDAApBAwAKQQMACk2Br6QCnlmViPZobKgIa2f+z0rWWvf/b+HZI9/+zlt94/Q6Z+/bQ+f6Z+/Y81tP1aMACkEDAApBAwAKQQMACkEDAApBAwAKQQMACkGKyDGTL14WSy+6Fnz3/qdRpjta4jaF2nMnb7jvr5NzT91OtQNv3+qQUDQAoBA0AKAQNACgEDQAoBA0AKAQNACgEDQIrRdTBD1r2ffmvrXmcx9TqaseuXPX3r8Vqmvv/Gzn/qdTLrfv/UggEghYABIIWAASCFgAEghYABIIWAASCFgAEgRXodzLprPR7GWOu+/utubB1J6zqWqY+30rqOhsenBQNACgEDQAoBA0AKAQNACgEDQAoBA0AKAQNACnUwI2WPl5Etu45h6vundR3Huo+3kr387PFwWu+fTacFA0AKAQNACgEDQAoBA0AKAQNACgEDQAoBA0CK9DqYde9nPrYffus6kyFjxwPJrnNY9/E+pl7n0nq8mHXf/9mmvn5DtGAASCFgAEghYABIIWAASCFgAEghYABIIWAASDG6Dqb1eBqtZdeRZE+frfX2j7Xuy5/69GNlL791Hdi604IBIIWAASCFgAEghYABIIWAASCFgAEghYABIMVgHcy6j0cwda376U99+VOvs1h3R/34tV7+ptOCASCFgAEghYABIIWAASCFgAEghYABIIWAASBFqckdtVv3M2/dT3/q452Mlb1/spc/deu+f7LXf933z5Cpb9/Q+mnBAJBCwACQQsAAkELAAJBCwACQQsAAkELAAJBicDyY1v3EW9eRTL0f/1it61iGtB6vZEjr62NI6+OTPf1Yra+/sVrvvyFaMACkEDAApBAwAKQQMACkEDAApBAwAKQQMACkGD0eTOs6g02vg2i9fUNaL3/qpn7+ZY+HlL1859e064i0YABIIWAASCFgAEghYABIIWAASCFgAEghYABIMTgezFit6wCy+/ln9+PP7uc+9ePTWuv9P1br/dt6+a3HO2pdpzIk+/6jBQNACgEDQAoBA0AKAQNACgEDQAoBA0AKAQNAisE6mOw6jtZ1GGNlr3/r/du6jmfqdUpjtV7+kNZ1Wtla18mN1fr6HKIFA0AKAQNACgEDQAoBA0AKAQNACgEDQAoBA0CKUkd21G5dx9K6TqB1HcDU64Ra98NvrXWd0abXYbS+v0y9Tqv1+aEFA0AKAQNACgEDQAoBA0AKAQNACgEDQAoBA0CKwfFgsrUeL2RI9nguY7Uej2bTta6zGLLux6f1+reuQxmy7uMtacEAkELAAJBCwACQQsAAkELAAJBCwACQQsAAkGL0eDCDC1jzfuStx1tpvfx1N/U6pKkfn9Z1QK33T+vrb+r7Xx0MAE0IGABSCBgAUggYAFIIGABSCBgAUggYAFIM1sG07oc+pHWdy5Cp1/G0rgNa9zqDIa3PvyHrfn0P2fTzb+rXvxYMACkEDAApBAwAKQQMACkEDAApBAwAKQQMACm2hj7Quh/1kNb93FvXMWQ76ts/ZGwdROv9O/XrM7tOZ+z6tV7/sYwHA8BaEjAApBAwAKQQMACkEDAApBAwAKQQMACkGKyDWfc6k9bjNbTeP1Pfv9nrl12n0LqOZEjrOo11r+MZ0rpOZ+q0YABIIWAASCFgAEghYABIIWAASCFgAEghYABIkT4ezNj5Z0+/6f3YW9cJjD1/pr7/WteRbPryh7SuE2td59N6/w/RggEghYABIIWAASCFgAEghYABIIWAASCFgAEgxWAdzFit62haj4eSPf/WdQBTt+n7Z+rj0bQ29eO36bRgAEghYABIIWAASCFgAEghYABIIWAASCFgAEiRXgeTXYfQug5lrNZ1QENaT996PIzWdVLZ02db9+M/1lGvw9GCASCFgAEghYABIIWAASCFgAEgRXovMpiGUqNE/9j/uuwv+09Pbq6llHL+f4CLCRg2WynLiChRaxc1Zo/99ax7ehrxy75fliil64qnAnCg1JEdsf3h9vhajzfSuo6i1fbX1YldZ91Bgsx3vxa7p74YWztnI+LpKT6otcT+mZNx9qHnxnL/RESsAq3Wy4Jsqtb9+Le+fqau9f1DC4aN0/e177rSlYgSp27+cLnhexdx7Y0vjPnuS6I8zff+fhGx98iX4uv3fKTe//Eb4szX/2REqQcZtt53JxhJCybZ1P8CW/e/YB/rMFy+8cjZh3/m3/ynj7/jf334L0SUiH4/Sq21xOXvYS4s6/Lldd3jr18f0UXpSszmEYu9vbj3Q++vX/jQ7RGlj6glJh4y6378W18/U9f8/iFgck39Aln3G8zF+r72pUR54Bunv/7aN739qx+968u3xKNnl6VEdFuzbrFYlthfXP0BWVeizC806mtExN7+4Odns64u9/eX0c1mMd8t8aWPv79+9t1/Lkr0UWsXEw6ZdT/+ra+fqWt+/xAwuaZ+gaz7Deaiz9W+1r7va//qN/7CH935h/e+dF739he1zvvFMuL0udj5lpNx07NPxXzr8sdkJUqcPvdo3PeVByMO1mnWlfjOG5991VbMmXN7ce9XHox45Gx0155YrcVyuR8712zHPR98T737//zQ1N/JrPvxb339TF3r+4d3MGyEvkY/67rZ297xP9935yfvu30VLjHvz+3FdSePx1t+6kfi9a9+edz8bc+KrdmlHb36vo9ZN4vf+/Cn4of/4b+OrRPHYrG3H9eePBkf+NW3xLNOHl9dSBdfazXi3P5+fOaer8Sv/Lf3xi//1u9Hmc1KmW3N66OnF3HzrT8UD37+Y/GNL37f1EMGsggYNsKsK7OvP3z6wX/1H9/5fV3/aN/X2KqP7sVN15+K3337m+KlL7j5qtOWUqIrJWZXaKnMZt1BC+by352Y7cTLXvjt8Uv/+CfilbfeEj/+s/8uaq0lSik1opbnvLzUb/x2RJ3uIzLIpM8+G+N/vP8Tn3zwbH+q9FFrraXUGr/+8/8gXvqCm2NvfxF9rasX+XHpT1/r6t9XaO0f/u78Zy7+qRF9X2NvfxGvf/Wt8U9/6q/H8ptnotuazWK5H3HdjS+J3Wd9LqJ2q5f+cLQMtmBaP8Mfkj2eQuv1H7v/Wz/DHuvJrN8dH/l0LaXUrVmp5x4+E6+67U/Fq2+9JRbLPrbnVz/VH6+r18W/u+wzqxL+mJdZ9H2NN/3NV8Uv/ud3x1ce+EZs78yX+2W+Fdfe+MU4++B3RSmHL/yvuv4ttH6HsenX71hTH49qiBYMG+Ou+x44WVcF9SUWy3jN97/4cW8Afa2x7PvzP31/+Wcv/v2y7684v9VFWuOa48fiz37P8yLO7Z3vGFB2r9Ny4cjyDoaNcfrso9sRETX6ElHi+uuuOX/zf6y+1uhW3yJ2/utirjm+c8lnSilx6prjl32dTK31sr/8+roqr3z2qWsiao1y2N7p5v6I48gSMGyM+gS/AabWiK6UuPerD8Wn7/piLGP1Mv8jn74nousOeoyV2Fss4nfu/IM4eXwnaq0x77q49XueFyd3d+LgI5copf0jL5gSAcORsuxrzLoSv/ehT8WP/aNfjIcePn0hKboSZXsefV+jdF188/Sj8aNv+rcXTbyMW1703HjX298cN/+JZ12xJbNYeiIGhzTfOWJWLYy3veNd8dADD8XOtSdidnxn9bOzfcknS4kLvzu+EzunTsanPvbH8Y53fTBKWYUVcHVaMBwph+9Gzu0tomzPY7m88sv9Qxf/ri99dDvzOHtu70ksUQhxdAkYNlatNfr+4KesbvSHgfFU35f0By9frjTfvtQr1dJIGI6swYBpXUcxtp/21PvhZ9exDGl9fNO2r0bsbM+j60psdxe+peWw+/BTHmisRmxvzS6b7+G/51vdMxop2edX9vLHzn+s7Our9fXTmhYMG2e5rFFO7MRbf+Od8Rvv/ODqpf3BdV5j1YPsI5++J8rO9qpF8kTn29coJ47Ff/jv74/3fPSzl863rsLrE3fdF+XEzmoo5qd77BlYMwKGjVNrjZhvxSc/84X45B/evSrBP8yRw38f246y1T2pvwAP53vX5++Puz5775XnuzOPMt+6/Msx4QgSMGymWmO+eyxm11z5Lr+/v3xSrZeL5zvbmUc5tn3FR2Gr7zu7QpEMHEEChs1USuw/cib29xdX/v3xY6vBxZ7Ki/5FHzEw0iUgYNhAXVdieWYv/upffHn86Rc9N5b9wdfCxKrav5QSv/67H4i77/lyzLbnT64lU2t0121H//DeE2ylTPslLGQSMGycrisR5/bix3/4++NvvebPXPEzH/jEXXH3H98bZWf7ibdiuhL1zDK2v/dbIrZKnH3XvVGOzx9/evnCESZg2EylxMOnz8Zi2cdi2Z8fxbLva3Rdif3F8im/J6n7fRy//TlRzyzi3P/+cpTdp/aoDTbd6PFgxk6f3Y+7dT/x1nUmQzZ5vJ9Z150PlvMBU1YB0/c1Zl0XpZSLtuGKhZIXHA4O09eo55axe9sNUboSZ993f5TdWZPWSus6qaNeRzOk9f2nNS0YjpTVBV/iputPxfLh07E8th2x7CNi1fOrPLYA87FfI7PfR3dyvprX2WUc+4EbokbEuauFTO2r0Sw5qgQMR0rpStQa8c9/8q/FPfd9NT519/1RD1o3+4tlPHLm0UvqV8qxrQv/v68xf9mzY/vFp6LuLVfvZM4tY/cHboiIiHN33h/l2Cpkao3VgraPbx8Mmbx8hjcVmhMwHCmHvcm+6znXx52/+pb42kOPxKL2sdV18Z6PfTb+xpvfHrPdY9EvllGObcU1r3/e6h1Lvyqc7E7Moy5XCXIYPOcfl0XE2YOQWdY66/q9vr/+Ra+I01+7I+776O1RukXU3jXHkeFkZ2N0US55QPV43Y8Px3L51lPXnP9v33rtiUsfcZWIcnzrQsDE6gX/ZRX65TGPy+68P8qxrehr7aLu9+X5t90eEXdUIcMRYzwYNsZ1J3fPrb6Qv6sRNe6+/+tX/ezhy99aayyWy6i1rnqWPVZfI5YHP/3jfP1LifOPy479wA1Rzy4OeqmVEntnF/H8224vz3nZHVH7rSjdVao/YbMIGDbGd3/nTd8s3azWWmvszOO33/f/zv/uao2Zw15kl/Yme+yH4ol9r1iJqOcWq5C57XzIlOi62VVC5mh3MWLjCRg2xl96xXefqP2yLJe1bO0ei0/8wefi7b/1+7E162KxXMbiYHCxq/5cKYXqk/yJEvXs4tKWTMQqZPYvC5llPer9WNlo6ePBDGk9/Vit61xaH5/WdTIX1iPqq2695SUvuPG6z3/uSw89d1aXy9mJY7M3v+034+TuTvzdv/LnrzptdzCWy+72/LLflXmJMu8u76581cZHiVpr1EUfx195U5R5F2ff96UoW12JclFL5uCdzLKvi61Zuep12Pr8GdL6+htr3e8/Y2Vfv142shH62vc721s7b/3pH/3Sj/3cr31HKX1fazfro483/NyvxH9594fjJ173irjlO74tduaXBsnyoBfZZ77w5Uur+2vE8oFHo+wsLg2Yw0dmA/fmvkZsv+i6WD5wLvb+6MEo8+7Sx2URd2zNutsXy36xNetci2ycMraJvu4JPlbrFsyQ1pX22ZXkF1v2/XLWdbOfedtvvveXfuf//uC87u0vFsut0pWy/ObZiKgRuzuXF1M+FUMBc9Hvy7xb9T67oEbfL2N7d+vn/95r7/jZv/O6q4ZMdgty6i2Yqa9fa63vH4Pnn4AZp/UFPqT1DeCZDJhaa+1r7btSup986zvu/Pfv/NBtsdiLWO4vZrOtEiW6ZX9pDcuFaQ8bL0/z/jpc/8v2Q1+jlmXMj83/xd9/3R1v+duvvf0wIC/+lICZ9vq11vr+IWCStb7Ah7S+ATyTAXPw+Vpr1K4r3S//1/e896f/5a+9OHauvT5qH9EvI6Keb1xc+AayJ/TE6+m3CrVaZzvln73hNXf8kzf85dsPA/LwIwJm2uvXWuv7h4BJ1voCH9L6BvBMB8zBNOdDpmwf/2q5/oWfjFPPvS52n3VjzLauWa1UbXTiXrrY3d1jMetm/em9/vgvvPFH3vvG17/yB8tFO03ATHv9Wmt9/xAwyVpf4ENa3wBaBMyhZd8vt2azC4+cZvNHYjY/8/R+L9gT2L5LP3LJBt1zzz1RIkrpunLu0b2959/07G8XMBdMff1aa33/EDDJWl/gQ1rfAFoGzGr5XY1SllFrt/rSyWnJPn8EzGbfn1rfP4aWnz4eTGut6zSmfgJsvlqi1sPz/PDt/vmdslw+fmPm4gbQUzE0/4tet0SsvgvgSZ2QrY//ugdk6/Fspj79WPrec5SU8+X2B7pu6AIbdwPKnj9M2eQeGQCwGQQMACkEDAApBAwAKQQMACkEDAAp0rspt+6Hve7z5/Ft+ng3615o2LoOrLXWdUpDss9vLRgAUggYAFIIGABSCBgAUggYAFIIGABSCBgAUgwOODb1fuZDWo/30FrrOo/W+6d1ncrUx/vY9Dqf1uPNtL5/tt6/WjAApBAwAKQQMACkEDAApBAwAKQQMACkEDAApEgfD2ZIdj/t7DqO1nUiret0WtdhTH37hmRvnzqXadfxtT6/smnBAJBCwACQQsAAkELAAJBCwACQQsAAkELAAJBisA5m6nUO2XUQ2ds39e3PrsMYq3WdxLqPdzP14zN1rc+/Ia3Hs9GCASCFgAEghYABIIWAASCFgAEghYABIIWAASBF+ngwU+8nPmTq/fRb79913z+ttd7/rfdP6zq67PGkhkz9+hlLCwaAFAIGgBQCBoAUAgaAFAIGgBQCBoAUAgaAFKU27og99fEi1r0ffOv1zz6+U68Dmvr2t57/WK2P/1it65iyj58WDAApBAwAKQQMACkEDAApBAwAKQQMACkEDAApJj8ezNj5Dxla/tTrVMauX+s6ialvf3adROs6nLFaj+cyZOp1PEPWff21YABIIWAASCFgAEghYABIIWAASCFgAEghYABIMTgezLr3029dx9J6+8dqvf7ZdRStp8/Wus6o9fkxpPX1O/X1H7t+WjAApBAwAKQQMACkEDAApBAwAKQQMACkEDAApBgcD2ZsP+rWdTTZ/bw3vZ98ttbj2QyZep1B6+O76df3WK3Pj9a0YABIIWAASCFgAEghYABIIWAASCFgAEghYABIMVgH03q8kqnXkWQvP1vr4zvWUV//1nU0m17HMiS7Dq71eDpjj48WDAApBAwAKQQMACkEDAApBAwAKQQMACkEDAApSh3Z0bx1P/bWdRCt62yGtB6vJns8ldZa16GYf9vzr/X9rfX+HaIFA0AKAQNACgEDQAoBA0AKAQNACgEDQAoBA0CKwfFgxsqus5j6eBFHXes6nLGyx/PIXv+jfn1Mvc5lSPb6Gw8GgLUkYABIIWAASCFgAEghYABIIWAASCFgAEgxOB5M6/FKxmo9Hknr7Rty1MfTmLrWdRitj9+Q1td3a62vH3UwADQhYABIIWAASCFgAEghYABIIWAASCFgAEgxWAdz1E29DiZb6zoBdUrrXWc0dvmbvn1jlz+k9f7XggEghYABIIWAASCFgAEghYABIIWAASCFgAEgxdbQB1rXQWQb6se97uNJZPfjb12nkX181n39h4zdvtZ1XlMfD2bq50/28dOCASCFgAEghYABIIWAASCFgAEghYABIIWAASDFYB3MkNb94Iese53KWNn97LOnb631+rcez+Oon5+tx2MZ0rrOZYgWDAApBAwAKQQMACkEDAApBAwAKQQMACkEDAApRtfBDJl6P/ohR308h3WvA8iefqypH9/W52fr7c+ePlvr9dOCASCFgAEghYABIIWAASCFgAEghYABIIWAASBFeh0MuVrXGQ0tv3UdTevxToYc9TqT1ssf0vr4rPv+04IBIIWAASCFgAEghYABIIWAASCFgAEghYABIIU6mJFa11EMaV3HMiS7zmDd6yDGar38scbu36nXoUz9/jGWFgwAKQQMACkEDAApBAwAKQQMACkEDAApBAwAKUod6Mg99X7+Q1r3Y596P/mp15GMddSPb2ut7w+t92/r86P19a0FA0AKAQNACgEDQAoBA0AKAQNACgEDQAoBA0CK0XUw6+6o91Of+ngrQzZ9+eteJ5Qtu84m+/povf+z118LBoAUAgaAFAIGgBQCBoAUAgaAFAIGgBQCBoAUg3UwAPBUaMEAkELAAJBCwACQQsAAkELAAJBCwACQQsAAkOL/A4g4s3paEfAWAAAAAElFTkSuQmCC",
        "result": "SUCCESS",
        "total_fee": 100,
        "appid": "mch35005",
        "PaymentID": "90020230717185354750819",
        "PaymentCode": "00020101021230750016A0000006770101120115010556019950701022020230717185354750819030890035005530376454041.005802TH630427F2",
        "code_url": "00020101021230750016A0000006770101120115010556019950701022020230717185354750819030890035005530376454041.005802TH630427F2",
        "stalls_name": "90035005",
        "device_id": ""
    }
}

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

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

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 20. Fail Response Example
{
    "code": 0,
    "status_code": "",
    "status_msg": "",
    "sign": "02635a1a60cfcaf461c6b860ac7ffd967c98c19803ddc4b698d2279502451f837d225fe38810357dc5e50c9de114bb40ad3513dd972f2e7db8ff08a09240c604",
    "version": "2.0.0",
    "msg": "ok",
    "time_stamp": "",
    "data": {
        "result": "FAIL",
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": ""
    }
}

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

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

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

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

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: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (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 22. 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

refer to relevant chapter Signature Algorithm

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

Webhook Notify

What’s Webhook?

  • Webhook is API response when Customer paid like event. It make customer don’t need to polling to check status.

When webhook callback?

  • add parameter name "notify_url" when you request, ksher will initiate a webhook callback.

  • ksher will polling check the status payment within 2 hours.

    • if the order has been successful payment within 2 hours, webhook will callback.

    • if the order has not been paid within 2 hours , The merchant needs to query request by yourself.

  • If ksher got callback from wallet. we will call webhook to merchant also.

What going on If internet not stable and don’t got webhook at the first time?

  • If the merchant does not return correct format,we will try to callback again.

Correct format response

{"result": "SUCCESS", "msg": "OK"}

This is table webhook with times notification, if customer not response correct success type and or we can’t callback

Times retry Times between the last retry

1st retry

1s

2nd retry

2s

3rd retry

2s

4th retry

10s

5th retry

30s

6th retry

1min

7th retry

10min

8th retry

1hour

9th retry

3hour

10th retry

5hour

11th retry

8hour

12th retry

12hour

Delayed messages will be retried 12 times within 29 hours

After consumer pays, Ksher system will notify merchant only SUCCUSSFULL payment

API method

URL

http://api.mch.ksher.net/KsherPay/pay_notify

Method

POST

Parameter organization format

text/plain;charset=utf-8

Payment Result of SUCCESS

Parameter Type Required Example Description

code

int

YES

0

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

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

String(32)

YES

"3.0.0"

API version

msg

String(32)

YES

ok

the response message.

time_stamp

String(256)

YES

"20190622131804"

time stamp

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

nonce_str

String(32)

YES

ae0e6jm55qlq1o7

Random string, must be unique for signature.

openid

String(128)

YES

o5x64wG48fnZyqWOxqJl-MPSkNJ4

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

channel_order_no

String(32)

YES

4001432001201705110439447536

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

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

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.

ksher_order_no

String(32)

YES

90020210420105438458353

Order no. generated by Ksher.

time_end

String(14)

YES

2014-10-30 13:35:25

the merchant local time when the order is finished，the format is yyyy-MM-dd HH:mm:ss

fee_type

String(16)

YES

THB

Currency code for total_fee. refer to with ISO 4217. Value range:

THB: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (UAE)

attach

String(127)

YES

any extra information can be added here.

rate

string(16)

YES

exchange rate of foreign currency to RMB.

result

string(16)

YES

SUCCESS

Status payment. Value range: SUCCESS

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

operation

String

YES

QUICK-PAY

this shows what operatation the request is.

device_id

String(32)

NO

POS001

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

cash_fee

int

YES

specifies the total cash payment amount of a transaction.

mch_order_no

String(32)

YES

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

order_no

String(32)

YES

generated by merchant self, it must be unique on the merchant side, same as the input.Equate to mch_order_no.
Example 24. SUCCESS Example

Data will response in text format following like this

{"code": 0, "version": "3.0.0", "status_code": "", "msg": "ok", "time_stamp": "2023-05-22T15:14:55.794084+08:00", "status_msg": "", "data": {"openid": "tmn.10036553303", "channel_order_no": "230522141453987OFSWN", "operator_id": "29398", "cash_fee_type": "THB", "ksher_order_no": "90020230522151258706179", "nonce_str": "4XiQyVYA98tNo21jSX24oatxw6FTXo6D", "time_end": "2023-05-22 14:14:53", "fee_type": "THB", "attach": "", "rate": 0.0, "result": "SUCCESS", "total_fee": 100, "appid": "mch35005", "order_no": "20230522140400", "operation": "NATIVE-PAY", "device_id": "", "cash_fee": 100, "channel": "truemoney", "mch_order_no": "20230522140400"}, "sign": "40cb0b83dd675d5f043ac57696d92575e337431fc682d3dbe529cb324cb2a4cfefe6984b9811790c6c1f0dc75e4fa83a8bb3114ad9a3eeef55dba453ea844706"}

after convert data to json format will following this

{
   "code":0,
   "version":"3.0.0",
   "status_code":"",
   "msg":"ok",
   "time_stamp":"2023-05-22T15:14:55.794084+08:00",
   "status_msg":"",
   "data":{
      "openid":"tmn.10036553303",
      "channel_order_no":"230522141453987OFSWN",
      "operator_id":"29398",
      "cash_fee_type":"THB",
      "ksher_order_no":"90020230522151258706179",
      "nonce_str":"4XiQyVYA98tNo21jSX24oatxw6FTXo6D",
      "time_end":"2023-05-22 14:14:53",
      "fee_type":"THB",
      "attach":"",
      "rate":0.0,
      "result":"SUCCESS",
      "total_fee":100,
      "appid":"mch35005",
      "order_no":"20230522140400",
      "operation":"NATIVE-PAY",
      "device_id":"",
      "cash_fee":100,
      "channel":"truemoney",
      "mch_order_no":"20230522140400"
   },
   "sign":"40cb0b83dd675d5f043ac57696d92575e337431fc682d3dbe529cb324cb2a4cfefe6984b9811790c6c1f0dc75e4fa83a8bb3114ad9a3eeef55dba453ea844706"
}
notes:

In the notify calling back function, a response is needed to return to Ksher Server, the response is JSON formated and the content is as follow:

Example 25. For success:
{"result": "SUCCESS", "msg": "OK"}
Example 26. For error:
{"result": "FAIL", "msg": "some error information"}

Order Refund

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

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

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,wechat,linepay,airpay,promptpay,truemoney

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: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (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 27. 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

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

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: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (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 28. 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.

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

Order Close

API method

URL

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

Method

POST

Parameter organization format

application/x-www-form-urlencoded

Order Close 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

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

channel

String(32)

YES

wechat

Value range:

  • airpay

  • wechat

  • alipay

  • alipayplus :only japan merchant

  • ktbcard

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.

time_stamp

String(256)

YES

time stamp example: "time_stamp": "20190622131804"
Example 30. Request Example
{
    "code": 0,
    "data": {
        "appid": "mch36591",
        "mch_order_no": "test3",
        "nonce_str": "7a57e84495bfe7abff4ff23591516511",
        "result": "SUCCESS"
    },
    "msg": "ok",
    "sign": "61805f39c7c484d936cbf40c864b11b9fec0b93205fdbc4efe5b71c9c7dfd98152e1ebc9af5866dd54cf58008418b52ea6122e7994f1d3fe5e6d559a8b022e5f",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-12-25T17:44:54.226116+08:00",
    "version": "3.0.0"
}

Order Close 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

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

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

mch_order_no

String(32)

YES

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

nonce_str

String(32)

YES

Random string

result

string(16)

YES

SUCCESS

Value range: SUCCESS
Example 31. SUCCESS Response Example
{
    "code": 0,
    "data": {
        "appid": "mch36591",
        "mch_order_no": "test3",
        "nonce_str": "7a57e84495bfe7abff4ff23591516511",
        "result": "SUCCESS"
    },
    "msg": "ok",
    "sign": "61805f39c7c484d936cbf40c864b11b9fec0b93205fdbc4efe5b71c9c7dfd98152e1ebc9af5866dd54cf58008418b52ea6122e7994f1d3fe5e6d559a8b022e5f",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-12-25T17:44:54.226116+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

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

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.

  • 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 32. Fail Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_ORDER_NO",
        "err_msg": "failed to find this order no ('mch_order_no:test33,ksher_order_no:,channel_order_no:',).",
        "nonce_str": "7a57e84495bfe7abff4ff23591516511",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "01d2436ef5ed44cb77d3594adccc2c92e2a6a8b39cad2bd1abc3dcd9d64b7c00a303355fc47cb61c3862fb116ed7f67b9db73634da95e91a1fcfc6b12a96da59",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-12-25T17:55:25.248752+08:00",
    "version": "3.0.0"
}

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

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

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

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

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: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (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 33. 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

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

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: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (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 34. 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

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

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

ERROR CODES

Name Description Reason Solution

APPID_NOT_EXIST

APPID not exist

APPID was absent in parameters.

Please check if the APPID is correct.

APPID_MCHID_NOT_MATCH

APPID and MCHID not match

APPID and MCHID not match

please check if the APPID and mchid match.

INVALID_ORDER_NO

invalid order no.

order no. passed in is not correct.

parameter error, please check if the original order no. passed in exist or if the original order is failed.

KSHER_SIGN_ERROR

signature error

merchant signature is not correct

check the signature parameter

KSHER_SYSTEMERROR

Error occurred during handling the request.

Error occurred during handling the request.

Issue the refund request again.

KSHER_VERSION_ERROR

API version used by merchant is not compatible with the API of the vendor

API version used does not match

contact the vendor to confirm current API version

KSHER_ERROR_ORDER_NO

Missing order no parameter

Missing order no parameter

Check the order no.(mch_order_no, ksher_order_no, channel_order_no)

KSHER_REFUND_EXPIRE

Refund can not be made via API by merchant after the order already settled.

Refund can not be made via API by merchant after the order already settled.

Please submit refund request on the Ksher merchant platform.

KSHER_INVALID_MCHINFO

merchant information is not correct

the appid passed in does not exist in the vendor’s system

confirm if the appid passed in is correct, contact the vendor if needed.

KSHER_INVALID_ORDER_NO

order no. does not exist

the order no. passed in cannot be found in vendor’s system

check if the order no. passed in is correct

KSHER_INVALID_REFUND_FEE

invalid amount to refund

amount to refund is greater than the available amount

check if the amount to refund is correct

KSHER_INVALID_REFUND_AMOUNT

Partially refund is not allowed

Partially refund is not allowed

refund completely is allowed.

KSHER_INVALID_REFUND_BALANCE

The balance amount of this order(price fee minus amount already refunded.) is not enough for the amount to refund.

The balance amount of this order(price fee minus amount already refunded.) is not enough for the amount to refund.

Check the amount to refund.

KSHER_INVALID_REFUND_ORDER_NO

invalid refund order no.

the refund order no. passed already used.

check if the refund order no. passed in, use a new one.

KSHER_INVALID_REFUND_FEE_OR_TYPE

Refund currency or amount invalid

Refund currency or amount invalid

Check the currcency or amount to refund.

KSHER_PARAM_OVERLENGTH

Some parameters are too long.

Some paramters are too long

Check the parameters.

KSHER_INVALID_PARAM

Missing parameter(s)

Some parameter(s) invalid

Check parameter(s) is correct

KSHER_DUPLICATED_ORDERNO

The merchant order no already used.

The merchant order no already used.

Use a new order no to make the order again.

KSHER_EXCEED_AMOUNT_LIMIT

the amount to pay exceeds the amount limit configured

the amount to pay exceeds the amount limit configured

make sure if the amount to pay exceeds the limit.

KSHER_FEETYPE_NOT_MATCH

fee type does not match

pricing fee type does not match the registered fee type

merchant needs to modify the program, if merchant is sure that the fee type passed in is correct, contact the vendor.

KSHER_DUPLICATED_ORDERNO

The merchant order no already used.

The merchant order no already used.

Use a new order no to make the order again.

KSHER_DUPLICATED_REFUND_ORDERNO

invalid refund order no

the refund order no. passed already used.

check if the refund order no. passed in, use a new one.

KSHER_AMOUNT_IS_TOO_SMALL

The amount is too small.

The amount is too small

Pass in a larger amount

KSHER_CHANNEL_RESPONSE_ERROR

Error occurred during query operation

Error occurred during query operation

Make an order query again.

LACK_PARAMS

parameter absent

mandatory parameter(s) was absent

please check if the parameters were sufficient

MCHID_NOT_EXIST

MCHID not exist

MCHID was absent in parameters.

please check if the MCHID is correct.

NOAUTH

the merchant has no access to this interface.

the merchant has not yet got the access to this interface.

contact the vendor(Ksher)

NOT_UTF8

coding format error

required coding format was not used.

please use UTF-8 coding

NOTENOUGH

Not enough unsettled fund for refund

There is not enough unsettled fund for refund

This error code means refund request failed due to not enough unsettled fund for refund.Merchants need to contact Ksher to authorise credit for this kind of situation. If unsettled fund is enough ,please call the refund API once there is enough unsettled fund, or retry it continuously.

ORDERPAID

order closed already

the order closed already.

the order no. is already closed, please launch a new order.

ORDERNOTEXISTR

the order no. does not exist

the order does not exist in the system

merchant need to check if the order no. is correct.

OUT_TRADE_NO_USED

repetitive out_trade_no

the same order cannot be submitted for multi times.

please verify whether the out_trade_no. was submitted repetitively

PARAM_ERROR

parameters error

parameters requested are not correct

check the application according to the information returned, contact the vendor if needed.

POST_DATA_EMPTY

post parameters are empty

post parameters should not be empty

please check the paremeters posted in the http request.

REQUIRE_POST_METHOD

please use POST method

the method used to pass the parameters was not POST.

please check if the parameters was passed by POST method

SYSTEMERROR

system error

system timeout

call the order query API immediately to check order status, and decide next step according to the status of the order

SIGNERROR

signature error

the signature parameter is not correct

please check if the signature parameter and method meet the requirements of signature algorithm

TRADE_STATE_ERROR

order state error

there will be latency for the result for refund application, please query later(20 minutes for balance payment, 3 workdays for card payment)

USER_ACCOUNT_ABNORMALE

refund failed

user account is exceptional or unregistered.

this status stands for the failure of the refund operation, merchant can handle the refund by himself.

XML_FORMAT_ERROR

XML format error

XML format error

please check whether the format of XML parameters is correct.

SHOP_ID_ERROR

Invalid merchant information

Invalid merchant information

Please check if the APPID is correct.

CANCEL_ERROR

The cancellation failed

The cancellation failed

Order cannot cancel because of wallet not support or already paid

ORDER_NOT_EXIST

This order does not exist.

Not found this order

Check mch order no is correct or not

USER_NOT_EXIST

This user does not exist.

Not found this order

Check mch order no is correct or not

ORDER_NOT_PAY

This order has not been paid.

This order has not been paid.

Order still not paid

ORDER_ALREADY_REFUND

This order has been refunded.

This order has been refunded.

order has been refunded.

REFUND_FAILED

Refund failed.

Refund failed.

check value is correct

EXPIIRE_ORDER

The order has timed out

The order has timed out

expired time set in order is timeout

ORDER_ERROT

Order number must be unique

Order number must be unique

Check order should be not duplicate or create before

SHOP_NOT_EXIST

This shop does not exist

This shop does not exist

Please check if the APPID is correct.

PRICE_NOT_EXIST

Invalid price

Invalid price

Check amount should be not 0 or create this order before

MCH_ORDER_ERROR

Duplicate order number

Duplicate order number

Check order should be not duplicate or create before

RADIS_DOES_NOT_EXIST

Redis does not exist

Check url is correct

QUERY_ORDER_ERROR

Search for failed not completed transaction

Search for failed not completed transaction

check your value is correct

ORDER_PAYMENT_ERROR

Your payment failed

Your payment failed

Retry to paid again

SMS_CODE_ERROR

Failed to receive OTP code

Failed to receive OTP code

check you mobile phone is correct

CHANNEL_LIST_ERROR

You have not apply for any ewallets nor credit card payment services

You have not apply for any ewallets nor credit card payment services

check your channel value is correct or support

MEMBER_ID_ERROR

member_id cannot be number only

member_id cannot be number only

Please check your member_id not use Real number like 1,1200,00001, but can use string with number like ABC1234.

SAVE_CARD_ERROR

Failed to save card

Failed to save card

Check Bank card channel can support save card function

MEMBER_CARD_ERROR

This card cannot be used

This card cannot be used

This card is not available, please change card to paid

EMPTY_CARD_NO

Card information is incorrect

Card information is incorrect

Check your card input information

DELETE_MEMBER_CARD_ERROR

Failed to delete card

Failed to delete card

Refresh page and try to delete again

MEMBER_CARD_NOT_EXIST

This card does not exists

This card does not exists

check your member_id is correct

MEMBER_ID_LENGTH_OUT_OF_LIMIT

member_id cannot be more than 32 characters

member_id cannot be more than 32 characters

Please check your member_id not use Real number like 1,1200,00001, but can use string with number like ABC1234.

and member_id cannot be more than 32 characters

ORDER_ALREADY_CANCEL

The order has been canceled

The order has been canceled

This order already cancel, Please try to create the new order.

ORDER_ALREADY_CANCEL_OPERATION_CANNOT_BE_PERFORMED

The order has been canceled, this action cannot proceed

The order has been canceled, this action cannot proceed

This order already cancel, Please try to create the new order.

ORDER_ALREADY_PAY_OPERATION_CANNOT_BE_PERFORMED

This order has already been paid, this action cannot proceed

This order has already been paid, this action cannot proceed

This order already paid, Please try to create the new order.

ORDER_ALREADY_PAYMENT_SUCCESS

Order has been completed

Order has been completed

This order already paid, Please try to create the new order.

INSTAL_FEE_PAYER_ERROR

Failed to apply setting of interest-bearing

Failed to apply setting of interest-bearing

check at instal_fee_payer_merchant_channel_list or instal_fee_payer is correct

TRUEMONEY_OPT_CODE_ERROR

Wrong OTP code

Wrong OTP code

check OTP is correct

MANY_OPEN

Someone is paying this bill. DO NOT pay twice.

Someone is paying this bill. DO NOT pay twice.

check on exclusive is turn on or not. if have another person open payment page

LANG_REPEAT_SUBMIT

Repetitive submission

Repetitive submission

order already create before, create the new one.

Solution C Redirect to H5

User Experience Scenarios

Checkout Page

Checkout Page created by Ksher, Visual design like logo, banner background color, ect., which can DIY by merchant via API.

If you send only one channel, it will be skip checkout page and redirected to each wallet you send.

h5 checkout

Credit Card

  1. Select Card, it will turn to Ksher DIY checkout page.

  2. Continue to pay with fill personal card information.

  3. It will redirect to card bank OTP website, fill OTP.

  4. After correct OTP it redirect back to KTB and your Success page.

h5 ktbcard 01
h5 ktbcard 02
h5 ktbcard 03
h5 ktbcard 04

Alipay

Select Alipay, it will redirect to Alipay payment page, continue to pay with open Alipay e-wallte app or login Alipay account browser.

h5 alipay

Shopeepay

or old name before rebranding is Airpay.

Select Shopeepay, it will redirect to Shopeepay payment page. Continue to pay with turning into Shopeepay e-wallets.

h5 airpay

WeChat

Open payment link in WeChat browser ,it will create Ksher checkout page. Continue to pay with WeChat app.

h5 wechat

Promptpay

Select Promptpay, will create Ksher checkout page. Continue payment with scan QR code.

h5 promptpay

LINE pay

Select LINE pay, continue to pay with turning into LINE Pay e-wallets

h5 linepay

TrueMoney

Truemoney has a dynamic QR Code or OTP depend on what’s your select when opening an account with us.

Select TrueMoney, it will create Ksher checkout page. Continue to pay with verifying user phone number OTP code.

h5 truemoney

Select TrueMoney, it will create Ksher checkout page. Continue payment with scan QR code.

h5 truemoney dynamic

Mobile Atome

  1. Select Thai E-wallets tab and select Atome, will display pay by app or pay in browser

  2. If merchant select pay by app, will open Atome app on mobile phone

  3. Enter coupon card, payment method and pay

  4. Click Back to Merchant to go back Merchant page

h5 atome01
h5 atome02
h5 atome03
h5 atome04

KTC Installment

  1. Select Credit/Debit Card tab and select KTC Installment, will redirect to Fill in page.

  2. fill card information and select how long installmet term.

  3. It will redirect to card bank OTP website, fill OTP.

  4. After correct OTP it redirect back to KTB and your Success page.

h5 ktcinstallment 01
h5 ktcinstallment customer absorb

or if merchant absorb fee will display

h5 ktcinstallment merchant absorb
h5 ktcinstallment 02
h5 ktcinstallment 03
h5 ktcinstallment 02

KBANK Installment

  1. Select Credit/Debit Card tab and select KBANK Installment, will redirect to Fill in page.

  2. fill card information and select how long installmet term.

  3. It will redirect to card bank OTP website, fill OTP.

  4. After correct OTP it redirect back to KBANK and your Success page.

h5 kbankinstallment 01
h5 kbankinstallment customer absorb

or if merchant absorb fee will display

h5 kbankinstallment merchant absorb
h5 kbankinstallment 02
h5 kbankinstallment 03
h5 kbankinstallment 02

K Installment

  1. Select Credit/Debit Card tab and select KBANK Installment, will redirect to Fill in page.

  2. fill card information and select how long installmet term.

  3. It will redirect to card bank OTP website, fill OTP.

  4. After correct OTP it redirect back to KBANK and your Success page.

h5 kbankinstallment 01
h5 kbankinstallment customer absorb

or if merchant absorb fee will display

h5 kbankinstallment merchant absorb
h5 kbankinstallment 02
h5 kbankinstallment 03
h5 kbankinstallment 02

Mobile Krungsri Installment

  1. Select Credit/Debit Card tab and select Krungsri Installment, will redirect to Fill in page.

  2. fill card information and select how long installment term.

  3. It will redirect to card bank OTP website, fill OTP.

  4. After correct OTP it redirect back to your Success page.

h5 kcc instal
h5 kcc instal customer absorb

or if merchant absorb fee will display

h5 kcc instal merchant absorb
h5 kcc instal otp

Mobile First Choice Installment

  1. Select Credit/Debit Card tab and select First Choice Installment, will redirect to Fill in page.

  2. fill card information and select how long installment term.

  3. It will redirect to card bank OTP website, fill OTP.

  4. After correct OTP it redirect back to your Success page.

h5 kfc instal
h5 kfc instal customer absorb

or if merchant absorb fee will display

h5 kfc instal merchant absorb
h5 kfc instal otp

Mobile SCB Easy

only support on mobile app

If customer not install app when click to pa will redirect to Google Play SCB Easy or App Store SCB Easy depend on customer OS.

  1. Select Mobile Banking tab, and select SCB EASY.

  2. Input App PIN.

  3. Select your payment method and Click Review to go next page.

  4. will summary Information customer have to pay, click Confirm to pay

  5. Click Return to Merchant to go back Merchant page

h5 scbeasy 01
h5 scbeasy 02
h5 scbeasy 03
h5 scbeasy 04

Mobile Bualuang mBanking

only support on mobile app.

If customer not install app when click to pa will redirect to Google Play Bualuang mBanking or App Store Bualuang mBanking depend on customer OS.

  1. Select Mobile Banking tab, and select Bualuang mBanking.

  2. Input App PIN.

  3. Select your payment method and Click Next to go next page.

  4. will summary Information customer have to pay, click Confirm to pay

  5. Click Back to Ksher Payment to go back Merchant page

h5 bbldeeplink 01
h5 bbldeeplink 02
h5 bbldeeplink 03
h5 bbldeeplink 04

Mobile KMA-Krungsri Mobile App

only support on mobile app.

If customer not install app when click to pa will redirect to Google Play KMA or App Store KMA depend on customer OS.

  1. Select Mobile Banking tab, and select KMA.

  2. Input App PIN.

  3. Select your payment method and Click Next to go next page.

  4. will summary Information customer have to pay, click Confirm to pay

  5. Click Back to Ksher Payment to go back Merchant page

h5 baydeeplink 01
h5 baydeeplink 02
h5 baydeeplink 03

Mobile KPLUS

If customer not install app when click to pa will redirect to Google Play KPLUS or App Store KPLUS depend on customer OS.

  1. Select Mobile Banking tab, and select KPLUS.

  2. Input App PIN.

  3. If first time customer paid with ksher by using Kplus, will appear Authorized Page.

  4. Select your payment method and Click Next to go next page.

  5. will summary Information customer have to pay, click Confirm to pay

  6. Click Back to KSHER PAYMENT to go back Merchant page

h5 kplus 01
h5 kplus 02
h5 kplus 03
h5 kplus 04

Payment Flow Sequence Diagram

Merchant can follow this procedure to implement own system follow Online Gateway Pay payment flow.

Gateway Pay payment flow
Figure 2. Gateway Pay payment flow

  1. Buyer login merchant’s website to choose product and place an order.

  2. Merchant request Ksher PaymentSystem a transaction

  3. Ksher Payment System response Ksher aggregator payment page URL.

  4. Merchant display Ksher aggregator payment page with response URL.

  5. User choose payment E-wallet on Ksher aggregator gateway payment page.

  6. Ksher Payment System verify and create an order.

  7. Ksher Payment System request transaction to EwalletPaymentSystem

  8. Ewallet Payment System response transaction data including: QR Code, etc. to Ksher

    1. For WeChat /PromptPay, Ksher Payment System forward transaction data including QR Code to Ksher Gateway Payment Page.

    2. For Alipay/Airpay/LINE Pay, Ksher Payment System redirect to e-wallets confirm pay page.

  9. User confirm to pay.

  10. Merchant polling query payment result from Ksher Payment System.

  11. Ksher Payment System polling query payment result from E-wallet Payment System.

  12. E-wallet response payment result to Ksher.

  13. Ksher response payment result to Merchant.

  14. Ksher aggregator gateway payment page redirect to merchant redirect_url.

Specifications of APIs

Order Apply

API method

URL

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

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

channel_list

String(128)

YES

alipay,wechat,linepay,airpay,promptpay,truemoney,card,ktccard,ktc_instal

Payment Merchant list support. Value range:

alipay: Alipay Wallet.

alipayplus: Alipay+ Wallet. Country support only Japan.

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. minimum of 20 Baht. Country support only Thailand.

promptpay: PromptPay QR code (Thailand standard bank transfer QR code). Country support only Thailand.

scb_easy: SCB EASY Mobile App. minimum of 20 Baht. (only support on mobile). Country support only Thailand.

bbl_deeplink: Bualuang mBanking Mobile App. minimum of 20 Baht. (only support on mobile). Country support only Thailand.

baybank_deeplink: KMA Krungsri Mobile App. minimum of 20 Baht. (only support on mobile). Country support only Thailand.

kplus: KPLUS. minimum of 20 Baht. (only support on mobile). 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. minimum of 3,000 Baht. Country support only Thailand.

kbank_instal: KBANK Installment. support only KBANK Card. minimum of 3,000 Baht. Country support only Thailand.

kcc_instal: Krungsri Installment. support only Krungsri Card. minimum of 3,000 Baht.(5,000 Baht. for 10 months or more than). Country support only Thailand.

kfc_instal: First Choice Installment. support only Krungsri First Choice Card. minimum of 3,000 Baht. Country support only Thailand.

If multiple e-payment method required,a string made up by required e-wallets ,which seperated by "," without space, for example:"promptpay,linepay,airpay,truemoney,atome,card,ktc_instal,kbank_instal,kcc_instal,kfc_instal,scb_easy,bbl_deeplink,baybank_deeplink,kplus,alipay,wechat". will open all of channel your merchant you have. It will send Ksher checkout page to select your wallet want to paid.

If you send only one channel, it will be redirected to each wallet you send.

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

mch_code

String(256)

YES

123456acb

Order No. It will be display to customer.

mch_redirect_url

String(256)

YES

http://www.yourweb.com/gateway_pay/success/

After the payment is succeed, the web page is redirected to this URL. If merchant leaves this field blank, the web page will stay on payment page after payment succeed.

mch_redirect_url_fail

String(256)

YES

http://www.yourweb.com/gateway_pay/fail/

After the payment is failed, the web page is redirected to this URL. If merchant leaves this field blank, the web page will stay on payment page after payment failed.

mch_notify_url

String(256)

NO

http://www.yourweb.com/gateway_pay/pay_notify

the url to receive the asynchronous notification about the status of the payment from Ksher; If merchant leaves this field blank, then there will be no notification to send back to merchant.

mch_order_no

String(32)

YES

123456acb

Merchant order number, generated by merchant self. It must be unique on the merchant side.

don’t use name like 01,02,100,200

product_name

String(512)

YES

Demo

Name or description of your product.

Precautions when using "product_name"

please use General English characters. Avoid using special characters such as +&/$%

Because in some wallets, product_name will be shown to the product that the customer purchases. and wallet does not support special characters.

refer_url

String(256)

YES

The URL of the merchant website homepage. If the merchant doesn’t have a website, the merchant app download address can be used for this field.

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: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (UAE)

device

String( )

NO

H5

Value Range:PC, H5;

If you leave this blank, Ksher will determine user device automatically and will return an adaptive page.

member_id

String(32)

NO

ABC12345

User ID, support ktb storage card function when user ID is transmitted.

Can’t use Real number like 1,1200,00001, but can use string with number like ABC1234.

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

20190622131804

Time of create the request.the format is '%Y%m%d%H%M%S%SS'

color

String(32)

NO

#FF5C72

The color code of banner on payment page, which can be DIY by merchant.

background

String

NO

https://img.examplefile.com/image1.png

The url of banner background picture on payment page, which can be DIY by merchant.

payment_color

String

NO

#FF5C72

The color code of payment button, which can be DIY by merchant.

ksher_explain

String(256)

NO

Copyright information on payment page, which can be DIY by merchant.

hide_explain

Integer

NO

0

Value range:0,1;

1: to display an expiration timer.

0: to hide expire time information.

Default is "1".

expire_time

Integer

NO

30

How long the payment is valid to pay, the unit is minute. If merchant leave this blank, there will be no time limit.

hide_exp_time

Integer

NO

1

Value range:0,1;

1: to display an expiration timer. 0: to hide expire time information.

Default is "1".

logo

String

NO

https://file.ksher.cn/ksherbd/h5/2020325/201654.png

The url of logo picture on payment page, which can be DIY by merchant.

lang

String

NO

en

The display language. Value range:

en for English,

cn for Chinese,

th for Thai.

Default is en.

shop_name

String

NO

The Remark or description

attach

String

NO

The Remark or description

If you want data to display merchant platform at table data "consumer remark" and "merchants remark" Please send data by using this format

"attach": "{"consumer_remark": "remark from customer", "merchants_remark": "remark from merchant"}"

instal_fee_payer

String

NO

Who is carrying charge on installment fee. Value range:1, 2

1 : Means that the consumer bears the installment fee

2 : Indicates that the merchant bears the installment fee

The default value is 1

if you want to customize depend on each channel, please not use "instal_fee_payer", switch to use value "instal_fee_payer_merchant"

exclusive

Integer

NO

Limit to open link only one person. Value Range:1, 2

1: Limit people who click on the link to only one person.

2: not limit.

The default value is 1

instal_fee_payer_merchant_channel_list

String

NO

"ktc_instal,kbank_instal"

Which payment channel merchant has to absorb interest rate, available for multiple channels. Example if send "instal_fee_payer_merchant_channel_list":"kbank_instal"

customer who paid by KBANK Installment merchant will bears the installment fee.

But another Installment channels, consumer bears the installment fee.

channel_instal_times_list

String

NO

"{\"ktc_instal\": [3,4,5], \"kbank_instal\": [4,5,6,7,8]}"

Installment period, available for multiple channels. Example if send "channel_instal_times_list": "{\"ktc_instal\": [3,4,5], \"kbank_instal\": [4,5,6,7,8]}"

customer who paid by KTC Installment will display 3/4/5 months available to paid.

KBANK Installment will display 4/5/6/7/8 months available to paid.

Please send this value in JSON Objects convert to string format, don’t send in JSON Objects, because it will error signature.
Example 36. Request Example
{
    "appid": "mch28321",
    "channel_list": "wechat,alipay,linepay,promptpay,truemoney,card",
    "device": "",
    "fee_type": "THB",
    "mch_code": "233114471",
    "mch_order_no": "233114471",
    "mch_redirect_url": "https://www.yourweb.com/",
    "mch_redirect_url_fail": "https://www.yourweb.com/fail",
    "mch_notify_url": "https://www.yourweb.com/notify",
    "nonce_str": "8d22a1335bc893fe6e90a236a93ca3c5",
    "product_name": "sdd",
    "refer_url": "https://www.yourweb.com/",
    "sign": "5f01d9fe632bcf7d07deedcd3b419d37c653c571e7ea8759ad8cd4e44594b73776ab23720a7238e1a4442fb13e63d7a4b0e80695eedf50bd65d7c8e4a80c6d21",
    "time_stamp": "2020041414150505S",
    "total_fee": 13000
}
Example 37. Request Example by use cURL
curl --location 'https://gateway.ksher.com/api/gateway_pay' \
--data-urlencode 'appid=mch35005' \
--data-urlencode 'channel_list=promptpay,linepay,airpay,truemoney,atome,card,ktc_instal,kbank_instal,kcc_instal,kfc_instal,scb_easy,bbl_deeplink,baybank_deeplink,kplus,alipay,wechat,card,ktc_instal,kbank_instal,kcc_instal,kfc_instal' \
--data-urlencode 'fee_type=THB' \
--data-urlencode 'lang=en' \
--data-urlencode 'mch_code=2023-02-22-17-11-00' \
--data-urlencode 'mch_notify_url=https://www.yourweb.com/api/gateway_pay/notify_url/' \
--data-urlencode 'mch_order_no=2023-02-22-17-11-00' \
--data-urlencode 'mch_redirect_url=https://www.yourweb.com/api/gateway_pay/success' \
--data-urlencode 'mch_redirect_url_fail=https://www.yourweb.com/api/gateway_pay/fail' \
--data-urlencode 'nonce_str=a2de1d78127dd837e648ef0c28773fcb' \
--data-urlencode 'product_name=2023-02-20-17-27-00' \
--data-urlencode 'refer_url=https://www.yourweb.com' \
--data-urlencode 'sign=5a665ecc4e1a94f01de579a9dd1c4850984066a7d4b479bb3bc3d8872c5ac871a3e868efdf9da0b8baaac1cd3f3ce789f7e6e677fb8ff25ea1b872c387980161db485ed84e28c9ae064dacae877d8855deb4bb3332499e9a5f73675377e0fa7baf66f8129299c4e505439501e2088abfed1558a9a2bff39a582dcf36b364a049' \
--data-urlencode 'time_stamp=2023030317445454S' \
--data-urlencode 'total_fee=100'

Order Applying SUCCESS Response Parameters

Parameter Type Required Example Description

code

Integer

YES

0

Value range:

0: The request data was received successfully but it does not mean the process is succeeded.

Not 0: The API request failed. Please check response’s message first. You can try to send a new request with the same parameters again.

lang

String

NO

en

The display language. Value range:

en for English cn for Chinese th for Thai.

Default is en.

message

String(256)

YES

ok

Detailed description of result. If fail it will be show in detail error in here.

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

msg

String(256)

YES

SUCCESS

Hint message of result

data

JSON

YES

{"pay_content": "https://gateway.ksher.com/page?order_uuid=49ba030e7e1711ea97e652540075451d"}

Gateway payment data, refered to data parameters

Gateway payment data parameters

Parameter Type Required Example Description

pay_content

String(256)

YES

https://gateway.ksher.com/page?order_uuid=49ba030e7e1711ea97e652540075451d

Ksher Payment Page URL. You can use this to redirect the buyer to payment page.
Example 38. SUCCESS Response Example
{
    "code": 0,
    "msg": "SUCCESS",
    "data": {
        "pay_content": "https://gateway.ksher.com/ua?order_uuid=f624f098b8d111edacef525400962f26&lang=en"
    },
    "sign": "7b2159b7f2ec4bff350322b5cdef55bfe4265c03023390ccf8e98292c559a29d79c34ad2eaceaeb5b7d5c6ab9e13afb8c85b0bf267046ea0c5b3d24bf53c09d6",
    "message": "SUCCESS"
}

Order Applying FAIL Response Parameters

Parameter Type Required Example Description

code

Integer

YES

-4

Value Range:

0: The request data was received successfully but it does not mean the process is succeeded.

Not 0: The API request failed. Please check response’s message first. You can try to send a new request with the same parameters again.

-1: {'cn': '商户信息错误', 'th': 'ข้อมูลร้านค้าผิดพลาด', 'en': 'Invalid merchant information'}

-2: {'cn': '验证商户签名失败', 'th': 'การตรวจสอบลายเซ็นของร้านค้าล้มเหลว', 'en': 'The verification of merchant signature failed'}

-101: {'cn': '验证商户签名失败', 'th': 'การตรวจสอบลายเซ็นของร้านค้าล้มเหลว', 'en': 'The verification of merchant signature failed'}

-102: {'cn': 'member_id 不能是纯数字', 'th': 'member_id ไม่สามารถเป็นตัวเลขอย่างเดียวได้', 'en': 'member_id cannot be number only'}

-103: {'cn': 'member_id 长度不能超过32位', 'th': 'member_id ต้องไม่เกิน 32 ตัว', 'en': 'member_id cannot be more than 32 characters'}

-1000: {'cn': '参数校验失败: mch_order_no', 'th': 'ข้อมูลไม่ถูกต้อง: mch_order_no', 'en': 'Paramter invalid: mch_order_no'}

-1001: {'cn': '您没有开通任何钱包或银行卡', 'th': 'คุณไม่ได้เปิดใช้บริการกระเป๋าเงินหรือบัตรเครดิต', 'en': 'You have not apply for any ewallets nor credit card payment services'}

-4: {'cn': '订单号必须唯一', 'th': 'หมายเลขรายการซื้อขายต้องไม่ซ้ำ', 'en': 'Order number must be unique'}

-41: {'cn': '订单已被取消', 'th': 'ออเดอร์ดังกล่าวถูกยกเลิก', 'en': 'The order has been canceled'}

-201: {'cn': '创建支付订单失败', 'th': 'การสร้างรายการชำระเงินล้มเหลว', 'en': 'Transaction creation failed'}

1: {'cn': '订单已支付成功', 'th': 'ออเดอร์ถูกจ่ายสำเร็จแล้ว', 'en': 'Order has been completed'}

lang

String

YES

The display language. Value range:

en for English

cn for Chinese

th for Thai.

Default is en.

message

String(256)

YES

Detailed description of result

msg

String(256)

YES

Hint message of result
Example 39. Failed Response Example
{
    "lang": "",
    "code": -4,
    "msg": "订单号不唯一",
    "message": "订单号不唯一"
}

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 (mch_order_no, ksher_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 not needed to provide all, you can select at least one parameters to to sending.)

Order no. generated by Ksher.
Example 40. 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: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (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 41. 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 42. Fail Response Example
{'lang': '', 'code': -3, 'msg': '该订单不存在', 'message': '该订单不存在'}

Webhook Notify

What’s Webhook?

  • Webhook is API response when Customer paid like event. It make customer don’t need to polling to check status.

When webhook callback?

  • add parameter name "mch_notify_url" when you request, ksher will initiate a webhook callback.

  • ksher will polling check the status payment within 2 hours.

    • if the order has been successful payment within 2 hours, webhook will callback.

    • if the order has not been paid within 2 hours , The merchant needs to query request by yourself.

  • If ksher got callback from wallet. we will call webhook to merchant also.

What going on If internet not stable and don’t got webhook at the first time?

  • If the merchant does not return correct format,we will try to callback again.

Correct format response

{"result": "SUCCESS", "msg": "OK"}

This is table webhook with times notification, if customer not response correct success type and or we can’t callback

Times retry Times between the last retry

1st retry

1s

2nd retry

2s

3rd retry

2s

4th retry

10s

5th retry

30s

6th retry

1min

7th retry

10min

8th retry

1hour

9th retry

3hour

10th retry

5hour

11th retry

8hour

12th retry

12hour

Delayed messages will be retried 12 times within 29 hours

After consumer pays, Ksher system will notify merchant only SUCCUSSFULL payment

API method

Method

POST

Parameter organization format

text/plain;charset=utf-8

Payment Result of SUCCESS

Parameter Type Required Example Description

code

int

YES

0

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

msg

String(32)

YES

操作成功

the response message.

message

String(32)

YES

操作成功

the response message.

data Parameters (JSON )

channel

String(128)

YES

alipay

Payment channel pay by this transaction.

openid

String(128)

YES

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

channel_order_no

String(32)

YES

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

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.

ksher_order_no

String(32)

YES

90020210420105438458353

Order no. generated by Ksher.

nonce_str

String(32)

YES

WQVzZs6qgYUVXWkt9nw15QBWI2jFNMjk

Random string

time_end

String(14)

YES

2014-10-30 13:35:25

the merchant local time when the order is finished，the format is yyyy-MM-dd HH:mm:ss

fee_type

String(16)

YES

THB

Currency code for total_fee. refer to with ISO 4217. Value range:

THB: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (UAE)

attach

String(127)

YES

any extra information can be added here.

rate

string(16)

YES

exchange rate of foreign currency to RMB.

result

string(16)

YES

SUCCESS

Status payment. Value range: SUCCESS

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

appid

String(32)

YES

mch12345

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

cash_fee

int

YES

specifies the total cash payment amount of a transaction.

mch_order_no

String(32)

YES

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

pay_mch_order_no

String(32)

YES

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

Data will response in text format following like this

{"code": 0, "msg": "操作成功", "data": {"channel": "truemoney", "openid": "tmn.10036553303", "channel_order_no": "230523131245589KSUSL", "cash_fee_type": "THB", "ksher_order_no": "90020230523141245533239", "nonce_str": "DLtzj2QZ5FSaydJEUTS3sTAO552IGhwp", "time_end": "2023-05-23 13:12:45", "fee_type": "THB", "attach": "", "rate": "", "result": "SUCCESS", "total_fee": 100, "appid": "mch35005", "cash_fee": 100, "mch_order_no": "2023-05-23-13-10-00", "pay_mch_order_no": "2305231312099897"}, "sign": "389cbf000d6bf322b1ebb99e726417f7604384654bdc41cd82a70b1155ad7ddb381592f5127516bc7690c66011c563b6075700f9e5d00de8ab82aafecf55d9d6", "message": "操作成功"}

after convert data to json format will following this

{
   "code":0,
   "msg":"操作成功",
   "data":{
      "channel":"truemoney",
      "openid":"tmn.10036553303",
      "channel_order_no":"230523131245589KSUSL",
      "cash_fee_type":"THB",
      "ksher_order_no":"90020230523141245533239",
      "nonce_str":"DLtzj2QZ5FSaydJEUTS3sTAO552IGhwp",
      "time_end":"2023-05-23 13:12:45",
      "fee_type":"THB",
      "attach":"",
      "rate":"",
      "result":"SUCCESS",
      "total_fee":100,
      "appid":"mch35005",
      "cash_fee":100,
      "mch_order_no":"2023-05-23-13-10-00",
      "pay_mch_order_no":"2305231312099897"
   },
   "sign":"389cbf000d6bf322b1ebb99e726417f7604384654bdc41cd82a70b1155ad7ddb381592f5127516bc7690c66011c563b6075700f9e5d00de8ab82aafecf55d9d6",
   "message":"操作成功"
}
notes:

In the notify calling back function, a response is needed to return to Ksher Server, the response is JSON formated and the content is as follow:

Example 44. For success:
{"result": "SUCCESS", "msg": "OK"}
Example 45. For error:
{"result": "FAIL", "msg": "some error information"}

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

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

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

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,wechat,linepay,airpay,promptpay,truemoney

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: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (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 46. 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

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

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: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (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 47. 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.

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

Order Close

API method

URL

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

Method

POST

Parameter organization format

application/x-www-form-urlencoded

Order Close 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

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

channel

String(32)

YES

wechat

Value range:

  • airpay

  • wechat

  • alipay

  • alipayplus :only japan merchant

  • ktbcard

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.

time_stamp

String(256)

YES

time stamp example: "time_stamp": "20190622131804"
Example 49. Request Example
{
    "code": 0,
    "data": {
        "appid": "mch36591",
        "mch_order_no": "test3",
        "nonce_str": "7a57e84495bfe7abff4ff23591516511",
        "result": "SUCCESS"
    },
    "msg": "ok",
    "sign": "61805f39c7c484d936cbf40c864b11b9fec0b93205fdbc4efe5b71c9c7dfd98152e1ebc9af5866dd54cf58008418b52ea6122e7994f1d3fe5e6d559a8b022e5f",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-12-25T17:44:54.226116+08:00",
    "version": "3.0.0"
}

Order Close 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

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

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

mch_order_no

String(32)

YES

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

nonce_str

String(32)

YES

Random string

result

string(16)

YES

SUCCESS

Value range: SUCCESS
Example 50. SUCCESS Response Example
{
    "code": 0,
    "data": {
        "appid": "mch36591",
        "mch_order_no": "test3",
        "nonce_str": "7a57e84495bfe7abff4ff23591516511",
        "result": "SUCCESS"
    },
    "msg": "ok",
    "sign": "61805f39c7c484d936cbf40c864b11b9fec0b93205fdbc4efe5b71c9c7dfd98152e1ebc9af5866dd54cf58008418b52ea6122e7994f1d3fe5e6d559a8b022e5f",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-12-25T17:44:54.226116+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

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

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.

  • 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 51. Fail Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_ORDER_NO",
        "err_msg": "failed to find this order no ('mch_order_no:test33,ksher_order_no:,channel_order_no:',).",
        "nonce_str": "7a57e84495bfe7abff4ff23591516511",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "01d2436ef5ed44cb77d3594adccc2c92e2a6a8b39cad2bd1abc3dcd9d64b7c00a303355fc47cb61c3862fb116ed7f67b9db73634da95e91a1fcfc6b12a96da59",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-12-25T17:55:25.248752+08:00",
    "version": "3.0.0"
}

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

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

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

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

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: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (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 52. 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

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

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: Thailand

MYR: Malaysia

JPY: Japan

AED: United Arab Emirates dirham (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 53. 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

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

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

Save Card Function

  • Customers can select to save the card for next time purchase, customers don’t have to enter card information again.

  • Available for merchants who do API integration and Plugin only.

    • Link Pay or Ksher Boss pro can not open this function.

  • Any API Online Merchants that want to open this function, have to adding Parameter field of “member_id” when Post to Gateway Order Apply. API can use Save card, Please see.

  • Save Card Function is based on merchants, not customers.

    • For example, "customer A" makes a payment to "Merchants A" by credit card with save card function.

    • The next time when make a payment to Ksher "Merchants A" again, no need to filled card information, customer can select the card to pay directly.

    • If the customer makes a payment to Ksher "Merchants B", he/she still have to fill in credit card information when make a payment.

  • Merchants & Ksher self will not see or collect any customers’ card information.

PC Web scenario User experience

pc checkout

  • In case you’ve never saved card, you can directly click at “credit/debit" to pay

pc checkout savecard01

  • In case you’ve ever saved card, you can click to pay with your saved card or can click at “Other’s credit/debit card to pay

pc checkout savecard02

  • After Selected , It will automatically change to filled card’s information page in which there will be adding to click accept that Customers acknowledge that his/her card information is save in my Ksher account for subsequent transactions.

pc checkout deletecard 01
pc checkout deletecard 02

  • In case you’ve ever saved card, you can click to pay with your saved card or can click at “Other’s credit/debit card to pay

H5/Mobile browser scenario User experience

h5 checkout

  • In case you’ve never saved card, you can directly click at “credit/debit" to pay

h5 checkout savecard01

  • In case you’ve ever saved card, you can click to pay with your saved card or can click at “Other’s credit/debit card to pay

h5 checkout savecard02

  • After Selected , It will automatically change to filled card’s information page in which there will be adding to click accept that Customers acknowledge that his/her card information is save in my Ksher account for subsequent transactions.

h5 checkout deletecard 01
h5 checkout deletecard 02

  • In case you’ve ever saved card, you can also delete saved card

ERROR CODES

Name Description Reason Solution

APPID_NOT_EXIST

APPID not exist

APPID was absent in parameters.

Please check if the APPID is correct.

APPID_MCHID_NOT_MATCH

APPID and MCHID not match

APPID and MCHID not match

please check if the APPID and mchid match.

INVALID_ORDER_NO

invalid order no.

order no. passed in is not correct.

parameter error, please check if the original order no. passed in exist or if the original order is failed.

KSHER_SIGN_ERROR

signature error

merchant signature is not correct

check the signature parameter

KSHER_SYSTEMERROR

Error occurred during handling the request.

Error occurred during handling the request.

Issue the refund request again.

KSHER_VERSION_ERROR

API version used by merchant is not compatible with the API of the vendor

API version used does not match

contact the vendor to confirm current API version

KSHER_ERROR_ORDER_NO

Missing order no parameter

Missing order no parameter

Check the order no.(mch_order_no, ksher_order_no, channel_order_no)

KSHER_REFUND_EXPIRE

Refund can not be made via API by merchant after the order already settled.

Refund can not be made via API by merchant after the order already settled.

Please submit refund request on the Ksher merchant platform.

KSHER_INVALID_MCHINFO

merchant information is not correct

the appid passed in does not exist in the vendor’s system

confirm if the appid passed in is correct, contact the vendor if needed.

KSHER_INVALID_ORDER_NO

order no. does not exist

the order no. passed in cannot be found in vendor’s system

check if the order no. passed in is correct

KSHER_INVALID_REFUND_FEE

invalid amount to refund

amount to refund is greater than the available amount

check if the amount to refund is correct

KSHER_INVALID_REFUND_AMOUNT

Partially refund is not allowed

Partially refund is not allowed

refund completely is allowed.

KSHER_INVALID_REFUND_BALANCE

The balance amount of this order(price fee minus amount already refunded.) is not enough for the amount to refund.

The balance amount of this order(price fee minus amount already refunded.) is not enough for the amount to refund.

Check the amount to refund.

KSHER_INVALID_REFUND_ORDER_NO

invalid refund order no.

the refund order no. passed already used.

check if the refund order no. passed in, use a new one.

KSHER_INVALID_REFUND_FEE_OR_TYPE

Refund currency or amount invalid

Refund currency or amount invalid

Check the currcency or amount to refund.

KSHER_PARAM_OVERLENGTH

Some parameters are too long.

Some paramters are too long

Check the parameters.

KSHER_INVALID_PARAM

Missing parameter(s)

Some parameter(s) invalid

Check parameter(s) is correct

KSHER_DUPLICATED_ORDERNO

The merchant order no already used.

The merchant order no already used.

Use a new order no to make the order again.

KSHER_EXCEED_AMOUNT_LIMIT

the amount to pay exceeds the amount limit configured

the amount to pay exceeds the amount limit configured

make sure if the amount to pay exceeds the limit.

KSHER_FEETYPE_NOT_MATCH

fee type does not match

pricing fee type does not match the registered fee type

merchant needs to modify the program, if merchant is sure that the fee type passed in is correct, contact the vendor.

KSHER_DUPLICATED_ORDERNO

The merchant order no already used.

The merchant order no already used.

Use a new order no to make the order again.

KSHER_DUPLICATED_REFUND_ORDERNO

invalid refund order no

the refund order no. passed already used.

check if the refund order no. passed in, use a new one.

KSHER_AMOUNT_IS_TOO_SMALL

The amount is too small.

The amount is too small

Pass in a larger amount

KSHER_CHANNEL_RESPONSE_ERROR

Error occurred during query operation

Error occurred during query operation

Make an order query again.

LACK_PARAMS

parameter absent

mandatory parameter(s) was absent

please check if the parameters were sufficient

MCHID_NOT_EXIST

MCHID not exist

MCHID was absent in parameters.

please check if the MCHID is correct.

NOAUTH

the merchant has no access to this interface.

the merchant has not yet got the access to this interface.

contact the vendor(Ksher)

NOT_UTF8

coding format error

required coding format was not used.

please use UTF-8 coding

NOTENOUGH

Not enough unsettled fund for refund

There is not enough unsettled fund for refund

This error code means refund request failed due to not enough unsettled fund for refund.Merchants need to contact Ksher to authorise credit for this kind of situation. If unsettled fund is enough ,please call the refund API once there is enough unsettled fund, or retry it continuously.

ORDERPAID

order closed already

the order closed already.

the order no. is already closed, please launch a new order.

ORDERNOTEXISTR

the order no. does not exist

the order does not exist in the system

merchant need to check if the order no. is correct.

OUT_TRADE_NO_USED

repetitive out_trade_no

the same order cannot be submitted for multi times.

please verify whether the out_trade_no. was submitted repetitively

PARAM_ERROR

parameters error

parameters requested are not correct

check the application according to the information returned, contact the vendor if needed.

POST_DATA_EMPTY

post parameters are empty

post parameters should not be empty

please check the paremeters posted in the http request.

REQUIRE_POST_METHOD

please use POST method

the method used to pass the parameters was not POST.

please check if the parameters was passed by POST method

SYSTEMERROR

system error

system timeout

call the order query API immediately to check order status, and decide next step according to the status of the order

SIGNERROR

signature error

the signature parameter is not correct

please check if the signature parameter and method meet the requirements of signature algorithm

TRADE_STATE_ERROR

order state error

there will be latency for the result for refund application, please query later(20 minutes for balance payment, 3 workdays for card payment)

USER_ACCOUNT_ABNORMALE

refund failed

user account is exceptional or unregistered.

this status stands for the failure of the refund operation, merchant can handle the refund by himself.

XML_FORMAT_ERROR

XML format error

XML format error

please check whether the format of XML parameters is correct.

SHOP_ID_ERROR

Invalid merchant information

Invalid merchant information

Please check if the APPID is correct.

CANCEL_ERROR

The cancellation failed

The cancellation failed

Order cannot cancel because of wallet not support or already paid

ORDER_NOT_EXIST

This order does not exist.

Not found this order

Check mch order no is correct or not

USER_NOT_EXIST

This user does not exist.

Not found this order

Check mch order no is correct or not

ORDER_NOT_PAY

This order has not been paid.

This order has not been paid.

Order still not paid

ORDER_ALREADY_REFUND

This order has been refunded.

This order has been refunded.

order has been refunded.

REFUND_FAILED

Refund failed.

Refund failed.

check value is correct

EXPIIRE_ORDER

The order has timed out

The order has timed out

expired time set in order is timeout

ORDER_ERROT

Order number must be unique

Order number must be unique

Check order should be not duplicate or create before

SHOP_NOT_EXIST

This shop does not exist

This shop does not exist

Please check if the APPID is correct.

PRICE_NOT_EXIST

Invalid price

Invalid price

Check amount should be not 0 or create this order before

MCH_ORDER_ERROR

Duplicate order number

Duplicate order number

Check order should be not duplicate or create before

RADIS_DOES_NOT_EXIST

Redis does not exist

Check url is correct

QUERY_ORDER_ERROR

Search for failed not completed transaction

Search for failed not completed transaction

check your value is correct

ORDER_PAYMENT_ERROR

Your payment failed

Your payment failed

Retry to paid again

SMS_CODE_ERROR

Failed to receive OTP code

Failed to receive OTP code

check you mobile phone is correct

CHANNEL_LIST_ERROR

You have not apply for any ewallets nor credit card payment services

You have not apply for any ewallets nor credit card payment services

check your channel value is correct or support

MEMBER_ID_ERROR

member_id cannot be number only

member_id cannot be number only

Please check your member_id not use Real number like 1,1200,00001, but can use string with number like ABC1234.

SAVE_CARD_ERROR

Failed to save card

Failed to save card

Check Bank card channel can support save card function

MEMBER_CARD_ERROR

This card cannot be used

This card cannot be used

This card is not available, please change card to paid

EMPTY_CARD_NO

Card information is incorrect

Card information is incorrect

Check your card input information

DELETE_MEMBER_CARD_ERROR

Failed to delete card

Failed to delete card

Refresh page and try to delete again

MEMBER_CARD_NOT_EXIST

This card does not exists

This card does not exists

check your member_id is correct

MEMBER_ID_LENGTH_OUT_OF_LIMIT

member_id cannot be more than 32 characters

member_id cannot be more than 32 characters

Please check your member_id not use Real number like 1,1200,00001, but can use string with number like ABC1234.

and member_id cannot be more than 32 characters

ORDER_ALREADY_CANCEL

The order has been canceled

The order has been canceled

This order already cancel, Please try to create the new order.

ORDER_ALREADY_CANCEL_OPERATION_CANNOT_BE_PERFORMED

The order has been canceled, this action cannot proceed

The order has been canceled, this action cannot proceed

This order already cancel, Please try to create the new order.

ORDER_ALREADY_PAY_OPERATION_CANNOT_BE_PERFORMED

This order has already been paid, this action cannot proceed

This order has already been paid, this action cannot proceed

This order already paid, Please try to create the new order.

ORDER_ALREADY_PAYMENT_SUCCESS

Order has been completed

Order has been completed

This order already paid, Please try to create the new order.

INSTAL_FEE_PAYER_ERROR

Failed to apply setting of interest-bearing

Failed to apply setting of interest-bearing

check at instal_fee_payer_merchant_channel_list or instal_fee_payer is correct

TRUEMONEY_OPT_CODE_ERROR

Wrong OTP code

Wrong OTP code

check OTP is correct

MANY_OPEN

Someone is paying this bill. DO NOT pay twice.

Someone is paying this bill. DO NOT pay twice.

check on exclusive is turn on or not. if have another person open payment page

LANG_REPEAT_SUBMIT

Repetitive submission

Repetitive submission

order already create before, create the new one.