From 71e59c018ec22ba5cb75e243876ffd276131bc36 Mon Sep 17 00:00:00 2001
From: Remi Jannel <remi@stripe.com>
Date: Fri, 3 May 2019 20:27:55 -0700
Subject: [PATCH] Add support for Customer Balance Transaction resource and
 APIs

---
 init.php                                      |  1 +
 lib/CreditNote.php                            |  1 +
 lib/Customer.php                              | 54 +++++++++++-
 lib/CustomerBalanceTransaction.php            | 88 +++++++++++++++++++
 lib/Util/Util.php                             |  1 +
 .../Stripe/CustomerBalanceTransactionTest.php | 18 ++++
 tests/Stripe/CustomerTest.php                 | 41 +++++++++
 7 files changed, 203 insertions(+), 1 deletion(-)
 create mode 100644 lib/CustomerBalanceTransaction.php
 create mode 100644 tests/Stripe/CustomerBalanceTransactionTest.php

diff --git a/init.php b/init.php
index d476e32d2e..e3cb473bdf 100644
--- a/init.php
+++ b/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');
diff --git a/lib/CreditNote.php b/lib/CreditNote.php
index 169ed0815c..64ecc5c8a5 100644
--- a/lib/CreditNote.php
+++ b/lib/CreditNote.php
@@ -8,6 +8,7 @@
  * @property string $id
  * @property string $object
  * @property int $amount
+ * @property StripeObject $customer_balance_transaction
  * @property int $created
  * @property string $currency
  * @property string $customer
diff --git a/lib/Customer.php b/lib/Customer.php
index acb5c3131c..710f778273 100644
--- a/lib/Customer.php
+++ b/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_CUSTOMER_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 customer 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_CUSTOMER_BALANCE_TRANSACTIONS, $params, $opts);
+    }
+
+    /**
+     * @param string|null $id The ID of the customer to which the customer balance transaction belongs.
+     * @param string|null $balanceTransactionId The ID of the customer 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_CUSTOMER_BALANCE_TRANSACTIONS, $balanceTransactionId, $params, $opts);
+    }
+
+    /**
+     * @param string|null $id The ID of the customer on which to update the customer balance transaction.
+     * @param string|null $balanceTransactionId The ID of the customer 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_CUSTOMER_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 allCustomerBalanceTransactions($id, $params = null, $opts = null)
+    {
+        return self::_allNestedResources($id, static::PATH_CUSTOMER_BALANCE_TRANSACTIONS, $params, $opts);
+    }
 }
diff --git a/lib/CustomerBalanceTransaction.php b/lib/CustomerBalanceTransaction.php
new file mode 100644
index 0000000000..a8997b0257
--- /dev/null
+++ b/lib/CustomerBalanceTransaction.php
@@ -0,0 +1,88 @@
+<?php
+
+namespace Stripe;
+
+/**
+ * Class CustomerBalanceTransaction
+ *
+ * @package Stripe
+ *
+ * @property string $id
+ * @property string $object
+ * @property int $amount
+ * @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 customer 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_MIGRATION               = 'migration';
+    const TYPE_UNSPENT_RECEIVER_CREDIT = 'unspent_receiver_credit';
+
+    /**
+     * @return string The API URL for this customer 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 Customer 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 Customer Balance Transaction using Customer::updateBalanceTransaction('cus_123', 'cbtxn_123', $params) instead.";
+        throw new Error\InvalidRequest($msg, null);
+    }
+}
diff --git a/lib/Util/Util.php b/lib/Util/Util.php
index 24e7421214..d133cc4030 100644
--- a/lib/Util/Util.php
+++ b/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',
diff --git a/tests/Stripe/CustomerBalanceTransactionTest.php b/tests/Stripe/CustomerBalanceTransactionTest.php
new file mode 100644
index 0000000000..817a46899f
--- /dev/null
+++ b/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()
+        );
+    }
+}
diff --git a/tests/Stripe/CustomerTest.php b/tests/Stripe/CustomerTest.php
index 1defcbfa4b..c09f5d750e 100644
--- a/tests/Stripe/CustomerTest.php
+++ b/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::allCustomerBalanceTransactions(self::TEST_RESOURCE_ID);
+        $this->assertTrue(is_array($resources->data));
+    }
 }