Add refund_standalone function with tests

README.markdown

@@ -1,7 +1,7 @@
 PHP API Library for Fat Zebra
 ==============================
 
-Release 1.2.3 for API version 1.0
+Release 1.2.4 for API version 1.0
 
 A PHP library for the [Fat Zebra](https://www.fatzebra.com.au) Online Payment Gateway (for Australian Merchants)
 Now supports recurring billing (subscriptions, plans, customers)

composer.json

@@ -1,6 +1,6 @@
 {
 	"name": "fatzebra/fatzebra-php",
-	"version": "1.2.3",
+	"version": "1.2.4",
 	"repositories": [
 		{
 			"type": "vcs",

src/Gateway.php

@@ -363,6 +363,36 @@ public function refund($transaction_id, $amount, $reference, $extra = null)
         return $this->do_request("POST", "/refunds", $payload);
     }
 
+    /**
+     * Performs a standalone refund against the FatZebra gateway without an original transaction
+     * @param float $amount the amount to be refunded
+     * @param string $reference the refund reference
+     * @param string $card_token the card token to refund to
+     * @param array<string,string> $extra an assoc. array of extra params to merge into the request (e.g. metadata, fraud etc)
+     * @return \StdObject
+     */
+    public function refund_standalone($amount, $reference, $card_token, $extra = null)
+    {
+        if (is_null($amount) || strlen($amount) === 0) throw new \InvalidArgumentException("Amount is required");
+        if (intval($amount) < 1) throw new \InvalidArgumentException("Amount is invalid - must be a positive value");
+        if (is_null($reference) || strlen($reference) === 0) throw new \InvalidArgumentException("Reference is required");
+        if (is_null($card_token) || strlen($card_token) === 0) throw new \InvalidArgumentException("Card token is required");
+
+        $int_amount = self::floatToInt($amount);
+
+        $payload = array(
+            "amount" => $int_amount,
+            "reference" => $reference,
+            "card_token" => $card_token
+        );
+
+        if (is_array($extra)) {
+            $payload = array_merge_recursive($payload, $extra);
+        }
+
+        return $this->do_request("POST", "/refunds", $payload);
+    }
+
     /**
      * Retrieves a purchase from the FatZebra gateway
      * @param string $reference the purchase ID

test/GatewayTest.php

@@ -331,4 +331,47 @@ public function test_create_customer()
 		$this->assertTrue($result->successful);
 		$this->assertNotNull($result->response->id);
 	}
+
+	/**
+	 * Test a standalone refund with a valid card token (mocked)
+	 */
+	public function test_refund_standalone()
+	{
+		$stubbed_response = '{"successful":true,"response":{"id":"refund123","successful":true,"message":"Refund processed"},"errors":[],"test":true}';
+		$stub = $this->createMock(FatZebra\Gateway::class);
+		$stub->method('refund_standalone')->willReturn(json_decode($stubbed_response));
+		$result = $stub->refund_standalone(50.00, "UNITTEST" . rand(), "TOK123");
+
+		$this->assertTrue($result->successful);
+		$this->assertTrue($result->response->successful);
+		$this->assertEquals($result->response->message, "Refund processed");
+	}
+
+	/**
+	 * Test standalone refund with an invalid card token
+	 */
+	public function test_refund_standalone_invalid_token()
+	{
+		$gw = new FatZebra\Gateway("TEST", "TEST", true, GW_URL);
+		$gw->timeout = 30;
+
+		$result = $gw->refund_standalone(50.00, "UNITTEST" . rand(), "INVALID_TOKEN");
+
+		$this->assertFalse($result->successful);
+	}
+
+	/**
+	 * Test standalone refund with extra parameters (mocked)
+	 */
+	public function test_refund_standalone_with_extra()
+	{
+		$stubbed_response = '{"successful":true,"response":{"id":"refund456","successful":true,"message":"Refund processed"},"errors":[],"test":true}';
+		$stub = $this->createMock(FatZebra\Gateway::class);
+		$stub->method('refund_standalone')->willReturn(json_decode($stubbed_response));
+		$extra = array("metadata" => "test_metadata");
+		$result = $stub->refund_standalone(50.00, "UNITTEST" . rand(), "TOK123", $extra);
+
+		$this->assertTrue($result->successful);
+		$this->assertTrue($result->response->successful);
+	}
 }