Website Integration Guide
Overview
Ksher Gateway Pay is an Online e-Payment aggregator service. With our service, you only need to integrate once to have all e-wallets, WeChat Pay, Alipay, PromptPay, AirPay, LINE Pay, True Money and Credit/Debit Card Online Payment available in your website.
It helps merchant to create a checkout page with all Online e-wallets and Card Payment available for consumers to choose. Both Web and H5/Mobile payment scenarios (WeChat Pay only allowed open in WeChat browser) are able to be achieved by using Ksher Gateway Pay.
Ksher provide two method for calling Online e-payment aggregator service:
-
API method. Which allows merchant POST data to API url " https://gateway.ksher.com/api/gateway_pay " to request order.
It’s recommended to use gateway pay for Website integration.
Applicable Cases
Both PC website and H5/mobile payment scenarios are supported by Ksher Gateway Pay. Our payment system automatically recognises user’s device and response the correct page for H5/mobile or PC accordingly.
You can choose to display H5 or PC checkout page version if you prefered.
Payment Flow Sequence Diagram
Merchant can follow this procedure to implement own system follow Online Gateway Pay payment flow.
-
Buyer login merchant’s website to choose product and place an order.
-
Merchant request Ksher PaymentSystem a transaction
-
Ksher Payment System response Ksher aggregator payment page URL.
-
Merchant display Ksher aggregator payment page with response URL.
-
User choose payment E-wallet on Ksher aggregator gateway payment page.
-
Ksher Payment System verify and create an order.
-
Ksher Payment System request transaction to EwalletPaymentSystem
-
Ewallet Payment System response transaction data including: QR Code, etc. to Ksher
-
For WeChat /PromptPay, Ksher Payment System forward transaction data including QR Code to Ksher Gateway Payment Page.
-
For Alipay/Airpay/LINE Pay, Ksher Payment System redirect to e-wallets confirm pay page.
-
-
User confirm to pay.
-
Merchant polling query payment result from Ksher Payment System.
-
Ksher Payment System polling query payment result from E-wallet Payment System.
-
E-wallet response payment result to Ksher.
-
Ksher response payment result to Merchant.
-
Ksher aggregator gateway payment page redirect to merchant redirect_url.
User Experience of Online Gateway Pay PC Web scenario
Checkout Page
Checkout Page created by Ksher, Visual design like logo, banner background color, ect., which can DIY by merchant via API.
If you send only one channel, it will be skip checkout page and redirected to each wallet you send.
Credit Card
-
Select Card, it will turn to Ksher DIY checkout page.
-
Continue to pay with fill personal card information.
-
It will redirect to card bank OTP website, fill OTP.
-
After correct OTP it redirect back to KTB and your Success page.
WeChat Pay
Select WeChat Pay, it will turn to Ksher DIY checkout page, continue to pay with scanning QR code use WeChat app. Visual design can DIY by merchant via API.
PromptPay
Select PromptPay, it will turn to Ksher DIY checkout page, continue to pay with scanning QR code use bank app. Visual design can DIY by merchant via API.
Alipay
Select Alipay, it will redirect to Alipay checkout page, continue to pay with open Alipay e-wallte app or login Alipay account browser.
LINE pay
Select LINE pay, it will redirect to LINE checkout page, continue to pay with open LINE Pay e-wallets to sacn QR code or login LINE account.
Shopeepay
or old name before rebranding is Airpay.
Select Shopeepay, it will redirect to Airpay checkout page, continue to pay with open Airpay e-wallets to sacn QR code.
TrueMoney
Truemoney has a dynamic QR Code or OTP depend on what’s your select when opening an account with us.
Atome
-
Select Thai E-wallets tab and select Atome, will display QR
-
Using Atome app to QR to Scan QR to pay or pay on browser.
-
If select pay on browser, Enter mobile, OTP and click Next.
-
Enter payment method, accept the condition and Confirm payment
-
Click Back to Merchant to go back Merchant page
KTC Installment
-
Select Card tab and select KTC Installment, will redirect to Fill in page.
-
fill card information and select how long installmet term.
-
It will redirect to card bank OTP website, fill OTP.
-
After correct OTP it redirect back to KTB and your Success page.
If merchant absort fee will display like this
KBANK Installment
-
Select Card tab and select KBANK Installment, will redirect to Fill in page.
-
fill card information and select how long installmet term.
-
It will redirect to card bank OTP website, fill OTP.
-
After correct OTP it redirect back to KTB and your Success page.
If merchant absort fee will display like this
Krungsri Installment
-
Select Card tab and select Krungsri Installment, will redirect to Fill in page.
-
fill card information and select how long installment term.
-
It will redirect to card bank OTP website, fill OTP.
-
After correct OTP it redirect back to your Success page.
or if merchant absorb fee will display
First Choice Installment
-
Select Card tab and select First Choice Installment, will redirect to Fill in page.
-
fill card information and select how long installment term.
-
It will redirect to card bank OTP website, fill OTP.
-
After correct OTP it redirect back to your Success page.
or if merchant absorb fee will display
QR Card
Ksher PC page - QR CardUser Experience of Online Gateway Pay H5/Mobile browser scenario
Checkout Page
Checkout Page created by Ksher, Visual design like logo, banner background color, ect., which can DIY by merchant via API.
If you send only one channel, it will be skip checkout page and redirected to each wallet you send.
Credit Card
-
Select Card, it will turn to Ksher DIY checkout page.
-
Continue to pay with fill personal card information.
-
It will redirect to card bank OTP website, fill OTP.
-
After correct OTP it redirect back to KTB and your Success page.
Alipay
Select Alipay, it will redirect to Alipay payment page, continue to pay with open Alipay e-wallte app or login Alipay account browser.
Shopeepay
or old name before rebranding is Airpay.
Select Shopeepay, it will redirect to Shopeepay payment page. Continue to pay with turning into Shopeepay e-wallets.
Open payment link in WeChat browser ,it will create Ksher checkout page. Continue to pay with WeChat app.
Promptpay
Select Promptpay, will create Ksher checkout page. Continue payment with scan QR code.
TrueMoney
Truemoney has a dynamic QR Code or OTP depend on what’s your select when opening an account with us.
TrueMoney OTP
Ksher Mobile page - TMN
Mobile Atome
-
Select Thai E-wallets tab and select Atome, will display pay by app or pay in browser
-
If merchant select pay by app, will open Atome app on mobile phone
-
Enter coupon card, payment method and pay
-
Click Back to Merchant to go back Merchant page
KTC Installment
-
Select Credit/Debit Card tab and select KTC Installment, will redirect to Fill in page.
-
fill card information and select how long installmet term.
-
It will redirect to card bank OTP website, fill OTP.
-
After correct OTP it redirect back to KTB and your Success page.
or if merchant absorb fee will display
KBANK Installment
-
Select Credit/Debit Card tab and select KBANK Installment, will redirect to Fill in page.
-
fill card information and select how long installmet term.
-
It will redirect to card bank OTP website, fill OTP.
-
After correct OTP it redirect back to KBANK and your Success page.
or if merchant absorb fee will display
K Installment
-
Select Credit/Debit Card tab and select KBANK Installment, will redirect to Fill in page.
-
fill card information and select how long installmet term.
-
It will redirect to card bank OTP website, fill OTP.
-
After correct OTP it redirect back to KBANK and your Success page.
or if merchant absorb fee will display
Mobile Krungsri Installment
-
Select Credit/Debit Card tab and select Krungsri Installment, will redirect to Fill in page.
-
fill card information and select how long installment term.
-
It will redirect to card bank OTP website, fill OTP.
-
After correct OTP it redirect back to your Success page.
or if merchant absorb fee will display
Mobile First Choice Installment
-
Select Credit/Debit Card tab and select First Choice Installment, will redirect to Fill in page.
-
fill card information and select how long installment term.
-
It will redirect to card bank OTP website, fill OTP.
-
After correct OTP it redirect back to your Success page.
or if merchant absorb fee will display
Mobile SCB Easy
|
only support on mobile app If customer not install app when click to pa will redirect to Google Play SCB Easy or App Store SCB Easy depend on customer OS. |
Mobile Bualuang mBanking
|
only support on mobile app. If customer not install app when click to pa will redirect to Google Play Bualuang mBanking or App Store Bualuang mBanking depend on customer OS. |
Mobile KMA-Krungsri Mobile App
|
only support on mobile app. If customer not install app when click to pa will redirect to Google Play KMA or App Store KMA depend on customer OS. |
-
Select Mobile Banking tab, and select KMA.
-
Input App PIN.
-
Select your payment method and Click Next to go next page.
-
will summary Information customer have to pay, click Confirm to pay
-
Click Back to Ksher Payment to go back Merchant page
Mobile KPLUS
|
If customer not install app when click to pa will redirect to Google Play KPLUS or App Store KPLUS depend on customer OS. |
-
Select Mobile Banking tab, and select KPLUS.
-
Input App PIN.
-
If first time customer paid with ksher by using Kplus, will appear Authorized Page.
-
Select your payment method and Click Next to go next page.
-
will summary Information customer have to pay, click Confirm to pay
-
Click Back to KSHER PAYMENT to go back Merchant page
QR Card
Ksher Mobile page - QR CardSpecifications of Gateway Pay APIs
Order Apply
Please see Gateway Pay API
Order Query
Please see Gateway Order Query API
Webhook Notify
Please see Mch Notify URL (Gateway Pay) API
Order Refund
|
If want to refund, before refund please use Gateway order query to get Pay_mch_order_no and using mch_order_no = Pay_mch_order_no value on refund API or use ksher_order_no to refund |
Please see Order refund API
Order Cancel
|
Canceling an order will close the payment link and prevent customers from accessing it to initiate new payments. However, if a customer has already saved the QR code to their device, they may still be able to complete the payment using that QR. For card payments, if the status is already in progress, the order cannot be canceled. This is because the customer may be in the middle of the OTP process, and allowing cancellation at this stage could result in a successful payment after the order has been canceled. |
Please see Order Cancel API
Refund Query
Please see Refund Query API
Save Card Function
-
Customers can select to save the card for next time purchase, customers don’t have to enter card information again.
-
Available for merchants who do API integration and Plugin only.
-
Link Pay or Ksher Boss pro can not open this function.
-
-
Any API Online Merchants that want to open this function, have to adding Parameter field of “member_id” when Post to Gateway Order Apply. API can use Save card, Please see. Gateway Pay request Parameters
-
Save Card Function is based on merchants, not customers.
-
For example, "customer A" makes a payment to "Merchants A" by credit card with save card function.
-
The next time when make a payment to Ksher "Merchants A" again, no need to filled card information, customer can select the card to pay directly.
-
If the customer makes a payment to Ksher "Merchants B", he/she still have to fill in credit card information when make a payment.
-
-
Merchants & Ksher self will not see or collect any customers’ card information.
PC Web scenario User experience
-
In case you’ve never saved card, you can directly click at “credit/debit" to pay
-
In case you’ve ever saved card, you can click to pay with your saved card or can click at “Other’s credit/debit card to pay
-
After Selected , It will automatically change to filled card’s information page in which there will be adding to click accept that Customers acknowledge that his/her card information is save in my Ksher account for subsequent transactions.
-
In case you’ve ever saved card, you can click to pay with your saved card or can click at “Other’s credit/debit card to pay
H5/Mobile browser scenario User experience
-
In case you’ve never saved card, you can directly click at “credit/debit" to pay
-
In case you’ve ever saved card, you can click to pay with your saved card or can click at “Other’s credit/debit card to pay
-
After Selected , It will automatically change to filled card’s information page in which there will be adding to click accept that Customers acknowledge that his/her card information is save in my Ksher account for subsequent transactions.
-
In case you’ve ever saved card, you can also delete saved card
Gateway pay integrated online testing tool
You can use online testing tools. Please get it from https://gateway.ksher.com/demo.html
ERROR CODES
| Name | Description | Reason | Solution |
|---|---|---|---|
APPID_NOT_EXIST |
APPID not exist |
APPID was absent in parameters. |
Please check if the APPID is correct. |
APPID_MCHID_NOT_MATCH |
APPID and MCHID not match |
APPID and MCHID not match |
please check if the APPID and mchid match. |
INVALID_ORDER_NO |
invalid order no. |
order no. passed in is not correct. |
parameter error, please check if the original order no. passed in exist or if the original order is failed. |
KSHER_SIGN_ERROR |
signature error |
merchant signature is not correct |
Generally, this means that the signature parameter is incorrect. However, signature generation involves multiple factors, including: - The private key of the merchant being used - The data used to generate the signature parameter Typically, if an SDK has not been newly developed, we recommend checking whether the private key in use is the latest version downloaded from the merchant platform. If you have developed the API yourself, we recommend verifying that your signature generation follows the format outlined in Signature Creation. |
KSHER_SYSTEMERROR |
Error occurred during handling the request. |
Error occurred during handling the request. |
Issue the refund request again. |
KSHER_VERSION_ERROR |
API version used by merchant is not compatible with the API of the vendor |
API version used does not match |
contact the vendor to confirm current API version |
KSHER_ERROR_ORDER_NO |
Missing order no parameter |
Missing order no parameter |
Check the order no.(mch_order_no, ksher_order_no, channel_order_no) |
KSHER_REFUND_EXPIRE |
Refund can not be made via API by merchant after the order already settled. |
Refund can not be made via API by merchant after the order already settled. |
Please submit refund request on the Ksher merchant platform. |
KSHER_INVALID_MCHINFO |
merchant information is not correct |
the appid passed in does not exist in the vendor’s system |
confirm if the appid passed in is correct, contact the vendor if needed. |
KSHER_INVALID_ORDER_NO |
order no. does not exist |
the order no. passed in cannot be found in vendor’s system |
check if the order no. passed in is correct |
KSHER_INVALID_REFUND_FEE |
invalid amount to refund |
amount to refund is greater than the available amount |
check if the amount to refund is correct |
KSHER_INVALID_REFUND_AMOUNT |
Partially refund is not allowed |
Partially refund is not allowed |
refund completely is allowed. |
KSHER_INVALID_REFUND_BALANCE |
The balance amount of this order(price fee minus amount already refunded.) is not enough for the amount to refund. |
The balance amount of this order(price fee minus amount already refunded.) is not enough for the amount to refund. |
Check the amount to refund. |
KSHER_INVALID_REFUND_ORDER_NO |
invalid refund order no. |
the refund order no. passed already used. |
check if the refund order no. passed in, use a new one. |
KSHER_INVALID_REFUND_FEE_OR_TYPE |
Refund currency or amount invalid |
Refund currency or amount invalid |
Check the currcency or amount to refund. |
KSHER_PARAM_OVERLENGTH |
Some parameters are too long. |
Some paramters are too long |
Check the parameters. |
KSHER_INVALID_PARAM |
Missing parameter(s) |
Some parameter(s) invalid |
Check parameter(s) is correct |
KSHER_DUPLICATED_ORDERNO |
The merchant order no already used. |
The merchant order no already used. |
Use a new order no to make the order again. |
KSHER_EXCEED_AMOUNT_LIMIT |
the amount to pay exceeds the amount limit configured |
the amount to pay exceeds the amount limit configured |
make sure if the amount to pay exceeds the limit. |
KSHER_FEETYPE_NOT_MATCH |
fee type does not match |
pricing fee type does not match the registered fee type |
merchant needs to modify the program, if merchant is sure that the fee type passed in is correct, contact the vendor. |
KSHER_DUPLICATED_ORDERNO |
The merchant order no already used. |
The merchant order no already used. |
Use a new order no to make the order again. |
KSHER_DUPLICATED_REFUND_ORDERNO |
invalid refund order no |
the refund order no. passed already used. |
check if the refund order no. passed in, use a new one. |
KSHER_AMOUNT_IS_TOO_SMALL |
The amount is too small. |
The amount is too small |
Pass in a larger amount |
KSHER_CHANNEL_RESPONSE_ERROR |
Error occurred during query operation |
Error occurred during query operation |
Make an order query again. |
LACK_PARAMS |
parameter absent |
mandatory parameter(s) was absent |
please check if the parameters were sufficient |
MCHID_NOT_EXIST |
MCHID not exist |
MCHID was absent in parameters. |
please check if the MCHID is correct. |
NOAUTH |
the merchant has no access to this interface. |
the merchant has not yet got the access to this interface. |
contact the vendor(Ksher) |
NOT_UTF8 |
coding format error |
required coding format was not used. |
please use UTF-8 coding |
NOTENOUGH |
Not enough unsettled fund for refund |
There is not enough unsettled fund for refund |
This error code means refund request failed due to not enough unsettled fund for refund.Merchants need to contact Ksher to authorise credit for this kind of situation. If unsettled fund is enough ,please call the refund API once there is enough unsettled fund, or retry it continuously. |
ORDERPAID |
order closed already |
the order closed already. |
the order no. is already closed, please launch a new order. |
ORDERNOTEXISTR |
the order no. does not exist |
the order does not exist in the system |
merchant need to check if the order no. is correct. |
OUT_TRADE_NO_USED |
repetitive out_trade_no |
the same order cannot be submitted for multi times. |
please verify whether the out_trade_no. was submitted repetitively |
PARAM_ERROR |
parameters error |
parameters requested are not correct |
check the application according to the information returned, contact the vendor if needed. |
POST_DATA_EMPTY |
post parameters are empty |
post parameters should not be empty |
please check the paremeters posted in the http request. |
REQUIRE_POST_METHOD |
please use POST method |
the method used to pass the parameters was not POST. |
please check if the parameters was passed by POST method |
SYSTEMERROR |
system error |
system timeout |
call the order query API immediately to check order status, and decide next step according to the status of the order |
SIGNERROR |
signature error |
the signature parameter is not correct |
please check if the signature parameter and method meet the requirements of signature algorithm |
TRADE_STATE_ERROR |
order state error |
there will be latency for the result for refund application, please query later(20 minutes for balance payment, 3 workdays for card payment) |
|
USER_ACCOUNT_ABNORMALE |
refund failed |
user account is exceptional or unregistered. |
this status stands for the failure of the refund operation, merchant can handle the refund by himself. |
XML_FORMAT_ERROR |
XML format error |
XML format error |
please check whether the format of XML parameters is correct. |
SHOP_ID_ERROR |
Invalid merchant information |
Invalid merchant information |
Please check if the APPID is correct. |
CANCEL_ERROR |
The cancellation failed |
The cancellation failed |
Order cannot cancel because of wallet not support or already paid |
ORDER_NOT_EXIST |
This order does not exist. |
Not found this order |
Check mch order no is correct or not |
USER_NOT_EXIST |
This user does not exist. |
Not found this order |
Check mch order no is correct or not |
ORDER_NOT_PAY |
This order has not been paid. |
This order has not been paid. |
Order still not paid |
ORDER_ALREADY_REFUND |
This order has been refunded. |
This order has been refunded. |
order has been refunded. |
REFUND_FAILED |
Refund failed. |
Refund failed. |
check value is correct |
EXPIIRE_ORDER |
The order has timed out |
The order has timed out |
expired time set in order is timeout |
ORDER_ERROT |
Order number must be unique |
Order number must be unique |
Check order should be not duplicate or create before |
SHOP_NOT_EXIST |
This shop does not exist |
This shop does not exist |
Please check if the APPID is correct. |
PRICE_NOT_EXIST |
Invalid price |
Invalid price |
Check amount should be not 0 or create this order before |
MCH_ORDER_ERROR |
Duplicate order number |
Duplicate order number |
Check order should be not duplicate or create before |
RADIS_DOES_NOT_EXIST |
Redis does not exist |
Check url is correct |
|
QUERY_ORDER_ERROR |
Search for failed not completed transaction |
Search for failed not completed transaction |
check your value is correct |
ORDER_PAYMENT_ERROR |
Your payment failed |
Your payment failed |
Retry to paid again |
SMS_CODE_ERROR |
Failed to receive OTP code |
Failed to receive OTP code |
check you mobile phone is correct |
CHANNEL_LIST_ERROR |
You have not apply for any ewallets nor credit card payment services |
You have not apply for any ewallets nor credit card payment services |
check your channel value is correct or support |
MEMBER_ID_ERROR |
member_id cannot be number only |
member_id cannot be number only |
Please check your member_id not use Real number like 1,1200,00001, but can use string with number like ABC1234. |
SAVE_CARD_ERROR |
Failed to save card |
Failed to save card |
Check Bank card channel can support save card function |
MEMBER_CARD_ERROR |
This card cannot be used |
This card cannot be used |
This card is not available, please change card to paid |
EMPTY_CARD_NO |
Card information is incorrect |
Card information is incorrect |
Check your card input information |
DELETE_MEMBER_CARD_ERROR |
Failed to delete card |
Failed to delete card |
Refresh page and try to delete again |
MEMBER_CARD_NOT_EXIST |
This card does not exists |
This card does not exists |
check your member_id is correct |
MEMBER_ID_LENGTH_OUT_OF_LIMIT |
member_id cannot be more than 32 characters |
member_id cannot be more than 32 characters |
Please check your member_id not use Real number like 1,1200,00001, but can use string with number like ABC1234. and member_id cannot be more than 32 characters |
ORDER_ALREADY_CANCEL |
The order has been canceled |
The order has been canceled |
This order already cancel, Please try to create the new order. |
ORDER_ALREADY_CANCEL_OPERATION_CANNOT_BE_PERFORMED |
The order has been canceled, this action cannot proceed |
The order has been canceled, this action cannot proceed |
This order already cancel, Please try to create the new order. |
ORDER_ALREADY_PAY_OPERATION_CANNOT_BE_PERFORMED |
This order has already been paid, this action cannot proceed |
This order has already been paid, this action cannot proceed |
This order already paid, Please try to create the new order. |
ORDER_ALREADY_PAYMENT_SUCCESS |
Order has been completed |
Order has been completed |
This order already paid, Please try to create the new order. |
INSTAL_FEE_PAYER_ERROR |
Failed to apply setting of interest-bearing |
Failed to apply setting of interest-bearing |
check at instal_fee_payer_merchant_channel_list or instal_fee_payer is correct |
TRUEMONEY_OPT_CODE_ERROR |
Wrong OTP code |
Wrong OTP code |
check OTP is correct |
MANY_OPEN |
Someone is paying this bill. DO NOT pay twice. |
Someone is paying this bill. DO NOT pay twice. |
check on exclusive is turn on or not. if have another person open payment page |
LANG_REPEAT_SUBMIT |
Repetitive submission |
Repetitive submission |
order already create before, create the new one. |