# FPX Payment

Preferred partner can have their own ID for processing payment. Merchant will use their own API credentials as usual. 

## Endpoint URL 

| Environment | URL                                            | Method |
| ----------- | ---------------------------------------------- | ------ |
| Sandbox     | <https://sandbox.securepay.my/api/v1/payments> | POST   |
| Production  | <https://securepay.my/api/v1/payments>         | POST   |

## Credentials

Using authentication parameter below:

|                                 |                                                                  |
| ------------------------------- | ---------------------------------------------------------------- |
| uid (Merchant API UID)          | 2aaa1633-e63f-4371-9b85-91d936aa56a1                             |
| token (Merchant API Auth Token) | ZyUfF8EmyabcMWPcaocX                                             |
| Checksum Token                  | 159026b3b7348e2390e5a2e7a1c8466073db239c1e6800b8c27e36946b1f8713 |

Partner may have many merchants. The uid and token are merchant credentials, partner only need to supply their partner\_uid only. While merchant need to use theirs. In some case, partner also can be a merchant.&#x20;

## API Credentials

![](https://1585239032-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MHFsN346MN-4Eibh12Q%2F-MKStHpYipOFmmU843tY%2F-MKSwjrme80ReF3XzCbw%2FScreenshot%202020-10-25%20at%2011.59.36%20AM.png?alt=media\&token=d9016ca5-ad12-4eaa-8b42-d490e6fb39e1)

## Partner UID

Every partner will be issued one or more partner UID (partner\_uid). SecurePay will identified partner account by using this identifier. &#x20;

## Request Parameters

| Parameter            | Description                                                                                                                                          | Condition  | Example                                                                                                                                                                                                                |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| order\_number        | Unique order number generated by merchant end for reference.                                                                                         | Compulsory | 20200425132755                                                                                                                                                                                                         |
| buyer\_name          | Valid buyer full name in one line.                                                                                                                   | Compulsory | AHMAD AMSYAR MOHD ALI                                                                                                                                                                                                  |
| buyer\_email         | Valid buyer email address for status update                                                                                                          | Compulsory | <amsyar@gmail.com>                                                                                                                                                                                                     |
| buyer\_phone         | Valid buyer phone number e.g: +60123121989                                                                                                           | Compulsory | +60123121678                                                                                                                                                                                                           |
| transaction\_amount  | Amount format: 100.20 , 1000.00, 7000.30                                                                                                             | Compulsory | 1540.40                                                                                                                                                                                                                |
| product\_description | <p>Meaningful Product Description e.g.</p><ul><li>Payment for order number 123</li><li>Payment for vintage table part #89782</li></ul>               | Compulsory | Payment for order no 20200425132755                                                                                                                                                                                    |
| checksum             | Signed strings for verification.                                                                                                                     | Compulsory | 2cb338beae0859e.......                                                                                                                                                                                                 |
| token                | API token                                                                                                                                            | Compulsory | ZyUfF8EmyabcMWPcaocX                                                                                                                                                                                                   |
| callback\_url        | Server to server. Securepay platform will post the payment status.                                                                                   | Optional   |                                                                                                                                                                                                                        |
| redirect\_url        | Browser to browser, Securepay platform will post to the endpoint browser.                                                                            | Optional   |                                                                                                                                                                                                                        |
| partner\_uid         | Partner UID value                                                                                                                                    | Compulsory | c52853e0-24d6 .....                                                                                                                                                                                                    |
| uid                  | API UID                                                                                                                                              | Compulsory | 2aaa1633-e63f ......                                                                                                                                                                                                   |
| redirect\_post       | Auto redirect to endpoint page.                                                                                                                      | Optional   | true                                                                                                                                                                                                                   |
| params               | Send  up to 18  values or parameters e.g: reference1\_label and reference1 .. reference18\_label and reference18                                     | optional   | "params": {"reference1\_label" : "Size", "reference1" : "XL", "reference2\_label" : "IC No" , "reference2" : "830102035587"                                                                                            |
| buyer\_bank\_code    | Bank code generated from the banks list                                                                                                              | Optional   | MBB0228                                                                                                                                                                                                                |
| shipping\_address    | Shipping address                                                                                                                                     | optional   | "shipping\_address":{"contact\_name":"John Doe John Kay", "contact\_phone\_number":"0133121999", "line1":"JLN UNGGUL 14/12","line2":"Bukit Harimau Belang", "postcode":"46000", "city":"Shah Alam","state":"Selangor"} |
| billing\_address     | Billing address                                                                                                                                      | optional   | "billing\_address":{"contact\_name":"John Doe John Kay", "contact\_phone\_number":"0133121999", "line1":"JLN UNGGUL 14/12","line2":"Bukit Harimau Belang", "postcode":"46000", "city":"Shah Alam","state":"Selangor"}  |
| model                | If not specify the platform will use B2C as default model. If using B2B1, set the model to B2B1. The FPX bank list also need to match with the model | optional   | B2C or B2B1                                                                                                                                                                                                            |
| fpx\_bank\_selection | If using securepay page for bank selection page. The bank selection can be displayed as dropdown or grid                                             | optional   | dropdown or grid                                                                                                                                                                                                       |
| cancel\_url          | SecurePay page for bank selection. If set the cancel URL. Button cancel will appear.                                                                 | optional   | <p>e.g: </p><p><https://yourdom.com/securepay>\_<em>cancel?order\_</em>number=123123</p><p></p>                                                                                                                        |
| timeout\_url         | SecurePay page for bank selection. if set the timeout URL. The page will timeout within 3 minutes                                                    | optional   | <p>e.g: </p><p><https://yourdom.com/securepay_timeout><em>?order\_</em>number=123123</p>                                                                                                                               |

B2C or B2B1 please set on the API settings inside SecurePay Apps. Other settings also can be set at the settings page.

#### API settings page

![](https://1585239032-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MHFsN346MN-4Eibh12Q%2F-Mchr_KTwOsgrYaqzwFd%2F-Mchs7s3X1q46UdDQM3H%2FScreenshot%202021-06-21%20at%205.21.09%20PM.png?alt=media\&token=853c7d44-8fa7-4bbe-ad45-b0d06cf204b3)

#### SecurePay bank selection page&#x20;

![](https://1585239032-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MHFsN346MN-4Eibh12Q%2F-Mchr_KTwOsgrYaqzwFd%2F-MchsQKy6hn5Nx4AB69-%2FScreenshot%202021-06-21%20at%205.12.56%20PM.png?alt=media\&token=9a07480d-1028-40d8-95ce-9319ccc4d298)

#### Grid bank selection

![](https://1585239032-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MHFsN346MN-4Eibh12Q%2F-Mchr_KTwOsgrYaqzwFd%2F-MchszsU87Tq9FLJlByQ%2FScreenshot%202021-06-21%20at%205.24.05%20PM.png?alt=media\&token=74196b2f-c115-4a48-b13b-23db4c946514)

## Generate Checksum

Below is how to generate checksum parameter

* [ ] Arrange the parameter variables in ascending order as below (except partner\_uid)

```bash
buyer_email|buyer_name|buyer_phone|callback_url|order_number|product_description|redirect_url|transaction_amount|uid
```

* [ ] Construct the parameter values string based on the position in point no 1.

```bash
amsyar@gmail.com|AHMAD AMSYAR MOHD ALI|+60123121678||20200425132755|Payment for order no 20200425132755||1540.40|2aaa1633-e63f-4371-9b85-91d936aa56a1S
```

* [ ] Sign the string with checksum token using HMAC256

{% tabs %}
{% tab title="Ruby" %}

```ruby
string = "​amsyar@gmail.com|AHMAD AMSYAR MOHD ALI|+60123121678||20200425132755|Payment for order no 20200425132755||1540.40|2aaa1633-e63f-4371-9b85-91d936aa56a1​"
checksum_token = "159026b3b7348e2390e5a2e7a1c8466073db239c1e6800b8c27e36946b1f8713​"
OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), checksum_token, string)
=> "5475e02fc8c9443c055eef6bca36b5b5b7999e36c14d9890c45409ea56c53942" 

```

{% endtab %}

{% tab title="PHP" %}

```php
$string = "amsyar@gmail.com|AHMAD AMSYAR MOHD ALI|0123121678||20200425132755|Payment for order no 20200425132755||1540.40|2aaa1633-e63f-4371-9b85-91d936aa56a1​"
$checksum_token = ​"​159026b3b7348e2390e5a2e7a1c8466073db239c1e6800b8c27e36946b1f8713​"
$sign = hash_hmac('sha256', $string, $checksum_token)
=> "5475e02fc8c9443c055eef6bca36b5b5b7999e36c14d9890c45409ea56c53942" 

```

{% endtab %}
{% endtabs %}

Generate checksum from the above example:

&#x20;**75b54e403151b1e9b413df8ce5c426ef0dbbc9adcec58b8f5dd5c9c5c6b78844**

{% hint style="info" %}
Sending all parameters in Request Parameter Table to the payment URL by using post method
{% endhint %}

## Sample Codes

{% tabs %}
{% tab title="PHP" %}

```bash
<?php

//Author: amir@p.my, amir@securepay.my
//Org   : SecurePay
//We need more contribution on sample codes. Email me.

if(isset($_POST['order_number']))
{
//Change with your token	
$uid = '9097b595-b77a-4321-94c0-0a6d323b5252';
$checksum_token = 'f4e4f07afb72a56fc6681d652713522436b50f087306efec39ab7d1be5b8c684';
$auth_token = '5BXhsTmVmRBKkg6xizNB';
$partner_uid = 'ebea23429-024a-4803-8968-cca40814b234';
$url = 'https://sandbox.securepay.my/api/v1/payments';

#$_POST['order_number'] = '20200425132755';
#$_POST['buyer_name'] = 'AHMAD AMSYAR MOHD ALI';
#$_POST['buyer_email'] = 'amsyar@gmail.com';
#$_POST['buyer_phone'] = '+60123121678';
#$_POST['transaction_amount'] = '10.00';
#$_POST['product_description'] = 'Payment for order no 20200425132755';
#$_POST['callback_url'] = "";
#$_POST['redirect_url'] = "";
#$_POST['token'] = $auth_token;
#$_POST['redirect_post'] = "true";

$order_number = $_POST['order_number'];
$buyer_name = $_POST['buyer_name'];
$buyer_phone = $_POST['buyer_phone'];
$buyer_email = $_POST['buyer_email'];
$product_description = $_POST['product_description'];
$transaction_amount = $_POST['transaction_amount'];
$callback_url = $_POST['callback_url'];
$redirect_url = $_POST['redirect_url'];
$redirect_post = "true";
if(isset($_POST['buyer_bank_code'])) { 
	$buyer_bank_code = $_POST['buyer_bank_code']; 
}




//buyer_email|buyer_name|buyer_phone|callback_url|order_number|product_description|redirect_url|transaction_amount|uid 

$string = $buyer_email."|".$buyer_name."|".$buyer_phone."|".$callback_url."|".$order_number."|".$product_description."|".$redirect_url ."|".$transaction_amount."|".$uid;

#echo $string . "\n";
#string = "amsyar@gmail.com|AHMAD AMSYAR MOHD ALI|+60123121678||20200425132755|Payment for order no 20200425132755||1540.40|5d80cc30-1a42-4f9f-9d6b-a69db5d26b01​"


#$string = "amsyar@gmail.com|AHMAD AMSYAR MOHD ALI|0123121678||20200425132755|Payment for order no 20200425132755||1540.40|2aaa1633-e63f-4371-9b85-91d936aa56a1​";
#$checksum_token = "159026b3b7348e2390e5a2e7a1c8466073db239c1e6800b8c27e36946b1f8713​";

$sign = hash_hmac('sha256', $string, $checksum_token);

#echo $sign . "\n";

//
//echo $sign

//$hashed_string = hash_hmac($checksum_token.urldecode($_POST['product_description']).urldecode($_POST['transaction_amount']).urldecode($_POST['order_number']));

if(isset($_POST['buyer_bank_code'])) {  

$post_data = "buyer_name=".urlencode($buyer_name)."&token=". urlencode($auth_token) 
."&callback_url=".urlencode($callback_url)."&redirect_url=". urlencode($redirect_url) . 
"&order_number=".urlencode($order_number)."&buyer_email=".urlencode($buyer_email).
"&buyer_phone=".urlencode($buyer_phone)."&transaction_amount=".urlencode($transaction_amount).
"&product_description=".urlencode($product_description)."&redirect_post=".urlencode($redirect_post).
"&checksum=".urlencode($sign)."&buyer_bank_code=".urlencode($buyer_bank_code)."&partner_uid=".urlencode($partner_uid);
}
else
{
$post_data = "buyer_name=".urlencode($buyer_name)."&token=". urlencode($auth_token) 
."&callback_url=".urlencode($callback_url)."&redirect_url=". urlencode($redirect_url) . 
"&order_number=".urlencode($order_number)."&buyer_email=".urlencode($buyer_email).
"&buyer_phone=".urlencode($buyer_phone)."&transaction_amount=".urlencode($transaction_amount).
"&product_description=".urlencode($product_description)."&redirect_post=".urlencode($redirect_post).
"&checksum=".urlencode($sign)."&partner_uid=".urlencode($partner_uid);	
}


#echo $post_data. "\n";

// Generated by curl-to-PHP: http://incarnate.github.io/curl-to-php/
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);

curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,$post_data);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

curl_exec($ch);

$output = curl_exec($ch);

echo $output;

}




#header('Location: ' + $output);
#exit();

#curl_close($ch);

$order_number = rand(1111111111,9999999999);

$json = file_get_contents('https://sandbox.securepay.my/api/public/v1/banks/b2c');
$obj = json_decode($json, true);
//echo $obj->access_token;
//$obj->fpx_bankList

//print_r($obj['fpx_bankList']);

$options = "";

foreach ($obj['fpx_bankList'] as $value) {
	if($value['status_format2'])
	{
	    $options .= "<option value=". $value['code'] . ">" . $value['name'] . "</option>";
	}
	else
	{
		$options .= "<option value=". $value['code'] . " disabled>" . $value['name'] . " (offline)</option>";
	}
	//echo $value['code'];
}
 
//print_r($obj->fpx_bankList);

?>
<h1>SecurePay sample code for PHP</h1>
<hr> 
<h3>Form without bank list</h3>
<form action="" method="post">
  <label for="fname">Full name:</label><br>
  <input type="text" id="fname" name="buyer_name" value="John Doe"><br>
  <label for="lname">Email:</label><br>
  <input type="text" id="lname" name="buyer_email" value="john@gmail.com"><br>
  <label for="lname">Phone No:</label><br>
  <input type="text" id="lname" name="buyer_phone" value="+60129997979"><br>
  <label for="lname">Order number:</label><br>
  <input type="text" id="lname" name="order_number" value="<?=$order_number;?>"><br>
  <label for="lname">Descriptions:</label><br>
  <input type="text" id="lname" name="product_description" value="Payment for order no. <?=$order_number;?>"><br>
  
  <label for="lname">Callback URL:</label><br>
  <input type="text" id="lname" name="callback_url" value="" placeholder="Optional"><br>
  
  <label for="lname">Redirect URL:</label><br>
  <input type="text" id="lname" name="redirect_url" value="" placeholder="Optional"><br>
  
  <label for="lname">Amount:</label><br>
  <input type="text" id="lname" name="transaction_amount" value="199"><br>
  <br>
  <input type="submit" value="Submit">
</form>

<hr> 

<h3>Form with bank list</h3>


<form action="" method="post">
  <label for="fname">Full name:</label><br>
  <input type="text" id="fname" name="buyer_name" value="John Doe"><br>
  <label for="lname">Email:</label><br>
  <input type="text" id="lname" name="buyer_email" value="john@gmail.com"><br>
  <label for="lname">Phone No:</label><br>
  <input type="text" id="lname" name="buyer_phone" value="+60129997979"><br>
  <label for="lname">Order number:</label><br>
  <input type="text" id="lname" name="order_number" value="<?=$order_number;?>"><br>
  <label for="lname">Descriptions:</label><br>
  <input type="text" id="lname" name="product_description" value="Payment for order no. <?=$order_number;?>"><br>
  <label for="lname">Amount:</label><br>
  <input type="text" id="lname" name="transaction_amount" value="199"><br>
  <label for="lname">Callback URL:</label><br>
  <input type="text" id="lname" name="callback_url" value="" placeholder="Optional"><br>
  
  <label for="lname">Redirect URL:</label><br>
  <input type="text" id="lname" name="redirect_url" value="" placeholder="Optional"><br>
  
  <label for="lname">Select bank:</label><br>
  <select id="buyer_bank_code" name="buyer_bank_code"><?=$options?></select><br>
  
  <br>
  <input type="submit" value="Submit">
</form>
```

{% endtab %}

{% tab title="Rails" %}

```
```

{% endtab %}
{% endtabs %}