Issue #12 changes

README.md

@@ -221,7 +221,7 @@ $request = $gateway->purchase([
     'items' => $items, // array or ItemBag of Omnipay\Common\Item or Omnipay\Wirecard\Extend\Item objects
     //
     // These three URLs are required to the gateway, but will be defaulted to the
-    // returnUrl where they are not set.
+    // returnUrl if they remain not set.
     'returnUrl' => 'https://example.com/complete',
     //'cancelUrl' => 'https://example.com/complete?status=cancel', // User cancelled
     //'failureUrl' => 'https://example.com/complete?status=failure', // Failed to authorise
@@ -332,37 +332,53 @@ This payment method will send the user off to the Wirecard site to authorise
 a payment. The user will return with the result of the transaction, which
 is parsed by the `completePurchase` object.
 
-    $complete_purchase_request = $gateway->completePurchase();
-
-The message will be signed to check for alteration en route, so the gateway
-needs to be given the `secret` when instantiating it.
-
-Here `$complete_purchase_request` will contain all the data needed to parse the
-result.
-
-    // Checks the message is correctly signed.
-    $complete_purchase_request->isValid();
-
-    // Checks if the authorisation was successful.
-    // If the fingerprint signing fails, then this will return false.
-    $complete_purchase_request->isSuccessful();
-
-    // Get the success or failure message.
-    // Some messages are generated by the gateway, and some are filled
-    // in by this driver.
-    $complete_purchase_request->getMessage();
-
-    // Checks if the authorisation was cancelled by the user.
-    $complete_purchase_request->isCancelled();
-
-    // Get the raw data.
-    $complete_purchase_request->getData();
-
-    // Get the transaction ID (generated by the merchant site).
-    $complete_purchase_request->getTransactonId();
-
-    // Get the transaction reference (generated by the gateway).
-    $complete_purchase_request->getTransactonReference();
+    $complete_purchase_request = $gateway->completePurchase([
+        'transactionId' => $origionalTransactionId,
+    ]);
+
+The `$origionalTransactionId` is the transaction ID provided in the original
+`$gateway->purchase([...])` request, and is mandatory.
+It is set here to ensure the application is responding to the correct
+transaction result.
+
+The message is signed by the gateway to check for tampering en route,
+so the gateway needs to be given the `secret` when instantiating it.
+
+Here `$complete_purchase_request` will contain all the data needed to parse
+the result.
+
+```php
+// Confirms the message signature is valid.
+
+$complete_purchase_request->isValid();
+
+// Checks if the authorisation was successful.
+// If the fingerprint signing fails, then this will return false.
+
+$complete_purchase_request->isSuccessful();
+
+// Get the success or failure message.
+// Some messages are generated by the gateway, and some are filled
+// in by this driver.
+
+$complete_purchase_request->getMessage();
+
+// Checks if the authorisation was cancelled by the user.
+
+$complete_purchase_request->isCancelled();
+
+// Get the raw data.
+
+$complete_purchase_request->getData();
+
+// Get the transaction ID (generated by the merchant site).
+
+$complete_purchase_request->getTransactonId();
+
+// Get the transaction reference (generated by the gateway).
+
+$complete_purchase_request->getTransactonReference();
+```
 
 The merchant site will normally `send()` the `$complete_purchase_request`
 to get the final response object. In this case, you will just get the same

src/CheckoutPageGateway.php

@@ -86,7 +86,7 @@ public function recurPurchase(array $parameters = array())
     public function completeAuthorize(array $parameters = array())
     {
         return $this->createRequest(
-            '\Omnipay\Wirecard\Message\Checkout\Page\Complete',
+            '\Omnipay\Wirecard\Message\Checkout\Page\CompleteRequest',
             $parameters
         );
     }
@@ -97,7 +97,7 @@ public function completeAuthorize(array $parameters = array())
     public function completePurchase(array $parameters = array())
     {
         return $this->createRequest(
-            '\Omnipay\Wirecard\Message\Checkout\Page\Complete',
+            '\Omnipay\Wirecard\Message\Checkout\Page\CompleteRequest',
             $parameters
         );
     }

src/Message/Checkout/AbstractRequest.php

@@ -21,7 +21,7 @@ abstract class AbstractRequest extends MessageAbstractRequest
     const AUTO_DEPOSIT_NO = 'no';
 
     // The name of the custom field the transaction ID will go into.
-    const CUSTOM_FIELD_NAME_TRANSACTION_ID = 'omnipay_transactionId';
+    const CUSTOM_FIELD_NAME_TRANSACTION_ID = 'omnipayTransactionId';
 
     /**
      * The Payment Type will default to SELECT if not set.

src/Message/Checkout/Page/CompleteRequest.php

@@ -0,0 +1,73 @@
+<?php
+
+namespace Omnipay\Wirecard\Message\Checkout\Page;
+
+/**
+ * Complete a Wirecard Checkout Page purchase transaction on the
+ * user returning to the merchant shop.
+ * Experimentally, this one class covers both the request and the response,
+ * since not further requests back to the gateway are needed.
+ * The advantage of doing this is that all the results needed are in the
+ * initial request object. A merchant site can still send() that message
+ * and get the same message back.
+ * It should be possible to extend this as the notification handler too. If
+ * so, then the HasFingerprintTrait becomes redundant.
+ */
+
+use Omnipay\Common\Message\ResponseInterface as OmnipayResponseInterface;
+use Omnipay\Wirecard\Message\Checkout\AbstractRequest;
+use Omnipay\Wirecard\Message\AbstractResponse;
+use Omnipay\Wirecard\Message\HasDataTrait;
+
+class CompleteRequest extends AbstractRequest
+{
+    use HasDataTrait;
+
+    /**
+     * @inheric
+     */
+    public function getData()
+    {
+        return $this->httpRequest->request->all();
+    }
+
+    /**
+     * Create a new Response message given the raw data in the response.
+     */
+    protected function createResponse($data)
+    {
+        $this->validate('secret', 'transactionId');
+
+        $this->response = new CompleteResponse($this, $this->getData());
+
+        // Set the original transactionId and the secret, both for
+        // validating the response.
+
+        $this->response->setOriginalTransactionId($this->getTransactionId());
+        $this->response->setSecret($this->getSecret());
+
+        return $this->response;
+    }
+
+    /**
+     * The secret for hashing.
+     */
+    public function setSecret($value)
+    {
+        return $this->setParameter('secret', $value);
+    }
+
+    public function getSecret()
+    {
+        return $this->getParameter('secret');
+    }
+
+    /**
+     * The transaction ID supplied by the gateway, in case the
+     * application needs to look it up before calling send().
+     */
+    public function getOriginalTransactionId()
+    {
+        return $this->getDataValue(AbstractRequest::CUSTOM_FIELD_NAME_TRANSACTION_ID);
+    }
+}

src/Message/Checkout/Page/CompleteResponse.php

@@ -0,0 +1,82 @@
+<?php
+
+namespace Omnipay\Wirecard\Message\Checkout\Page;
+
+/**
+ * Complete a Wirecard Checkout Page purchase transaction on the
+ * user returning to the merchant shop.
+ * Experimentally, this one class covers both the request and the response,
+ * since not further requests back to the gateway are needed.
+ * The advantage of doing this is that all the results needed are in the
+ * initial request object. A merchant site can still send() that message
+ * and get the same message back.
+ * It should be possible to extend this as the notification handler too. If
+ * so, then the HasFingerprintTrait becomes redundant.
+ */
+
+use Omnipay\Common\Message\AbstractResponse as OmnipayAbstractResponse;
+use Omnipay\Wirecard\Message\Checkout\AbstractRequest;
+use Omnipay\Wirecard\Message\AbstractResponse;
+use Omnipay\Wirecard\Message\HasDataTrait;
+use Omnipay\Wirecard\Message\HandlesNotificationTrait;
+
+class CompleteResponse extends OmnipayAbstractResponse
+{
+    use HasDataTrait;
+    use HandlesNotificationTrait;
+
+    protected $transactionIdCheckEnabled = true;
+
+    protected $originalTransactionId;
+    protected $secret;
+
+    public function isRedirect()
+    {
+        return false;
+    }
+
+    /**
+     * The secret for hashing.
+     */
+    public function setSecret($value)
+    {
+        return $this->secret = $value;
+    }
+
+    public function getSecret()
+    {
+        return $this->secret;
+    }
+
+    /**
+     * The original transactionId that we are expecting to get back.
+     */
+    public function setOriginalTransactionId($value)
+    {
+        $this->originalTransactionId = $value;
+        return $this;
+    }
+
+    public function getOriginalTransactionId()
+    {
+        return $this->originalTransactionId;
+    }
+
+    /**
+     * We put the transaction ID into a custom field, which will be passed
+     * through by the gateway to the notification data.
+     */
+    public function getTransactionId()
+    {
+        return $this->getDataValue(AbstractRequest::CUSTOM_FIELD_NAME_TRANSACTION_ID);
+    }
+
+    /**
+     * @inherit
+     */
+    public function isExpectedTransactionId()
+    {
+        return $this->getTransactionId()
+            && $this->getTransactionId() === $this->getOriginalTransactionId();
+    }
+}