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

channel

String(32)

YES

wechat

Value range: alipay

device_id

String(32

NO

POS001

the terminal id from which the request is issued.

fee_type

String(16)

YES

CNY

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

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

The id for cashier

pay_timeout

payee_logon_id

payee_user_id

sign

String(256)

YES

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

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

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

sign

String(256)

YES

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

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

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

the terminal id from which the request is issued.

fee_type

String(16)

YES

CNY

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

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

The id for cashier

sign

String(256)

YES

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

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

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

sign

String(256)

YES

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

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

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

the terminal id from which the request is issued.

fee_type

String(16)

YES

CNY

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

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

The id for cashier

sign

String(256)

YES

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

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

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

sign

String(256)

YES

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

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

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

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

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

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

sign

String(256)

YES

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

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

refer to relevant chapter Signature Algorithm

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

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

sign

String(256)

YES

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

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

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

the terminal id from which the request is issued.

fee_type

String(16)

YES

CNY

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

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

The id for 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

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

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

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

sign

String(256)

YES

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

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

CNY

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

mch_refund_no

String(32)

YES

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

operator_id

String(32)

NO

The id for 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

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

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

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

sign

String(256)

YES

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

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

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

the terminal id from which the request is issued.

fee_type

String(16)

YES

CNY

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

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

The id for cashier

pay_timeout

payee_logon_id

payee_user_id

sign

String(256)

YES

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

version

3.0.0

version of the API

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

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

sign

String(256)

YES

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

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

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

the terminal id from which the request is issued.

fee_type

String(16)

YES

CNY

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

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

The id for cashier

sign

String(256)

YES

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

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

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

sign

String(256)

YES

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

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

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

the terminal id from which the request is issued.

fee_type

String(16)

YES

CNY

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

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

The id for cashier

sign

String(256)

YES

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

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

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

sign

String(256)

YES

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

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

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

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

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

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

sign

String(256)

YES

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

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

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

the terminal id from which the request is issued.

fee_type

String(16)

YES

CNY

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

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

The id for 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

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

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

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

sign

String(256)

YES

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

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

CNY

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

mch_refund_no

String(32)

YES

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

operator_id

String(32)

NO

The id for 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

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

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

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

sign

String(256)

YES

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

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

refer to relevant chapter Signature Algorithm

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

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

sign

String(256)

YES

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

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

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

the terminal id from which the request is issued.

fee_type

String(16)

YES

CNY

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

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

The id for cashier

pay_timeout

payee_logon_id

payee_user_id

sign

String(256)

YES

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

version

3.0.0

version of the API

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

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

sign

String(256)

YES

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

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

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

the terminal id from which the request is issued.

fee_type

String(16)

YES

CNY

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

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

The id for cashier

sign

String(256)

YES

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

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

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

sign

String(256)

YES

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

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

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

the terminal id from which the request is issued.

fee_type

String(16)

YES

CNY

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

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

The id for cashier

sign

String(256)

YES

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

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

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

sign

String(256)

YES

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

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

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

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

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

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

sign

String(256)

YES

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

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

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

the terminal id from which the request is issued.

fee_type

String(16)

YES

CNY

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

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

The id for 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

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

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

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

sign

String(256)

YES

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

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

CNY

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

mch_refund_no

String(32)

YES

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

operator_id

String(32)

NO

The id for 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

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

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

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

sign

String(256)

YES

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

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

refer to relevant chapter Signature Algorithm

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

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

sign

String(256)

YES

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

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

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

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

the terminal id from which the request is issued.

fee_type

String(16)

YES

CNY

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

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

The id for cashier

pay_timeout

payee_logon_id

payee_user_id

sign

String(256)

YES

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

version

3.0.0

version of the API

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

Example 62. SUCCESS Response Example

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

sign

String(256)

YES

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

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

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

the terminal id from which the request is issued.

fee_type

String(16)

YES

CNY

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

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

The id for cashier

sign

String(256)

YES

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

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

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

sign

String(256)

YES

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

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

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

the terminal id from which the request is issued.

fee_type

String(16)

YES

CNY

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

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

The id for cashier

sign

String(256)

YES

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

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

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

sign

String(256)

YES

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

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

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

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

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

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

sign

String(256)

YES

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

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

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

the terminal id from which the request is issued.

fee_type

String(16)

YES

CNY

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

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

The id for 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

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

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

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

sign

String(256)

YES

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

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

CNY

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

mch_refund_no

String(32)

YES

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

operator_id

String(32)

NO

The id for 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

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

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

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

sign

String(256)

YES

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

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

refer to relevant chapter Signature Algorithm

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

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

sign

String(256)

YES

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

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