Add support for Customer Balance Transaction resource and APIs

.travis.yml

@@ -13,7 +13,7 @@ php:
 
 env:
   global:
-    - STRIPE_MOCK_VERSION=0.57.0
+    - STRIPE_MOCK_VERSION=0.58.0
   matrix:
     - AUTOLOAD=1
     - AUTOLOAD=0

init.php

@@ -76,6 +76,7 @@
 require(dirname(__FILE__) . '/lib/Coupon.php');
 require(dirname(__FILE__) . '/lib/CreditNote.php');
 require(dirname(__FILE__) . '/lib/Customer.php');
+require(dirname(__FILE__) . '/lib/CustomerBalanceTransaction.php');
 require(dirname(__FILE__) . '/lib/Discount.php');
 require(dirname(__FILE__) . '/lib/Dispute.php');
 require(dirname(__FILE__) . '/lib/EphemeralKey.php');

lib/CreditNote.php

@@ -8,6 +8,7 @@
  * @property string $id
  * @property string $object
  * @property int $amount
+ * @property string $customer_balance_transaction
  * @property int $created
  * @property string $currency
  * @property string $customer

lib/Customer.php

@@ -7,8 +7,8 @@
  *
  * @property string $id
  * @property string $object
- * @property int $account_balance
  * @property mixed $address
+ * @property int $balance
  * @property string $created
  * @property string $currency
  * @property string $default_source
@@ -62,6 +62,7 @@ public static function getSavedNestedResources()
         return $savedNestedResources;
     }
 
+    const PATH_BALANCE_TRANSACTIONS = '/balance_transactions';
     const PATH_SOURCES = '/sources';
     const PATH_TAX_IDS = '/tax_ids';
 
@@ -265,4 +266,55 @@ public static function allTaxIds($id, $params = null, $opts = null)
     {
         return self::_allNestedResources($id, static::PATH_TAX_IDS, $params, $opts);
     }
+
+    /**
+     * @param string|null $id The ID of the customer on which to create the balance transaction.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return ApiResource
+     */
+    public static function createBalanceTransaction($id, $params = null, $opts = null)
+    {
+        return self::_createNestedResource($id, static::PATH_BALANCE_TRANSACTIONS, $params, $opts);
+    }
+
+    /**
+     * @param string|null $id The ID of the customer to which the balance transaction belongs.
+     * @param string|null $balanceTransactionId The ID of the balance transaction to retrieve.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return ApiResource
+     */
+    public static function retrieveBalanceTransaction($id, $balanceTransactionId, $params = null, $opts = null)
+    {
+        return self::_retrieveNestedResource($id, static::PATH_BALANCE_TRANSACTIONS, $balanceTransactionId, $params, $opts);
+    }
+
+    /**
+     * @param string|null $id The ID of the customer on which to update the balance transaction.
+     * @param string|null $balanceTransactionId The ID of the balance transaction to update.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     *
+     * @return ApiResource
+     */
+    public static function updateBalanceTransaction($id, $balanceTransactionId, $params = null, $opts = null)
+    {
+        return self::_updateNestedResource($id, static::PATH_BALANCE_TRANSACTIONS, $balanceTransactionId, $params, $opts);
+    }
+
+    /**
+     * @param string|null $id The ID of the customer on which to retrieve the customer balance transactions.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return Collection The list of customer balance transactions.
+     */
+    public static function allBalanceTransactions($id, $params = null, $opts = null)
+    {
+        return self::_allNestedResources($id, static::PATH_BALANCE_TRANSACTIONS, $params, $opts);
+    }
 }

lib/CustomerBalanceTransaction.php

@@ -0,0 +1,88 @@
+<?php
+
+namespace Stripe;
+
+/**
+ * Class CustomerBalanceTransaction
+ *
+ * @package Stripe
+ *
+ * @property string $id
+ * @property string $object
+ * @property int $amount
+ * @property string $credit_note
+ * @property int $created
+ * @property string $currency
+ * @property string $customer
+ * @property string $description
+ * @property int $ending_balance
+ * @property string $invoice
+ * @property bool $livemode
+ * @property StripeObject $metadata
+ * @property string $type
+ */
+class CustomerBalanceTransaction extends ApiResource
+{
+    const OBJECT_NAME = "customer_balance_transaction";
+
+    /**
+     * Possible string representations of a balance transaction's type.
+     * @link https://stripe.com/docs/api/customers/customer_balance_transaction_object#customer_balance_transaction_object-type
+     */
+    const TYPE_ADJUSTEMENT             = 'adjustment';
+    const TYPE_APPLIED_TO_INVOICE      = 'applied_to_invoice';
+    const TYPE_CREDIT_NOTE             = 'credit_note';
+    const TYPE_INITIAL                 = 'initial';
+    const TYPE_INVOICE_TOO_LARGE       = 'invoice_too_large';
+    const TYPE_INVOICE_TOO_SMALL       = 'invoice_too_small';
+    const TYPE_UNSPENT_RECEIVER_CREDIT = 'unspent_receiver_credit';
+
+    /**
+     * @return string The API URL for this balance transaction.
+     */
+    public function instanceUrl()
+    {
+        $id = $this['id'];
+        $customer = $this['customer'];
+        if (!$id) {
+            throw new Error\InvalidRequest(
+                "Could not determine which URL to request: class instance has invalid ID: $id",
+                null
+            );
+        }
+        $id = Util\Util::utf8($id);
+        $customer = Util\Util::utf8($customer);
+
+        $base = Customer::classUrl();
+        $customerExtn = urlencode($customer);
+        $extn = urlencode($id);
+        return "$base/$customerExtn/balance_transactions/$extn";
+    }
+
+    /**
+     * @param array|string $_id
+     * @param array|string|null $_opts
+     *
+     * @throws \Stripe\Error\InvalidRequest
+     */
+    public static function retrieve($_id, $_opts = null)
+    {
+        $msg = "Customer Balance Transactions cannot be accessed without a customer ID. " .
+               "Retrieve a balance transaction using Customer::retrieveBalanceTransaction('cus_123', 'cbtxn_123') instead.";
+        throw new Error\InvalidRequest($msg, null);
+    }
+
+    /**
+     * @param string $_id
+     * @param array|null $_params
+     * @param array|string|null $_options
+     *
+     * @throws \Stripe\Error\InvalidRequest
+     */
+    public static function update($_id, $_params = null, $_options = null)
+    {
+        $msg = "Customer Balance Transactions cannot be accessed without a customer ID. " .
+               "Update a balance transaction using Customer::updateBalanceTransaction('cus_123', 'cbtxn_123', $params) instead.";
+        throw new Error\InvalidRequest($msg, null);
+    }
+}

lib/Util/Util.php

@@ -88,6 +88,7 @@ public static function convertToStripeObject($resp, $opts)
             \Stripe\Coupon::OBJECT_NAME => 'Stripe\\Coupon',
             \Stripe\CreditNote::OBJECT_NAME => 'Stripe\\CreditNote',
             \Stripe\Customer::OBJECT_NAME => 'Stripe\\Customer',
+            \Stripe\CustomerBalanceTransaction::OBJECT_NAME => 'Stripe\\CustomerBalanceTransaction',
             \Stripe\Discount::OBJECT_NAME => 'Stripe\\Discount',
             \Stripe\Dispute::OBJECT_NAME => 'Stripe\\Dispute',
             \Stripe\EphemeralKey::OBJECT_NAME => 'Stripe\\EphemeralKey',

tests/Stripe/CustomerBalanceTransactionTest.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Stripe;
+
+class CustomerBalanceTransactionTest extends TestCase
+{
+    const TEST_CUSTOMER_ID = 'cus_123';
+    const TEST_RESOURCE_ID = 'cbtxn_123';
+
+    public function testHasCorrectUrl()
+    {
+        $resource = \Stripe\Customer::retrieveBalanceTransaction(self::TEST_CUSTOMER_ID, self::TEST_RESOURCE_ID);
+        $this->assertSame(
+            "/v1/customers/" . self::TEST_CUSTOMER_ID . "/balance_transactions/" . self::TEST_RESOURCE_ID,
+            $resource->instanceUrl()
+        );
+    }
+}

tests/Stripe/CustomerTest.php

@@ -7,6 +7,7 @@ class CustomerTest extends TestCase
     const TEST_RESOURCE_ID = 'cus_123';
     const TEST_SOURCE_ID = 'ba_123';
     const TEST_TAX_ID_ID = 'txi_123';
+    const TEST_CUSTOMER_BALANCE_TRANSACTION_ID = 'cbtxn_123';
 
     public function testIsListable()
     {
@@ -304,4 +305,44 @@ public function testCanListTaxIds()
         $resources = Customer::allTaxIds(self::TEST_RESOURCE_ID);
         $this->assertTrue(is_array($resources->data));
     }
+
+    public function testCanCreateBalanceTransaction()
+    {
+        $this->expectsRequest(
+            'post',
+            '/v1/customers/' . self::TEST_RESOURCE_ID . '/balance_transactions'
+        );
+        $resource = Customer::createBalanceTransaction(self::TEST_RESOURCE_ID, [
+            "amount" => 1234,
+            "currency" => "usd",
+        ]);
+    }
+
+    public function testCanRetrieveBalanceTransaction()
+    {
+        $this->expectsRequest(
+            'get',
+            '/v1/customers/' . self::TEST_RESOURCE_ID . '/balance_transactions/' . self::TEST_CUSTOMER_BALANCE_TRANSACTION_ID
+        );
+        $resource = Customer::retrieveBalanceTransaction(self::TEST_RESOURCE_ID, self::TEST_CUSTOMER_BALANCE_TRANSACTION_ID);
+    }
+
+    public function testCanUpdateBalanceTransaction()
+    {
+        $this->expectsRequest(
+            'post',
+            '/v1/customers/' . self::TEST_RESOURCE_ID . '/balance_transactions/' . self::TEST_CUSTOMER_BALANCE_TRANSACTION_ID
+        );
+        $resource = Customer::updateBalanceTransaction(self::TEST_RESOURCE_ID, self::TEST_CUSTOMER_BALANCE_TRANSACTION_ID, ["description" => "new"]);
+    }
+
+    public function testCanListCustomerBalanceTransactions()
+    {
+        $this->expectsRequest(
+            'get',
+            '/v1/customers/' . self::TEST_RESOURCE_ID . '/balance_transactions'
+        );
+        $resources = Customer::allBalanceTransactions(self::TEST_RESOURCE_ID);
+        $this->assertTrue(is_array($resources->data));
+    }
 }

tests/bootstrap.php

@@ -2,7 +2,7 @@
 
 require_once(__DIR__ . '/StripeMock.php');
 
-define("MOCK_MINIMUM_VERSION", "0.57.0");
+define("MOCK_MINIMUM_VERSION", "0.58.0");
 
 if (\Stripe\StripeMock::start()) {
     register_shutdown_function('\Stripe\StripeMock::stop');