Alipay pre-auth Integration Guide

Overview

Pre-authorization is also well known as authorization hold which is within the banking industry of verifying electronic transactions initiated with the account and rendering this balance as unavailable until the merchant clears the transaction. As the trade initiates, the merchant sends a pre-auth request to Alipay for a certain amount of funds. Successful pre-auth means that the user authorizes the merchant to acquire the funds. At the closure of this trade, the merchant can capture the funds according the actual costs and fees. For example, at a hotel check-in: the merchant requests a pre-auth of a sum basing on the room rate and other costs during a user’s stay. When the user checks out, the merchant then requests the capture according to the actual expenses.

Below are 4 Solutions of Alipay pre-auth Integration : A.Merchant-scan pre-auth (Offline Scenario) B.Customer-scan pre-auth (Online Scenario) C.Website payment pre-auth (Online Scenario) D.App payment pre-auth (Online Scenario)

A.Merchant-scan pre-auth (Offline Scenario)

In this scenario, the user shows their Alipay Payment Code to the store cashier at the beginning of the trade. The cashier scans the code with the scanning tool, together with other required data, the merchant system then sends a pre-auth request to Alipay. Alipay then freezes the specified sum of funds from the user’s funds channel to complete the pre-auth. At the settlement session, the cashier determines the total amount according to the user’s actual spending, and sends request to Alipay to capture the due amount.

Notes: . After the merchant successfully captures the due amount, the remaining funds (if any) are unfrozen automatically. . The actual amount paid by the user for the merchant’s capture request depends on the live exchange rate at the request. If the amount frozen by the pre-auth is insufficient, the capture will fail. As such, it is suggested that in scenarios where there is a long time span between the pre-auth and capture, the pre- auth amount should be higher than the expected transaction amount to avoid capture failure that might occur due to exchange rate fluctuation. Note: Capture failure occurs when the pre-auth is insufficient and no enough funds in all customer funding channels. For example, the frozen amount launched by the pre-auth on Monday is $100, with an exchange rate of 6.3 Chinese Yuan (CNY) to US Dollar (USD). Therefore, the frozen amount of the buyer is 630 CNY. On Wednesday, the exchange rate became 7.3 CNY to USD and a payment of $100 was launched. The amount to be deducted from the frozen amount became 730 CNY, which is more than the frozen amount launched on Monday. Alipay cannot deduct enough amount from the frozen amount, it deducts funds from all the other funding channels of the customer. If funds in all the other funding channels are insufficient, capture failure occurs.

User Experience Scenarios

flow of funds pre auth (freeze)

Payment Flow Sequence Diagram

Specifications of APIs

*Call this interface to create Alipay funds pre-auth order and freeze the funds. Used for barcode payment. *

API method

URL

https://api.mch.pospre.com/KsherPayPreAuth/barcode_freeze

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

auth_code

String(32)

YES

POS001

authorization code, scanned from the barcode or QR code on the wechat interface of consumer

amount

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

channel

String(32)

YES

wechat

Value range: 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

limit_pay

mch_order_no

String(32)

YES

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

mch_request_no

nonce_str

String(32)

YES

Random string

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.

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

pay_timeout

payee_logon_id

payee_user_id

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API

product

String(512)

NO
Example 1. Request Example
{
    "amount": 99000,
    "appid": "mch201630",
    "auth_code": "289735853425973816",
    "channel": "alipay",
    "device_id": "",
    "fee_type": "THB",
    "limit_pay": "",
    "mch_order_no": "1591922956",
    "mch_request_no": "RN1591922956",
    "nonce_str": "lYHuTudsjVTxkkyryAI55l71ohMZcdKt",
    "notify_url": "",
    "operator_id": "",
    "pay_timeout": "",
    "payee_logon_id": "",
    "payee_user_id": "",
    "product": "",
    "sign": "a7c43a10c1c1c6fb53e90b978ce58ade05a03298c76b848314ee136a571f5445c98f4868ade06b5969a62814524d4ba781e5cb1859ef1a208e961e5d6f6746d7",
    "version": "3.0.0"
}

Barcode Freeze 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.
Example 2. SUCCESS Response Example

Barcode Freeze 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.

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 3. FAIL Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "lYHuTudsjVTxkkyryAI55l71ohMZcdKt",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "b3ce97249b72a3e19e36233f98ad768e287590ffcc343473800922f6a2ad683c06e8da58cd912856a19a4728f296bea5393aa8b1971dc4775f5f2241a77ea513",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T08:49:17.745379+08:00",
    "version": "2.0.0"
}

Call this interface to cancel the pre-auth (freezing)

API method

URL

https://api.mch.pospre.com/KsherPayPreAuth/cancel_freeze

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

amount

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

attach

String(127)

NO

any extra information can be added here.

channel

String(32)

YES

wechat

Value range: 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

limit_pay

mch_order_no

String(32)

YES

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

mch_request_no

nonce_str

String(32)

YES

Random string

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.

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API

operation_reason
Example 4. Request Example
{
    "appid": "mch201630",
    "attach": "",
    "auth_no": "2019070310002001000283268102",
    "channel": "alipay",
    "channel_request_no": "",
    "device_id": "",
    "ksher_order_no": "",
    "ksher_request_no": "40020190703162939858914",
    "mch_order_no": "",
    "nonce_str": "ilkBIt5AhWjSnfRPbbhApPNZrBzT9a5w",
    "notify_url": "",
    "operation_reason": "",
    "operator_id": "",
    "sign": "13a0e3d9ec295781a38e8e1a16afa7da2f95e4e86b665a79ca1f82855d603e362b830c3fbfe9fccc49db1ee225a32980c8e0b315b23987240e9bf12f027bc3ec",
    "version": "3.0.0"
}

Cancel Freeze 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.
Example 5. SUCCESS Response Example

Cancel Freeze 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.

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 6. FAIL Response Example
 {
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "ilkBIt5AhWjSnfRPbbhApPNZrBzT9a5w",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "0624599a7da7a4fe787052634d84d99b565fa31b5881809642a0002b2b792f5205e0da423f3b4b4bdbb6b433a1645211bb76b2724df32337ab900df7d2503bd2",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T08:57:20.111084+08:00",
    "version": null
}

To unfreeze full or partial amount of the funds. Within a certain period after the funds pre-auth happens, if the buyer/merchant needs to unfreeze the funds for some reasons, the merchant can call Ksher Unfreeze interface to unfreeze the funds.

API method

URL

https://api.mch.pospre.com/KsherPayPreAuth/unfreeze

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

amount

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

auth_no

operation_reason

attach

String(127)

NO

any extra information can be added here.

channel

String(32)

YES

wechat

Value range: 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

mch_order_no

String(32)

YES

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

mch_request_no

nonce_str

String(32)

YES

Random string

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.

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API
Example 7. Request Example

Unfreeze 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.
Example 8. SUCCESS Response Example

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

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 9. FAIL Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "XG03CI0cCpWIkjaBwBT12hAOMiWx1ACO",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "6087dfcce27c4deae88a9d3e13445d9ea04bda7ef39ff1f8d098f6f5cda944ca16f89b7d590cb7cac4b834946a65f2bc439301566c298b7d69418a432ba7f183",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T07:23:19.288475+08:00",
    "version": "2.0.0"
}

Call this interface to query the detail information of the pre-auth

API method

URL

https://api.mch.pospre.com/KsherPayPreAuth/auth_query

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

auth_no

channel_request_no

ksher_request_no

NO

channel

String(32)

YES

wechat

Value range: alipay

ksher_order_no

String(32)

YES

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API
Example 10. Request Example
{
    "appid": "mch201630",
    "auth_no": "",
    "channel": "alipay",
    "channel_request_no": "",
    "ksher_order_no": "60020190703162939226705",
    "ksher_request_no": "40020190703162939858914",
    "mch_order_no": "",
    "nonce_str": "l1FT0BpBtm3fvtRRhGa601AUvxFLwrAw",
    "sign": "67324141f8554e3d666989309deeb05ed4d71ee91086e1eda79d3b7aae48543a4ff324ba5797c6f4b7345bff09192f27a578dc0218a145115eb9e1fa83654eb4",
    "version": "3.0.0"
}

Auth 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.
Example 11. SUCCESS Response Example

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

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 12. FAIL Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "l1FT0BpBtm3fvtRRhGa601AUvxFLwrAw",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "3ef322ea6282d8754941a4bc998092cd10e69f4c49e52344180e3cf5675a3318d8144cf2b0bbe606998d3800ec5ae5a2b4a94aed54ad451ffd5276f60c6b4510",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T08:16:05.550654+08:00",
    "version": "2.0.0"
}

Call this interface to query the payment transaction status.

API method

URL

https://api.mch.pospre.com/KsherPay/order_query

Method

POST

Parameter organization format

application/x-www-form-urlencoded

Auth Order Query 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}.

channel

String(32)

YES

wechat

Value range: alipay

channel_order_no

String(32)

YES

Order no. Generated by wechat.

ksher_order_no

String(32)

YES

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API

time_stamp

String(256)

YES

time stamp
Example 13. Request Example
 {
    "appid": "mch20795",
    "channel": "alipay",
    "channel_order_no": "",
    "ksher_order_no": "70020190629122845908072",
    "mch_order_no": "",
    "nonce_str": "ElVnMYCL4yiRfB0lruYn98kHSMMIrKXk",
    "sign": "a812d32d90c0297c1043289948d857671477abad2f8436822f0d50f0376110bacb707138e75a07c2d4d0d4de5699f784f339d860671815d2a38fd7c83fd09ec2",
    "time_stamp": "20200612080513",
    "version": "3.0.0"
}

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

SUCCESS Response Example

Response Example(Success)

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

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 14. FAIL Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_ PAYKEY",
        "err_msg": "Invalid paykey  Pls login to merchant platform to reset the payment key",
        "nonce_str": "ElVnMYCL4yiRfB0lruYn98kHSMMIrKXk",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "befc94b24e95d6183b9cc1470f605146322953562ba274fdb1ddc5dc484d14d4737b57505ee5bd77a861b25e66057d3b131267232aa263bd3d314bf49fcf319a",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T08:05:13.969262+08:00",
    "version": "3.0.0"
}

Call this interface to create Alipay payment order and complete the payment with the pre-authed funds.

API method

URL

https://api.mch.pospre.com/KsherPayPreAuth/trade_pay

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

amount

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

attach

String(127)

NO

any extra information can be added here.

channel

String(32)

YES

wechat

Value range: 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)

auth_no

auth_confirm_mode

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)

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.

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

pay_timeout

total_fee

Int

YES

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API
Example 15. Request Example

Trade Pay 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.
Example 16. SUCCESS Response Example

Trade Pay 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.

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 17. FAIL Response Example
 {
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "Wcr6fqjWHYaCDgW67Lrma0obeF5NKX5j",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "4ae397025291e4ec26fc2773c98bba20fdab0cc4851c9eb5cb769f5c0a9feb974f3196e776797b4f5e8e2d365ef92cd8f2c2a18ac5e6caea8f1909aafebbbaf2",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T09:16:57.815506+08:00",
    "version": "2.0.0"
}

Call this interface to perform full or partial refunding

API method

URL

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

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

fee_type

String(16)

YES

THB

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

THB: Thailand

mch_refund_no

String(32)

YES

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

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

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

ksher_request_no

channel

String(32)

YES

wechat

Value range: alipay

ksher_order_no

String(32)

YES

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API

time_stamp

String(32)

YES

time stamp

total_fee

Int

YES

total amount of the order and it must be an integer, the unit is cent
Example 18. Request Example
 {
    "appid": "mch201630",
    "channel": "alipay",
    "channel_order_no": "",
    "fee_type": "THB",
    "ksher_order_no": "70020190629145145953847",
    "mch_order_no": "",
    "mch_refund_no": "refund1591921587",
    "nonce_str": "x2FyI0HjlO1LwQXfW7ReNTGnA8yZskVd",
    "operator_id": "",
    "refund_fee": 5000,
    "sign": "4045240ff27282f5e0483ec8dc94b8316b7b6cebbc55df2509e821db08ba695cf1d1f38eacbc622f1c4a9443721975f8895ed8fa75321b1a4bd21fce6286de67",
    "time_stamp": "20200612082627",
    "total_fee": 5000,
    "version": "3.0.0"
}

Auth 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.
Example 19. SUCCESS Response Example

Auth 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 parameters 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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 20. FAIL Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "x2FyI0HjlO1LwQXfW7ReNTGnA8yZskVd",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "19c4a126fdf87a2cfcae6f39e97be4848e6cd04a76dde29beda724bc4d9dd86b54342a44f501ead0deb65e791e983b8b90347dbf3548971d8d87e233d3f77e7f",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T08:26:28.538731+08:00",
    "version": "2.0.0"
}

B.Customer-scan pre-auth (Online Scenario)

In this scenario, the merchant calls the related API to generate a QR code of pre-auth transaction for users to scan. Users, after scanning the code with their Alipay app, type in their payment password to confirm the pre-auth.

User Experience Scenarios

Customer scan pre auth

Payment Flow Sequence Diagram

Specifications of APIs

Call this interface to create QR code. The QR code is presented for the user to scan and confirm the pre-auth order to freeze the funds.Used for C-scan-B payment and website payment.

API method

URL

https://api.mch.pospre.com/KsherPayPreAuth/qrcode_freeze

Method

POST

Parameter organization format

application/x-www-form-urlencoded

QR Code Freeze 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}.

amount

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

attach

String(127)

NO

any extra information can be added here.

channel

String(32)

YES

wechat

Value range: 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

limit_pay

NO

mch_order_no

String(32)

YES

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

mch_request_no

String(32)

YES

nonce_str

String(32)

YES

Random string

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.

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

pay_timeout

NO

payee_logon_id

NO

payee_user_id

NO

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
Example 21. Request Example
 {
    "amount": 9900,
    "appid": "mch28018",
    "attach": "",
    "channel": "alipay",
    "device_id": "",
    "fee_type": "MYR",
    "limit_pay": "",
    "mch_order_no": "1591923735",
    "mch_request_no": "1591923735",
    "nonce_str": "2hjB3sChQyWzwV2EqT80zWlvf5E20EPl",
    "notify_url": "",
    "operator_id": "",
    "pay_timeout": "",
    "payee_logon_id": "",
    "payee_user_id": "",
    "sign": "2f6e6167e50d183ab9f1c2c2469bb45532fde33d6ab13b3d2328cbbcf8e18a04f0c6401b41a338b98d3e9344e384812569829d145653913fccc44a10f5d753c8",
    "version": "3.0.0"
}

QR Code Freeze 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.
Example 22. SUCCESS Response Example

QR Code Freeze 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.

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 23. FAIL Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_PAYKEY",
        "err_msg": "Invalid paykey  Pls login to merchant platform to reset the payment key",
        "nonce_str": "2hjB3sChQyWzwV2EqT80zWlvf5E20EPl",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "aad1dfe6dde3e47f8f1160ecba1c8ea1b6d556564cf58c687e097ac6429195fb4033c4e5b1c78ba63abbab5871cf855b5849e914bdcd1d6d669633646c249b32",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T09:02:15.765734+08:00",
    "version": "3.0.0"
}

Call this interface to cancel the pre-auth (freezing)

API method

URL

https://api.mch.pospre.com/KsherPayPreAuth/cancel_freeze

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

amount

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

attach

String(127)

NO

any extra information can be added here.

channel

String(32)

YES

wechat

Value range: 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

limit_pay

mch_order_no

String(32)

YES

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

mch_request_no

nonce_str

String(32)

YES

Random string

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.

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API

operation_reason
Example 24. Request Example
{
    "appid": "mch201630",
    "attach": "",
    "auth_no": "2019070310002001000283268102",
    "channel": "alipay",
    "channel_request_no": "",
    "device_id": "",
    "ksher_order_no": "",
    "ksher_request_no": "40020190703162939858914",
    "mch_order_no": "",
    "nonce_str": "ilkBIt5AhWjSnfRPbbhApPNZrBzT9a5w",
    "notify_url": "",
    "operation_reason": "",
    "operator_id": "",
    "sign": "13a0e3d9ec295781a38e8e1a16afa7da2f95e4e86b665a79ca1f82855d603e362b830c3fbfe9fccc49db1ee225a32980c8e0b315b23987240e9bf12f027bc3ec",
    "version": "3.0.0"
}

Cancel Freeze 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.
Example 25. SUCCESS Response Example

Cancel Freeze 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.

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 26. FAIL Response Example
 {
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "ilkBIt5AhWjSnfRPbbhApPNZrBzT9a5w",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "0624599a7da7a4fe787052634d84d99b565fa31b5881809642a0002b2b792f5205e0da423f3b4b4bdbb6b433a1645211bb76b2724df32337ab900df7d2503bd2",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T08:57:20.111084+08:00",
    "version": null
}

To unfreeze full or partial amount of the funds. Within a certain period after the funds pre-auth happens, if the buyer/merchant needs to unfreeze the funds for some reasons, the merchant can call Ksher Unfreeze interface to unfreeze the funds.

API method

URL

https://api.mch.pospre.com/KsherPayPreAuth/unfreeze

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

amount

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

auth_no

operation_reason

attach

String(127)

NO

any extra information can be added here.

channel

String(32)

YES

wechat

Value range: 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

mch_order_no

String(32)

YES

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

mch_request_no

nonce_str

String(32)

YES

Random string

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.

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API
Example 27. Request Example

Unfreeze 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.
Example 28. SUCCESS Response Example

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

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 29. FAIL Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "XG03CI0cCpWIkjaBwBT12hAOMiWx1ACO",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "6087dfcce27c4deae88a9d3e13445d9ea04bda7ef39ff1f8d098f6f5cda944ca16f89b7d590cb7cac4b834946a65f2bc439301566c298b7d69418a432ba7f183",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T07:23:19.288475+08:00",
    "version": "2.0.0"
}

Call this interface to query the detail information of the pre-auth

API method

URL

https://api.mch.pospre.com/KsherPayPreAuth/auth_query

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

auth_no

channel_request_no

ksher_request_no

NO

channel

String(32)

YES

wechat

Value range: alipay

ksher_order_no

String(32)

YES

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API
Example 30. Request Example
{
    "appid": "mch201630",
    "auth_no": "",
    "channel": "alipay",
    "channel_request_no": "",
    "ksher_order_no": "60020190703162939226705",
    "ksher_request_no": "40020190703162939858914",
    "mch_order_no": "",
    "nonce_str": "l1FT0BpBtm3fvtRRhGa601AUvxFLwrAw",
    "sign": "67324141f8554e3d666989309deeb05ed4d71ee91086e1eda79d3b7aae48543a4ff324ba5797c6f4b7345bff09192f27a578dc0218a145115eb9e1fa83654eb4",
    "version": "3.0.0"
}

Auth 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.
Example 31. SUCCESS Response Example

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

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 32. FAIL Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "l1FT0BpBtm3fvtRRhGa601AUvxFLwrAw",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "3ef322ea6282d8754941a4bc998092cd10e69f4c49e52344180e3cf5675a3318d8144cf2b0bbe606998d3800ec5ae5a2b4a94aed54ad451ffd5276f60c6b4510",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T08:16:05.550654+08:00",
    "version": "2.0.0"
}

Call this interface to create Alipay payment order and complete the payment with the pre-authed funds.

API method

URL

https://api.mch.pospre.com/KsherPayPreAuth/trade_pay

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

amount

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

attach

String(127)

NO

any extra information can be added here.

channel

String(32)

YES

wechat

Value range: 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)

auth_no

auth_confirm_mode

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)

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.

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

pay_timeout

total_fee

Int

YES

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API
Example 33. Request Example

Trade Pay 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.
Example 34. SUCCESS Response Example

Trade Pay 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.

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 35. FAIL Response Example
 {
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "Wcr6fqjWHYaCDgW67Lrma0obeF5NKX5j",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "4ae397025291e4ec26fc2773c98bba20fdab0cc4851c9eb5cb769f5c0a9feb974f3196e776797b4f5e8e2d365ef92cd8f2c2a18ac5e6caea8f1909aafebbbaf2",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T09:16:57.815506+08:00",
    "version": "2.0.0"
}

Call this interface to perform full or partial refunding

API method

URL

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

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

fee_type

String(16)

YES

THB

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

THB: Thailand

mch_refund_no

String(32)

YES

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

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

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

ksher_request_no

channel

String(32)

YES

wechat

Value range: alipay

ksher_order_no

String(32)

YES

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API

time_stamp

String(32)

YES

time stamp

total_fee

Int

YES

total amount of the order and it must be an integer, the unit is cent
Example 36. Request Example
 {
    "appid": "mch201630",
    "channel": "alipay",
    "channel_order_no": "",
    "fee_type": "THB",
    "ksher_order_no": "70020190629145145953847",
    "mch_order_no": "",
    "mch_refund_no": "refund1591921587",
    "nonce_str": "x2FyI0HjlO1LwQXfW7ReNTGnA8yZskVd",
    "operator_id": "",
    "refund_fee": 5000,
    "sign": "4045240ff27282f5e0483ec8dc94b8316b7b6cebbc55df2509e821db08ba695cf1d1f38eacbc622f1c4a9443721975f8895ed8fa75321b1a4bd21fce6286de67",
    "time_stamp": "20200612082627",
    "total_fee": 5000,
    "version": "3.0.0"
}

Auth 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.
Example 37. SUCCESS Response Example

Auth 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 parameters 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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 38. FAIL Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "x2FyI0HjlO1LwQXfW7ReNTGnA8yZskVd",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "19c4a126fdf87a2cfcae6f39e97be4848e6cd04a76dde29beda724bc4d9dd86b54342a44f501ead0deb65e791e983b8b90347dbf3548971d8d87e233d3f77e7f",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T08:26:28.538731+08:00",
    "version": "2.0.0"
}

Call this interface to query the payment transaction status.

API method

URL

https://api.mch.pospre.com/KsherPay/order_query

Method

POST

Parameter organization format

application/x-www-form-urlencoded

Auth Order Query 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}.

channel

String(32)

YES

wechat

Value range: alipay

channel_order_no

String(32)

YES

Order no. Generated by wechat.

ksher_order_no

String(32)

YES

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API

time_stamp

String(256)

YES

time stamp
Example 39. Request Example
 {
    "appid": "mch20795",
    "channel": "alipay",
    "channel_order_no": "",
    "ksher_order_no": "70020190629122845908072",
    "mch_order_no": "",
    "nonce_str": "ElVnMYCL4yiRfB0lruYn98kHSMMIrKXk",
    "sign": "a812d32d90c0297c1043289948d857671477abad2f8436822f0d50f0376110bacb707138e75a07c2d4d0d4de5699f784f339d860671815d2a38fd7c83fd09ec2",
    "time_stamp": "20200612080513",
    "version": "3.0.0"
}

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

SUCCESS Response Example

Response Example(Success)

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

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 40. FAIL Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_ PAYKEY",
        "err_msg": "Invalid paykey  Pls login to merchant platform to reset the payment key",
        "nonce_str": "ElVnMYCL4yiRfB0lruYn98kHSMMIrKXk",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "befc94b24e95d6183b9cc1470f605146322953562ba274fdb1ddc5dc484d14d4737b57505ee5bd77a861b25e66057d3b131267232aa263bd3d314bf49fcf319a",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T08:05:13.969262+08:00",
    "version": "3.0.0"
}

C.Website payment pre-auth (Online Scenario)

In this scenario, Alipay APIs can be integrated to e-commerce websites of the merchant. The merchant can call the related API to generate a QR code of pre-auth transaction for users to scan. Users, after scanning the code with their Alipay app, type in their payment password to confirm the pre-auth.

User Experience Scenarios

pre auth Website payment

Payment Flow Sequence Diagram

Specifications of APIs

Call this interface to create QR code. The QR code is presented for the user to scan and confirm the pre-auth order to freeze the funds.Used for C-scan-B payment and website payment.

API method

URL

https://api.mch.pospre.com/KsherPayPreAuth/qrcode_freeze

Method

POST

Parameter organization format

application/x-www-form-urlencoded

QR Code Freeze 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}.

amount

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

attach

String(127)

NO

any extra information can be added here.

channel

String(32)

YES

wechat

Value range: 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

limit_pay

NO

mch_order_no

String(32)

YES

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

mch_request_no

String(32)

YES

nonce_str

String(32)

YES

Random string

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.

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

pay_timeout

NO

payee_logon_id

NO

payee_user_id

NO

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
Example 41. Request Example
 {
    "amount": 9900,
    "appid": "mch28018",
    "attach": "",
    "channel": "alipay",
    "device_id": "",
    "fee_type": "MYR",
    "limit_pay": "",
    "mch_order_no": "1591923735",
    "mch_request_no": "1591923735",
    "nonce_str": "2hjB3sChQyWzwV2EqT80zWlvf5E20EPl",
    "notify_url": "",
    "operator_id": "",
    "pay_timeout": "",
    "payee_logon_id": "",
    "payee_user_id": "",
    "sign": "2f6e6167e50d183ab9f1c2c2469bb45532fde33d6ab13b3d2328cbbcf8e18a04f0c6401b41a338b98d3e9344e384812569829d145653913fccc44a10f5d753c8",
    "version": "3.0.0"
}

QR Code Freeze 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.
Example 42. SUCCESS Response Example

QR Code Freeze 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.

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 43. FAIL Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_PAYKEY",
        "err_msg": "Invalid paykey  Pls login to merchant platform to reset the payment key",
        "nonce_str": "2hjB3sChQyWzwV2EqT80zWlvf5E20EPl",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "aad1dfe6dde3e47f8f1160ecba1c8ea1b6d556564cf58c687e097ac6429195fb4033c4e5b1c78ba63abbab5871cf855b5849e914bdcd1d6d669633646c249b32",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T09:02:15.765734+08:00",
    "version": "3.0.0"
}

Call this interface to cancel the pre-auth (freezing)

API method

URL

https://api.mch.pospre.com/KsherPayPreAuth/cancel_freeze

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

amount

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

attach

String(127)

NO

any extra information can be added here.

channel

String(32)

YES

wechat

Value range: 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

limit_pay

mch_order_no

String(32)

YES

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

mch_request_no

nonce_str

String(32)

YES

Random string

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.

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API

operation_reason
Example 44. Request Example
{
    "appid": "mch201630",
    "attach": "",
    "auth_no": "2019070310002001000283268102",
    "channel": "alipay",
    "channel_request_no": "",
    "device_id": "",
    "ksher_order_no": "",
    "ksher_request_no": "40020190703162939858914",
    "mch_order_no": "",
    "nonce_str": "ilkBIt5AhWjSnfRPbbhApPNZrBzT9a5w",
    "notify_url": "",
    "operation_reason": "",
    "operator_id": "",
    "sign": "13a0e3d9ec295781a38e8e1a16afa7da2f95e4e86b665a79ca1f82855d603e362b830c3fbfe9fccc49db1ee225a32980c8e0b315b23987240e9bf12f027bc3ec",
    "version": "3.0.0"
}

Cancel Freeze 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.
Example 45. SUCCESS Response Example

Cancel Freeze 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.

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 46. FAIL Response Example
 {
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "ilkBIt5AhWjSnfRPbbhApPNZrBzT9a5w",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "0624599a7da7a4fe787052634d84d99b565fa31b5881809642a0002b2b792f5205e0da423f3b4b4bdbb6b433a1645211bb76b2724df32337ab900df7d2503bd2",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T08:57:20.111084+08:00",
    "version": null
}

To unfreeze full or partial amount of the funds. Within a certain period after the funds pre-auth happens, if the buyer/merchant needs to unfreeze the funds for some reasons, the merchant can call Ksher Unfreeze interface to unfreeze the funds.

API method

URL

https://api.mch.pospre.com/KsherPayPreAuth/unfreeze

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

amount

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

auth_no

operation_reason

attach

String(127)

NO

any extra information can be added here.

channel

String(32)

YES

wechat

Value range: 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

mch_order_no

String(32)

YES

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

mch_request_no

nonce_str

String(32)

YES

Random string

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.

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API
Example 47. Request Example

Unfreeze 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.
Example 48. SUCCESS Response Example

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

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 49. FAIL Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "XG03CI0cCpWIkjaBwBT12hAOMiWx1ACO",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "6087dfcce27c4deae88a9d3e13445d9ea04bda7ef39ff1f8d098f6f5cda944ca16f89b7d590cb7cac4b834946a65f2bc439301566c298b7d69418a432ba7f183",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T07:23:19.288475+08:00",
    "version": "2.0.0"
}

Call this interface to query the detail information of the pre-auth

API method

URL

https://api.mch.pospre.com/KsherPayPreAuth/auth_query

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

auth_no

channel_request_no

ksher_request_no

NO

channel

String(32)

YES

wechat

Value range: alipay

ksher_order_no

String(32)

YES

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API
Example 50. Request Example
{
    "appid": "mch201630",
    "auth_no": "",
    "channel": "alipay",
    "channel_request_no": "",
    "ksher_order_no": "60020190703162939226705",
    "ksher_request_no": "40020190703162939858914",
    "mch_order_no": "",
    "nonce_str": "l1FT0BpBtm3fvtRRhGa601AUvxFLwrAw",
    "sign": "67324141f8554e3d666989309deeb05ed4d71ee91086e1eda79d3b7aae48543a4ff324ba5797c6f4b7345bff09192f27a578dc0218a145115eb9e1fa83654eb4",
    "version": "3.0.0"
}

Auth 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.
Example 51. SUCCESS Response Example

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

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 52. FAIL Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "l1FT0BpBtm3fvtRRhGa601AUvxFLwrAw",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "3ef322ea6282d8754941a4bc998092cd10e69f4c49e52344180e3cf5675a3318d8144cf2b0bbe606998d3800ec5ae5a2b4a94aed54ad451ffd5276f60c6b4510",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T08:16:05.550654+08:00",
    "version": "2.0.0"
}

Call this interface to create Alipay payment order and complete the payment with the pre-authed funds.

API method

URL

https://api.mch.pospre.com/KsherPayPreAuth/trade_pay

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

amount

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

attach

String(127)

NO

any extra information can be added here.

channel

String(32)

YES

wechat

Value range: 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)

auth_no

auth_confirm_mode

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)

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.

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

pay_timeout

total_fee

Int

YES

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API
Example 53. Request Example

Trade Pay 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.
Example 54. SUCCESS Response Example

Trade Pay 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.

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 55. FAIL Response Example
 {
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "Wcr6fqjWHYaCDgW67Lrma0obeF5NKX5j",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "4ae397025291e4ec26fc2773c98bba20fdab0cc4851c9eb5cb769f5c0a9feb974f3196e776797b4f5e8e2d365ef92cd8f2c2a18ac5e6caea8f1909aafebbbaf2",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T09:16:57.815506+08:00",
    "version": "2.0.0"
}

Call this interface to perform full or partial refunding

API method

URL

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

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

fee_type

String(16)

YES

THB

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

THB: Thailand

mch_refund_no

String(32)

YES

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

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

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

ksher_request_no

channel

String(32)

YES

wechat

Value range: alipay

ksher_order_no

String(32)

YES

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API

time_stamp

String(32)

YES

time stamp

total_fee

Int

YES

total amount of the order and it must be an integer, the unit is cent
Example 56. Request Example
 {
    "appid": "mch201630",
    "channel": "alipay",
    "channel_order_no": "",
    "fee_type": "THB",
    "ksher_order_no": "70020190629145145953847",
    "mch_order_no": "",
    "mch_refund_no": "refund1591921587",
    "nonce_str": "x2FyI0HjlO1LwQXfW7ReNTGnA8yZskVd",
    "operator_id": "",
    "refund_fee": 5000,
    "sign": "4045240ff27282f5e0483ec8dc94b8316b7b6cebbc55df2509e821db08ba695cf1d1f38eacbc622f1c4a9443721975f8895ed8fa75321b1a4bd21fce6286de67",
    "time_stamp": "20200612082627",
    "total_fee": 5000,
    "version": "3.0.0"
}

Auth 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.
Example 57. SUCCESS Response Example

Auth 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 parameters 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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 58. FAIL Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "x2FyI0HjlO1LwQXfW7ReNTGnA8yZskVd",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "19c4a126fdf87a2cfcae6f39e97be4848e6cd04a76dde29beda724bc4d9dd86b54342a44f501ead0deb65e791e983b8b90347dbf3548971d8d87e233d3f77e7f",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T08:26:28.538731+08:00",
    "version": "2.0.0"
}

Call this interface to query the payment transaction status.

API method

URL

https://api.mch.pospre.com/KsherPay/order_query

Method

POST

Parameter organization format

application/x-www-form-urlencoded

Auth Order Query 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}.

channel

String(32)

YES

wechat

Value range: alipay

channel_order_no

String(32)

YES

Order no. Generated by wechat.

ksher_order_no

String(32)

YES

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API

time_stamp

String(256)

YES

time stamp
Example 59. Request Example
 {
    "appid": "mch20795",
    "channel": "alipay",
    "channel_order_no": "",
    "ksher_order_no": "70020190629122845908072",
    "mch_order_no": "",
    "nonce_str": "ElVnMYCL4yiRfB0lruYn98kHSMMIrKXk",
    "sign": "a812d32d90c0297c1043289948d857671477abad2f8436822f0d50f0376110bacb707138e75a07c2d4d0d4de5699f784f339d860671815d2a38fd7c83fd09ec2",
    "time_stamp": "20200612080513",
    "version": "3.0.0"
}

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

SUCCESS Response Example

Response Example(Success)

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

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 60. FAIL Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_ PAYKEY",
        "err_msg": "Invalid paykey  Pls login to merchant platform to reset the payment key",
        "nonce_str": "ElVnMYCL4yiRfB0lruYn98kHSMMIrKXk",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "befc94b24e95d6183b9cc1470f605146322953562ba274fdb1ddc5dc484d14d4737b57505ee5bd77a861b25e66057d3b131267232aa263bd3d314bf49fcf319a",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T08:05:13.969262+08:00",
    "version": "3.0.0"
}

D.App payment pre-auth (Online Scenario)

After selecting the goods in the merchant app, users can choose Alipay to pay by evoking Alipay app and confirming the payment in the Alipay wallet.

User Experience Scenarios

pre auth App payment

Payment Flow Sequence Diagram

Specifications of APIs

Call this interface to create Alipay funds pre-auth order and freeze the funds, used for app payment and Alipay mini program.

API method

URL

https://api.mch.pospre.com/KsherPayPreAuth/app_freeze

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

amount

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

attach

String(127)

NO

any extra information can be added here.

channel

String(32)

YES

wechat

Value range: 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

limit_pay

NO

mch_order_no

String(32)

YES

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

mch_request_no

NO

nonce_str

String(32)

YES

Random string

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.

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

pay_timeout

NO

payee_logon_id

NO

payee_user_id

NO

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
Example 61. Request Example

App Freeze 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.
Example 62. SUCCESS Response Example
{
    "code": 0,
    "data": {
        "amount": 100,
        "appid": "mch20163",
        "attach": "",
        "channel": "alipay",
        "device_id": "",
        "fee_type": "THB",
        "ksher_order_no": "90020240911194229201239",
        "ksher_request_no": "80020240911194229117651",
        "mch_order_no": "1726054949",
        "mch_request_no": "1726054949",
        "nonce_str": "364ba3a7fd9b65c317653b838738d34c",
        "operator_id": "1144",
        "order_str": "app_id=2019061365568092&biz_content={\"amount\":1.0,\"enable_pay_channels\":[{\"payChannelType\":\"PCREDIT_PAY\"},{\"payChannelType\":\"MONEY_FUND\"},{\"payChannelType\":\"CREDITZHIMA\"}],\"extra_param\":{\"category\":\"HOTEL\",\"outStoreCode\":\"1001\"},\"order_title\":\"WEST\\u00a0FIELD\",\"out_order_no\":\"90020240911194229201239\",\"out_request_no\":\"80020240911194229117651\",\"pay_timeout\":\"15m\",\"payee_user_id\":\"2088331936182062\",\"product_code\":\"OVERSEAS_INSTORE_AUTH\",\"scene_code\":\"OVERSEAS_ONLINE_AUTH_COMMON_SCENE\",\"settle_currency\":\"THB\",\"trans_currency\":\"THB\"}&charset=utf-8&method=alipay.fund.auth.order.app.freeze&notify_url=http://api.mch.pospre.com/KsherPayPreAuth/alipay_notify&sign=VrZZOChUFvvLriZljpKlzND6/rZzst29MiJnqu5FRNYJ8GyUc/TEkP+jPJN7/VB1kZhWqfBtcgxTr2rd5q16gj/XV3sFRinvhzzEae9JDeuUUnlGS0xlZA7pUSMDR5dQKUKjs6jOf0ovOhuhFCkOCynP7V/3iE9beEapVfzQSdUwKd983vQrdyAze1gye0GuaxFcTIG2kcPcgxLfJ/e1XbA2Y1+Q5sb3arPpnp4Nd/33bw10VnP8A8O6UKBoLJlA98qBhTAcY/z7M1sf3utuseUwK0PYEEvrZJhoiqcJJMyO2sNAxhMwxRpXiV0vI+IhoiKWIQ/DGCfJqKRNC0M6Yw==&sign_type=RSA2&timestamp=2024-09-11 18:42:29&version=1.0",
        "result": "SUCCESS"
    },
    "msg": "ok",
    "sign": "5e1843bca15ea58d81d1ca85aca050721bc01e50dada01de41f4a13baffcb3de44e4e2319604ad061881c884d128163ec72e5d62edc452703c038abee4b61e90",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2024-09-11T19:42:29.578865+08:00",
    "version": "3.0.0"
}

App Freeze 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.

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

String

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.

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 63. FAIL Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "XG03CI0cCpWIkjaBwBT12hAOMiWx1ACO",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "6087dfcce27c4deae88a9d3e13445d9ea04bda7ef39ff1f8d098f6f5cda944ca16f89b7d590cb7cac4b834946a65f2bc439301566c298b7d69418a432ba7f183",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T07:23:19.288475+08:00",
    "version": "2.0.0"
}

Call this interface to cancel the pre-auth (freezing)

API method

URL

https://api.mch.pospre.com/KsherPayPreAuth/cancel_freeze

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

amount

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

attach

String(127)

NO

any extra information can be added here.

channel

String(32)

YES

wechat

Value range: 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

limit_pay

mch_order_no

String(32)

YES

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

mch_request_no

nonce_str

String(32)

YES

Random string

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.

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API

operation_reason
Example 64. Request Example
{
    "appid": "mch201630",
    "attach": "",
    "auth_no": "2019070310002001000283268102",
    "channel": "alipay",
    "channel_request_no": "",
    "device_id": "",
    "ksher_order_no": "",
    "ksher_request_no": "40020190703162939858914",
    "mch_order_no": "",
    "nonce_str": "ilkBIt5AhWjSnfRPbbhApPNZrBzT9a5w",
    "notify_url": "",
    "operation_reason": "",
    "operator_id": "",
    "sign": "13a0e3d9ec295781a38e8e1a16afa7da2f95e4e86b665a79ca1f82855d603e362b830c3fbfe9fccc49db1ee225a32980c8e0b315b23987240e9bf12f027bc3ec",
    "version": "3.0.0"
}

Cancel Freeze 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.
Example 65. SUCCESS Response Example

Cancel Freeze 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.

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 66. FAIL Response Example
 {
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "ilkBIt5AhWjSnfRPbbhApPNZrBzT9a5w",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "0624599a7da7a4fe787052634d84d99b565fa31b5881809642a0002b2b792f5205e0da423f3b4b4bdbb6b433a1645211bb76b2724df32337ab900df7d2503bd2",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T08:57:20.111084+08:00",
    "version": null
}

To unfreeze full or partial amount of the funds. Within a certain period after the funds pre-auth happens, if the buyer/merchant needs to unfreeze the funds for some reasons, the merchant can call Ksher Unfreeze interface to unfreeze the funds.

API method

URL

https://api.mch.pospre.com/KsherPayPreAuth/unfreeze

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

amount

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

auth_no

operation_reason

attach

String(127)

NO

any extra information can be added here.

channel

String(32)

YES

wechat

Value range: 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

mch_order_no

String(32)

YES

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

mch_request_no

nonce_str

String(32)

YES

Random string

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.

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API
Example 67. Request Example

Unfreeze 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.
Example 68. SUCCESS Response Example

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

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 69. FAIL Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "XG03CI0cCpWIkjaBwBT12hAOMiWx1ACO",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "6087dfcce27c4deae88a9d3e13445d9ea04bda7ef39ff1f8d098f6f5cda944ca16f89b7d590cb7cac4b834946a65f2bc439301566c298b7d69418a432ba7f183",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T07:23:19.288475+08:00",
    "version": "2.0.0"
}

Call this interface to query the detail information of the pre-auth

API method

URL

https://api.mch.pospre.com/KsherPayPreAuth/auth_query

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

auth_no

channel_request_no

ksher_request_no

NO

channel

String(32)

YES

wechat

Value range: alipay

ksher_order_no

String(32)

YES

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API
Example 70. Request Example
{
    "appid": "mch201630",
    "auth_no": "",
    "channel": "alipay",
    "channel_request_no": "",
    "ksher_order_no": "60020190703162939226705",
    "ksher_request_no": "40020190703162939858914",
    "mch_order_no": "",
    "nonce_str": "l1FT0BpBtm3fvtRRhGa601AUvxFLwrAw",
    "sign": "67324141f8554e3d666989309deeb05ed4d71ee91086e1eda79d3b7aae48543a4ff324ba5797c6f4b7345bff09192f27a578dc0218a145115eb9e1fa83654eb4",
    "version": "3.0.0"
}

Auth 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.
Example 71. SUCCESS Response Example

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

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 72. FAIL Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "l1FT0BpBtm3fvtRRhGa601AUvxFLwrAw",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "3ef322ea6282d8754941a4bc998092cd10e69f4c49e52344180e3cf5675a3318d8144cf2b0bbe606998d3800ec5ae5a2b4a94aed54ad451ffd5276f60c6b4510",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T08:16:05.550654+08:00",
    "version": "2.0.0"
}

Call this interface to create Alipay payment order and complete the payment with the pre-authed funds.

API method

URL

https://api.mch.pospre.com/KsherPayPreAuth/trade_pay

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

amount

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

attach

String(127)

NO

any extra information can be added here.

channel

String(32)

YES

wechat

Value range: 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)

auth_no

auth_confirm_mode

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)

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.

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

pay_timeout

total_fee

Int

YES

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API
Example 73. Request Example

Trade Pay 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.
Example 74. SUCCESS Response Example

Trade Pay 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.

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 75. FAIL Response Example
 {
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "Wcr6fqjWHYaCDgW67Lrma0obeF5NKX5j",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "4ae397025291e4ec26fc2773c98bba20fdab0cc4851c9eb5cb769f5c0a9feb974f3196e776797b4f5e8e2d365ef92cd8f2c2a18ac5e6caea8f1909aafebbbaf2",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T09:16:57.815506+08:00",
    "version": "2.0.0"
}

Call this interface to perform full or partial refunding

API method

URL

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

Method

POST

Parameter organization format

application/x-www-form-urlencoded

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

fee_type

String(16)

YES

THB

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

THB: Thailand

mch_refund_no

String(32)

YES

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

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

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

ksher_request_no

channel

String(32)

YES

wechat

Value range: alipay

ksher_order_no

String(32)

YES

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API

time_stamp

String(32)

YES

time stamp

total_fee

Int

YES

total amount of the order and it must be an integer, the unit is cent
Example 76. Request Example
 {
    "appid": "mch201630",
    "channel": "alipay",
    "channel_order_no": "",
    "fee_type": "THB",
    "ksher_order_no": "70020190629145145953847",
    "mch_order_no": "",
    "mch_refund_no": "refund1591921587",
    "nonce_str": "x2FyI0HjlO1LwQXfW7ReNTGnA8yZskVd",
    "operator_id": "",
    "refund_fee": 5000,
    "sign": "4045240ff27282f5e0483ec8dc94b8316b7b6cebbc55df2509e821db08ba695cf1d1f38eacbc622f1c4a9443721975f8895ed8fa75321b1a4bd21fce6286de67",
    "time_stamp": "20200612082627",
    "total_fee": 5000,
    "version": "3.0.0"
}

Auth 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.
Example 77. SUCCESS Response Example

Auth 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 parameters 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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 78. FAIL Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_MCHINFO",
        "err_msg": "merchant not exist.",
        "nonce_str": "x2FyI0HjlO1LwQXfW7ReNTGnA8yZskVd",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "19c4a126fdf87a2cfcae6f39e97be4848e6cd04a76dde29beda724bc4d9dd86b54342a44f501ead0deb65e791e983b8b90347dbf3548971d8d87e233d3f77e7f",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T08:26:28.538731+08:00",
    "version": "2.0.0"
}

Call this interface to query the payment transaction status.

API method

URL

https://api.mch.pospre.com/KsherPay/order_query

Method

POST

Parameter organization format

application/x-www-form-urlencoded

Auth Order Query 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}.

channel

String(32)

YES

wechat

Value range: alipay

channel_order_no

String(32)

YES

Order no. Generated by wechat.

ksher_order_no

String(32)

YES

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

sign

String(256)

YES

b000e9b6ec3fbda482d96a3d7c75c6956a5864336c3098462525e7229e8e046e490939a3e8b320a6c68eb63795a25b79d8c74f042f0972039bb5fe9b861cefb4

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

version

3.0.0

version of the API

time_stamp

String(256)

YES

time stamp
Example 79. Request Example
 {
    "appid": "mch20795",
    "channel": "alipay",
    "channel_order_no": "",
    "ksher_order_no": "70020190629122845908072",
    "mch_order_no": "",
    "nonce_str": "ElVnMYCL4yiRfB0lruYn98kHSMMIrKXk",
    "sign": "a812d32d90c0297c1043289948d857671477abad2f8436822f0d50f0376110bacb707138e75a07c2d4d0d4de5699f784f339d860671815d2a38fd7c83fd09ec2",
    "time_stamp": "20200612080513",
    "version": "3.0.0"
}

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

SUCCESS Response Example

Response Example(Success)

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

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

reserved for future use

time_stamp

String(32)

YES

the time stamp of request order

version

version of the API

data Parameters (JSON )

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

result

string(16)

YES

FAIL

FAIL
Example 80. FAIL Response Example
{
    "code": 0,
    "data": {
        "err_code": "KSHER_INVALID_ PAYKEY",
        "err_msg": "Invalid paykey  Pls login to merchant platform to reset the payment key",
        "nonce_str": "ElVnMYCL4yiRfB0lruYn98kHSMMIrKXk",
        "result": "FAIL"
    },
    "msg": "ok",
    "sign": "befc94b24e95d6183b9cc1470f605146322953562ba274fdb1ddc5dc484d14d4737b57505ee5bd77a861b25e66057d3b131267232aa263bd3d314bf49fcf319a",
    "status_code": "",
    "status_msg": "",
    "time_stamp": "2020-06-12T08:05:13.969262+08:00",
    "version": "3.0.0"
}

Customer transaction record pages sample

Customer transaction record pages sample