PURCHASE API

Use this API to accept payments from cards, ABA PAY and other alternative payment methods, initiate the transaction by posting the transaction details and its Hash to PayWay

PayWay will create a transaction and respond with a Checkout page or QR value, Deeplink depending on use case.

POSSIBLE USE CASES

Create Transaction API can be used in following scenarios

Card or ABA PAY Checkout on web
Generate QR to display on Screen or print on Receipts or Invoices
Get Deeplink for native mobile app to trigger and launch ABA mobile from Merchant app
Create purchase transaction with saved credentials (Credentials on file) for recurring and non-recurring payments.

API ENDPOINTS

PayWay has separate domain for Production and Sandbox environment, to use Purchase API you must target to correct URL, following are the URL for respective environment.

TESTING URL:

https://checkout-sandbox.payway.com.kh/api/payment-gateway/v1/payments/purchase

PRODUCTION URL:

https://checkout.payway.com.kh/api/payment-gateway/v1/payments/purchase

Method: POST
Content Type: multipart/form-data
Body: form-data

Note:

These APIs are only accessible from a whitelisted domain or IP, Developers need to provide one domain/ IP to PayWay Integration team to whitelist before calling the APIs
Calling API from non-whitelisted domain will return error code “‘6’ wrong domain”
Accessing API directly from browser address bar or calling with GET method will return “405 Method Not Allowed”.
Developer must pass parameters related to the order plus Hash of the parameters to successfully post the transaction to PayWay.
Hash must include all the parameters being posted to PayWay; Developers may choose to skip optional parameters that are not relevant to their usecase.

REQUEST PARAMETERS DESCRIPTION

#	Field name	Data type	Remark	Example
1	language optional	HEADER/ string[2]	Support [en, km] – to be included on header of the request to request Payment page in specific language. en – English km – Khmer	en
2	req_time mandatory	Timestamp [UTC]	Format YYYYmmddHis	20210123234559
3	merchant_id mandatory	String [30]	Merchant ID provided by PayWay Team	onlinesshop24
4	tran_id mandatory	String [20]	Transaction ID – unique order ID	24os-pr0001 or 12345 or OS12345
5	ctid optional	String [255]	Consumer token ID – used when using Credentials on file feature on PayWay
6	pwt optional	String [255]	PayWay token – used when using Credentials on file feature on PayWay
7	firstname optional	String [20]	User this parameter to pass customer name to Payway to record on transaction., Note: no Special character allowed	John or ប៉ហ៊ួ
8	lastname optional	String [20]	User this parameter to pass customer last name to Payway so we can keep record on transaction, Note: no Special character allowed	Doe
9	email optional	String [50]	Email	[email protected]
10	phone optional	String [8-20]	Phone	0900000000
11	amount mandatory	decimal (10, 2)	Total amount	USD 100.00 KHR 10000
12	type optional	String [20]	Possible Values • pre-auth, • Purchase ‘purchase’ is set as default if value is left as blank; Merchant need to pass the value as ‘pre-auth’ to create pre-auth transaction.	purchase
13	payment_option mandatory	String [20]	Available payment option for payment • cards • abapay • abapay_deeplink • wechat • alipay • bakong	abaypay
14	Items optional	String [500]	base64 encode of json object e.g. [{'name':'test','quantity':'1','price':'1.00'}]	W3snbmFtZSc6J3Rlc3QnLCdxdWFudGl0eSc6JzEnLCdwcmljZSc6JzEuMDAnfV0
15	currency optional	String [3]	Possible values • USD – US Dollars • KHR – Khmer Riel ‘USD’ is used as default value if left blank, but for merchants using KHR in Settlement amount need to pass ‘KHR’
16	return_url optional	String [255]	Convert URL to base64 string base64_encode(‘domain.com’)	d3d3LnBheChoduTeriS5jb20ua2gLCdxdW
17	cancel_url optional	String [255]
18	continue_success_url optional	String [255]	Static URL string	www.staticmerchanturl.com
19	return_deeplink optional	String [255]	Merchant can use this link to pass a deeplink so that aba mobile app can pass success message to Merchant app. [Link] [parameters values]	php echo base64_encode('{"ios_scheme":"https://uat-epayment.com.kh/app/?value={\"bankRefId\":\"###BANK_REF###\",\"msgDesc\":\"###MSG_DESC###\",\"msgCode\":\"###MSG_CODE###\",\"transactionId\":\"###TRAN_ID###\"}"}') ?>"/>
20	custom_fields optional	String [255]	Include customer fields, which are not available base64_encode(json_encode({custom_field)));
21	return_param optional	string or json string – can be used for remark or adding a note to the transaction. return_params will be included on payment success callback to merchant.	‘this is a note for transaction’ or ‘mxBorGgaom778oliLLimoBhosD’ or “{‘key’: ‘value’, ‘Key’: ’value’, ‘key’: ‘value’ }”
22	view_type optional	String [255]	To be included on the request to get Payment page for • hosted_view – to redirect to checkout page • native_app – for native app web view. • checkout – to load checkout pop-up without redirecting
23	payment_gate optional	String [255]	• 0 • null
24	payout optional	String [255]	base64_encode of json string
25	optional
26	hash mandatory	Text	Base64 encode of hash hmac sha512 encryption String = req_time + merchant_id + tran_id + amount + items + shipping + ctid + pwt + firstname + lastname + email + phone + type + payment_option + return_url + cancel_url + continue_success_url + return_deeplink + currency + custom_fields + return_params with public_key. Please note to maintain the sequence of parameters as listed above. Ex in PHP: base64_encode(hash_hmac('sha512', string, $public_key, true)); • Step 1 generate hash: (req_time + merchant_id + tran_id + amount + items + gdt + shipping + ctid + pwt + firstname + lastname + email + phone + type + payment_option + return_url + cancel_url + continue_success_url + return_deeplink + topup_channel + currency + custom_fields + return_params) • Step 2 Encrypt with: "[\"sha512_true\”, \"fb629880e9a741dc9862a4ad260f6668\"]"

EXAMPLE REQUEST

Submit required parameter as form-data

Sample of request body


        
{ 
"req_time":"20210123234559",
"merchant_id":"onlinesshop24",
"tran_id":"00002894",
"firstname":"Fristname",
"lastname":"Customer Last name",
"email":"[email protected]",
"phone":"0965965965",
"amount":5000,
"type":"purcahse",
"payment_option":"abapay",
"items":"W3snbmFtZSc6J3Rlc3QnLCdxdWFudGl0eSc6JzEnLCdwcmljZSc6JzEuMDAnfV0=",
"currency":"KHR",
"continue_success_url":"www.staticmerchanturl.com/Success",
"return_deeplink":,
"custom_fields":"{"Purcahse order ref":"Po-MX9901", "Customfield2":"value for custom field"}",
"return_param":"500 Character notes included here will be returned on pushback notification after transaction is successful.",
"hash":"K3nd/2Z4g45Paoqx06QA3UQeHRC2Ts37zjudG7DqyyU2Cq0cvOFMYqwtEsXkaEmNOSiFh6Y+IHRdwnA2WA/M/Qg==
}

EXAMPLE RESPONSE

Response from PayWay Create transaction API differs based on the parameter value of payment_option parameter you pass to PayWay.

DEFAULT CHECKOUT - WEB

For Card payment method on website or WebView on Native app, you’ll pass payment_option value as ‘cards’. PayWay will respond with Card Checkout webpage that you can render in an iFrame on your website or implement WebView on mobile application.

DEEPLINK FOR NATIVE APP

For ABA PAY payment method on mobile app integration you will pass payment_option value as ‘abapay_deeplink’ . PayWay will then respond with Deeplink to ABA mobile with the unique transaction values that you can use launch ABA mobile to complete payment.

Notes

Call as Rest API
Include header referrer on the request.

EXAMPLE REQUEST

To receive abapay_deeplink that you can use to native app integration, use Purchase API with payment_option as abapay_deeplink.

EXAMPLE RESPONSE

Sample of request body


        
{
 "status": {"code":"00","message":"Success!"},
 "description":"success",
 "qrString":"ABA1004512511032001203116131016327983181421Merchant040a367f91e5643bf2eac8a486ef87c82cbc12d2374",
 "abapay_deeplink":"abamobilebank://ababank.com?type=payway&qrcode=ABA100451256327983181421Foreigner2d2374",
 "app_store":"https://itunes.apple.com/al/app/aba-mobile-bank/id968860649?mt=8",
 "play_store":"https://play.google.com/store/apps/details?id=com.paygo24.ibank"
}

HANDLE RESPONSE

Use the following code snippet to handle deeplink from PayWay API response to open ABA mobile to complete payment.

Android
iOS


// private fun openDeepLink(qrString: String) {
	  try {
        val url = "{ABA_SCHEME}://{ABA_DOMAIN}?type=payway&qrcode={qrString}"         
        val intent = Intent(Intent.ACTION_VIEW, Uri.parse(url))
        startActivity(intent)
      } catch (ex: Exception) {
        val intent: Intent = Intent(Intent.ACTION_VIEW).apply {
            intent.data = Uri.parse("market://details?id=com.paygo24.ibank")
        }
        startActivity(intent)
      }
      finish()
    }
	  companion object {
        const val ABA_SCHEME = "abamobilebank"     
 	    const val ABA_DOMAIN = "ababank.com"
  	  }


    // model - mapping from API response
    // - deeplink - ABA mobile app scheme Or  Appstore - ABA mobile app store link
	guard 
	let deeplinkURL = URL(string: model.deeplink), 
	let appStoreURL = URL(string: model.appStore) else {
	// Something went wrong, check url respond from API.
	 return}
    UIApplication.shared.open(deeplinkURL, options: [:]) { success in  if !success
	// Open app store
	UIApplication.shared.open(appStoreURL, options: [:]) } }

CHECKOUT ERROR CODE

Error Code	Error Description
1	Invalid Hash, Hash generated is incorrect and not following the guideline to generate the Hash.
2	Invalid Transaction ID, unsupported characters included in Transaction ID
3	Invalid Amount format need not include decimal point for KHR transaction. example for USD 100.00 for KHR 100
4	Duplicate Transaction ID, the transaction ID already exists in PayWay, generate new transaction.
5	Invalid Continue Success URL, (Domain must be registered in PayWay backend to use success URL)
6	Invalid Domain Name (Request originated from non-whitelisted domain need to register domain in PayWay backend)
7	Invalid Return Param (String must be lesser than 500 chars)
8	-
9	Invalid Limit Amount (The amount must be smaller than value that allowed in PayWay backend)
10	Invalid Shipping Amount
11	PayWay Server Side Error
12	Invalid Currency Type (Merchant is allowed only one currency - USD or KHR)
13	Invalid Item, value for items parameters not following the guideline to generate the base64 encoded array of item list.
14	-
15	Invalid Channel Values for parameter topup_channel
16	Invalid First Name - unsupported special characters included in value
17	Invalid Last Name
18	Invalid Phone Number
19	Invalid Email Address
20	Required purchase details when checkout
21	Expired production key