Introduction

Payment Gateway Specification Document

This documentation aims to provide all the information you need to work with our API.

Supported payment methods

	ABA Pay			Acleda Bank
	KESS Pay			Sathapana Bank
	Wing Bank			TrueMoney
	U-Pay			Visa/Master Card
	eMoney			KHQR Code
	WeChat Pay			Alipay

Authenticating

Authenticate requests to this API's endpoints by sending an Authorization header with the value "Bearer {ACCESS TOKEN}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

POST {baseUrl}/oauth/token

• Sample request
• Sample response

                    
curl --location --request POST '{baseUrl}/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "grant_type": "password",
    "client_id": "{CLIENT ID}",
    "client_secret": "{CLIENT SECRET}",
    "username": "{USERNAME}",
    "password": "{PASSWORD}"
}'
                    
                

                    
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => '{baseUrl}/oauth/token',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
        "grant_type": "password",
        "client_id": "{CLIENT ID}",
        "client_secret": "{CLIENT SECRET}",
        "username": "{USERNAME}",
        "password": "{PASSWORD}"
    }',
    CURLOPT_HTTPHEADER => array(
        'Content-Type: application/json',
         
    )
));

$response = curl_exec($curl);

curl_close($curl);

echo $response;
                    
                

                    

{
    "token_type": "Bearer",
    "expires_in": "1800",
    "access_token": "ACCESS TOKEN",
    "refresh_token": "REFRESH TOKEN"
}
              
                    
                

API Gateway

Use a single endpoint to access every available service based on its service’s name and dynamical parameters. We have provided two common services “initiate transaction” and “query” for our merchants to interact with our customers over a web application (WebPay) to process the payment with dynamic amounts and currency.

List Bakong Members

POST {baseUrl}/api/mch/v2/gateway requires authentication

• Sample request
• Sample response

                    
curl --location --request POST '{baseUrl}/api/mch/v2/gateway' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {ACCESS TOKEN}' \
--data-raw '{
    "service": "webpay.acquire.getbakongmembers",
    "sign_type": "MD5",
    "sign": "{SIGNATURE}"
}'
                    
                

                    
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => '{baseUrl}/api/mch/v2/gateway',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
        "service": "webpay.acquire.getbakongmembers",
        "sign_type": "MD5",
        "sign": "{SIGNATURE}"
    }',
    CURLOPT_HTTPHEADER => array(
        'Content-Type: application/json',
        'Authorization: Bearer {ACCESS TOKEN}' 
    )
));

$response = curl_exec($curl);

curl_close($curl);

echo $response;
                    
                

                    
{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "xxx",
            "branch_code": "xx",
            "bic": "xx",
            "crypto_key_id": null,
            "owner_address_fk_country": null,
            "owner_address_city": "PP",
            "owner_address_region": "PP",
            "owner_address_postalcode": "12100",
            "owner_address_line1": "Bakong bank members",
            "owner_address_line2": null,
            "status": 1,
            "logo": "https://clientdev.kesspay.io/banks/December2022/g8diT9AEdH603rj9GVfA.png",
            "position": null,
            "payin_rate": 0,
            "payout_rate": 0,
            "is_display_on_app": 0
        }
    ],
    "sign": "{SIGNATURE}",
    "sign_type": "MD5"
}      
              
                    
                

List payment methods

Pull available payment methods under merchant account.

POST {baseUrl}/api/mch/v2/gateway requires authentication

• Sample request
• Sample response

                    
curl --location --request POST '{baseUrl}/api/mch/v2/gateway' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {ACCESS TOKEN}' \
--data-raw '{
    "service": "webpay.acquire.getpaymentmethods",
    "sign_type": "MD5",
    "sign": "{SIGNATURE}"
}'
                    
                

                    
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => '{baseUrl}/api/mch/v2/gateway',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
        "service": "webpay.acquire.getpaymentmethods",
        "sign_type": "MD5",
        "sign": "{SIGNATURE}"
    }',
    CURLOPT_HTTPHEADER => array(
        'Content-Type: application/json',
        'Authorization: Bearer {ACCESS TOKEN}' 
    )
));

$response = curl_exec($curl);

curl_close($curl);

echo $response;
                    
                

                    
{
    "success": true,
    "data": [
        {
            "id": 9,
            "title": "Visa/Master Card",
            "img_url": "https://devwebpayment.kesspay.io/storage/payment-methods/January2021/PYH0yz4Spxk0He64zmdE.png",
            "bic": "VISA_MASTER",
            "storelink": {
                "ios": null,
                "android": null
            }
        },
        {
            "id": 11,
            "title": "KESS PAY",
            "img_url": "https://devwebpayment.kesspay.io/storage/payment-methods/June2022/sUGkSOt9bwpLUP80Rdst.png",
            "bic": "KESSKH",
            "storelink": {
                "ios": "itms-apps://apple.com/app/1518521952",
                "android": "https://play.google.com/store/apps/details?id=io.kessinnovation.kesschat"
            }
        },
        {
            "id": 12,
            "title": "ABA PAY",
            "img_url": "https://devwebpayment.kesspay.io/storage/payment-methods/January2021/zNSxh2tYwT9KaNnoQb67.png",
            "bic": "ABAAKHPP",
            "storelink": {
                "ios": "itms-apps://apple.com/app/968860649",
                "android": "https://play.google.com/store/apps/details?id=com.paygo24.ibank&hl=en&gl=US"
            }
        },
        {
            "id": 13,
            "title": "ACLEDA Bank",
            "img_url": "https://devwebpayment.kesspay.io/storage/payment-methods/January2021/hByq9E5xKTA9n6En12V2.png",
            "bic": "ACLBKHPP",
            "storelink": {
                "ios": "itms-apps://apple.com/app/1196285236",
                "android": "http://play.google.com/store/apps/details?id=com.domain.acledabankqr&hl=en"
            }
        },
        {
            "id": 14,
            "title": "Sathapana",
            "img_url": "https://devwebpayment.kesspay.io/storage/payment-methods/January2021/upXnfv34dpBz9UMNeVGm.png",
            "bic": "SBPLKHPP",
            "storelink": {
                "ios": "itms-apps://apple.com/app/1499664210",
                "android": "https://play.google.com/store/apps/details?id=kh.com.sathapana.consumer"
            }
        },
        {
            "id": 15,
            "title": "WeChat Pay",
            "img_url": "https://devwebpayment.kesspay.io/storage/payment-methods/January2021/ZjWHPwMknOrbjPPi6Rtp.png",
            "bic": "WECHAT",
            "storelink": {
                "ios": "itms-apps://apple.com/app/414478124",
                "android": "https://play.google.com/store/apps/details?id=com.tencent.mm"
            }
        },
        {
            "id": 16,
            "title": "AliPay",
            "img_url": "https://devwebpayment.kesspay.io/storage/payment-methods/January2021/Q9ERYHkIObsx9b4AHdJ4.jpg",
            "bic": "ALIPAY",
            "storelink": {
                "ios": "itms-apps://apple.com/app/333206289",
                "android": "https://play.google.com/store/apps/details?id=com.eg.android.AlipayGphone"
            }
        },
        {
            "id": 17,
            "title": "eMoney",
            "img_url": "https://devwebpayment.kesspay.io/storage/payment-methods/June2021/oLIH0G2nZcd5liB5usUs.png",
            "bic": "EMONEY",
            "storelink": {
                "ios": null,
                "android": null
            }
        },
        {
            "id": 18,
            "title": "Wing Bank",
            "img_url": "https://devwebpayment.kesspay.io/storage/payment-methods/July2022/Q44YlfkgxgXoCwJixuX5.png",
            "bic": "WING",
            "storelink": {
                "ios": "itms-apps://apple.com/app/1113286385",
                "android": "https://play.google.com/store/apps/details?id=com.wingmoney.wingpay"
            }
        },
        {
            "id": 19,
            "title": "TrueMoney",
            "img_url": "https://devwebpayment.kesspay.io/storage/payment-methods/June2022/MBBLsHM6EJeZ3ZejFvkO.png",
            "bic": "TRUEMONEY",
            "storelink": {
                "ios": "itms-apps://apple.com/app/663885752",
                "android": "https://play.google.com/store/apps/details?id=kh.com.truemoney.truemoneymobile"
            }
        }
    ],
    "sign": "{SIGNATURE}",
    "sign_type": "MD5"
}      
              
                    
                

Generate Payment Link

Send or open payment link to procceed payment.

POST {baseUrl}/api/mch/v2/gateway requires authentication

• Sample request
• Sample response

                    
curl --location --request POST '{baseUrl}/api/mch/v2/gateway' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {ACCESS TOKEN}' \
--data-raw '{
    "service": "webpay.acquire.createorder",
    "sign_type": "MD5",
    "sign": "{SIGNATURE}",
    "seller_code": "{SELLER CODE}",
    "out_trade_no": "TEST-1234567891",
    "body": "iPhone 13 pro Case",
    "total_amount": 10,
    "currency": "USD",
    "notify_url": "https:\/\/sample.com\/notifyme",
    "login_type": "ANONYMOUS"
}'
                    
                

                    
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => '{baseUrl}/api/mch/v2/gateway',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
        "service": "webpay.acquire.createorder",
        "sign_type": "MD5",
        "sign": "{SIGNATURE}",
        "seller_code": "{SELLER CODE}",
        "out_trade_no": "TEST-1234567891",
        "body": "iPhone 13 pro Case",
        "total_amount": 10,
        "currency": "USD",
        "notify_url": "https://sample.com/notifyme",
        "login_type": "ANONYMOUS"
    }',
    CURLOPT_HTTPHEADER => array(
        'Content-Type: application/json',
        'Authorization: Bearer {ACCESS TOKEN}' 
    )
));

$response = curl_exec($curl);

curl_close($curl);

echo $response;
                    
                

                    
{
    "success": true,
    "data": {
        "token": "111612f019b6836bf1255554",
        "out_trade_no": "TEST-1234567891",
        "transaction_id": null,
        "body": "iPhone 13 pro Case",
        "total_amount": 10,
        "currency": "USD",
        "status": "WAITING",
        "paid_at": null,
        "settled_at": null,
        "settlement_date": null,
        "expired_at": "2022-07-18T10:44:53.000000Z",
        "created_at": "2022-07-18T07:44:54.000000Z",
        "detail": [],
        "seller": {
            "code": "{SELLER CODE}",
            "display_name": "ABCD"
        },
        "payment_detail": null,
        "queue_number": "0001",
        "payment_link": "{baseUrl}/pay/{token}"
    },
    "sign": "{SIGNATURE}",
    "sign_type": "MD5"
}      
              
                    
                

Native Pay

Generate dynamic QR code or deeplink.

POST {baseUrl}/api/mch/v2/gateway requires authentication

• Sample request
• Sample response

                    
curl --location --request POST '{baseUrl}/api/mch/v2/gateway' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {ACCESS TOKEN}' \
--data-raw '{
    "service": "webpay.acquire.nativePay",
    "sign_type": "MD5",
    "sign": "{SIGNATURE}",
    "seller_code": "{SELLER CODE}",
    "out_trade_no": "TEST-1234567891",
    "body": "iPhone 13 pro Case",
    "total_amount": 10,
    "currency": "USD",
    "notify_url": "https:\/\/sample.com\/notifyme",
    "service_code": "KESSKH"
}'
                    
                

                    
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => '{baseUrl}/api/mch/v2/gateway',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
        "service": "webpay.acquire.nativePay",
        "sign_type": "MD5",
        "sign": "{SIGNATURE}",
        "seller_code": "{SELLER CODE}",
        "out_trade_no": "TEST-1234567891",
        "body": "iPhone 13 pro Case",
        "total_amount": 10,
        "currency": "USD",
        "notify_url": "https://sample.com/notifyme",
        "service_code": "KESSKH"
    }',
    CURLOPT_HTTPHEADER => array(
        'Content-Type: application/json',
        'Authorization: Bearer {ACCESS TOKEN}' 
    )
));

$response = curl_exec($curl);

curl_close($curl);

echo $response;
                    
                

                    
{
    "success": true,
    "data": {
        "qrcode": "00020101021230100006KESSKH5204000053038405402105802KH5919KESS INNOVATION PLC6010Phnom Penh6236012444816b39953515cd6262b1870304test630448F7",
        "deeplink": null,
        "expires_in": 10799,
        "brand_logo": "https://devwebpayment.kesspay.io/storage/payment-methods/June2022/sUGkSOt9bwpLUP80Rdst.png",
        "app_name": "KESSCHAT",
        "service_code": "KESSKH",
        "order_info": {
            "token": "44816b39953515cd6262b187",
            "out_trade_no": "TEST-1234567892",
            "transaction_id": null,
            "body": "iPhone 13 pro Case",
            "total_amount": 10,
            "currency": "USD",
            "status": "WAITING",
            "paid_at": null,
            "settled_at": null,
            "settlement_date": null,
            "expired_at": "2022-07-19T09:18:55.000000Z",
            "created_at": "2022-07-19T06:18:56.000000Z",
            "detail": [],
            "seller": {
                "code": "{SELLER CODE}",
                "display_name": "Merchant Name"
            },
            "payment_detail": null,
            "error_logs": []
        }
    },
    "sign": "{SIGNATURE}",
    "sign_type": "MD5"
}      
              
                    
                

Direct Pay

Initiate Credit/Debit card transaction directly from merchant server.

Sequence diagram

API specification

POST {baseUrl}/api/mch/v2/gateway requires authentication

• Sample request
• Sample response

                    
curl --location --request POST '{baseUrl}/api/mch/v2/gateway' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {ACCESS TOKEN}' \
--data-raw '{
    "service": "webpay.acquire.directPay",
    "sign_type": "MD5",
    "sign": "{SIGNATURE}",
    "seller_code": "{SELLER CODE}",
    "out_trade_no": "TEST-1234567891",
    "body": "iPhone 13 pro Case",
    "total_amount": 10,
    "currency": "USD",
    "notify_url": "https:\/\/sample.com\/notifyme",
    "redirect_url": "https:\/\/sample.com\/redirectme",
    "card": "{ENCRYPTED CARD INFORMATION}"
}'
                    
                

                    
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => '{baseUrl}/api/mch/v2/gateway',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
        "service": "webpay.acquire.directPay",
        "sign_type": "MD5",
        "sign": "{SIGNATURE}",
        "seller_code": "{SELLER CODE}",
        "out_trade_no": "TEST-1234567891",
        "body": "iPhone 13 pro Case",
        "total_amount": 10,
        "currency": "USD",
        "notify_url": "https://sample.com/notifyme",
        "redirect_url": "https://sample.com/redirectme",
        "card": "{ENCRYPTED CARD INFORMATION}"
    }',
    CURLOPT_HTTPHEADER => array(
        'Content-Type: application/json',
        'Authorization: Bearer {ACCESS TOKEN}' 
    )
));

$response = curl_exec($curl);

curl_close($curl);

echo $response;
                    
                

                    
{
    "success": true,
    "data": {
        "required_3ds": true,
        "pre_card_input": true,
        "html_confirm_payment": "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01 Transitional//EN\" \"http://www.w3.org/TR/html4/loose.dtd\"><html><head><title>Process Secure Payment</title><meta http-equiv=\"content-type\" content=\"text/html;charset=UTF-8\"><meta name=\"description\" content=\"Process Secure Payment\"><meta name=\"robots\" content=\"noindex\"><style type=\"text/css\">body {font-family:\"Trebuchet MS\",sans-serif; background-color: #FFFFFF; }#msg {border:5px solid #666; background-color:#fff; margin:20px; padding:25px; max-width:40em; -webkit-border-radius: 10px; -khtml-border-radius: 10px; -moz-border-radius: 10px; border-radius: 10px;}#submitButton { text-align: center ; }#footnote {font-size:0.8em;}</style></head><body onload=\"return window.document.echoForm.submit()\"><form name=\"echoForm\" method=\"POST\" action=\"https://mtf.gateway.mastercard.com/acs/MastercardACS/a1ea9661-2440-4f41-82f2-8f5cf81bb808\" accept-charset=\"UTF-8\"><input type=\"hidden\" name=\"PaReq\" value=\"eAFVUdtugkAUfDfxHwjpa9kLomiOa6yXSEzRVG36SmArpLLogre/71mvLU/M7J7ZOTPQO+Ub6yB1mRWqazOH2pZUcZFkat21V8vxq2/3RL0Gy1RLOVzIeK+lgHdZltFaWlmCMxQ/5lOP03bTFjDvf8idgJumQEmHA7lDHNVxGqlKQBTv3oJQeKzJuQvkBiGXOhgKxl2KeksgVwwqyqWYjhaLIAxnn/1lMAuBXEiIi72q9Fkw1gRyB7DXG5FW1bZDyPF4dH7QcqZUcYgqXNWJixyIuQLk6Wi+N95KXPCUJWKQkBEPdPo9jGnpHc5fGfcn2zFpTxtdIOYGJFElBaec0xZrW4x2qN9xcZcLD1FujInVYmi9MOpQikteKdial/pXYAIE8pcBTFljDWfhN/DogUCetoWSqImJPv6BPH0PJibXuMIEvUbL9bCZpqkHCzIJXw6MSoZxcY9eZQwAYkbJrTzM5FIwMv+Kr9d+AQfRs6A=\"><input type=\"hidden\" name=\"TermUrl\" value=\"https://clientdev.kesspay.io/api/3DSecureId/3dsT710032233656121?secureKey=FBDSHJF345FBDNVFD@G5499\"><input type=\"hidden\" name=\"MD\" value=\"\"><noscript><div id=\"msg\"><div id=\"submitButton\"><input type=\"submit\" value=\"Click here to continue\" class=\"button\"></div></div></noscript></form></body></html>\n",
        "order_info": {
            "token": "746173280aeb862720557599",
            "out_trade_no": "1234567893",
            "transaction_id": null,
            "body": "iPhone 13 pro Case",
            "total_amount": 10,
            "currency": "USD",
            "meta": null,
            "status": "WAITING",
            "paid_at": null,
            "settled_at": null,
            "settlement_date": null,
            "expired_at": "2022-07-19T13:08:27.000000Z",
            "created_at": "2022-07-19T10:08:28.000000Z",
            "detail": [],
            "seller": {
                "code": "{SELLER CODE}",
                "display_name": "Merchant Name"
            },
            "payment_detail": null
        }
    },
    "sign": "{SIGNATURE}",
    "sign_type": "MD5"
}      
              
                    
                

Close Order

Update transaction status to CLOSED.

POST {baseUrl}/api/mch/v2/gateway requires authentication

• Sample request
• Sample response

                    
curl --location --request POST '{baseUrl}/api/mch/v2/gateway' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {ACCESS TOKEN}' \
--data-raw '{
    "service": "webpay.acquire.closeorder",
    "sign_type": "HMAC-SHA256",
    "sign": "4d9ec129143a8f1953b51b1e09f5e632d68f253d4c9458887f0494921922bfb5",
    "out_trade_no": "TEST-1234567891"
}'
                    
                

                    
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => '{baseUrl}/api/mch/v2/gateway',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
        "service": "webpay.acquire.closeorder",
        "sign_type": "HMAC-SHA256",
        "sign": "4d9ec129143a8f1953b51b1e09f5e632d68f253d4c9458887f0494921922bfb5",
        "out_trade_no": "TEST-1234567891"
    }',
    CURLOPT_HTTPHEADER => array(
        'Content-Type: application/json',
        'Authorization: Bearer {ACCESS TOKEN}' 
    )
));

$response = curl_exec($curl);

curl_close($curl);

echo $response;
                    
                

                    
{
    "success": true,
    "data": {
        "token": "111612f019b6836bf1255554",
        "out_trade_no": "TEST-1234567891",
        "transaction_id": null,
        "body": "Repay",
        "total_amount": 10,
        "currency": "USD",
        "status": "CLOSED",
        "paid_at": null,
        "settled_at": null,
        "settlement_date": null,
        "expired_at": "2022-07-18T10:44:53.000000Z",
        "created_at": "2022-07-18T07:44:54.000000Z",
        "detail": [],
        "seller": {
            "code": "{SELLER CODE}",
            "display_name": "Merchant Name"
        },
        "payment_detail": null,
        "error_logs": []
    },
    "sign": "{SIGNATURE}",
    "sign_type": "MD5"
}      
              
                    
                

Query Order

Transaction inquiry.

POST {baseUrl}/api/mch/v2/gateway requires authentication

• Sample request
• Sample response

                    
curl --location --request POST '{baseUrl}/api/mch/v2/gateway' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {ACCESS TOKEN}' \
--data-raw '{
    "service": "webpay.acquire.queryOrder",
    "sign_type": "MD5",
    "sign": "{SIGNATURE}",
    "out_trade_no": "TEST-1234567891"
}'
                    
                

                    
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => '{baseUrl}/api/mch/v2/gateway',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
        "service": "webpay.acquire.queryOrder",
        "sign_type": "MD5",
        "sign": "{SIGNATURE}",
        "out_trade_no": "TEST-1234567891"
    }',
    CURLOPT_HTTPHEADER => array(
        'Content-Type: application/json',
        'Authorization: Bearer {ACCESS TOKEN}' 
    )
));

$response = curl_exec($curl);

curl_close($curl);

echo $response;
                    
                

                    
{
    "success": true,
    "data": {
        "token": "111612f019b6836bf1255554",
        "out_trade_no": "TEST-1234567891",
        "transaction_id": null,
        "body": "iPhone 13 pro Case",
        "total_amount": 10,
        "currency": "USD",
        "status": "WAITING",
        "paid_at": null,
        "settled_at": null,
        "settlement_date": null,
        "expired_at": "2022-07-18T10:44:53.000000Z",
        "created_at": "2022-07-18T07:44:54.000000Z",
        "detail": [],
        "seller": {
            "code": "{SELLER CODE}",
            "display_name": "Merchant Name"
        },
        "payment_detail": null,
        "queue_number": "0001",
        "card_info" : {
            "BIN": null,
            "scheme": null,
            "card_token": null,
            "swift_code": null,
            "card_hashed": null,
            "holder_name": null,
            "account_logo": null,
            "account_name": null,
            "account_number": null
        },
        "wechat_alipay_info" : {
            "openid": "2088632596656451",
            "service": "Alipay or Wechat",
            "currency": "USD",
            "total_amount": "0.01",
            "total_amount_cny": "0.07"
        }
    },
    "sign": "{SIGNATURE}",
    "sign_type": "MD5"
}      
              
                    
                

Query Order By Date Range

Transaction inquiry.

POST {baseUrl}/api/mch/v2/gateway requires authentication

• Sample request
• Sample response

                    
curl --location --request POST '{baseUrl}/api/mch/v2/gateway' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {ACCESS TOKEN}' \
--data-raw '{
    "service": "webpay.acquire.queryorderbydaterange",
    "sign_type": "MD5",
    "sign": "{SIGNATURE}",
    "start_date": "2022-01-15",
    "end_date": "2022-01-16",
    "per_page": 50,
    "page": 1
}'
                    
                

                    
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => '{baseUrl}/api/mch/v2/gateway',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
        "service": "webpay.acquire.queryorderbydaterange",
        "sign_type": "MD5",
        "sign": "{SIGNATURE}",
        "start_date": "2022-01-15",
        "end_date": "2022-01-16",
        "per_page" : 50,
        "page" : 1
    }',
    CURLOPT_HTTPHEADER => array(
        'Content-Type: application/json',
        'Authorization: Bearer {ACCESS TOKEN}' 
    )
));

$response = curl_exec($curl);

curl_close($curl);

echo $response;
                    
                

                    
{
    "success": true,
    "data": {
        "items": [
            {
                "token": "111612f019b6836bf1255554",
                "out_trade_no": "TEST-1234567891",
                "transaction_id": null,
                "body": "iPhone 13 pro Case",
                "total_amount": 10,
                "currency": "USD",
                "status": "WAITING",
                "paid_at": null,
                "settled_at": null,
                "settlement_date": null,
                "expired_at": "2022-07-18T10:44:53.000000Z",
                "created_at": "2022-07-18T07:44:54.000000Z",
                "detail": [],
                "seller": {
                    "code": "{SELLER CODE}",
                    "display_name": "Merchant Name"
                },
                "payment_detail": null,
                "queue_number": "0001"
            }
        ],
        "current_page": 1,
        "last_page": 1,
        "total": 1,
        "per_page": 50
    },
    "sign": "{SIGNATURE}",
    "sign_type": "MD5"
}      
              
                    
                

Refund

Available for VISA_MASTER ,Wing Bank, ACLEDA Bank, WeChat and Alipay only.
For refund, Visa Card,Wing Bank,ACLEDA Bank processing time is up to 15 days.

POST {baseUrl}/api/mch/v2/gateway requires authentication

• Sample request
• Sample response

                    
curl --location --request POST '{baseUrl}/api/mch/v2/gateway' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {ACCESS TOKEN}' \
--data-raw '{
    "service": "webpay.acquire.refund",
    "sign_type": "MD5",
    "sign": "{SIGNATURE}",
    "out_trade_no": "TEST-1234567891",
    "reason": "test"
}'
                    
                

                    
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => '{baseUrl}/api/mch/v2/gateway',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
        "service": "webpay.acquire.refund",
        "sign_type": "MD5",
        "sign": "{SIGNATURE}",
        "out_trade_no": "TEST-1234567891",
        "reason" : "test"
    }',
    CURLOPT_HTTPHEADER => array(
        'Content-Type: application/json',
        'Authorization: Bearer {ACCESS TOKEN}' 
    )
));

$response = curl_exec($curl);

curl_close($curl);

echo $response;
                    
                

                    
{
    "success": true,
    "data": {
        "token": "12314666447313d6a2e93676",
        "out_trade_no": "uiJ9GmgznaZNbXadQG57gMnTo",
        "transaction_id": "111612f019b6836bf1255554",
        "body": "Iphone 14 Pro",
        "total_amount": 0.1,
        "currency": "USD",
        "version": 3,
        "status": "REFUNDED",
        "paid_at": "2022-09-21T08:10:23.000000Z",
        "settled_at": null,
        "settlement_date": "2022-09-28T00:00:00.000000Z",
        "expired_at": "2022-09-21T11:07:20.000000Z",
        "created_at": "2022-09-21T08:07:22.000000Z",
        "detail": [],
        "seller": {
            "code": "{SELLER CODE}",
            "display_name": "Merchant Name"
        },
        "payment_detail": {
            "id": 10698,
            "payer_id": 973,
            "method_id": 16,
            "tokenize_id": null,
            "method_desc": "VISA_MASTER,ALIPAY OR WECHAT",
            "holder_name": null,
            "card_info": null,
            "bank_info": null,
            "created_at": "2022-09-21T08:10:23.000000Z",
            "payment_method_bic": "VISA_MASTER,Wing,ACLEDA,ALIPAY OR WECHAT"
        },
        "error_logs": []
    },
    "sign": "{SIGNATURE}",
    "sign_type": "MD5"
}      
              
                    
                

Withdraw (Cash-out)

To withdraw (cash-out) please follow these guidelines:

1. Verify bank account
2. Tokenize bank account
3. Initiate withdrawal transaction

Verify Bank Account

Verify bank account number and pull bank number holder name (use to display to sender).

POST {baseUrl}/api/mch/v2/gateway requires authentication

• Sample request
• Sample response

                    
curl --location --request POST '{baseUrl}/api/mch/v2/gateway' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {ACCESS TOKEN}' \
--data-raw '{
    "service": "webpay.acquire.verifybankaccount",
    "sign": "00afabe1d95f8f671becc626b4785c39",
    "sign_type": "MD5",
    "seller_code": "{SELLER CODE}",
    "bank_account_number": "123456789",
    "bic": "ABAAKHPP"
}'
                    
                

                    
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => '{baseUrl}/api/mch/v2/gateway',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
        "service": "webpay.acquire.verifybankaccount",
        "sign": "00afabe1d95f8f671becc626b4785c39",
        "sign_type": "MD5",
        "seller_code": "{SELLER CODE}",
        "bank_account_number": "123456789",
        "bic": "ABAAKHPP"
    }',
    CURLOPT_HTTPHEADER => array(
        'Content-Type: application/json',
        'Authorization: Bearer {ACCESS TOKEN}' 
    )
));

$response = curl_exec($curl);

curl_close($curl);

echo $response;
                    
                

                    
{
    "success": true,
    "data": {
        "owner_name": "TESTING-ABA-KESS",
        "currency": "USD",
        "account_number": "123456789"
    },
    "sign": "{SIGNATURE}",
    "sign_type": "MD5"
}      
              
                    
                

Tokenize Bank Account

Store bank account numbers with customer information in the KESS system for future usage.

POST {baseUrl}/api/mch/v2/gateway requires authentication

• Sample request
• Sample response

                    
curl --location --request POST '{baseUrl}/api/mch/v2/gateway' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {ACCESS TOKEN}' \
--data-raw '{
    "service": "webpay.acquire.tokenizebankaccount",
    "sign": "79e69e298da1c85cf09366c35e366917",
    "sign_type": "MD5",
    "bank_account_number": "123456789",
    "bic": "ABAAKHPP",
    "seller_code": "{SELLER CODE}",
    "customer": "{ENCRYPTED CUSTOMER DATA}"
}'
                    
                

                    
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => '{baseUrl}/api/mch/v2/gateway',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
        "service": "webpay.acquire.tokenizebankaccount",
        "sign": "79e69e298da1c85cf09366c35e366917",
        "sign_type": "MD5",
        "bank_account_number": "123456789",
        "bic": "ABAAKHPP",
        "seller_code": "{SELLER CODE}",
        "customer": "{ENCRYPTED CUSTOMER DATA}"
    }',
    CURLOPT_HTTPHEADER => array(
        'Content-Type: application/json',
        'Authorization: Bearer {ACCESS TOKEN}' 
    )
));

$response = curl_exec($curl);

curl_close($curl);

echo $response;
                    
                

                    
{
    "success": true,
    "data": {
        "token": "02246c07832b03d22a81551c7e962129c5628301324a0c90a",
        "holder_name": "TESTING-ABA-KESS",
        "account_number": "12****789",
        "bank_bic": "ABAAKHPP",
        "currency": "USD"
    },
    "sign": "{SIGNATURE}",
    "sign_type": "MD5"
}      
              
                    
                

Withdraw

Withdraw from merchant wallet to bank account (tokenized bank account).

Sequence diagram

API specification

POST {baseUrl}/api/mch/v2/gateway requires authentication

• Sample request
• Sample response

                    
curl --location --request POST '{baseUrl}/api/mch/v2/gateway' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {ACCESS TOKEN}' \
--data-raw '{
    "service": "webpay.acquire.withdraw",
    "sign": "79e69e298da1c85cf09366c35e366917",
    "sign_type": "MD5",
    "seller_code": "{SELLER CODE}",
    "bank_account_token": "02246c07832d03d22a81551c7e962129c5628301324a0c90d",
    "out_trade_no": "WD-00000TEST0002",
    "total_amount": 10,
    "currency": "USD",
    "expires_in": 300,
    "customer": "{ENCRYPTED CUSTOMER DATA}"
}'
                    
                

                    
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => '{baseUrl}/api/mch/v2/gateway',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
        "service": "webpay.acquire.withdraw",
        "sign": "79e69e298da1c85cf09366c35e366917",
        "sign_type": "MD5",
        "seller_code": "{SELLER CODE}",
        "bank_account_token": "02246c07832d03d22a81551c7e962129c5628301324a0c90d",
        "out_trade_no": "WD-00000TEST0002",
        "total_amount": 10,
        "currency": "USD",
        "expires_in": 300,
        "customer": "{ENCRYPTED CUSTOMER DATA}"
    }',
    CURLOPT_HTTPHEADER => array(
        'Content-Type: application/json',
        'Authorization: Bearer {ACCESS TOKEN}' 
    )
));

$response = curl_exec($curl);

curl_close($curl);

echo $response;
                    
                

                    
{
    "success": true,
    "data": {
        "token": "UHlHRHk2Nzg462df82a70a8bc",
        "out_trade_no": "WD-00000TEST0002",
        "transaction_id": null,
        "body": "Fund transfer",
        "total_amount": -10,
        "currency": "USD",
        "status": "WAITING",
        "paid_at": null,
        "settled_at": null,
        "settlement_date": null,
        "expired_at": "2022-07-26T06:04:03.000000Z",
        "created_at": "2022-07-26T05:59:03.000000Z",
        "detail": [],
        "seller": {
            "code": "{SELLER CODE}",
            "display_name": "Merchant Name"
        },
        "payment_detail": {
            "id": 8949,
            "payer_id": 793,
            "method_id": 12,
            "tokenize_id": 944,
            "method_desc": "Transfer to customer bank (From Merchant wallet)",
            "holder_name": "airport.taxi",
            "card_info": null,
            "bank_info": null,
            "created_at": "2022-07-26T05:59:03.000000Z",
            "payment_method_bic": "ABAAKHPP",
            "payment_method": {
                "id": 12,
                "title": "ABA PAY",
                "instruction_text": null,
                "type": "tokenize_bank_account",
                "img": "payment-methods/January2021/zNSxh2tYwT9KaNnoQb67.png",
                "app_name": "ABA Mobile",
                "app_logo": null,
                "brand_logo": "payment-methods/August2021/DIoFm9KEvnrnNf6w5Cm4.png",
                "swift_code": "ABAAKHPP",
                "payment_type": "offline",
                "sort_level": "1",
                "emv_enabled": 0,
                "native_pay_enabled": 1,
                "ios_deeplink": "itms-apps://apple.com/app/968860649",
                "android_deeplink": "https://play.google.com/store/apps/details?id=com.paygo24.ibank&hl=en&gl=US",
                "activated": 1,
                "created_at": null,
                "updated_at": "2022-07-01T08:20:05.000000Z",
                "deleted_at": null
            }
        },
        "receiver_name": "Sok Dara",
        "is_required_otp": true,
        "verify_otp_url": "{URL}"
    },
    "sign": "{SIGNATURE}",
    "sign_type": "MD5"
}      
              
                    
                

Signature

Signature algorithm

Sample ...

    
function makeSign(array $param, $key)
{
    $signType = $param['sign_type'];

    $string = toUrlParams($param);
    $string = $string . "&key=".$key;

    if ($signType == "MD5")
        $string = md5($string);
    else if ($signType == "HMAC-SHA256")
        $string = hash_hmac("sha256", $string, $key);

    return $string;
}

function toUrlParams(array $values)
{

    $values = array_filter($values, function ($var) {
        return !is_null($var);
    });

    ksort($values);

    $buff = "";

    foreach ($values as $k => $v)
    {
        if($k != "sign" && $v !== "" && !is_array($v) && !is_object($v)){
            $buff .= $k . "=" . $v . "&";
        }
    }

    $buff = trim($buff, "&");

    return $buff;
}

// Request parameters
$params = json_decode('
{
    "service": "webpay.acquire.directPay",
    "sign_type": "MD5",
    "sign": "{SIGNATURE}",
    "seller_code": "{SELLER CODE}",
    "out_trade_no": "TEST-1234567891",
    "body": "iPhone 13 pro Case",
    "total_amount": 10,
    "currency": "USD",
    "notify_url": "https://sample.com/notifyme",
    "redirect_url": "https://sample.com/redirectme",
    "card": "{ENCRYPTED CARD INFORMATION}"
}
', true);

echo makeSign($params, '{API SECRET KEY}');
    

Objects

Common objects that used in the API Gateway.

setting

customer

    
$rawText = json_encode([
    "phone_number" => "012345678"
    "email" => "sample@sample.com",
    "first_name" => "Sok",
    "last_name" => "Dara"
]);

$publicKey = '-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----
';

openssl_public_encrypt($rawText, $encrypted, $publicKey);

$encrypted_hex = bin2hex($encrypted);

echo $encrypted_hex;
    

transaction

order_info

payment_detail

card

    
$rawText = json_encode([
    "number" => "5473500160001018",
    "securityCode" => "123",
    "expiry" => [
        "month" => "12",
        "year"  => "35"
    ]
]);

$publicKey = '-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----
';

openssl_public_encrypt($rawText, $encrypted, $publicKey);

$encrypted_hex = bin2hex($encrypted);

echo $encrypted_hex;
    

{
    "month": "12",
    "year": "35"
}

payment_method

{
    "ios": "itms-apps://apple.com/app/1518521952",
    "android": "https://play.google.com/store/apps/details?id=io.kessinnovation.kesschat"
}

Redirect Url

Success

Failure Only VISA MASTER

{"gatewayCode": "51","acquirerMessage": "Not sufficient funds"}

Notify Url

Params

{"id":8072,"payer_id":255,"method_id":11,"tokenize_id":null,"method_desc":"KESSKH","holder_name":"Test","card_info":null,"bank_info":null,"created_at":"2022-07-07T09:33:45.000000Z","payment_method_bic":"KESSKH"}

{"card_token":"162847514461108f080312a","swift_code":"VISA_MASTER","card_hashed":"4ccf428eb78130eae273080085cd0add","holder_name":"Test","account_name":"Visa/Master","account_number":"******** **** 0040"}

Visa Token

Url