Add support for SagePay ERROR and INVALID responses. Closes thephpleague#120

Author: dchesterton

src/Omnipay/SagePay/Message/ServerCompleteAuthorizeResponse.php

@@ -29,23 +29,91 @@ public function getTransactionReference()
     /**
      * Confirm (Sage Pay Server only)
      *
+     * Notify Sage Pay you received the payment details and wish to confirm the payment, and
+     * provide a URL to forward the customer to.
+     *
+     * @param string URL to forward the customer to. Note this is different to your standard
+     *               return controller action URL.
+     * @param string Optional human readable reasons for accepting the transaction.
+     */
+    public function confirm($nextUrl, $detail = null)
+    {
+        $this->sendResponse('OK', $nextUrl, $detail);
+    }
+
+    /**
+     * Error (Sage Pay Server only)
+     *
+     * Notify Sage Pay you received the payment details but there was an error and the payment
+     * cannot be completed. Error should be called rarely, and only when something unforseen
+     * has happened on your server or database.
+     *
+     * @param string URL to foward the customer to. Note this is different to your standard
+     *               return controller action URL.
+     * @param string Optional human readable reasons for not accepting the transaction.
+     */
+    public function error($nextUrl, $detail = null)
+    {
+        $this->sendResponse('ERROR', $nextUrl, $detail);
+    }
+
+    /**
+     * Invalid (Sage Pay Server only)
+     *
+     * Notify Sage Pay you received the payment details but they were invalid and the payment
+     * cannot be completed. Invalid should be called if you are not happy with the contents
+     * of the POST, such as the MD5 hash signatures did not match or you do not wish to proceed
+     * with the order.
+     *
+     * @param string URL to foward the customer to. Note this is different to your standard
+     *               return controller action URL.
+     * @param string Optional human readable reasons for not accepting the transaction.
+     */
+    public function invalid($nextUrl, $detail = null)
+    {
+        $this->sendResponse('INVALID', $nextUrl, $detail);
+    }
+
+    /**
+     * Respond to SagePay confirming or rejecting the payment.
+     *
      * Sage Pay Server does things backwards compared to every other gateway (including Sage Pay
      * Direct). The return URL is called by their server, and they expect you to confirm receipt
      * and then pass a URL for them to forward the customer to.
      *
      * Because of this, an extra step is required. In your return controller, after calling
-     * $gateway->completePurchase(), you should update your database with details of the
-     * successful payment. You must then call $response->confirm() to notify Sage Pay you
-     * received the payment details, and provide a URL to forward the customer to.
+     * $gateway->completePurchase(), you should attempt to process the payment. You must then call
+     * either $response->confirm(), $response->error() or $response->invalid() to notify Sage Pay
+     * whether to complete the payment or not, and provide a URL to forward the customer to.
      *
      * Keep in mind your original confirmPurchase() script is being called by Sage Pay, not
      * the customer.
      *
-     * @param string URL to foward the customer to. Note this is different to your standard
+     * @param string The status to send to Sage Pay, either OK, INVALID or ERROR.
+     * @param string URL to forward the customer to. Note this is different to your standard
      *               return controller action URL.
+     * @param string Optional human readable reasons for accepting the transaction.
+     */
+    public function sendResponse($status, $nextUrl, $detail = null)
+    {
+        $message = "Status=$status\r\nRedirectUrl=$nextUrl";
+
+        if (null !== $detail) {
+            $message .= "\r\nStatusDetail=".$detail;
+        }
+
+        $this->exitWith($message);
+    }
+
+    /**
+     * Exit to ensure no other HTML, headers, comments, or text are included.
+     *
+     * @access private
+     * @codeCoverageIgnore
      */
-    public function confirm($nextUrl)
+    public function exitWith($message)
     {
-        exit("Status=OK\r\nRedirectUrl=".$nextUrl);
+        echo $message;
+        exit;
     }
 }

tests/Omnipay/SagePay/Message/ServerCompleteAuthorizeResponseTest.php

@@ -3,6 +3,7 @@
 namespace Omnipay\SagePay\Message;
 
 use Omnipay\TestCase;
+use Mockery as m;
 
 class ServerCompleteAuthorizeResponseTest extends TestCase
 {
@@ -45,4 +46,44 @@ public function testServerCompleteAuthorizeResponseFailure()
         $this->assertNull($response->getTransactionReference());
         $this->assertNull($response->getMessage());
     }
+
+    public function testConfirm()
+    {
+        $response = m::mock('\Omnipay\SagePay\Message\ServerCompleteAuthorizeResponse[sendResponse]');
+        $response->shouldReceive('sendResponse')->once()->with('OK', 'https://www.example.com/', 'detail');
+
+        $response->confirm('https://www.example.com/', 'detail');
+    }
+
+    public function testError()
+    {
+        $response = m::mock('\Omnipay\SagePay\Message\ServerCompleteAuthorizeResponse[sendResponse]');
+        $response->shouldReceive('sendResponse')->once()->with('ERROR', 'https://www.example.com/', 'detail');
+
+        $response->error('https://www.example.com/', 'detail');
+    }
+
+    public function testInvalid()
+    {
+        $response = m::mock('\Omnipay\SagePay\Message\ServerCompleteAuthorizeResponse[sendResponse]');
+        $response->shouldReceive('sendResponse')->once()->with('INVALID', 'https://www.example.com/', 'detail');
+
+        $response->invalid('https://www.example.com/', 'detail');
+    }
+
+    public function testSendResponse()
+    {
+        $response = m::mock('\Omnipay\SagePay\Message\ServerCompleteAuthorizeResponse[exitWith]');
+        $response->shouldReceive('exitWith')->once()->with("Status=FOO\r\nRedirectUrl=https://www.example.com/");
+
+        $response->sendResponse('FOO', 'https://www.example.com/');
+    }
+
+    public function testSendResponseDetail()
+    {
+        $response = m::mock('\Omnipay\SagePay\Message\ServerCompleteAuthorizeResponse[exitWith]');
+        $response->shouldReceive('exitWith')->once()->with("Status=FOO\r\nRedirectUrl=https://www.example.com/\r\nStatusDetail=Bar");
+
+        $response->sendResponse('FOO', 'https://www.example.com/', 'Bar');
+    }
 }