V2 add support for Apply Credit Balance to existing invoice feature

Add new available_credit_balance_in_cents attribute to
Recurly_AccountBalance. The available_credit_balance_in_cents attribute
is a similar format to the balance_in_cents attribute and contains
the total of open balances for credit invoices in each currency.
This value is useful when trying to determine if the customer's
account has any available credit that can be applied to an
existing collectible invoice on the account.

Add new applyCreditBalance method to Recurly_Invoice. This action will
be available for collectible charge invoices. If the account has
available credit it will be applied to pay down the balance on the
invoice.

Tests/Recurly/AccountBalance_Test.php

@@ -33,5 +33,9 @@ public function testGet() {
     $this->assertInstanceOf('Recurly_CurrencyList', $balance->processing_prepayment_balance_in_cents);
     $this->assertEquals(-3000, $balance->processing_prepayment_balance_in_cents['USD']->amount_in_cents);
     $this->assertEquals(0, $balance->processing_prepayment_balance_in_cents['EUR']->amount_in_cents);
+
+    $this->assertInstanceOf('Recurly_CurrencyList', $balance->available_credit_balance_in_cents);
+    $this->assertEquals(-3000, $balance->available_credit_balance_in_cents['USD']->amount_in_cents);
+    $this->assertEquals(0, $balance->available_credit_balance_in_cents['EUR']->amount_in_cents);
   }
 }

Tests/Recurly/Invoice_Test.php

@@ -117,6 +117,15 @@ public function testForceCollect() {
     $this->assertEquals($invoice->state, 'paid');
   }
 
+  public function testApplyCreditBalance() {
+    // See the notes in testMarkSuccessful().
+    $this->client->addResponse('PUT', 'https://api.recurly.com/v2/invoices/1001/apply_credit_balance', 'invoices/apply_credit_balance-200.xml');
+
+    $invoice = Recurly_Invoice::get('1001', $this->client);
+    $invoice->applyCreditBalance();
+    $this->assertEquals($invoice->state, 'paid');
+  }
+
   public function testMarkFailed() {
     // See the notes in testMarkSuccessful().
     $this->client->addResponse('PUT', 'https://api.recurly.com/v2/invoices/1001/mark_failed', 'invoices/mark_failed-200.xml');

Tests/fixtures/balance/show-200.xml

@@ -13,4 +13,8 @@ Content-Type: application/xml; charset=utf-8
     <USD type="integer">-3000</USD>
     <EUR type="integer">0</EUR>
   </processing_prepayment_balance_in_cents>
+  <available_credit_balance_in_cents>
+    <USD type="integer">-3000</USD>
+    <EUR type="integer">0</EUR>
+  </available_credit_balance_in_cents>
 </account_balance>

Tests/fixtures/invoices/apply_credit_balance-200.xml

@@ -0,0 +1,41 @@
+HTTP/1.1 200 OK
+Content-Type: application/xml; charset=utf-8
+
+<?xml version="1.0" encoding="UTF-8"?>
+<invoice href="https://api.recurly.com/v2/invoices/1001">
+  <account href="https://api.recurly.com/v2/accounts/1"/>
+  <uuid>012345678901234567890123456789aa</uuid>
+  <state>paid</state>
+  <invoice_number type="integer">1001</invoice_number>
+  <invoice_number_prefix></invoice_number_prefix>
+  <po_number nil="nil"></po_number>
+  <vat_number nil="nil"></vat_number>
+  <subtotal_in_cents type="integer">2995</subtotal_in_cents>
+  <tax_in_cents type="integer">0</tax_in_cents>
+  <total_in_cents type="integer">2995</total_in_cents>
+  <currency>USD</currency>
+  <created_at type="datetime">2012-05-28T17:44:13Z</created_at>
+  <line_items type="array">
+    <adjustment href="https://api.recurly.com/v2/adjustments/190357944dad4d461272774dd184a17e" type="charge">
+      <account href="https://api.recurly.com/v2/accounts/1"/>
+      <invoice href="https://api.recurly.com/v2/invoices/1001"/>
+      <uuid>012345678901234567890123456789ab</uuid>
+      <state>invoiced</state>
+      <description>Silver Plan</description>
+      <accounting_code></accounting_code>
+      <origin>plan</origin>
+      <unit_amount_in_cents type="integer">2995</unit_amount_in_cents>
+      <quantity type="integer">1</quantity>
+      <discount_in_cents type="integer">0</discount_in_cents>
+      <tax_in_cents type="integer">0</tax_in_cents>
+      <total_in_cents type="integer">2995</total_in_cents>
+      <currency>USD</currency>
+      <taxable type="boolean">false</taxable>
+      <start_date type="datetime">2012-05-28T17:44:13Z</start_date>
+      <end_date type="datetime">2013-05-28T17:44:13Z</end_date>
+      <created_at type="datetime">2012-05-28T17:44:13Z</created_at>
+    </adjustment>
+  </line_items>
+  <transactions type="array">
+  </transactions>
+</invoice>

lib/recurly/account_balance.php

@@ -7,6 +7,8 @@
  * @property Recurly_CurrencyList $balance_in_cents The account balance in cents for each currency.
  * @property Recurly_CurrencyList $processing_prepayment_balance_in_cents The account processing
  * prepayment balance in cents for each currency.
+ * @property Recurly_CurrencyList $available_credit_balance_in_cents The account open
+ * credit balance in cents for each currency.
  */
 class Recurly_AccountBalance extends Recurly_Resource
 {
@@ -18,6 +20,7 @@ function __construct($href = null, $client = null) {
     parent::__construct($href, $client);
     $this->balance_in_cents = new Recurly_CurrencyList('balance_in_cents');
     $this->processing_prepayment_balance_in_cents = new Recurly_CurrencyList('processing_prepayment_balance_in_cents');
+    $this->available_credit_balance_in_cents = new Recurly_CurrencyList('available_credit_balance_in_cents');
   }
 
   protected function getNodeName() {

lib/recurly/invoice.php

@@ -139,6 +139,13 @@ public function forceCollect($transaction_type = null) {
     $this->_save(Recurly_Client::PUT, $this->uri() . '/collect', $body, $this->_client);
   }
 
+  /**
+   * @throws Recurly_Error
+   */
+  public function applyCreditBalance() {
+    $this->_save(Recurly_Client::PUT, $this->uri() . '/apply_credit_balance');
+  }
+
   /**
    * @throws Recurly_Error
    */

lib/recurly/util/xml_tools.php

@@ -21,6 +21,7 @@ class XmlTools
     'add_ons' => 'Recurly_AddonList',
     'adjustment' => 'Recurly_Adjustment',
     'adjustments' => 'Recurly_AdjustmentList',
+    'available_credit_balance_in_cents' => 'Recurly_CurrencyList',
     'balance_in_cents' => 'Recurly_CurrencyList',
     'billing_info' => 'Recurly_BillingInfo',
     'billing_infos' => 'Recurly_BillingInfoList',