PayWay - Checkout

### Encode Additional Parameters for WeChat Mini Program in PHP Source: https://developer.payway.com.kh/purchase-14530820e0/index This code snippet shows how to Base64 encode additional parameters required for WeChat Mini Program integration. It includes placeholders for your WeChat App ID and Open ID. ```php $additional_params = base64_encode(json_encode([ 'wechat_sub_appid' => 'YOUR WECHAT APP ID', 'wechat_sub_openid' => 'YOUR WECHAT OPEN ID' ])); ``` -------------------------------- ### Purchase API Endpoint Source: https://developer.payway.com.kh/purchase-14530820e0/index This endpoint facilitates the creation of a purchase transaction through the PayWay system. It requires various parameters to define the transaction details, including merchant information, transaction ID, amount, and security hash. ```APIDOC ## POST /purchase ### Description This endpoint is used to initiate a purchase transaction. It requires a comprehensive set of parameters to define the transaction details, including merchant information, transaction identifiers, amounts, and security credentials. ### Method POST ### Endpoint /purchase ### Parameters #### Query Parameters - **req_time** (string) - Required - The timestamp of the request. - **merchant_id** (string) - Required - The unique identifier for the merchant. - **tran_id** (string) - Required - The unique transaction identifier. - **amount** (number) - Required - The transaction amount. - **items** (string) - Optional - A description of the items being purchased. - **shipping** (string) - Optional - Shipping details. - **firstname** (string) - Optional - The customer's first name. - **lastname** (string) - Optional - The customer's last name. - **email** (string) - Optional - The customer's email address. - **phone** (string) - Optional - The customer's phone number. - **type** (string) - Optional - The transaction type. - **payment_option** (string) - Optional - The payment method to be used. - **return_url** (string) - Optional - The URL to redirect to upon successful payment. - **cancel_url** (string) - Optional - The URL to redirect to if the payment is cancelled. - **continue_success_url** (string) - Optional - The URL to redirect to after a successful payment. - **return_deeplink** (string) - Optional - A deep link for returning to the application. - **currency** (string) - Optional - The currency of the transaction. - **custom_fields** (string) - Optional - Custom fields for additional data. - **return_params** (string) - Optional - Parameters to be returned with the response. - **payout** (string) - Optional - Base64-encoded JSON string representing payout details. - **lifetime** (integer) - Optional - The payment's lifetime in minutes. Default is 30 days. - **additional_params** (string) - Optional - Additional parameters, such as WeChat Mini Program details. - **google_pay_token** (string) - Optional - Required if `payment_option` is `google_pay` and payment selection is merchant-managed. - **skip_success_page** (string) - Optional - Flag to skip the success page. - **hash** (string) - Required - Base64 encoded HMAC SHA512 hash of concatenated request parameters and the public key. ### Request Example ```json { "req_time": "2023-10-27T10:00:00Z", "merchant_id": "MERCHANT123", "tran_id": "TRANS456", "amount": 100.50, "items": "Product A, Product B", "email": "customer@example.com", "phone": "1234567890", "return_url": "https://example.com/return", "cancel_url": "https://example.com/cancel", "payout": "eyJ1c2VyIjogImFjY291bnRfaWQiIH0=", "additional_params": "eyJ3ZWNoYXRfc3ViX2FwcGlkIjogIlhYWFhYWFhYWFhYIiwgIndlY2hhdF9zdWJfb3Blbm9pZCI6ICJZTllOWU5OW55OSJ9", "hash": "YOUR_GENERATED_HASH" } ``` ### Response #### Success Response (200) - **01JME5PQCH7BA4JH9V9C51N1FV** (string) - A unique identifier or status code for the transaction. #### Response Example ```html PayWay - Checkout ... ... ``` ``` -------------------------------- ### Purchase Transaction API Source: https://developer.payway.com.kh/purchase-14530820e0/index Initiates a purchase transaction with PayWay. This endpoint accepts various parameters to configure the payment process, including amounts, currency, return URLs, and custom fields. ```APIDOC ## POST /purchase ### Description Initiates a purchase transaction with PayWay. This endpoint accepts various parameters to configure the payment process, including amounts, currency, return URLs, and custom fields. ### Method POST ### Endpoint /purchase ### Parameters #### Request Body - **shipping** (number) - Optional - Shipping fee. - **amount** (number) - Required - Purchase amount. - **currency** (string) - Required - Transaction currency of the payment. Supported values are `KHR` or `USD`. - **return_url** (string) - Required - URL to receive callbacks upon payment completion, encrypted with Base64. - **cancel_url** (string) - Optional - The URL to redirect to after the user closes the payment dialog or when user cancels the payment. - **skip_success_page** (integer) - Optional - Skip success page. Supported value: `0` (Don't skip success pages), `1` (Skip success page). - **continue_success_url** (string) - Optional - The URL to redirect to after a successful payment. - **return_deeplink** (string) - Optional - The deep link for redirecting to the app after a successful payment from ABA Mobile. Must be base64-encoded. - **custom_fields** (string) - Optional - Additional information to attach to the transaction. It's base64-encoded JSON info. - **return_params** (string) - Optional - Information to include when PayWay calls your return URL after a successful payment. - **view_type** (string) - Optional - Defines the view type for the payment page. Supported values: `hosted_view`, `popup`. - **payment_gate** (integer) - Optional - If your merchant profile also supports the QR Payment API service, please set this parameter to `0` to use the Checkout service. ### Request Example ```json { "amount": 100, "currency": "USD", "return_url": "aHR0cHM6Ly9leGFtcGxlLmNvbS9yZXR1cm4=", "cancel_url": "aHR0cHM6Ly9leGFtcGxlLmNvbS9jYW5jZWw=", "skip_success_page": 0, "continue_success_url": "aHR0cHM6Ly9leGFtcGxlLmNvbS9jb250aW51ZQ==", "return_deeplink": "eyJpb3Nfc2NoZW1lIjogIkRFRUxMSU5LIFRPIFJFVEVSTiBUTyBZT1VS$JOS$QVBQIiwgImFuZHJvaWRfc2NoZW1lIjogIkRFRUxMSU5LIFRPIFJFVEVSTiBUTyBZT1VSJ05EUk9JRF9BUFA=" } ``` ### Response #### Success Response (200) - **transaction_id** (string) - The unique identifier for the transaction. - **payment_url** (string) - The URL to redirect the user to for completing the payment. #### Response Example ```json { "transaction_id": "txn_12345abcde", "payment_url": "https://payway.kh/pay?token=xyz789" } ``` ``` -------------------------------- ### POST /api/payment-gateway/v1/payments/purchase Source: https://developer.payway.com.kh/purchase-14530820e0/index Initiates a payment transaction between a customer and a merchant through PayWay. After the API call, the customer is redirected to PayWay’s hosted checkout page to complete the payment. ```APIDOC ## POST /api/payment-gateway/v1/payments/purchase ### Description Initiates a payment transaction between a customer and a merchant through PayWay. It allows merchants to request a payment by providing transaction details such as the amount, currency, item list, and other relevant data. Once the API is called, the customer is redirected to PayWay’s hosted checkout page, bottom sheet, or modal popup—depending on your integration option—where they can complete the payment using the available methods (e.g., card, ABA PAY, KHQR, digital wallets). After the transaction is completed, PayWay will return the transaction result to the merchant via the configured return URL or callback. ### Method POST ### Endpoint /api/payment-gateway/v1/payments/purchase ### Parameters #### Header Parameters - **Content-Type** (string) - Required - Example: `multipart/form-data` #### Request Body - **req_time** (string) - Required - Request date and time in UTC format as YYYYMMDDHHmmss. - **merchant_id** (string) - Required - A unique merchant key provided by ABA Bank. Max length: 30. - **tran_id** (string) - Required - A unique transaction identifier for the payment. Max length: 20. - **firstname** (string) - Optional - Buyer's first name. Max length: 100. - **lastname** (string) - Optional - Buyer's last name. Max length: 100. - **email** (string) - Optional - Buyer's email. Max length: 50. - **phone** (string) - Optional - Buyer's phone. Max length: 20. - **type** (string) - Optional - Type of the transaction, default value is `purchase`. Supported values: `pre-auth`, `purchase`. Note: `pre-auth` only supports ABA PAY, KHQR, and Card Payment. Max length: 20. - **payment_option** (string) - Optional - Specifies the payment method for the transaction. Supported values: `cards`, `abapay_khqr`, `abapay_khqr_deeplink`, `alipay`, `wechat`, `google_pay`. If no value is provided, the payment gateway will automatically display supported payment options. Max length: 20. - **items** (string) - Required - A base64-encoded JSON array describing the items being purchased. Max length: 500. ### Request Example ```json { "req_time": "20231027103000", "merchant_id": "M12345", "tran_id": "T98765", "firstname": "John", "lastname": "Doe", "email": "john.doe@example.com", "phone": "+85512345678", "type": "purchase", "payment_option": "abapay_khqr", "items": "W3sibmFtZSI6InByb2R1Y3QgMSIsInF1YW50aXR5IjogMSwicHJpY2UiOiAxLjAwfSx7Im5hbWUiOiJwcm9kdWN0IDIiLCJxdWFudGl0eSI6MiwicHJpY2UiOiA0LjAwfV0=" } ``` ### Response #### Success Response (200) - **status** (string) - Transaction status. - **message** (string) - Transaction message. - **transaction_id** (string) - Unique identifier for the transaction. - **payment_url** (string) - URL for completing the payment (if applicable). - **qr_string** (string) - QR code string for payment (if applicable). - **abapay_deeplink** (string) - Deep link for ABA PAY (if applicable). - **checkout_qr_url** (string) - URL for the checkout QR code page (if applicable). #### Response Example ```json { "status": "SUCCESS", "message": "Transaction initiated successfully.", "transaction_id": "TXN123456789", "payment_url": "https://payway.aba.com/checkout/TXN123456789", "qr_string": "ABAQRCODE...", "abapay_deeplink": "abapay://payment?data=...", "checkout_qr_url": "https://payway.aba.com/qr/TXN123456789" } ``` ``` -------------------------------- ### Encode Items for PayWay Purchase API (PHP) Source: https://developer.payway.com.kh/purchase-14530820e0/index This snippet demonstrates how to format and encode the 'items' parameter for the PayWay Purchase API using PHP. It involves creating a JSON array of items and then base64 encoding it. ```yaml items: type: string maxLength: 500 description: >- A base64-encoded JSON array describing the items being purchased. **PHP Sample Code** ```php $item = base64_encode(json_encode([ ["name" => "product 1","quantity" => 1,"price" => 1.00], ["name" => "product 2","quantity" => 2, "price" => 4.00] ])); ``` ``` ```php $item = base64_encode(json_encode([ ["name" => "product 1","quantity" => 1,"price" => 1.00], ["name" => "product 2","quantity" => 2, "price" => 4.00] ])); ``` -------------------------------- ### PayWay KH Purchase - Exception Response Source: https://developer.payway.com.kh/purchase-14530820e0/index Handles exception scenarios for PayWay KH purchase transactions, detailing various error codes and their meanings. ```APIDOC ## POST /websites/developer_payway_kh_purchase-14530820e0 ### Description Handles exception scenarios for PayWay KH purchase transactions, detailing various error codes and their meanings. ### Method POST ### Endpoint /websites/developer_payway_kh_purchase-14530820e0 ### Parameters #### Query Parameters None #### Request Body None specified in the provided documentation. ### Request Example ```json { "example": "No request body example provided." } ``` ### Response #### Error Response (Non-200 Status Codes) - **status** (object) - Contains the status code, message, and transaction ID. - **code** (integer) - Error code indicating the nature of the failure. Possible values include: - `0`: Success - `1`: Wrong hash - `2`: Invalid transaction ID - `3`: Invalid transaction amount - `4`: Duplicated transaction ID - `5`: Transaction not found - `6`: Requested domain is not in whitelist - `7`: Wrong return param - `8`: Something went wrong while saving data. Please try again later or contact merchant for help. - `10`: Wrong shipping price - `11`: Something went wrong. Try again or contact the merchant for help. - `12`: Payment currency is not allowed - `13`: Invalid items - `14`: Invalid credit multi acc - `15`: Invalid or missing channel values from smart merchant - `16`: Invalid first name. It must not contain numbers or special characters or not more than 100 characters. - `17`: Invalid last name. It must not contain numbers or special characters or not more than 100 characters. - `18`: Invalid phone number - `19`: Invalid email - `20`: Something went wrong. Please contact merchant. - `21`: End of API lifetime - `22`: Pre-auth transaction is not enabled - `23`: Selected payment option is not enabled for this merchant profile - `24`: Cannot decrypt data - `25`: Allow maximum 10 payout per requests - `26`: Invalid merchant profile - `27`: Invalid ctid - `28`: Invalid pwt - `29`: Invalid pwt or ctid - `30`: Merchant is not enabled COF - `31`: Unsecure 3Ds page - `33`: Cannot identify cardOrigin - **message** (string) - Description of the error. - **tran_id** (string) - Unique identifier for the transaction (if applicable). #### Response Example ```json { "status": { "code": 2, "message": "Invalid transaction ID", "tran_id": "trx-invalid-id" } } ``` ``` -------------------------------- ### Encode Payout Details in PHP Source: https://developer.payway.com.kh/purchase-14530820e0/index This snippet demonstrates how to create a Base64-encoded JSON string representing payout details. It takes an array of account and amount pairs and encodes them for use with the PayWay API. ```php $payout = base64_encode(json_encode([ ["acc" => "000133879","amt"=> 1], ["acc" => "000133880","amt" => 1] ])); ``` -------------------------------- ### Encode Return Deeplink for ABA Mobile (PHP) Source: https://developer.payway.com.kh/purchase-14530820e0/index This snippet demonstrates how to properly encode the return deeplink for ABA Mobile integration. It ensures that both iOS and Android schemes are included in a base64-encoded JSON format, which is mandatory for mobile transactions. ```php $return_deeplink = base64_encode(json_encode([ "ios_scheme" => "DEEPLINK TO RETURN TO YOUR IOS APP", "android_scheme" => "DEEPLINK TO RETURN TO YOUR ANDROID APP" ])); ``` -------------------------------- ### Payway Kh Purchase API Error Codes Source: https://developer.payway.com.kh/purchase-14530820e0/index This section details the various error codes returned by the Payway Kh purchase API, along with their corresponding descriptions. ```APIDOC ## Payway Kh Purchase API Error Codes ### Description This section details the various error codes returned by the Payway Kh purchase API, along with their corresponding descriptions. ### Method N/A (This is a reference for error codes, not a specific endpoint) ### Endpoint N/A ### Parameters N/A ### Request Example N/A ### Response #### Error Codes and Messages - **`80`** (string) - Failed to decrypt the payment token provided by Google Pay - **`81`** (string) - The return URL is not in the whitelist - **`82`** (string) - The payout has exceeded the maximum allowable amount per transaction - **`83`** (string) - Payment credential is disabled - **`84`** (string) - Payment credential is expired - **`85`** (string) - Purchase reach limit amount per transaction - **`86`** (string) - Unsupported merchant purchase mode - **`87`** (string) - Payment credential is removed - **`200`** (string) - Payment was canceled - **`201`** (string) - Payment was declined - **`401`** (string) - Unauthorized access - **`403`** (string) - Something went wrong. Try again or contact the merchant for help. - **`429`** (string) - Too many requests, please try again in 1min. - **`503`** (string) - System under maintenance #### Response Example ```json { "status": { "code": "80", "message": "Failed to decrypt the payment token provided by Google Pay" } } ``` ``` -------------------------------- ### PayWay KH Purchase - Success Response Source: https://developer.payway.com.kh/purchase-14530820e0/index This endpoint handles successful purchase transactions via PayWay KH, returning transaction details and payment links. ```APIDOC ## POST /websites/developer_payway_kh_purchase-14530820e0 ### Description Handles successful purchase transactions via PayWay KH, returning transaction details and payment links. ### Method POST ### Endpoint /websites/developer_payway_kh_purchase-14530820e0 ### Parameters #### Query Parameters None #### Request Body None specified in the provided documentation. ### Request Example ```json { "example": "No request body example provided." } ``` ### Response #### Success Response (200 OK) - **status** (object) - Contains the status code, message, and transaction ID. - **code** (string) - Status code of the transaction. - **message** (string) - Message indicating the success of the transaction. - **tran_id** (string) - Unique identifier for the transaction. - **qr_string** (string) - The QR code string for payment. - **abapay_deeplink** (string) - A deep link for initiating payment via ABA Pay. - **checkout_qr_url** (string) - A URL for displaying the checkout QR code. #### Response Example ```json { "status": { "code": "00", "message": "Success!", "tran_id": "trx-20201019130949" }, "qr_string": "00020101021230510016abaakhppxxx@abaa01153250212100849350208ABA Bank520410165...", "abapay_deeplink": "abamobilebank://ababank.com?type=payway&qrcode=00020101021230510016...", "checkout_qr_url": "https://checkout-uat.payway.com.kh/eyJzdGF0dXMiOnsiY29kZSI6IjAwIiw..." } ``` ``` -------------------------------- ### Generate HMAC SHA512 Hash for API Requests in PHP Source: https://developer.payway.com.kh/purchase-14530820e0/index This PHP code generates a Base64 encoded HMAC SHA512 hash required for securing API requests. It concatenates various transaction details and encrypts them using a provided public key. ```php // public key provided by ABA Bank $api_key = "API KEY PROVIDED BY ABA BANK"; // Prepare the data to be hashed $b4hash = $req_time . $merchant_id . $tran_id . $amount . $items . $shipping . $firstname . $lastname . $email . $phone . $type . $payment_option . $return_url . $cancel_url . $continue_success_url . $return_deeplink . $currency . $custom_fields . $return_params . $payout . $lifetime . $additional_params . $google_pay_token .$skip_success_page; // Generate the HMAC hash using SHA-512 and encode it in // Base64 $hash = base64_encode(hash_hmac('sha512', $b4hash, $api_key, true)); ``` -------------------------------- ### PayWay KH Purchase API Success Response Source: https://developer.payway.com.kh/purchase-14530820e0/index This JSON object represents a successful purchase transaction through the PayWay KH API. It includes a status object with a success code and message, a QR string for payment, a deep link for the ABA Pay app, and a URL for checkout QR code display. This response is typically returned when a transaction is processed without errors. ```json { "status": { "code": "00", "message": "Success!", "tran_id": "trx-20201019130949" }, "qr_string": "00020101021230510016abaakhppxxx@abaa01153250212100849350208ABA Bank520410165...", "abapay_deeplink": "abamobilebank://ababank.com?type=payway&qrcode=00020101021230510016...", "checkout_qr_url": "https://checkout-uat.payway.com.kh/eyJzdGF0dXMiOnsiY29kZSI6IjAwIiw..." } ``` -------------------------------- ### PayWay KH Purchase API Exception Status Codes Source: https://developer.payway.com.kh/purchase-14530820e0/index This JSON schema defines the structure for exception responses from the PayWay KH API. The 'status.code' property is an integer representing various error conditions, such as invalid transaction IDs, wrong hashes, or payment processing issues. Each code has a corresponding descriptive message indicating the nature of the error. ```json { "status": { "code": 1, "message": "Wrong hash" } } ``` -------------------------------- ### Encode Custom Fields for Transactions (PHP) Source: https://developer.payway.com.kh/purchase-14530820e0/index This code snippet shows how to encode additional transaction information using base64 encoding of a JSON object. These custom fields can be attached to transactions and will be visible in transaction lists, details, and reports. ```php $custom_field = base64_encode(json_encode([ "field1" => "myvalue1", "field2" => "myvalue2" ])); ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.