Gateway Pay APIs

Overview

TGateway Pay is Ksher Online e-payment aggregator service. Merchant just need to integrated once to have all e-wallets function of WeChat Pay, Alipay, Prompt Pay, Airpay, LinePay, True Money.

It helps merchant to create a checkout page with all e-wallets 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 Ksher Online e-payment aggregator service:

A. API method. Which allows merchant POST data to API url " https://gateway.ksher.com/gateway_pay" to request order.
B. Html Form method. Which allows merchant put param value into html from, requested order data will be posted to http://gateway.ksher.com/h5 or http://gateway.ksher.com/pc when buyer click checkout button. Demo code is provided in chapter "5. HTML Form Method Demo Code".

Applicable Cases

Both Web and H5/mobile payment scenarios are able to be achieved by using Ksher Gateway Pay.

Examples

Typical Example of Payment Flow

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

1) Buyer login merchant's website to choose product and place an order.
2) Merchant request Ksher Payment System a transaction by choosing one method:
   2.A. API method or 2.B. Html Form method.
3) Ksher Payment System response Ksher aggregator payment page URL.
4) Merchant display Ksher aggregator payment page with response URL.
5) User choose payment E-wallet on Ksher aggregator payment page.
6) Ksher Payment System verify and create an order.
7) Ksher Payment System request transaction to E-wallet Payment System
8) E-wallet Payment System response transaction data including: QR Code, etc. to Ksher.
9) For WeChat /PromptPay, Ksher Payment System forward transaction data including QR Code to Ksher gateway payment page. For Alipay/Airpay/LINE Pay, Ksher Payment System redirect to e-wallets confirm pay page.
10) User confirm to pay.
11) Ksher gateway payment front-end polling query payment result from e-wallet Payment System.
12) E-wallet send payment result notify to Ksher.
13) Ksher Redirect to merchant redirect_url.

4. User Experience of Online Gateway Pay

  4.1 PC Web scenario User experience

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

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

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

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

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

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

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




  4.2 H5/Mobile browser scenario User experience

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

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

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

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

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

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

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



5. HTML Form Method Demo Code

Merchant can follow this demo to implement his own system.



<!DOCTYPE html>

<html lang="en">

<head>

<meta charset="UTF-8">

<title>Demo</title>

</head>

<body>

<form action="" name="pay" method="post" enctype="multipart/form-data" target="_blank">

<input type="hidden" name="appid" value="">

<input type="hidden" name="mch_order_no" value="">

<input type="hidden" name="mch_code" value="">

<input type="hidden" name="total_fee" value="50000">

<input type="hidden" name="fee_type" value="">

<input type="hidden" name="nonce_str" value="">

<input type="hidden" name="channel_list" value="">

<input type="hidden" name="mch_redirect_url" value="">

<input type="hidden" name="mch_redirect_url_fail" value="">

<input type="hidden" name="product_name" value="">

<input type="hidden" name="refer_url" value="">

<input type="hidden" name="shop_name" value="">

<input type="hidden" name="color" value="">

<input type="hidden" name="background" value="">

<input type="hidden" name="payment_color" value="">

<input type="hidden" name="ksher_explain" value="">

<input type="hidden" name="hide_explain" value="">

<input type="hidden" name="logo" value="">

<input type="hidden" name="lang" value="">

<input type="hidden" name="expire_time" value="30">

<input type="hidden" name="hide_exp_time" value ="1" >

<input type="hidden" name="sign">

<input type="submit" value="Checkout" name="submit" class="submit" onclick='go_pay()' >

</form>

</div>

<script>

function go_pay(){

// below is pseudocode, to judge your payment scenario use H5 or PC Web

var flag = [your payment senario];

if( flag == 'H5')

{

document.pay.action="http://gateway.ksher.com/h5";

}

else{

document.pay.action="http://gateway.ksher.com/pc";

}

}

</script>

</body>

</html>

6. Specifications of APIs

6.1 Order Applying

API method Request URL: https://gateway.ksher.com/gateway_pay

API method Parameter transfer mode: POST

API method Parameter organization format: application/x-www-form-urlencoded


Html Form method Request URL: http://gateway.ksher.com/pc (For PC Web) Request URL: http://gateway.ksher.com/h5 (For Mobile H5)

6.1.1. Order Applying Request Parameters

Input parameter:

Parameter Type Required Value Example Description

appid

String(32)

YES

 

assigned by Ksher

nonce_str

String(32)

YES

 

Random string

channel_list

String(128)

YES

alipay,wechat,linepay,airpay,bbl_promt

A string made up by required e-wallets ,which seperated by "," without space.

sign

String(256)

YES

 

refer to following relevant chapter for signature algorithm

mch_code

String()

YES

 

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

mch_redirect_url
YES
After the payment is succeed, the web page is redirected to this URL. If merchant leaves this field blank, the web page will stay on payment page after payment succeed.
mch_redirect_url_fail  String() YES
After the payment is failed, the web page is redirected to this URL. If merchant leaves this field blank, the web page will stay on payment page after payment failed.
product_name String(512) YES
Name or descriptionof product.
refer_url

String(256)

YES

 

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

total_fee

Int

YES

 

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

fee_type

String(16)

YES

THB

comply with ISO 4217, 3 characters, refer to Appendix2 for its value range

device String( ) YES

time_stamp

String(256) YES  

 time stamp example:

 "time_stamp": "20190622131804"

color String(32) Optional

#FF5C72

The color code of banner on payment page, which can be DIY by merchant.
background String Optional
The url of banner background picture on payment page, which can be DIY by merchant.
payment_color String
#FF5C72 The color code of payment button, which can be DIY by merchant.
ksher_explain String(256)

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

Value range:

"1"----display copyright information.

"0"---- hide copyright information

expire_time int
30 How long the payment valid to pay, the unit is minute. If merchant leave this blank ,there will be no expire time limit.
hide_exp_time int
1

Value range:

"1"----display expire time information.

"0"---- hide expire time information

logo String

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

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

The display languange.

Value range:

"en"----English

"cn"----Chinese

"th"----Thai

The default language is English if no specification

shop_name String

The text next to logo, could be brand name, shop name or other DIY information.
attach String

The Remark or description

Request Example

{

"appid": "mch28321",

"channel_list": "wechat,alipay,linepay,bbl_prompt",

"device": "PC",

"fee_type": "THB",

"mch_code": "2311",

"mch_order_no": "233114471",

"mch_redirect_url": "https://www.baidu.com/",

"mch_redirect_url_fail": "https://www.baidu.com/",

"nonce_str": "8d22a1335bc893fe6e90a236a93ca3c5",

"product_name": "sdd",

"refer_url": "https://www.baidu.com/",

"sign": "5f01d9fe632bcf7d07deedcd3b419d37c653c571e7ea8759ad8cd4e44594b73776ab23720a7238e1a4442fb13e63d7a4b0e80695eedf50bd65d7c8e4a80c6d21",

"time_stamp": "2020041414150505S",

"total_fee": 13000

}

-SUCCESS Response Parameters

Parameter

Type

Required

Example

Description

code

int

YES

0

0:

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

 

Non 0:

Calling of the API failed, merchant can use the same parameters to launch the request again.

lang String

The display languange.

Value range:

"en"----English

"cn"----Chinese

"th"----Thai

The default language is English if no specification

message String(256) YES    Detailed description of result

sign

String(256)

YES

 

refer to following relevant chapter for signature algorithm

msg String(256) YES  

Hint message of result

data JSON YES    Gateway payment page will be sent to merchant

-SUCCESS Response example

{

"code": 0,

"data": {

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

},

"lang": "",

"message": "SUCCESS",

"msg": "SUCCESS",

"sgin": "6608b289c41550669d34236fd878045a5f95ad4a67b40988c4892ff71972ce2d809f453284b81c2c64dea5fbee826e6e81bf67a1644439a7e7917e555fbf8a9e"

}

-FAIL Response Parameters

Parameter

Type

Required

Example

Description

code

int

YES

0

0:

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

 

Non 0:

Calling of the API failed, merchant can use the same parameters to launch the request again.

lang String

The display languange.

Value range:

"en"----English

"cn"----Chinese

"th"----Thai

The default language is English if no specification

message String(256) YES    Detailed description of result
msg String(256) YES  

Hint message of result

-FAIL Response example

{'lang': '', 'code': -4, 'msg': '订单号不唯一', 'message': '订单号不唯一'}