Card Payment Integration Guide

Overview

Credit/Debit Card Online Payment is available for merchant to integrate by calling ksher Gateway Pay API.

Gateway Pay is Ksher Online e-payment aggregator service. Merchant only need to integrated once to have all Online Payment method acceptance for Card Payment, WeChat Pay, Alipay, Prompt Pay, Airpay, LinePay, True Money,

It helps merchant to create a checkout page with all Online e-wallets and Card Payment available for consumers to choose. Both Web and H5/Mobile payment scenarios (WeChat Pay only allowed open in WeChat browser) are able to be achieved by using Ksher Gateway Pay.

Ksher provide two method for calling Online e-payment aggregator service:

Payment Flow Sequence Diagram

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

Gateway Pay payment flow
Figure 1. Gateway Pay payment flow

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

  2. Merchant request Ksher PaymentSystem a transaction by choosing one method:

    1. API method or

    2. Html Form method.

  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.

  9. For WeChat /PromptPay, Ksher Payment System forward transaction data including QR Code to Ksher Gateway Payment Page. For Alipay/Airpay/LINE Pay, Ksher Payment System redirect to e-wallets confirm pay page.

  10. User confirm to pay.

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

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

  13. E-wallet response payment result to Ksher.

  14. Ksher response payment result to Merchant.

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

User Experience of Online Gateway Pay

PC Web scenario User experience

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

PCcheckoutpage

Credit Card

Select Card, it will turn to KTB card payment checkout page. Continue to pay with fill personal card information.

card method
fill card info

WeChat Pay

Select WeChat Pay, it will turn to Ksher DIY checkout page, continue to pay with scanning QR code use WeChat app. Visual design can DIY by merchant via API.

PCwechat

PromptPay

Select PromptPay, it will turn to Ksher DIY checkout page, continue to pay with scanning QR code use bank app. Visual design can DIY by merchant via API.

PCpromptpay

Alipay

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

PCalipay

LINE pay

Select LINE pay, it will redirect to LINE checkout page, continue to pay with open LINE Pay e-wallets to sacn QR code or login LINE account.

PClinepay

Airpay

Select Airpay, it will redirect to Airpay checkout page, continue to pay with open Airpay e-wallets to sacn QR code.

PCairpay

TrueMoney

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

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

PCTruemoney

Select TrueMoney and your account is dynamic QR, it will create Ksher checkout page. Continue payment with scan QR code.

PCtruemoney dynamic

H5/Mobile browser scenario User experience

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

Credit Card

h5 gateway with card

Select Card, it will turn to KTB card payment checkout page. Continue to pay with fill personal card information.

h5 card
h5 card info fill
h5 card info submit
h5 card payment result

Alipay

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

H5alipay
Airpay

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

H5airpay

WeChat

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

H5wechat

Promptpay

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

H5promptpay

LINE pay

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

H5linepay

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.

H5truemoney

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

H5truemoney dynamic

Specifications of Gateway Pay APIs

Order Apply

API method

URL

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

Method

POST

Parameter organization format

application/x-www-form-urlencoded

HTML Form method

URL for PC

http://gateway.ksher.com/pc

URL for H5/mobile

http://gateway.ksher.com/h5

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

String(128)

YES

alipay,wechat,linepay,airpay,bbl_promptpay,truemoney,ktbcard

Payment Merchant list support.

If only card method required, please fill value "ktbcard"; If multiple e-payment method required,a string made up by required e-wallets ,which seperated by "," without space, for example:"alipay,wechat,linepay,airpay,bbl_promptpay,truemoney,ktbcard"

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

12345

Your Merchant Number. Check on merchant ksher.

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_order_no

String(256)

YES

123456acb

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

product_name

String(512)

YES

Demo

Name or description of your product

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. refer to with ISO 4217.

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.

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
Example 1. Request Example
{
    "appid": "mch28321",
    "channel_list": "wechat,alipay,linepay,bbl_promptpay,truemoney,ktbcard",
    "device": "",
    "fee_type": "THB",
    "mch_code": "2311",
    "mch_order_no": "233114471",
    "mch_redirect_url": "https://www.yourweb.com/",
    "mch_redirect_url_fail": "https://www.yourweb.com/",
    "nonce_str": "8d22a1335bc893fe6e90a236a93ca3c5",
    "product_name": "sdd",
    "refer_url": "https://www.yourweb.com/",
    "sign": "5f01d9fe632bcf7d07deedcd3b419d37c653c571e7ea8759ad8cd4e44594b73776ab23720a7238e1a4442fb13e63d7a4b0e80695eedf50bd65d7c8e4a80c6d21",
    "time_stamp": "2020041414150505S",
    "total_fee": 13000
}

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 2. SUCCESS Response Example
{
    "code": 0,
    "data": {
        "pay_content": "https://gateway.ksher.com/page?order_uuid=49ba030e7e1711ea97e652540075451d"
    },
    "lang": "",
    "message": "SUCCESS",
    "msg": "SUCCESS",
    "sign": "6608b289c41550669d34236fd878045a5f95ad4a67b40988c4892ff71972ce2d809f453284b81c2c64dea5fbee826e6e81bf67a1644439a7e7917e555fbf8a9e"
}

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.

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

refer to relevant chapter Signature Algorithm

appid

String(32)

YES

assigned by Ksher

nonce_str

String(32)

YES

Random string, must be unique

time_stamp

String(256)

YES

time stamp example: "time_stamp": "20190622131804"
Example 4. 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/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 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

assigned by Ksher.

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, bbl_promptpay, truemoney.

channel_order_no

String(32)

Conditional

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

fee_type

String(16)

YES

CNY

Pricing currency, comply with ISO 4217, 3 characters, the default is CNY, refer to Appendix2 for its value range

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 5. 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": "ktbcard",
        "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 6. Fail Response Example
{'lang': '', 'code': -3, 'msg': '该订单不存在', 'message': '该订单不存在'}

Order Refund

API method

URL

http://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

sign

String(256)

YES

refer to relevant chapter Signature Algorithm

appid

String(32)

YES

assigned by Ksher

nonce_str

String(32)

YES

Random string

mch_order_no

String(32)

YES

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

ksher_order_no

String(32)

YES

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

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,ktbcard

total_fee

Int

YES

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

fee_type

String(16)

YES

CNY

Pricing currency, comply with ISO 4217, 3 characters, the default is CNY, refer to Appendix2 for its value range

mch_refund_no

String(32)

YES

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

refund_fee

Int

YES

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

attach

String(127)

OPTINAL

any extra information can be added here.

device_id

String(32)

OPTINAL

POS001

the terminal id from which the request is issued.

operator_id

String(32)

OPTINAL

The id for cashier
Example 7. Request Example
{
    "appid": "mch20163",
    "channel": "wechat",
    "fee_type": "THB",
    "mch_order_no": "1494904236",
    "refund_fee": 10,
    "mch_refund_no": "refund1494904599",
    "nonce_str": "IeYrVB93dq8JbJbHJq1oZAW4d7PEb4jU",
    "sign": "29bc5623d82c3a1e17c85a1508aafa6d5e2626b15ee0f374f2401ced9f5fd76e618c0d027bf9f651bf727110c76a64ab2ce7a1d32d1538707224466c9b5f5c35",
    "time_stamp": "20170516101639",
    "total_fee": 10,
    "version": "1.0.0"
}

or

{
    "appid": "mch28321",
    "ksher_order_no": "70020200714124058662887",
    "mch_refund_no": "refund1594708697",
    "nonce_str": "91591041baae5cefebc9e1809f2f48d6",
    "sign": "338d983913ef8c8c7dea538c789ad352fc78f65785bb14e6e072153f541e09bcc62dd0d6cea321ee217c3d1be2b12efb0ecf58c8edc28648d7c77dbd97379d9d",
    "time_stamp": "2020071416574040S"
}

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

sign

String(256)

YES

refer to relevant chapter Signature Algorithm

status_code

reserved for future use

status_msg

reserved for future use

time_stamp

String(32)

YES

2020042015374848S

the time stamp of request order

version

version of the API

data Parameters (JSON )

appid

String(32)

YES

assigned by Ksher

attach

String(127)

OPTINAL

any extra information can be added here.

cash_refund_fee

int

YES

Amount refunded to customer, normally in CNY.

channel_order_no

String(32)

YES

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

channel_refund_no

String(32)

YES

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

device_id

String(32)

OPTINA

POS001

the terminal id from which the request is issued.

fee_type

String(16)

YES

CNY

Pricing currency, comply with ISO 4217, 3 characters, the default is CNY

ksher_order_no

String(32)

YES

Order no. generated by Ksher.

ksher_refund_no

String(32)

YES

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)

OPTINAL

The id for cashier

refund_fee

Int

YES

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": "mch28321",
        "attach": "",
        "cash_refund_fee": "100",
        "channel_order_no": "509366",
        "channel_refund_no": "",
        "device_id": "",
        "fee_type": "THB",
        "ksher_order_no": "70020200714124058662887",
        "ksher_refund_no": "70020200714143818745766",
        "mch_order_no": "2007141140508182",
        "mch_refund_no": "refund1594708697",
        "nonce_str": "IeYrVB93dq8JbJbHJq1oZAW4d7PEb4jU",
        "operator_id": "",
        "refund_fee": 100,
        "result": "SUCCESS",
        "total_fee": 204
    },
    "msg": "ok",
    "sign": "3e4e6bffe0c83429ccf36beb8ba35076f2c03f0e576bd046bceb107760dff62ed1e70775ac8f47004471bbb6cd7053f6c6aa6c7f34c7c946f81c941339582a25",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "",
    "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

version

version of the API

status_code

reserved for future use

time_stamp

String(32)

YES

2020042015374848S

the time stamp of request order

status_msg

reserved for future use

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

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

API method

URL

http://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

refer to following relevant chapter for signature algorithm

appid

String(32)

YES

assigned by Ksher

nonce_str

String(32)

YES

Random string

mch_order_no

String(32)

YES

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

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

total_fee

Int

YES

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

fee_type

String(16)

YES

CNY

Pricing currency, comply with ISO 4217, 3 characters, the default is CNY, refer to Appendix2 for its value range

mch_refund_no

String(32)

YES

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

refund_fee

Int

YES

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

attach

String(127)

OPTINAL

any extra information can be added here.

device_id

String(32)

OPTINAL

POS001

the terminal id from which the request is issued.

operator_id

String(32)

OPTINAL

The id for cashier
Example 10. Request Example
{
    "appid": "mch20163",
    "channel": "wechat",
    "channel_order_no": "",
    "ksher_order_no": "",
    "mch_order_no": "1494904236",
    "nonce_str": "ogWfy5jDlujCyhJCKNjYQVlrSGkdj9LO",
    "sign": "68ba48d72206a1561f6322800db9d8dabe4d1e0e1965fd31e5e10e034d2b9123291d6c596ac2b271292545275cc8bf4689ec8cdca581ff17c4ea1f3efd8e321a",
    "time_stamp": "20170516125822",
    "version": "1.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

status_code

reserved for future use

status_msg

reserved for future use

time_stamp

String(32)

YES

2020042015374848S

the time stamp of request order

version

version of the API

sign

String(256)

YES

refer to following relevant chapter for signature algorithm

data Parameters (JSON )

cash_fee

int

YES

specifies the total cash payment amount of a transaction.

cash_fee_type

string(16)

YES

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

state response from e-wallet

fee_type

String(16)

YES

CNY

comply with ISO 4217, 3 characters, the default is CNY

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

Random string

refund_count

int

YES

Total times of refund for this order.

refund_fee

Int

YES

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

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

refer to following relevant chapter for signature algorithm

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

Rate Query

API method

URL

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

Method

POST

Parameter organization format

application/x-www-form-urlencoded

Rate_Query Request Parameters

Parameter Type Required Example Description

sign

String(256)

YES

refer to relevant chapter Signature Algorithm

appid

String(32)

YES

assigned by Ksher

nonce_str

String(32)

YES

Random string

channel

String(32)

YES

wechat

Value range: wechat

fee_type

String(16)

YES

THB

comply with ISO 4217, 3 characters, the default is CNY, refer to Appendix2 for its value range

date

String(16)

YES

2019-04-27

The format is yyyy-MM-dd, as indicated on April 27, 2019 as 2019-04-27. Time zone is GMT+8 beijing

time_stamp

String(32)

OPTINAL
Example 13. Request Example
{
    "appid": "mch20163",
    "channel": "wechat",
    "nonce_str": "ogWfy5jDlujCyhJCKNjYQVlrSGkdj9LO",
    "fee_type": "THB",
    "date": "2019-04-27",
    "sign": "68ba48d72206a1561f6322800db9d8dabe4d1e0e1965fd31e5e10e034d2b9123291d6c596ac2b271292545275cc8bf4689ec8cdca581ff17c4ea1f3efd8e321a",
    "time_stamp": "20170516125822",
    "version": "3.0.0"
}

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

status_code

reserved for future use

status_msg

String(32)

YES

reserved for future use

sign

String(256)

YES

refer to following relevant chapter for signature algorithm

version

version of the API

msg

time_stamp

String(32)

YES

2020042015374848S

the time stamp of request order

data Parameters (JSON )

rate

string(16)

YES

exchange rate of foreign currency to RMB.

nonce_str

String(32)

YES

Random string

result

string(16)

YES

SUCCESS

fee_type

String(16)

YES

THB

comply with ISO 4217, 3 characters
Example 14. SUCCESS Response Example
{
    "code": 0,
    "status_code": "",
    "status_msg": "",
    "sign": "5f58aa1c15faa29a66ae994b81ec09b0731e041f83f1e9e7e1ca4ef704d365e82e46515652b8e29f46430bed697e3a241487fedd7d507abf201034a9482bf73b",
    "version": "3.0.0",
    "msg": "ok",
    "time_stamp": "",
    "data": {
        "rate": "0.21193417",
        "nonce_str": "4UPerCQYBQXNDFxiYDpuLnez4Q1puLDO",
        "result": "SUCCESS",
        "fee_type": "THB"
    }
}

Rate_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 following relevant chapter for signature algorithm

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 15. FAIL Response Example
{
    "code": 0,
    "version": "3.0.0",
    "status_code": "",
    "msg": "ok",
    "time_stamp": "",
    "status_msg": "",
    "data": {
        "nonce_str": "PMlMGZ4RxvZzbwTh6mOriMrHgtxr0fWU",
        "err_msg": "merchant not exist.",
        "result": "FAIL",
        "err_code": "KSHER_INVALID_MCHINFO"
    },
    "sign": "5f58aa1c15faa29a66ae994b81ec09b0731e041f83f1e9e7e1ca4ef704d365e82e46515652b8e29f46430bed697e3a241487fedd7d507abf201034a9482bf73b4"
}

Merchant Info

API method

URL

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

Method

POST

Parameter organization format

application/x-www-form-urlencoded

Get_merchant_info Request Parameters

Parameter Type Required Example Description

sign

String(256)

YES

refer to following relevant chapter for signature algorithm, Fields required for signature 'mch_appid', 'nonce_str', 'time_stamp'

mch_appid

String(32)

YES

assigned by Ksher

nonce_str

String(32)

YES

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

time_stamp

String(256)

NO

time stamp example: "time_stamp": "20190622131804"
Example 16. Request Example
{
    "appid": "mch201630",
    "nonce_str": "a3ysjwp5Z9xxuNe4eIAKDlR2up4CH1qG",
    "sign": "96e485cdf592f3da7835883b60a52b9181369dad4f3c6790f7df558b2c79c7371338bcf62f24fc77170f5c02b4d235768596874bb8a12874032ed4a4e2da9d99",
    "time_stamp": "20200828143436",
}

Get_merchant_info 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 parameters to launch the request again.

sign

String(256)

YES

refer to following relevant chapter for signature algorithm, Fields required for signature "mobile", "mch_id", "account_type", "business_mode", "nonce_str"

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

JSON

data Parameters (JSON )

mch_appid

String(32)

YES

assigned by Ksher

nonce_str

String(32)

YES

Random string

country_support_channel

list

YES

"airpay", "alipay", "bbl_promptpay", "ktbcard", "linepay", "truemoney", "wechat"

Channels of state support,["airpay", "alipay", "bbl_promptpay", "ktbcard", "linepay", "truemoney", "wechat"],

business_mode

String(32)

YES

online

online or offline

mch_support_channel

JSON

YES

details

mch_support_channel Parameters (JSON )

day_sum_limit

Int

YES

-1

Limit of the day - 1 means no limit, others indicate limit amount

pay_channel

String(32)

YES

wechat

channel: wechat/alipay/linepay/airpay/bbl_promptpay/truemoney

settlement_time_type

String(32)

YES

T+1

Settlement group: T+1/T+2

single_order_limit

Int

YES

-1

Single limit, - 1 means no limit

mch_id

String(32)

YES

28811

assigned by Ksher

allow_remote_pay

String(32)

Y

Whether to support remote collection Y support N not support

allow_partial_refund

String(32)

N

Whether to support partial refund Y support N not support

master_mch_id

String()

bank_info Parameters (JSON )

swift_code

string

YES

Global bank code of the account bank

account_name

string

YES

Bank account name

bank_name

string

YES

Bank of deposit

account_id

string

YES

Bank account

logo_url

string

YES

Business logo

account_type

string

YES

Formal

Formal merchant or test merchant

country_info Parameters (JSON )

country_name

string

YES

Name of country

phone_code

string

YES

country code

mch_notify_url

string(256)

YES

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.

is_master_mch

string(32)

YES

N

Is it the parent merchant

scan_type

int

2

wht

int

0

ith holding tax calculate

bd_info Parameters (JSON )

mobile

string

YES

tel of bd

bd_name

string

YES

name of bd

country_id

int

YES

country id

bd_id

string

YES

id of bd

add_time

String(16)

YES

add time

has_open_use_coupon

string

YES

N

Whether or not to open coupon write off

price_fee_type

String(16)

YES

THB

Currency of bid price

rigist_time

String(16)

YES

2020-04-01 17:54:14

rigist_time

settlement_fee_type

String(16)

YES

THB

Currency of settlement

agency_info Parameters (JSON )

mobile

string

YES

tel of agency

agency_name

string

YES

name of agency

email

string

YES

email of agency

agency_id

string

YES

id of agency

rigist_time

String(16)

YES

2020-04-01 17:54:14

rigist time

mobile

string

YES

Merchant’s mobile phone number

time_zone

string

YES

+07:00

time zone

mch_name Parameters (JSON )

mch_brief_name

string

YES

Merchant abbreviation

merchant_name

string

YES

Merchant name

contact

string

YES

Merchant contact name

operator_list Parameters (JSON )

operator_id

string

YES

mch_id

string

YES

assigned by Ksher

state

int

state

operator

string

YES

rule_id

int

0

0 is the boss and 1 is the general cashier

add_time

String(16)

YES

2020-04-01 17:54:14

add time
Example 17. SUCCESS Response Example
{
	"code": 0,
	"status_code": "",
	"status_msg": "",
	"sign": "6d85861b1c69373ab97f1d1a96a1a0495307061759085f13fdcf2d933fe9ed7651e2c33d9923ee252942b83831d521eef11369fe2ae455ef0e11acd40c0473c7",
	"version": "2.0.0",
	"msg": "ok",
	"time_stamp": "2020-09-11T11:07:19.969854+08:00",
	"data": {
		"nonce_str": "V8ULba969xAu07hSkmivC0B67HLXeNEB",
		"country_support_channel": ["airpay", "alipay", "bbl_promptpay", "ktbcard", "linepay", "truemoney", "wechat"],  // 国家支持的通道
		"mch_appid": "mch28811",
		"business_mode": "offline", // 线上online  线下 offline
		"mch_support_channel": [{
			"day_sum_limit": -1,  // 当日限额  -1 表示不限额  其他表示限额金额
			"pay_channel": "alipay",  //通道
			"settlement_time_type": "T+1",  // 结算组
			"single_order_limit": -1  // 单笔限额  -1 表示不限额
		}, {
			"day_sum_limit": -1,
			"pay_channel": "linepay",
			"settlement_time_type": "T+2",
			"single_order_limit": -1
		}, {
			"day_sum_limit": -1,
			"pay_channel": "airpay",
			"settlement_time_type": "T+2",
			"single_order_limit": -1
		}, {
			"day_sum_limit": -1,
			"pay_channel": "wechat",
			"settlement_time_type": "T+1",
			"single_order_limit": -1
		}],
		"mch_id": "28811",
		"allow_remote_pay": "Y",  // 是否支持远程收款  Y支持  N不支持
		"allow_partial_refund": "N",  // 是否支持部分退款 Y支持  N不支持
		"master_mch_id": "",
		"bank_info": {
			"swift_code": "BKKBTHBK",  // 开户行的全球银行编码
			"account_name": "hello word",  // 银行户名
			"bank_name": "004,KASIKORNBANK PUBLIC COMPANY LIMITED",  //开户行
			"account_id": "86656664448"  // 银行账号
		},
		"logo_url": "", // 商户logo
		"account_type": "Formal", // Formal 正式商户  Test 测试商户
		"country_info": {
			"country_name": "Thailand",  // 国家名称
			"phone_code": "+66" // 国家区号
		},
		"mch_notify_url": "",  // 商户通知URL
		"is_master_mch": "N",  // 是否是父商户  Y是  N不是
		"scan_type": "2",
		"wht": 0,  // ith holding tax计算
		"bd_info": {
			"mobile": "13031028803",
			"bd_name": "vicky",
			"country_id": "2",
			"bd_id": "213",
			"add_time": ""
		},
		"has_open_use_coupon": "N",  // 是否开通优惠券核销  Y开通 N不开通
		"price_fee_type": "THB",  // 标价币种
		"rigist_time": "2020-04-01 17:54:14",
		"settlement_fee_type": "THB",  //结算币种
		"agency_info": {
			"mobile": "136101101101",
			"agency_name": "54321@ksher.net",
			"email": "vicky@ksher.net",
			"agency_id": "10119",
			"regist_time": "2019-10-11 10:39:11"
		},
		"mobile": "shhhh123456",  // 商户手机号
		"time_zone": "+07:00",  // 时区
		"mch_name": {
			"mch_brief_name": "uvuvuvt++1",  // 商户简称
			"merchant_name": "vyvycyct++1"  // 商户名称
		},
		"contact": "dhhhshyd",  // 商户联系人名称
		"operator_list": [{
			"operator_id": "13994",
			"mch_id": "28811",
			"state": "1",
			"operator": "dhhhshyd",
			"rule_id": "0",  // 0 表示老板  1 表示普通收银员
			"add_time": "2020-08-13 16:43:54"
		}]
	}
}

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 following relevant chapter for 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

JSON

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 18. Fail Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_PARAM",
        "err_msg": "error param nonce_str.",
        "nonce_str": "",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "248281e98c90131255f97bc06a8ab653d7ff5a1e1bbab7b6329cb1d326b76a41e0a1ab2a0fcfc2dff9264c3fd696c061c6d66bcff83e041dec0e31732f0f6da5",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-07-15T13:24:24.649287+08:00",
    "version": "2.0.0"
}

Get Settlement Info

API method

URL

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

Method

GET

Parameter organization format

application/x-www-form-urlencoded

Get_settlement_info Request Parameters

Parameter Type Required Example Description

mch_appid

String(32)

YES

assigned by Ksher

begin_date

String(16)

YES

2020-09-01

The format is yyyy-MM-dd, as indicated on September 01, 2020 as 2020-09-01. Time zone is GMT+8 beijing

end_date

String(16)

YES

2020-09-01

The format is yyyy-MM-dd, as indicated on September 01, 2020 as 2020-09-01. Time zone is GMT+8 beijing

pay_channel

String(32)

NO

wechat

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

sign

String(256)

YES

refer to relevant chapter Signature Algorithm,Fields required for signature 'mch_appid', 'nonce_str', 'begin_date', 'end_date', 'time_stamp'

nonce_str

String(32)

YES

Random string, must be unique

time_stamp

String(256)

YES

20190622131804

timestamp of the request
Example 19. Request Example
{
    "begin_date": "2020-07-01",
    "end_date": "2020-09-10",
    "mch_appid": "mch28811",
    "nonce_str": "db2e557e303d45576693801bf0f86b75",
    "pay_channel": "wechat",
    "sign": "2967d5a1788a477cc7be98acbbbb0a40ae2ad58be642f8a7e0fc1ffce753d070da0390992c2e655a49d72ba07cbe45ce963a3f608049ce1df3513af93c67a9dead3c977b3c03b2a7306be2c9388a1431bf8e6a574be1faa6b76cfe0ff8ec27821515df3f292de2d2769b995bff372e89438c36db83ddff3c2357810f189869c8",
    "time_stamp": "2020091611083232S"
}

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

status_code

int

YES

reserved for future use

status_msg

String(32)

YES

reserved for future use

sign

String(256)

YES

refer to following relevant chapter for signature algorithm, Fields required for signature "begin_date", "end_date", "nonce_str"``

version

String(32)

YES

3.0.0

version of the API

msg

String(128)

YES

the response message.

time_stamp

String(32)

YES

2020042015374848S

the time stamp of request order

data Parameters (JSON )

begin_date

String(16)

YES

2020-09-01

The format is yyyy-MM-dd, as indicated on September 01, 2020 as 2020-09-01. Time zone is GMT+8 beijing

end_date

String(16)

YES

2020-09-01

The format is yyyy-MM-dd, as indicated on September 01, 2020 as 2020-09-01. Time zone is GMT+8 beijing

nonce_str

String(32)

YES

1At1iDK27LQxVnIvSwzqjlzgEZCsXTsj

Random string

settlement_data Parameters (JSON )

begin_date

String(16)

YES

2020-09-01

The format is yyyy-MM-dd, as indicated on September 01, 2020 as 2020-09-01. Time zone is GMT+8 beijing

commission_fee

int

YES

0

Service charge.

end_date

String(16)

YES

2020-09-01

The format is yyyy-MM-dd, as indicated on September 01, 2020 as 2020-09-01. Time zone is GMT+8 beijing

transfer_amount

Int

YES

0

Transfer amount

pay_channel

String(32)

wechat

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

settlement_amount

Int

YES

0

Settlement amount

settlement_date

String(16)

YES

2020-09-01

Settlement date

transfer_date

String(16)

YES

2020-09-01

Transfer date

vat

String(16)

vat
Example 20. SUCCESS Response Example
 {
    "code": 0,
    "data": {
        "begin_date": "2020-07-01",
        "end_date": "2020-09-10",
        "nonce_str": "1At1iDK27LQxVnIvSwzqjlzgEZCsXTsj",
        "settlement_data": [
            {
                "begin_date": "2020-08-18",
                "commission_fee": 0,
                "end_date": "2020-08-18",
                "pay_channel": "wechat",
                "settlement_amount": 10780,
                "settlement_date": "2020-08-19",
                "transfer_amount": 0,
                "transfer_date": "",
                "vat": 0
            },
            {
                "begin_date": "2020-08-19",
                "commission_fee": 0,
                "end_date": "2020-08-19",
                "pay_channel": "wechat",
                "settlement_amount": 2940,
                "settlement_date": "2020-08-20",
                "transfer_amount": 0,
                "transfer_date": "",
                "vat": 0
            },
            {
                "begin_date": "2020-08-20",
                "commission_fee": -57,
                "end_date": "2020-08-20",
                "pay_channel": "wechat",
                "settlement_amount": -2939,
                "settlement_date": "2020-08-21",
                "transfer_amount": 0,
                "transfer_date": "",
                "vat": -4
            }
        ]
    },
    "msg": "ok",
    "sign": "17b62a22612f5639cfb584c437d7f70d3f9da6e2a0bdcb12334ccda34eb3cde2f7d781b0352474ab689c2d9b16a7aa78bef64afbb85110fd47f468e2be091eab",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-09-16T11:08:31.484616+08:00",
    "version": "2.0.0"
}

Get_settlement_info 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

refer to following relevant chapter for signature algorithm

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

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)

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/td>

XML format error

please check whether the format of XML parameters is correct.