INTRODUCTION

FYI:We made this API to fit the needs of our cooperated partner to transfer funds to our user wallet with secure transactions.

Business process model

alt
alt

GET ACCESS TOKEN

Before you can access our API gateway you need to use the generated access token from our OAuth2 API. Make sure before you use our API gateway the access token does not expire.

API Introduction

Request url (sandbox): https://clientdev.kesspay.io/partnerapi/v1/token

Request url (sandbox): POST

Headers

Field Type Required Description
partner-id String(64) YES Your partner id provide by KESS
partner-secret-key String(128) YES Your partner secret key provided by KESS

Parameters

Field Type Required Description
user_name String(64) YES our partner api user name provided by KESS
password String(64) YES Your partner api password provided by KESS

Response data

Field Type Description
access_token Text(1200) OAuth 2 access token
expire_in Integer OAuth 2 access token expire time in second

Response fail

Field Type Description
success Boolean The API response status (false).
error_code String(32) UNAUTHENTICATED
error_desc Text Unauthorized

Error code review

HttpCode: 401, UNAUTHENTICATED : Unauthorized (Invalid credential)

API GETEWAY SPECIFICATION

We designed the easy way for our partners to integrate all API services in just one route. What you need to do is know the API service name and use its parameters dynamically based on its service name.

API Introduction

Request url (sandbox): https://clientdev.kesspay.io/partnerapi/v1/gateway

Request url (sandbox): POST

Headers

Field Type Required Description
Authorization String(1200) YES Bearer {access_token}

Sample Parameters

Field Type Required Description
service String(64) YES API gateway service name
sign_type String(10) YES The signature algorithm
... ... ... ...
sign String Yes Generated signature based on sign_type and request parameters from your server.

Sample success response

Field Type Description
success Boolean The API response status (true).
code Number Http response code.
message Text Response code description.
data Object Response data.
sign_type String(10) The signature algorithm.
sign String Use it to verify the incoming response from the API.

Sample fail response

Field Type Description
success Boolean The API response status (false).
error_code String(32) The API response error code.
error_desc Text Error description.
sign_type String(10) Signature type. No for UNAUTHENTICATED
sign String Use it to verify the incoming response from the API. No for UNAUTHENTICATED

FUND TRANSFER

  • Fund transfer is an option that our partners use to transfer funds from their user account’s wallet to our user’s wallet in real time. We have two different steps to complete the fund transfer process.
  • Firstly, you need to request to create a unified fund transfer (pre-fund transfer) and you will get the pre-transfer ID and our user’s name to show your customer to make a confirmation.
  • After that, you just need to DEBIT your customer wallet and request the confirmation fund transfer to the API server to finalize the process.

CREATE UNIFIED FUND TRANSFER

Important note: This is the first step of the fund transfer process, we can also call it “Create pre fund transfer”. Its life time’s duration starts from the time created in second that we will return with the response data field expire_in = number of second. After the expiration you can not use it to confirm the fund transfer request (#4.2).

API Introduction

Request url (sandbox): https://clientdev.kesspay.io/partnerapi/v1/gateway

Request url (sandbox): POST

Service name: create.unified.fundTransfer

Headers

Field Type Required Description
Authorization String(1200) YES Bearer {access_token}

Sample Parameters

Field Type Required Description
service String(64) YES Value: create.unified.fundTransfer
sign_type String(10) YES The signature algorithm.
out_trade_no Alpha(64) Yes Your transfert unique reference number.
receiver_id Alpha(25) Yes KESS user ID or phone number.
sender_name String(96) YES Partner’s customer (sender) name.
amount Double YES Transfer amount. Ex: 0.50
currency Char(3) Yes Only USD allowed.
sign String Yes Generated signature based on sign_type and request parameters.

Response success data

Field Type Description
out_trade_no Alpha(64) Your unique reference ID.
receiver_id Alpha(25) KESS user ID or phone number.
amount Double Transfer amount. Ex: 0.50
currency Char(3) Value: KHR/USD
pre_transfer_id Alpha(64) Unified unique ID - use it for transfer confirmation.
receiver_name String(96) Receiver name - show this name to sender for making a confirmation.
expire_in Integer The expiration time of created unified fund transfer in second.

Response fail

Field Type Description
success Boolean False
sign_type String(10) The signature algorithm
error_code String(32 NOTELIGIBLE/VALIDATIONERROR/SYSTEMERROR
error_desc Text The reason for the error.
sign String Generated signature based on sign_type and response body.

Error code review

HttpCode: 400, NOTELIGIBLE: Receiver is not eligible for the fund.

HttpCode: 400, VALIDATIONERROR: Parameters validation incorrect.

HttpCode: 500, SYSTEMERROR: Server error or busy.

CONFIRM FUND TRANSFER

API Introduction

Request url (sandbox): https://clientdev.kesspay.io/partnerapi/v1/gateway

Request url (sandbox): POST

Service name: confirm.fundTransfer

Headers

Field Type Required Description
Authorization String(1200) YES Bearer {access_token}

Sample Parameters

Pre transfer ID got from created unified fund transfer.
Field Type Required Description
service String(64) YES Value: confirm.fundTransfer
sign_type String(10) YES The signature algorithm.
partner_transaction_id Alpha(64) Yes Your unique transaction ID of SUCCEED transaction between your customer and KESS bank account.
pre_transfer_id Alpha(64) YesKESS user ID or phone number.
sign String Yes Generated signature based on sign_type and request parameters.

Response success data

Field Type Description
result_code String(32) SUCCESS.
fund_transfer_id Alpha(64) Fund transferred ID after CREDIT the receiver SUCCEED.
out_trade_no Alpha(64) Your unique reference ID.
receiver_id Alpha(25) KESS user ID or phone number.
pre_transfer_id Alpha(64) Unified unique ID - use it for transfer confirmation.
amount Double Transfer amount. Ex: 0.50
currency Char(3) Value: KHR/USD
receiver_name String(96) Receiver name - show this name to sender for making a confirmation.

Response fail

Field Type Description
success Boolean False
sign_type String(10) The signature algorithm
error_code String(32 USED/NOTEXIST/EXPIRED/VALIDATIONERROR/SYSTEMERROR
error_desc String The reason for the error.
sign String Generated signature based on sign_type and response body.

Error code review

HttpCode: 400, USED: Pre fund transfer ID is used.

HttpCode: 400, NOTEXIST: Wrong pre transfer ID, or invalid string.

HttpCode: 400, EXPIRED: Unified fund transfer is expired.

HttpCode: 400, VALIDATIONERROR: Validation error field value is invalid.

HttpCode: 500, SYSTEMERROR: Server error or busy.

QUERY FUND TRANSFER

API Introduction

Request url (sandbox):https://clientdev.kesspay.io/partnerapi/v1/gateway

Request url (sandbox): POST

Service name: query.fundTransfer

Headers

Field Type Required Description
Authorization String(1200) YES Bearer {access_token}

Parameters

Field Type Required Description
service String(64) YES Value: query.fundTransfer
sign_type String(10) YES The signature algorithm.
out_trade_no Alpha(64) Yes Your unique reference ID that used to create unified fund transfer.
sign String Yes Generated signature based on sign_type and request parameters.

Response success data

Field Type Description
result_code String(32) SUCCESS.
fund_transfer_id Alpha(64) Fund transferred ID after CREDIT the receiver SUCCEED. *Note: available for the result_code = SUCCESS only.
out_trade_no Alpha(64) Your unique reference ID.
amount Double Transfer amount. Ex: 0.50
currency Char(3) Value: KHR/USD
receiver_id Alpha(25) KESS user ID or phone number.
receiver_name String(96) Receiver name - show this name to sender for making a confirmation.

Response fail

Field Type Description
success Boolean False
sign_type String(10) The signature algorithm
error_code String(32 USED/NOTEXIST/EXPIRED/VALIDATIONERROR/SYSTEMERROR
error_desc String The reason for the error.
sign String Generated signature based on sign_type and response body.

Error code review

HttpCode: 400, NOTEXIST: Wrong pre transfer ID, or invalid string.

HttpCode: 400, EXPIRED: Unified fund transfer is expired.

HttpCode: 400, VALIDATIONERROR: Validation error field value is invalid.

HttpCode: 500, SYSTEMERROR: Server error or busy.

Signature algorithm (PHP)

<?php

class RSA2

{

private static $PRIVATE_KEY = '{private key path}';

private static $PUBLIC_KEY = '{public key path}';

/**

* Get private key

* @return bool|resource

*/

private static function getPrivateKey()

{

return file_get_contents(self: : $PRIVATE_KEY);

}

/**

* Get public key

* @return bool|resource

*/

private static function getPublicKey()

{

return file_get_contents(self: : $PUBLIC_KEY);

}

/**

* Parse array to string

* @param array $data data

* @return string

*/

private static function toString(array $data)

{

ksort($data);

unset($data['sign_type'], $data['sign']);

return json_encode($data);

}

/**

* Create signature

* @param array $data data

* @return null|string

*/

public function createSign(array $data = [])

{

return openssl_sign(

self:: toString($data),

$sign,

self:: getPrivateKey(),

OPENSSL_ALGO_SHA256

) ? base64_encode($sign) : null;

}

/**

* Verifying signature

* @param array $data data

* @param string $sign autograph

* @return bool

*/

public function verifySign(array $data = [], string $sign = '')

{

return (bool) openssl_verify(

self: : toString($data),

base64_decode($sign),

self: : getPublicKey(),

OPENSSL_ALGO_SHA256

);

}

}

Make signature

$rsa2 = new RSA2();

$params['sign'] = $rsa2->createSign($params);

Verify signature

$rsa2 = new RSA2();

$isValidResponse = $rsa2->verifySign($response, $response['sign']);