[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  namespace Balanced;
   4  
   5  use Balanced\Resource;
   6  use \RESTful\URISpec;
   7  
   8  /**
   9   * Represent a buyer or merchant account on a marketplace.
  10   * 
  11   * You create these using Balanced\Marketplace->createBuyer or 
  12   * Balanced\Marketplace->createMerchant.
  13   * 
  14   * <code>
  15   * $marketplace = \Balanced\Marketplace::mine();
  16   * 
  17   * $card = $marketplace->cards->create(array(
  18   *     'street_address' => $street_address,
  19   *     'city' => 'Jollywood',
  20   *     'region' => 'CA',
  21   *     'postal_code' => '90210',
  22   *     'name' => 'Captain Chunk',
  23   *     'card_number' => '4111111111111111',
  24   *     'expiration_month' => 7,
  25   *     'expiration_year' => 2015
  26   *     ));
  27   *     
  28   * $buyer = $marketplace->createBuyer(
  29   *     '[email protected]',
  30   *     $card->uri,
  31   *     array(
  32   *         'my_id' => '1212121',
  33   *         )
  34   *     );
  35   * </code>
  36   * 
  37   * @see Balanced\Marketplace->createBuyer
  38   * @see Balanced\Marketplace->createMerchant
  39   */
  40  class Account extends Resource
  41  {
  42      protected static $_uri_spec = null;
  43  
  44      public static function init()
  45      {
  46          self::$_uri_spec = new URISpec('accounts', 'id');
  47          self::$_registry->add(get_called_class());
  48      }
  49      
  50      /**
  51       * Credit the account.
  52       * 
  53       * @param int amount Amount to credit the account in USD pennies.
  54       * @param string description Optional description of the credit.
  55       * @param array[string]string meta Optional metadata to associate with the credit.
  56       * @param mixed destination Optional URI of a funding destination (i.e. \Balanced\BankAccount) associated with this account to credit. If not specified the funding destination most recently added to the account is used.
  57       * @param string appears_on_statement_as Optional description of the credit as it will appears on the customer's billing statement.
  58       * 
  59       * @return \Balanced\Credit
  60       */
  61      public function credit(
  62          $amount,
  63          $description = null,
  64          $meta = null,
  65          $destination = null,
  66          $appears_on_statement_as = null)
  67      {
  68          if ($destination == null)
  69              $destination_uri = null;
  70          else
  71              $destination_uri = is_string($destination) ? $destination : $destination->uri;
  72          return $this->credits->create(array(
  73              'amount' => $amount,
  74              'description' => $description,
  75              'meta' => $meta,
  76              'destination_uri' => $destination_uri,
  77              'appears_on_statement_as' => $appears_on_statement_as
  78              ));
  79      }
  80      
  81      /**
  82       * Debit the account.
  83       * 
  84       * @param int amount Amount to debit the account in USD pennies.   
  85       * @param string appears_on_statement_as Optional description of the debit as it will appears on the customer's billing statement.
  86       * @param string description Optional description of the debit.
  87       * @param array[string]string meta Optional metadata to associate with the debit.
  88       * @param mixed Optional funding source (i.e. \Balanced\Card) or URI of a funding source associated with this account to debit. If not specified the funding source most recently added to the account is used.
  89       * 
  90       * @return \Balanced\Debit
  91       */
  92      public function debit(
  93          $amount,
  94          $appears_on_statement_as = null,
  95          $description = null,
  96          $meta = null,
  97          $source = null,
  98          $on_behalf_of = null)
  99      {
 100          if ($source == null) {
 101              $source_uri = null;
 102          } else if (is_string($source)) {
 103              $source_uri = $source;
 104          } else {
 105              $source_uri = $source->uri;
 106          }
 107  
 108          if ($on_behalf_of == null) {
 109              $on_behalf_of_uri = null;
 110          } else if (is_string($on_behalf_of)) {
 111              $on_behalf_of_uri = $on_behalf_of;
 112          } else {
 113              $on_behalf_of_uri = $on_behalf_of->uri;
 114          }
 115  
 116          if (isset($this->uri) && $on_behalf_of_uri == $this->uri)
 117              throw new \InvalidArgumentException(
 118                  'The on_behalf_of parameter MAY NOT be the same account as the account you are debiting!'
 119              );
 120  
 121          return $this->debits->create(array(
 122              'amount' => $amount,
 123              'description' => $description,
 124              'meta' => $meta,
 125              'source_uri' => $source_uri,
 126              'on_behalf_of_uri' => $on_behalf_of_uri,
 127              'appears_on_statement_as' => $appears_on_statement_as
 128              ));
 129      }
 130      
 131      /**
 132       * Create a hold (i.e. a guaranteed pending debit) for account funds. You
 133       * can later capture or void. A hold is associated with a account funding
 134       * source (i.e. \Balanced\Card). If you don't specify the source then the
 135       * current primary funding source for the account is used. 
 136       * 
 137       * @param int amount Amount of the hold in USD pennies.
 138       * @param string Optional description Description of the hold.
 139       * @param string Optional URI referencing the card to use for the hold.
 140       * @param array[string]string meta Optional metadata to associate with the hold.
 141       * 
 142       * @return \Balanced\Hold
 143       */
 144      public function hold(
 145          $amount,
 146          $description = null,
 147          $source_uri = null,
 148          $meta = null)
 149      {
 150          return $this->holds->create(array(
 151              'amount' => $amount,
 152              'description' => $description,
 153              'source_uri' => $source_uri,
 154              'meta' => $meta
 155              ));
 156      }
 157      
 158      /**
 159       * Creates or associates a created card with the account. The default
 160       * funding source for the account will be this card.
 161       * 
 162       * @see \Balanced\Marketplace->createCard
 163       * 
 164       * @param mixed card \Balanced\Card or URI referencing a card to associate with the account. Alternatively it can be an associative array describing a card to create and associate with the account.
 165       * 
 166       * @return \Balanced\Account
 167       */
 168      public function addCard($card)
 169      {
 170          if (is_string($card))
 171              $this->card_uri = $card;
 172          else if (is_array($card))
 173              $this->card = $card;
 174          else
 175              $this->card_uri = $card->uri;
 176          return $this->save();
 177      }
 178      
 179      /**
 180       * Creates or associates a created bank account with the account. The
 181       * new default funding destination for the account will be this bank account.
 182       * 
 183       * @see \Balanced\Marketplace->createBankAccount
 184       * 
 185       * @param mixed bank_account \Balanced\BankAccount or URI for a bank account to associate with the account. Alternatively it can be an associative array describing a bank account to create and associate with the account.
 186       * 
 187       * @return \Balanced\Account
 188       */
 189      public function addBankAccount($bank_account)
 190      {
 191          if (is_string($bank_account))
 192              $this->bank_account_uri = $bank_account;
 193          else if (is_array($bank_account))
 194              $this->bank_account = $bank_account;
 195          else
 196              $this->bank_account_uri = $bank_account->uri;
 197          return $this->save();
 198      }
 199      
 200      /**
 201       * Promotes a role-less or buyer account to a merchant.
 202       * 
 203       * @see Balanced\Marketplace::createMerchant
 204       *
 205       * @param mixed merchant Associative array describing the merchants identity or a URI referencing a created merchant.
 206       *       
 207       * @return \Balanced\Account
 208       */
 209      public function promoteToMerchant($merchant)
 210      {
 211          if (is_string($merchant))
 212              $this->merchant_uri = $merchant;
 213          else
 214              $this->merchant = $merchant;
 215          return $this->save();
 216      }
 217  }