API Reference
Start typing to search…

Security & Data Integrity

For online payment. The system uses “merchant ID”, “Verify Key” and “Secret Key” to generate encrypted hash string to ensure data integrity in the payment process.


🔑 Verify Key [Confidential]

Verify Key is unique shared secret for PG merchants to generate request to the payment gateway. It is a key or seed for generating one-time hash data, which are known as “vcode” (merchant’s payment request to the gateway) or some of the “skey” (APIs’ request from merchant to the gateway).


How to get the verify key?

  1. Logon to PG Merchant Portal
  2. Open up the “Transaction” drop down list in “MAIN NAVIGATION”.
  3. Clink on “Settings” option
  4. “Verify Key” will be listed at “Integration” tab
  5. Clink on Eye Icon to show the “Verify Key”

•••••• is Merchant’s Verify Key provided by the payment gateway. Please make sure it is at least 32 characters. Merchant may request to change the key when necessary.


🕵 Secret Key [Top Secret]

Secret Key is a unique shared secret for the payment gateway to generate responses to merchants. It is a key or seed for generating one-time hash data, which are known as “skey” (in the payment response) or some of the “VrfKey” (APIs’ response from payment gateway). Merchant or developer MUST NOT disclose this secret key to the public. Once the key is suspected to be compromised, please contact PG customer service immediately to reset the key.

Merchants who are using PG mobile xdk MUST use different strings for “Verify Key”(treat it as public key) and “Secret Key”(treat it like private key), respectively. Contact PG customer service to reset your keys whenever needed.


vcode (in payment request)

vcode is to ensure the data integrity passed from merchant-end (either website or mobile APP) to the payment page to avoid man-in-the-middle (MITM) attack. It uses “Verify Key”(like a public key) in combination with the data string for hashing purposes.

It becomes mandatory for each transaction if “Enable Verify Payment” is activated in merchant profile as shown:

vcode was generated using MD5 encryption hash function and consists of the following information (must be set in the following orders) :

  1. Transaction amount
  2. Merchant ID
  3. Order ID
  4. Verify Key

Extra parameters which are COMPULSORY for merchants accepting multi currency channels. To have these values calculated in the hash. Kindly enable it from Merchant Portal (Transactions -> Settings). Enable the option “Use extended format for Verify Payment” to include the following, which is essential for digital product or instant delivery services:

  1. Currency

Formula to generate vcode

vcode = md5( {amount}{merchantID}{orderID}{verify_key} )

Formula with extended vcode enabled

vcode = md5( {amount}{merchantID}{orderID}{verify_key}{currency} )

Example to generate vcode for PHP developer

<?php

$amount     = “27.60”;
$currency   = “MYR”;
$merchantID = “ACME”;
$orderid    = “OD8842”;
$verifykey  = “f5bb0c8de146c67b44babbf4e6584cc0”;
// Replace f5bb0c8de146c67b44babbf4e6584cc0 with your Verify Key

// vcode formula
//$vcode  = md5( $amount.$merchantID.$orderid.$verifykey ); //extended vcode off
$vcode  	= md5( $amount.$merchantID.$orderid.$verifykey.$currency );

// output of the vcode based on above information equals to :
$vcode  	= “5bf33e6500a53830d4f80087b67e13de”;

?>

Verification tool for vcode

To verify whether the vcode generated is correct, merchant may check on this URL:https://api.fiuu.com/RMS/query/vcode.php


What happens if a merchant passes in an incorrect vcode?

An error will be displayed on the payment page as shown:


skey (in payment response)

skey is a payment gateway generated returning hash string to ensure the payment result data integrity that passed to the merchant system. Merchants or developers MUST verify this hash string properly and compare the order ID, currency, amount, and also the payment date/time, to protect self interest from being cheated by a fraudster/hacker. It uses a “Secret Key”(like a private key) in combination with a data string for the hashing process.

Please note that there are other “skey” with different formulas in Merchant Request APIs’ parameters. Try not to confuse yourself with this payment response “skey”.

skey was encrypted twice using MD5 encryption hash function and consists of the following information (must be set in the following orders):

First hash string

  1. Transaction ID
  2. Order ID
  3. Status
  4. Merchant ID (domain)
  5. Amount
  6. Currency

Final hash string

  1. Payment Date/Time
  2. Merchant ID (domain)
  3. First hash string
  4. Approval Code
  5. Secret Key

Formula to generate skey

pre_skey = md5( {txnID}{orderID}{status}{merchantID}{amount}{currency} )
skey = md5( {paydate}{merchantID}{pre_skey}{appcode}{secret_key} )

Example to generate skey for PHP developer

<?php

$sec_key ="xxxxxxxxxx"; //Replace xxxxxxxxxx with your Secret_Key

/********************************
*Don't change below parameters
********************************/
$tranID 	=	$_POST['tranID'];
$orderid 	=	$_POST['orderid'];
$status 	=	$_POST['status'];
$merchant 	=	$_POST['domain'];
$amount 	=	$_POST['amount'];
$currency 	=	$_POST['currency'];
$appcode 	=	$_POST['appcode'];
$paydate 	=	$_POST['paydate'];
$skey 	              =	$_POST['skey']; //Security hashstring returned by PG

/***********************************************************
* To verify the data integrity sending by PG
************************************************************/
$key0 = md5( $tranID.$orderid.$status.$merchant.$amount.$currency );
$key1 = md5( $paydate.$merchant.$key0.$appcode.$sec_key );
//key1 : Hashstring generated on Merchant system 
// either $merchant or $domain could be one from POST
// and one that predefined internally 
// by right both values should be identical

if( $skey === $key1 ){
  // If matched, perform another extra checking before approved order

} elseif( $skey != $key1 ){
  // If unmatched, reject the order or merchant might send query to
  // PG using Merchant requery to double check payment status
  // for that particular order.
} else { 
  // error or exception case 
}

?>

Domain Registration for Merchant Endpoints

The Return URL, Callback URL, Notify URL and including the Cancel URL are the endpoints that need to be registered. It is important that a merchant register the domain if their endpoints are different from the main website of the business. Failure to do so may result in the merchant not receiving transaction statuses or customers not being redirected to the website when they click the cancel button.


Steps to Register Your Domain

  1. Login to merchant portal

    Navigate to https://portal.fiuu.com

  2. Go to the Domain Registration Page

    Navigate to the domain registration page in your merchant dashboard (UI will be provided).

  3. Enter Your Domain

    Input the domain you wish to use for payment requests. Ensure it is properly formatted and matches the domain you plan to use.

  4. Submit for Verification

    Once entered, submit the domain for verification by our support team.

  5. Verification by Support Team

    Our support team will review your domain. If everything is in order, the domain will be approved. If there are any issues, the registration will be rejected, and you will receive feedback on what needs to be corrected.

  6. Approval and Use

    Once the domain is approved, it will be available for use in payment requests. Ensure that only approved domains are used to avoid any disruptions during transactions