Merge pull request #2 from siewmai/master

Add void and partial refund

.gitignore

@@ -2,3 +2,4 @@
 composer.lock
 composer.phar
 phpunit.xml
+.idea

README.md

@@ -91,6 +91,63 @@ if ($response->isSuccessful()) {
 }
 ```
 
+### Void or Reverse a 'captured' transaction
+###### Only available for limited merchants and channels
+
+The following is the example to void a captured transaction, your can refer to MOLPay Reversal Request api spec.
+
+```php
+$gateway = Omnipay::create('MOLPay');
+
+$gateway->setMerchantId('your_merchant_id');
+$gateway->setVerifyKey('your_verify_key');
+$gateway->setSecretKey('your_secret_key');
+
+$request = $gateway->void([
+    'transactionReference' => '25248208'
+]);
+
+$response = $request->send();
+
+if ($response->isSuccessful()) {
+    // Update your data model
+} else {
+    echo $response->getMessage();
+}
+```
+
+### Request Partial Refund for a 'captured' or 'settled' transaction
+###### Only available for limited merchants and channels
+
+To perform a partial refund, you need to specify more parameters as below
+
+```php
+$gateway = Omnipay::create('MOLPay');
+
+$gateway->setMerchantId('your_merchant_id');
+$gateway->setVerifyKey('your_verify_key');
+$gateway->setSecretKey('your_secret_key');
+
+$request = $gateway->refund([
+    'transactionReference'  => '25248208',
+    'refId'                 => 'merchant_refund_red_id',
+    'amount'                => '10.00',
+    'channel'               => $transaction_channel, // data saved from $gateway->purchase() response, e.g FPX_MB2U
+    'bankCode'              => $bank_code, // from user who request to refund
+    'beneficiaryName'       => $beneficiary_name, // from user who request to refund
+    'beneficiaryAccountNo'  => $beneficiary_account_no, // from user who request to refund
+]);
+
+$response = $request->send();
+
+// The refund process will take about 7-14 days after the request sent
+if ($response->isSuccessful() || $response->isPending() ) {
+    // Update your data model
+} else {
+    echo $response->getMessage();
+}
+```
+
 ## Out Of Scope
 
 Omnipay does not cover recurring payments or billing agreements, and so those features are not included in this package. Extensions to this gateway are always welcome.

src/Gateway.php

@@ -198,8 +198,31 @@ public function completePurchase(array $parameters = array())
                     'sKey' => $this->httpRequest->request->get('skey'),
                     'status' => $this->httpRequest->request->get('status'),
                     'transactionReference' => $this->httpRequest->request->get('tranID'),
+                    'channel' => $this->httpRequest->request->get('channel')
                 )
             )
         );
     }
+
+    /**
+     * Create a refund request
+     *
+     * @param array $parameters
+     * @return \Omnipay\Common\Message\AbstractRequest
+     */
+    public function refund(array $parameters = array())
+    {
+        return $this->createRequest('\Omnipay\MOLPay\Message\PartialRefundRequest', $parameters);
+    }
+
+    /**
+     * Create a void request
+     *
+     * @param array $parameters
+     * @return \Omnipay\Common\Message\AbstractRequest
+     */
+    public function void(array $parameters = array())
+    {
+        return $this->createRequest('\Omnipay\MOLPay\Message\ReversalRequest', $parameters);
+    }
 }

src/Message/CompletePurchaseRequest.php

@@ -179,6 +179,16 @@ public function setTransactionReference($value)
         return $this->setParameter('transactionReference', $value);
     }
 
+    public function getChannel()
+    {
+        return $this->getParameter('channel');
+    }
+
+    public function setChannel($value)
+    {
+        return $this->setParameter('channel', $value);
+    }
+
     /**
      * {@inheritdoc}
      */

src/Message/PartialRefundRequest.php

@@ -0,0 +1,223 @@
+<?php
+
+namespace Omnipay\MOLPay\Message;
+
+/**
+ * Class PartialRefundRequest
+ * @package Omnipay\MOLPay\Message
+ *
+ * MOLPay Partial Refund
+ *
+ * ### Parameters
+ *
+ * * RefundType         [mandatory]     -   P for Partial Refund
+ * * MerchantID         [mandatory]     -   Merchant ID provided by MOLPay
+ * * RefID              [mandatory]     -   Unique tracking/references ID from merchant
+ * * TxnID              [mandatory]     -   MOLPay Transaction ID
+ * * Channel            [mandatory]     -   Refer to Channel List
+ * * Amount             [mandatory]     -   eg. '5.00' Amount to be refund
+ * * BankCode           [conditional]   -   Applicable for Online Banking and Physical Payment transaction only
+ * * BeneficiaryName    [conditional]   -   Applicable for Online Banking and Physical Payment transaction only
+ * * BeneficiaryAccNo   [conditional]   -   Applicable for Online Banking and Physical Payment transaction only
+ * * Signature          [mandatory]     -   This is data integrity protection hash string
+ * * mdr_flag           [optional]      -   This is to include or exclude MDR refund to buyer if the amount is same as bill amount
+ *                                          Available value is as below:
+ *                                          0 - Include MDR/Full Refund (Default)
+ *                                          1 - Exclude/Reserved MDR
+ * * notify_url         [optional]      -   This is the URL for merchant to receive refund status
+ *
+ */
+class PartialRefundRequest extends AbstractRequest
+{
+    /**
+     * Partial Refund URL
+     *
+     * @var string
+     */
+    protected $endpoint = 'https://api.molpay.com/MOLPay/API/refundAPI/index.php';
+
+    /**
+     * Sandbox Partial Refund URL
+     *
+     * @var string
+     */
+    protected $sandboxEndpoint = 'https://sandbox.molpay.com/MOLPay/API/refundAPI/index.php';
+
+    /**
+     * @return string
+     */
+    public function getRefundType()
+    {
+        return 'P';
+    }
+
+    /**
+     * @param $value
+     * @return \Omnipay\Common\Message\AbstractRequest
+     */
+    public function setRefId($value)
+    {
+        return $this->setParameter('refId', $value);
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getRefId()
+    {
+        return $this->getParameter('refId');
+    }
+
+    /**
+     * @param $value
+     * @return \Omnipay\Common\Message\AbstractRequest
+     */
+    public function setChannel($value)
+    {
+        return $this->setParameter('channel', $value);
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getChannel()
+    {
+        return $this->getParameter('channel');
+    }
+
+    /**
+     * @param $value
+     * @return \Omnipay\Common\Message\AbstractRequest
+     */
+    public function setBankCode($value)
+    {
+        return $this->setParameter('bankCode', $value);
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getBankCode()
+    {
+        return $this->getParameter('bankCode');
+    }
+
+    /**
+     * @param $value
+     * @return \Omnipay\Common\Message\AbstractRequest
+     */
+    public function setBeneficiaryName($value)
+    {
+        return $this->setParameter('beneficiaryName', $value);
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getBeneficiaryName()
+    {
+        return $this->getParameter('beneficiaryName');
+    }
+
+    /**
+     * @param $value
+     * @return \Omnipay\Common\Message\AbstractRequest
+     */
+    public function setBeneficiaryAccountNo($value)
+    {
+        return $this->setParameter('beneficiaryAccountNo', $value);
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getBeneficiaryAccountNo()
+    {
+        return $this->getParameter('beneficiaryAccountNo');
+    }
+
+    /**
+     * @param $value
+     * @return \Omnipay\Common\Message\AbstractRequest
+     */
+    public function setMdrFlag($value)
+    {
+        return $this->setParameter('mdrFlag', $value);
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getMdrFlag()
+    {
+        return $this->getParameter('mdrFlag');
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getData()
+    {
+        $this->validate('merchantId', 'refId', 'transactionReference', 'amount');
+
+        $data = array();
+        $data['RefundType'] = $this->getRefundType();
+        $data['MerchantID'] = $this->getMerchantId();
+        $data['RefID'] = $this->getRefId();
+        $data['TxnID'] = $this->getTransactionReference();
+        $data['Channel'] = $this->getChannel();
+        $data['Amount'] = $this->getAmount();
+        $data['BankCode'] = $this->getBankCode();
+        $data['BeneficiaryName'] = $this->getBeneficiaryName();
+        $data['BeneficiaryAccNo'] = $this->getBeneficiaryAccountNo();
+        $data['Signature'] = $this->generateSignature();
+        $data['mdr_flag'] = $this->getMdrFlag();
+        $data['notify_url'] = $this->getNotifyUrl();
+
+        return $data;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getEndpoint()
+    {
+        return $this->getTestMode() ? $this->sandboxEndpoint : $this->endpoint;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getHttpMethod()
+    {
+        return 'POST';
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function sendData($data)
+    {
+        $httpRequest = $this->httpClient->createRequest(
+            $this->getHttpMethod(),
+            $this->getEndpoint(),
+            null,
+            $data
+        );
+
+        $httpResponse = $httpRequest->send();
+
+        return $this->response = new PartialRefundResponse($this, $httpResponse->json());
+    }
+
+    /**
+     * Generate Signature
+     * @return string
+     */
+    protected function generateSignature()
+    {
+        $this->validate('merchantId', 'refId', 'transactionReference', 'amount', 'secretKey');
+
+        return md5($this->getRefundType() . $this->getMerchantId() .$this->getRefId() . $this->getTransactionReference() . $this->getAmount() . $this->getSecretKey());
+    }
+}