[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  namespace Balanced;
   4  
   5  use Balanced\Resource;
   6  use \RESTful\URISpec;
   7  
   8  /**
   9   * Represents pending debit of funds for an account. The funds for that debit
  10   * are held by the processor. You can later capture the hold, which results in
  11   * debit, or void it, which releases the held funds.
  12   * 
  13   * Note that a hold can expire so you should always check
  14   * Balanced\Hold::expires_at.
  15   * 
  16   * You create these using \Balanced\Account::hold.
  17   * 
  18   * <code>
  19   * $marketplace = \Balanced\Marketplace::mine();
  20   *     
  21   * $account = $marketplace
  22   *     ->accounts
  23   *     ->query()
  24   *     ->filter(Account::f->email_address->eq('[email protected]'))
  25   *     ->one();
  26   *     
  27   * $hold = $account->hold(
  28   *     100,
  29   *     'a description',
  30   *     null,
  31   *     array(
  32   *         'my_id': '1293712837'
  33   *         )
  34   *     );
  35   * 
  36   * $debit = $hold->capture(); 
  37   * </code>
  38   */
  39  class Hold extends Resource
  40  {
  41      protected static $_uri_spec = null;
  42      
  43      public static function init()
  44      {
  45          self::$_uri_spec = new URISpec('holds', 'id');
  46          self::$_registry->add(get_called_class());
  47      }
  48      
  49      /**
  50       ** Voids a pending hold. This releases the held funds. Once voided a hold
  51       * is not longer pending can cannot be re-captured or re-voided.
  52       * 
  53       * @return \Balanced\Hold
  54       */
  55      public function void()
  56      {
  57          $this->is_void = true;
  58          return $this->save();
  59      }
  60      
  61      /**
  62       * Captures a pending hold. This results in a debit. Once captured a hold
  63       * is not longer pending can cannot be re-captured or re-voided.
  64       * 
  65       * @param int amount Optional Portion of the pending hold to capture. If not specified the full amount associated with the hold is captured.
  66       * 
  67       * @return \Balanced\Debit
  68       */
  69      public function capture($amount = null)
  70      {
  71          $this->debit = $this->account->debits->create(array(
  72              'hold_uri' => $this->uri,
  73              'amount' => $amount,
  74              ));
  75          return $this->debit;
  76      }
  77  }