Requirement Needed To Use The API

In order to use the API, you will need to get the following credentials ready. The credentials can be retrieved in Pay Direct FPX Payment Gateway portal, under Manage API Tab. Get your FPX Seller ID, API Key information and Merchant ID as sample below. These information are extremely sensitive. Do not disclose to anyone.




How Do I Send My Payment Request To Pay Direct FPX Payment Gateway?

In order to send your payment request through our Payment Gateway, please follow the following format. The field name specified in the following table are mandatory or optional. The following fields are to be sent to our Payment Gateway using POST method.

Payment Gateway URL (endpoint):
Sandbox :{We will provide it once you signup with sandbox account}
Live Production : {We will provide it once you signup with sandbox account}


1) Required fields

This is required fields by our payment gateway. Please make sure all fields have valid value and correct hashing value. Send the data to the Sandbox or Live Production End Point.

Field Name Description Format
merchant_id This refers to merchant ID. Eg: 100001 Accept only numbers. This already pre-defined by the system.
invoice This refers to your uniquely generated invoice number. Eg: INV10124566 Accept alphabets, numbers and some special characters. The invoice characters must less than or equal to 18 characters and do not support ampersand(&), apostrophe(') and dash(-)
amount Specify total amount payable by the buyer, including all taxes and other charges if applicable. Must be in 2 decimal places (d.p) format. Eg: 1289.00
payment_desc This refers to the purpose of the payment.Eg: Parking Fee Accepts only alphabets and numbers. Do not support exclamation mark (!)
hash This is the secure hash string to validate the payment request sent through our Payment Gateway. Refer to the Securing section for more info on how to generate the secure hash string Accepts only alphabets and numbers.

2) Optional fields

This is OPTIONAL fields. Set this as null or remove it if or remove it if not required.


Field Name Description Format
buyer_name
(optional)
This refers to buyer's name. It's optional. Can be a null value. Accept only alphabets.
buyer_email
(optional)
This refers to buyer's email. It's optional. Can be a null value. Require a valid email address.
phone
(optional)
This refers to buyer's phone number. It's optional. Can be a null value. Accept only numbers and (+) symbol.
add_line_1
(optional)
This refers to buyer's address for line number 1 Accept only alphabets and numerics.
add_line_2
(optional)
This refers to buyer's address for line number 2 Accept only alphabets and numerics.
postcode
(optional)
This refers to buyer's postcode Accept only alphabets and numerics.
city
(optional)
This refers to buyer's city location Accept only alphabets and numerics.
comment
(optional)
Let buyer to leave any comment Accept only alphabets and numerics.


3) Optional Callback URL fields

This is OPTIONAL fields which are your callback url for back-end and front-end process. This fields will override the entries specified in your merchant dashboard. If not specified, we will use the entry in your merchant dashboard. This allow merchant to provide multiple web stores different back-end and front-end process.


Field Name Description Format
callback_url_be
(optional)
Callback URL for your back-end process Valid URL is required. Start the value with http or https
callback_url_fe_succ
(optional)
Callback URL for your front-end success transaction process Valid URL is required. Start the value with http or https
callback_url_fe_fail
(optional)
Callback URL for your front-end failed transaction process Valid URL is required. Start the value with http or https


4) Optional baggage fields

These are OPTIONAL fields. If you require a variable that provide the same value when you return it on your callback URL after transaction, use this baggage form. You can have more than one variable. Each variables and values is separate by "|". Please make sure total variables and values is sync with each other.


Field Name Description Format
baggage_
variable
(optional)
Name of the variable. PayDirect FPX will send back to the callback URL by using same variable provided.
Eg: variable1|variable2|
variable3|variable4
Accepts alphabets and numeric without empty space. Must be less than 5000 characters.
*Every variable name that has been stated in baggage_
variable*
(optional)
Value for each variable Aceepts alphabets and numeric without empty space. Must be less than 5000 characters. (Combined all total character of baggage's value)


How Do I Receive My Payment Request From Pay Direct FPX Payment Gateway?

Merchant needs to specify callback URL on their dashboard. Merchant will be able to debug the error or verify those data. PAYDIRECT FPX will send the data to merchant by using POST method. Data is secured using hashing.


1) Return Fields from PayDirect FPX

The response to your payment request will be sent back to your specified back-end URL in the following format. The response will be send back using POST method.

Field Name Description Format
fpx_fpxTxnId
OR
paypal_trx_id
OR
mastercard_
trx_id
This refers to the FPX or PayPal Transaction ID or MasterCard Txr ID returned by FPX/PayPal/MPGS. You can use this Transaction ID to track the transaction in Pay Direct's Payment Gateway portal.
Eg: 180824153
5340347
Return with number and character format.
fpx_sellerId This refers to your FPX seller ID. Eg: SE000008567 Aceepts alphabets and numeric without empty space.
invoice_no This refers to your uniquely generated invoice number. Eg: INV10154632 Accepts alphabets, numbers and some special characters. Do not support ampersand(&), slashes(/,\) and dash (-)
txn_status This refers to the status of the payment returned by FPX. Eg: 00
*Refers figure below to view the response codes and description for every code.
alphabets and numerics
msg This refers to the status message of the payment depend on status code from txn_status return by FPX. Eg: Transaction Approved alphabets and numerics
txn_amount This refers to the amount of transaction sent by merchant. Eg: 1289.00 numerics with 2 decimal points
pay_method This is method of transaction made by a buyer either through FPX or PayPal or MPGS .
Eg: fpx/paypal/
mastercard
alphabets
hash This is the secure hash string to validate the payment request response sent through our Payment Gateway. Refer to the Securing section for more info on how to validate the secure hash string. alphabets and numerics

2) Response code and description for transaction status

Below are the response code and description for txn_status fields. You can use this for verification and error debugging.

Response Code
Description
*Others* Unable To Trace An Error
00 Transaction Approved
03 Invalid Merchant
05 Invalid Seller or Acquiring Bank Code
13 Invalid Amount
00 Transaction Approved
09 Transaction Pending
12 Invalid Transaction
14 Invalid Buyer Account
20 Invalid Response
31 Invalid Bank
39 No Credit Account
45 Duplicate Seller Order Number
46 Invalid Seller Exhchange or Seller
47 Invalid Currency
48 Maximum Transaction Limit Exceeded RM30,000.00 for B2C
49 Merchant Specific Limit Exceeded
50 Invalid Seller for Merchant Specific Limit
51 Insufficient Funds
53 No Buyer Account Number
57 Transaction Not Premitted
58 Transaction To Merchant Not Premitted
70 Invalid Serial Number
76 Transaction Not Found
77 Invalid Buyer Name or Buyer ID
78 Decryption Failed
79 Host Decline When Down
80 Buyer Cancel Transaction
83 Invalid Transaction Model
84 Invalid Transaction Type
85 Internel Error At Bank System
87 Debit Failed Exception Handling
88 Credit Failed Exception Handling
89 Transaction Not Received Exception Handling
90 Bank Internet Banking Unavailable
92 Invalid Buyer Bank
96 System Manulfaction
98 MAC Error
99 Pending Authorization (Applicable for B2B model)
BC Transaction Cancelled By Customer
DA Invalid Applcaition Type
DB Invalid Email Format
DC Invalid Maximum Frequency
DD Invalid Frequency Mode
DE Invalid Expiry Date
DF Invalid e-Mandate
FE Internal Error
OE Transaction Rejected As Not In FPX Operating Hours
OF Transaction Timeout
SB Invalid Acquiring Bank Code
XA Invalid Source IP Address (Applicable for B2B2 model)
XB Invalid Seller Exchange IP
XC Seller Exchange Encryption Error
XE Invalid Message
XF Invalid Number of Orders
XI Invalid Seller Exchange
XM Invalid FPX Transaction Model
XN Transaction Rejected Due To Duplicate Seller Exchange Order Number
XO Duplicate Exchange Order Number
XS Seller Does Not Belong To Exchange
XT Invalid Transaction Type
XW Seller Exchange Date Difference Exceeded
1A Seller Buyer Session Timeout At Internet Banking Login Page
1B Buyer Failed To Provide The Necessary Info To Login To Internet Banking Login Page
1C Buyer Choose Cancel At Login Page
1D Buyer Session Timeout At Account Selection Page
1E Buyer Failed To Provide The Necessary Info To Login To Internet Banking Login Page
1F Buyer Choose Cancel At Account Selection Page
1G Buyer Session Timeout At TAC Request Page
1H Buyer Failed To Provide Necessary Info At TAC Request Page
1I Buyer Choose Cancel At TAC Request Page
1J Buyer Session Timeout At Confirmation Page
1K Buyer Failed To Provide Necessary Info At Confirmation Page
1L Buyer Choose Cancel At Confirmation Page
1M Internet Banking Session Timeout
2A Transaction Amount Is Lower Than Minimum Limit RM1.00 for B2C



How Do I Secure The Payment Request That I Send To Pay Direct FPX Payment Gateway?

In order to ensure the data integrity of information passing to and from our Payment Gateway, we used the secure hash string for verifying and validating. The secure hash is generated using md5 on string consisting of the following (according to sequence and separated by a pipe element '|' and WITHOUT spaces in between):


1) When sending payment request

Field Name Example Detail
api APIKEY123456
merchant_id 1000034
invoice INV10154632
amount 1289.00
payment_desc Parking Fee


Sample Hashing code :
md5($api."|".urldecode($merchant_id)."|".urldecode($invoice)."|".urldecode($amount)."|".urldecode($payment_desc));

For example, if the details to be sent are as above, the hash string to be generated is constructed as follows:
APIKEY123456|100055|INV10154632|1289.00|Parking Fee will generate something like e8f3ac1c718fa7e620b133d601fb4f73


2) When receiving the payment request response

Upon receiving the response from our Payment Gateway, merchant is required to hash the string received with their API Key and compare it with the hash sent in the response.

Field Name Example Details
fpx_fpxTxnId OR paypal_trx_id OR mastercard_
trx_id
1808241535340347
fpx_sellerId SE000008567
invoice_no INV10154632
msg Transaction Approved
txn_status 00
txn_amount 1289.00
hash dc8e364d222d6025
cbc505674b701asdw
pay_method fpx OR paypal OR mastercard
*Your baggage variable* *Your baggage value*

Sample Hashing code :
md5($api.$fpx_fpxTxnId.$invoice_no.$txn_status.$msg);

For example, if the details received are as above, the hash string to be generated is constructed as follows:
APIKEY123456|1808241535340347|INV012345|00|Transaction Approved will generate something like dc8e364d222d6025cbc505674b7012df

If the generated hash string is the same with the hash sent in the response message, the data is safe from tampering.



Sample PHP codes

PayDirect OpenAPI Sample Code

<?php
/**
 * This is a sample code for manual integration with PayDirect
 * It is so simple that you can do it in a single file
 * Make sure that in PayDirect Dashboard you have key in the return URL referring to this file
 */

# please fill in the required info as below
$merchant_id '10001'// this refers to your Merchant ID that can be obtain from PayDirect
$api 'APIKEY100001'// API key


# this part is to process data from the form that user key in, make sure that all of the info is passed so that we can process the payment
if(isset($_POST['amount']) && isset($_POST['invoice']) && isset($_POST['payment_desc']))
{

# assuming all of the data passed is correct and no validation required. Preferably you will need to validate the data passed
$hashed_string md5($api."|".urldecode($merchant_id)."|".urldecode($_POST['invoice'])."|".urldecode($_POST['amount'])."|".urldecode($_POST['payment_desc']));

# now we send the data to PayDirect by using post method

$paydirectfpx_link_sandbox '{Sandbox URL}';
$paydirectfpx_link_live '{Live Production URL}';

    
?>
<html>
<head>
<title>Pay Direct Payment Gateway API Sample Code</title>
</head>
<body onload="document.order.submit()">
#Specified the link below either for sandbox or live production
    <form name="order" method="post" action="<?= $paydirectfpx_link_sandbox ?>">
        <?=#  REQUIRED FORM START HERE ?>
          <input type="hidden" name="merchant_id" value="<?= $merchant_id?>">
          <input type="hidden" name="invoice" value="<?= $_POST['invoice']?>">
          <input type="hidden" name="amount" value="<?= $_POST['amount']; ?>">
          <input type="hidden" name="payment_desc" value="<?= $_POST['payment_desc']; ?>">
          <input type="hidden" name="hash" value="<?= $hashed_string?>">
        <?=#  REQUIRED FORM END HERE ?>

        <?=#   OPTIONAL FORM START HERE ?>
          <?=#  Set this as null or remove it if you're not required this form. This form will display on payment gateway and save the value in dashboard  ?>
          <?=#  Buyer Name ?>
          <input type="hidden" name="buyer_name" value="John">
          <?=#  Buyer Email. Must be valid email address. Buyer will get transaction status through this email ?>
          <input type="hidden" name="buyer_email" value="John@gmail.com">
          <?=#  Buyer Phone number with country code ?>
          <input type="hidden" name="phone" value="+0123456789">
          <?=#  Buyer Address form line 1?>
          <input type="hidden" name="add_line_1" value="10-3, 3rd Floor Jln PJU 5/9">
          <?=#  Buyer Address form line 2?>
          <input type="hidden" name="add_line_2" value="Dataran Sunway Kota Damansara">
          <?=#  Buyer Postcode ?>
          <input type="hidden" name="postcode" value="47810">
          <?=#  Buyer City ?>
          <input type="hidden" name="city" value="Petaling Jaya">
          <?=#  Buyer State ?>
          <input type="hidden" name="state" value="Selangor">
          <?=#  Buyer Comment ?>
          <input type="hidden" name="comment" value="">

          <?=#  Your callback url for backend process. If you already have specified it on your dashboard but want a different url for different process, please include this form. ?>
          <?=#  Your Back-end Process ?>
          <input type="hidden" name="callback_url_be" value="https://www.example.com/callback_url_be.php">
          <?=#  Your Front-end Process Success interface ?>
          <input type="hidden" name="callback_url_fe_succ" value="https://www.example.com/callback_fe_succ.php">
          <?=#  Your Front-end Process Fail interface ?>
          <input type="hidden" name="callback_url_fe_fail" value="https://www.example.com/callback_url_fe_fail.php">

          <?=#  If you required a variable that provide the same value when you return it after transaction, use this baggage form. You can have more than one variable.?>
          <?=# Please seperate each variable and value by using '|'. Please make sure that every form's value below not more than 5000 characters ?>
          <?=#   Your vaiable(s)?>
          <input type="hidden" name="baggage_variable" value="variable1|variable2|variable3|variable4">
          <?=#   Your value(s) of each variable(s). Must be synchonize with the total variable above ?>
          <input type="hidden" name="variable1" value="value1">
          <input type="hidden" name="variable2" value="value2">
          <input type="hidden" name="variable3" value="value3">
          <input type="hidden" name="variable4" value="value4">
        <?=#   OPTIONAL FORM END HERE ?>

    </form>
</body>
</html>

<?php
}
else
{
?>

<html>
<head>
  <title>Pay Direct Payment Gateway API Sample Code</title>
</head>
<body>
  <form method="post" action="<?= htmlentities($_SERVER['PHP_SELF']); ?>">
    <table>
      <tr>
          <td colspan="2">Please fill up the detail below in order to test the payment.</td>
      </tr>
      <tr>
        <?=#  AMOUNT VALUE  MUST MORE THAN RM1.50 AND WITH 2 DECIMAL POINTS ?>
          <td>Amount</td>
          <td>: <input type="text" name="amount" value="" placeholder="Amount to pay, for example 12.20" size="30"></td>
      </tr>
      <tr>
        <?=#   DESCRIPTION MUST BE LESS THAN 1,000 CHARACTERS ?>
          <td>Payment Description (Not more than 1,000 character)</td>
          <td>: <input type="text" name="payment_desc" value="" placeholder="Description of the transaction" size="30"></td>
      </tr>
      <tr>
         <?=#  MUST BE UNIQUE  ?>
          <td>Invoice (Not more than 17 char without '-')</td>
          <td>: <input type="text" name="invoice" value="" placeholder="Unique id to reference the transaction or order" size="30"></td>
      </tr>

      <tr>
          <td><input type="submit" value="Submit"></td>
      </tr>
    </table>
  </form>
</body>
</html>
<?php
}
?>


PayDirect CallBack Backend Sample Code

<?php

#Tracing the transaction which payment method is used by your customer
if($_REQUEST['pay_method'] == 'fpx'#Using FPX
{
  
$trx_id $_REQUEST['fpx_fpxTxnId']; #EX: 1808241535340347
}
else if(
$_REQUEST['pay_method'] == 'paypal'#Using PayPal
{
  
$trx_id $_REQUEST['paypal_trx_id']; #EX: 1808241535340347
}
else if(
$_REQUEST['pay_method'] == 'mastercard'#Using Mastercard
{
  
$trx_id $_REQUEST['mastercard_trx_id']; #EX: 1808241535340347
}

#These are the data that posible to get from the callback URL
$fpx_sellerId   $_REQUEST['fpx_sellerId']; #EX: SE10000001
$invoice_no $_REQUEST['invoice_no']; #EX: INV012345
$txn_status $_REQUEST['txn_status']; #EX: 00 *You can view more txn_status value from the documentation*
$msg $_REQUEST['msg']; #EX: Transaction Approved
$txn_amount $_REQUEST['txn_amount']; #EX: 1289.00
$pay_method $_REQUEST['pay_method']; #EX: fpx *Can be either fpx or PayPal
$hash $_REQUEST['hash']; #EX: dc8e364d222d6025cbc505674b7ASDDS
$sample_bagages_variables $_REQUEST['sample_bagages_variables']; # *The variable name is depend on what you have set when calling an API to the payment gateway. This is optional variables.

# assuming all of the data passed is correct and no validation required. Preferably you will need to validate the data passed
# This is important to prevent any attack from hackers
$hash =  md5($api.$trx_id.$invoice_no.$txn_status.$msg);

if(
$hash == $_REQUEST['hash'])
{
    echo 
'OK'# An 'OK' msg need to send to the PayDirect as a valid respond received from the merchant.
    # PayDirect will send the callback data at most 3 times every 10 minutes if PayDirect doesn't received an 'OK' message

    #Do stuff
    #You can manage your callback data here
}

else
{
    echo 
'Invalid Data';
    
#Invalid Data entered or hashing error
}

 
?>