Add support for refunding payments

config.example.php

@@ -4,7 +4,8 @@
  * This configuration is only needed for running tests.
  */
 return [
-    'version'             => '2015-04-29',
+    'version'             => '2015-07-06',
     'accessToken'         => '',
     'readOnlyAccessToken' => '',
+    'paymentToRefund'     => '',
 ];

src/Api.php

@@ -16,6 +16,7 @@
 use GoCardless\Pro\Models\Mandate;
 use GoCardless\Pro\Models\Payment;
 use GoCardless\Pro\Models\RedirectFlow;
+use GoCardless\Pro\Models\Refund;
 use GuzzleHttp\Client;
 use GuzzleHttp\Exception\BadResponseException;
 
@@ -27,6 +28,7 @@ class Api
     const CUSTOMER_BANK_ACCOUNTS = 'customer_bank_accounts';
     const MANDATES               = 'mandates';
     const PAYMENTS               = 'payments';
+    const REFUNDS                = 'refunds';
     const REDIRECT_FLOWS         = 'redirect_flows';
     const HELPERS                = 'helpers';
 
@@ -436,6 +438,20 @@ public function createPayment(Payment $payment)
         return Payment::fromArray($response);
     }
 
+    /**
+     * @see https://developer.gocardless.com/pro/#refunds-create-a-refund
+     *
+     * @param Refund $refund
+     *
+     * @return Refund
+     */
+    public function createRefund(Refund $refund)
+    {
+        $response = $this->post(self::REFUNDS, $refund->toArray());
+
+        return Refund::fromArray($response);
+    }
+
     /**
      * @see https://developer.gocardless.com/pro/#payments-get-a-single-payment
      *
@@ -450,6 +466,20 @@ public function getPayment($id)
         return Payment::fromArray($response);
     }
 
+    /**
+     * @see https://developer.gocardless.com/pro/#payments-list-payments
+     *
+     * @param array $options
+     *
+     * @return Payment[]
+     */
+    public function listPayments(array $options = [])
+    {
+        $response = $this->get(self::PAYMENTS, $options);
+
+        return $this->buildCollection(new Payment, $response);
+    }
+
     /**
      * @see https://developer.gocardless.com/pro/#payments-cancel-a-payment
      *

src/Models/Payment.php

@@ -33,7 +33,7 @@ class Payment extends Entity
      * @param $amount
      * @param $currency
      *
-     * @return $this
+     * @return Payment
      */
     public function collect($amount, $currency)
     {
@@ -53,7 +53,7 @@ public function using(Mandate $mandate)
     /**
      * @param Mandate $mandate
      *
-     * @return $this
+     * @return Payment
      */
     public function setMandate(Mandate $mandate)
     {
@@ -83,7 +83,7 @@ public function getChargeDate()
     /**
      * @param $date
      *
-     * @return $this
+     * @return Payment
      */
     public function setChargeDate($date)
     {
@@ -103,7 +103,7 @@ public function getAmount()
     /**
      * @param $amount
      *
-     * @return $this
+     * @return Payment
      */
     public function setAmount($amount)
     {
@@ -123,7 +123,7 @@ public function getCurrency()
     /**
      * @param $currency
      *
-     * @return $this
+     * @return Payment
      */
     public function setCurrency($currency)
     {
@@ -143,7 +143,7 @@ public function getDescription()
     /**
      * @param $description
      *
-     * @return $this
+     * @return Payment
      */
     public function setDescription($description)
     {
@@ -227,7 +227,7 @@ public function getReference()
     /**
      * @param $reference
      *
-     * @return $this
+     * @return Payment
      */
     public function setReference($reference)
     {

src/Models/Refund.php

@@ -0,0 +1,165 @@
+<?php
+
+namespace GoCardless\Pro\Models;
+
+use GoCardless\Pro\Models\Abstracts\Entity;
+use GoCardless\Pro\Models\Traits\Factory;
+use GoCardless\Pro\Models\Traits\Metadata;
+
+class Refund extends Entity
+{
+    use Factory;
+    use Metadata;
+
+    /** @var string */
+    private $amount;
+
+    /** @var string */
+    private $reference;
+
+    /** @var string */
+    private $currency;
+
+    /** @var string */
+    private $total_amount_confirmation;
+
+    /** @var Payment */
+    protected $payment;
+
+    /**
+     * @param Payment $payment
+     *
+     * @return Refund
+     */
+    public function of(Payment $payment)
+    {
+        return $this->setPayment($payment);
+    }
+
+    /**
+     * @param $amount
+     *
+     * @return Refund
+     */
+    public function returning($amount)
+    {
+        return $this->setAmount($amount);
+    }
+
+    /**
+     * @param $amount
+     *
+     * @return Refund
+     */
+    public function totalling($amount)
+    {
+        return $this->setTotalAmountConfirmation($amount);
+    }
+
+    /**
+     * @param $amount
+     *
+     * @return Refund
+     */
+    public function setAmount($amount)
+    {
+        $this->amount = $amount;
+
+        return $this;
+    }
+
+    /**
+     * @param $currency
+     *
+     * @return Refund
+     */
+    public function setCurrency($currency)
+    {
+        $this->currency = $currency;
+
+        return $this;
+    }
+
+    /**
+     * @param $amount
+     *
+     * @return Refund
+     */
+    public function setTotalAmountConfirmation($amount)
+    {
+        $this->total_amount_confirmation = $amount;
+
+        return $this;
+    }
+
+    /**
+     * @param $reference
+     *
+     * @return Refund
+     */
+    public function setReference($reference)
+    {
+        $this->reference = $reference;
+
+        return $this;
+    }
+
+    /**
+     * @param Payment $payment
+     *
+     * @return Refund
+     */
+    public function setPayment(Payment $payment)
+    {
+        $this->payment = $payment;
+
+        return $this;
+    }
+
+    /**
+     * @return int
+     */
+    public function getAmount()
+    {
+        return intval($this->amount);
+    }
+
+    /**
+     * @return int
+     */
+    public function getTotalAmountConfirmation()
+    {
+        return intval($this->total_amount_confirmation);
+    }
+
+    /**
+     * @return string
+     */
+    public function getCurrency()
+    {
+        return $this->currency;
+    }
+
+    /**
+     * @return string
+     */
+    public function getReference()
+    {
+        return $this->reference;
+    }
+
+    /**
+     * @return array
+     */
+    public function toArray()
+    {
+        $refund = array_filter(get_object_vars($this));
+
+        if ($this->payment instanceof Payment) {
+            unset($refund['payment']);
+            $refund['links']['payment'] = $this->payment->getId();
+        }
+
+        return $refund;
+    }
+}

tests/ApiTest.php

@@ -7,6 +7,7 @@
 use GoCardless\Pro\Models\CustomerBankAccount;
 use GoCardless\Pro\Models\Mandate;
 use GoCardless\Pro\Models\Payment;
+use GoCardless\Pro\Models\Refund;
 use GuzzleHttp\Client;
 
 class ApiTest extends \PHPUnit_Framework_TestCase
@@ -369,6 +370,35 @@ function test_it_can_get_a_single_payment(Payment $old)
         return $new;
     }
 
+    /** @test */
+    function it_returns_a_list_of_payments()
+    {
+        $payments = $this->api->listPayments();
+
+        $this->assertInternalType('array', $payments);
+        foreach ($payments as $payment) {
+            $this->assertInstanceOf('GoCardless\Pro\Models\Payment', $payment);
+        }
+    }
+
+    function test_it_can_create_a_refund()
+    {
+        $this->guardAgainstInvalidPaymentToRefund();
+
+        $config = require __DIR__ . '/../config.php';
+
+        $payment = $this->api->getPayment($config['paymentToRefund']);
+        $refund = (new Refund())->of($payment)->returning($payment->getAmount())->totalling($payment->getAmount());
+
+        $refund = $this->api->createRefund($refund);
+
+        $this->assertInstanceOf('GoCardless\Pro\Models\Refund', $refund);
+        $this->assertNotNull($refund->getId());
+        $this->assertNotNull($refund->getCreatedAt());
+        $this->assertSame($payment->getAmount(), $refund->getAmount());
+        $this->assertSame('GBP', $refund->getCurrency());
+    }
+
     /** @depends test_it_can_get_a_single_payment */
     function test_it_can_cancel_payments(Payment $payment)
     {
@@ -544,4 +574,19 @@ private function guardAgainstSmallNumberOfMandates()
             $this->markTestSkipped('Skipping test due to lack of mandates in system. This test requires at least 5.');
         }
     }
+
+    private function guardAgainstInvalidPaymentToRefund()
+    {
+        $config = require __DIR__ . '/../config.php';
+
+        if ( ! isset($config['paymentToRefund']) or $config['paymentToRefund'] == '') {
+            $this->markTestSkipped('Skipping test due to [paymentToRefund] was not set in the config');
+        }
+
+        $payment = $this->api->getPayment($config['paymentToRefund']);
+
+        if ( ! $payment->isConfirmed() or ! $payment->isPaidOut()) {
+            $this->markTestSkipped('Skipping test due to payment status is not confirmed or paid_out');
+        }
+    }
 }