[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  namespace Balanced;
   4  
   5  use Balanced\Resource;
   6  use Balanced\Errors;
   7  use Balanced\Account;
   8  use \RESTful\URISpec;
   9  
  10  /**
  11   * Represents a marketplace.
  12   *
  13   * To get started you create an api key and then create a marketplace:
  14   *
  15   * <code>
  16   * $api_key = new \Balanced\APIKey();
  17   * $api_key->save();
  18   * $secret = $api_key->secret  // better save this somewhere
  19   * print $secret;
  20   * \Balanced\Settings::$api_key = $secret;
  21   *
  22   * $marketplace = new \Balanced\Marketplace();
  23   * $marketplace->save();
  24   * var_dump($marketplace);
  25   * </code>
  26   *
  27   * Each api key is uniquely associated with an api key so once you've created a
  28   * marketplace:
  29   *
  30   * <code>
  31   * \Balanced\Settings::$api_key = $secret;
  32   * $marketplace = \Balanced\Marketplace::mine();  // this is the marketplace associated with $secret
  33   * </code>
  34   */
  35  class Marketplace extends Resource
  36  {
  37      protected static $_uri_spec = null;
  38  
  39      public static function init()
  40      {
  41          self::$_uri_spec = new URISpec('marketplaces', 'id', '/v1');
  42          self::$_registry->add(get_called_class());
  43      }
  44  
  45      /**
  46       * Get the marketplace associated with the currently configured
  47       * \Balanced\Settings::$api_key.
  48       *
  49       * @throws \RESTful\Exceptions\NoResultFound
  50       * @return \Balanced\Marketplace
  51       */
  52      public static function mine()
  53      {
  54          return self::query()->one();
  55      }
  56  
  57      /**
  58       * Create a card. These can later be associated with an account using
  59       * \Balanced\Account->addCard or \Balanced\Marketplace->createBuyer.
  60       *
  61       * @param string street_address Street address. Use null if there is no address for the card.
  62       * @param string city City. Use null if there is no address for the card.
  63       * @param string postal_code Postal code. Use null if there is no address for the card.
  64       * @param string name Name as it appears on the card.
  65       * @param string card_number Card number.
  66       * @param string security_code Card security code. Use null if it is no available.
  67       * @param int expiration_month Expiration month.
  68       * @param int expiration_year Expiration year.
  69       *
  70       * @return \Balanced\Card
  71       */
  72      public function createCard(
  73          $street_address,
  74          $city,
  75          $region,
  76          $postal_code,
  77          $name,
  78          $card_number,
  79          $security_code,
  80          $expiration_month,
  81          $expiration_year)
  82      {
  83          if ($region != null && strlen($region) > 0) {
  84              trigger_error("The region parameter will be deprecated in the next minor version of balanced-php", E_USER_NOTICE);
  85          }
  86  
  87          return $this->cards->create(array(
  88              'street_address' => $street_address,
  89              'city' => $city,
  90              'region' => $region,
  91              'postal_code' => $postal_code,
  92              'name' => $name,
  93              'card_number' => $card_number,
  94              'security_code' => $security_code,
  95              'expiration_month' => $expiration_month,
  96              'expiration_year' => $expiration_year
  97              ));
  98      }
  99  
 100      /**
 101       * Create a bank account. These can later be associated with an account
 102       * using \Balanced\Account->addBankAccount.
 103       *
 104       * @param string name Name of the account holder.
 105       * @param string account_number Account number.
 106       * @param string routing_number Bank code or routing number.
 107       * @param string type checking or savings
 108       * @param array meta Single level mapping from string keys to string values.
 109       *
 110       * @return \Balanced\BankAccount
 111       */
 112      public function createBankAccount(
 113          $name,
 114          $account_number,
 115          $routing_number,
 116          $type,
 117          $meta = null
 118          )
 119      {
 120          return $this->bank_accounts->create(array(
 121              'name'           => $name,
 122              'account_number' => $account_number,
 123              'routing_number' => $routing_number,
 124              'type'           => $type,
 125              'meta'           => $meta
 126              ));
 127      }
 128  
 129      /**
 130       * Create a role-less account. You can later turn this into a buyer by
 131       * adding a funding source (e.g a card) or a merchant using
 132       * \Balanced\Account->promoteToMerchant.
 133       *
 134       * @param string email_address Optional email address. There can only be one account with this email address.
 135       * @param array[string]string meta Optional metadata to associate with the account.
 136       *
 137       * @return \Balanced\Account
 138       */
 139      public function createAccount($email_address = null, $meta = null)
 140      {
 141          return $this->accounts->create(array(
 142              'email_address' => $email_address,
 143              'meta' => $meta,
 144              ));
 145      }
 146  
 147      /**
 148       * Find or create a role-less account by email address. You can later turn
 149       * this into a buyer by adding a funding source (e.g a card) or a merchant
 150       * using \Balanced\Account->promoteToMerchant.
 151       *
 152       * @param string email_address Email address. There can only be one account with this email address.
 153       *
 154       * @return \Balanced\Account
 155       */
 156      function findOrCreateAccountByEmailAddress($email_address)
 157      {
 158          $marketplace = Marketplace::mine();
 159          try {
 160              $account = $this->accounts->create(array(
 161                      'email_address' => $email_address
 162                      ));
 163          }
 164          catch (Errors\DuplicateAccountEmailAddress $e) {
 165              $account = Account::get($e->extras->account_uri);
 166          }
 167          return $account;
 168      }
 169  
 170      /**
 171       * Create a buyer account.
 172       *
 173       * @param string email_address Optional email address. There can only be one account with this email address.
 174       * @param string card_uri URI referencing a card to associate with the account.
 175       * @param array[string]string meta Optional metadata to associate with the account.
 176       * @param string name Optional name of the account.
 177       *
 178       * @return \Balanced\Account
 179       */
 180      public function createBuyer($email_address, $card_uri, $meta = null, $name = null)
 181      {
 182          return $this->accounts->create(array(
 183              'email_address' => $email_address,
 184              'card_uri' => $card_uri,
 185              'meta' => $meta,
 186              'name' => $name
 187              ));
 188      }
 189  
 190      /**
 191       * Create a merchant account.
 192       *
 193       * Unlike buyers the identity of a merchant must be established before
 194       * the account can function as a merchant (i.e. be credited). A merchant
 195       * can be either a person or a business. Either way that information is
 196       * represented as an associative array and passed as the merchant parameter
 197       * when creating the merchant account.
 198       *
 199       * For a person the array looks like this:
 200       *
 201       * <code>
 202       * array(
 203       *     'type' => 'person',
 204       *     'name' => 'William James',
 205       *     'tax_id' => '393-48-3992',
 206       *     'street_address' => '167 West 74th Street',
 207       *     'postal_code' => '10023',
 208       *     'dob' => '1842-01-01',
 209       *     'phone_number' => '+16505551234',
 210       *     'country_code' => 'USA'
 211       *     )
 212       * </code>
 213       *
 214       * For a business the array looks like this:
 215       *
 216       * <code>
 217       * array(
 218       *     'type' => 'business',
 219       *     'name' => 'Levain Bakery',
 220       *     'tax_id' => '253912384',
 221       *     'street_address' => '167 West 74th Street',
 222       *     'postal_code' => '10023',
 223       *     'phone_number' => '+16505551234',
 224       *     'country_code' => 'USA',
 225       *     'person' => array(
 226       *         'name' => 'William James',
 227       *         'tax_id' => '393483992',
 228       *         'street_address' => '167 West 74th Street',
 229       *         'postal_code' => '10023',
 230       *         'dob' => '1842-01-01',
 231       *         'phone_number' => '+16505551234',
 232       *         'country_code' => 'USA',
 233       *         )
 234       *     )
 235       * </code>
 236       *
 237       * In some cases the identity of the merchant, person or business, cannot
 238       * be verified in which case a \Balanced\Exceptions\HTTPError is thrown:
 239       *
 240       * <code>
 241       * $identity = array(
 242       *     'type' => 'business',
 243       *     'name' => 'Levain Bakery',
 244       *     'tax_id' => '253912384',
 245       *     'street_address' => '167 West 74th Street',
 246       *     'postal_code' => '10023',
 247       *     'phone_number' => '+16505551234',
 248       *     'country_code' => 'USA',
 249       *     'person' => array(
 250       *         'name' => 'William James',
 251       *         'tax_id' => '393483992',
 252       *         'street_address' => '167 West 74th Street',
 253       *         'postal_code' => '10023',
 254       *         'dob' => '1842-01-01',
 255       *         'phone_number' => '+16505551234',
 256       *         'country_code' => 'USA',
 257       *         ),
 258       *     );
 259       *
 260       *  try {
 261       *      $merchant = \Balanced\Marketplace::mine()->createMerchant(
 262       *          '[email protected]',
 263       *          $identity,
 264       *          );
 265       *  catch (\Balanced\Exceptions\HTTPError $e) {
 266       *      if ($e->code != 300) {
 267       *          throw $e;
 268       *      }
 269       *      print e->response->header['Location'] // this is where merchant must signup
 270       *  }
 271       * </code>
 272       *
 273       * Once the merchant has completed signup you can use the resulting URI to
 274       * create an account for them on your marketplace:
 275       *
 276       * <code>
 277       * $merchant = self::$marketplace->createMerchant(
 278       *     '[email protected]',
 279       *     null,
 280       *     null,
 281       *     $merchant_uri
 282       *     );
 283       * </coe>
 284       *
 285       * @param string email_address Optional email address. There can only be one account with this email address.
 286       * @param array[string]mixed merchant Associative array describing the merchants identity.
 287       * @param string $bank_account_uri Optional URI referencing a bank account to associate with this account.
 288       * @param string $merchant_uri URI of a merchant created via the redirection sign-up flow.
 289       * @param string $name Optional name of the merchant.
 290       * @param array[string]string meta Optional metadata to associate with the account.
 291       *
 292       * @return \Balanced\Account
 293       */
 294      public function createMerchant(
 295          $email_address = null,
 296          $merchant = null,
 297          $bank_account_uri = null,
 298          $merchant_uri = null,
 299          $name = null,
 300          $meta = null)
 301      {
 302          return $this->accounts->create(array(
 303              'email_address' => $email_address,
 304              'merchant' => $merchant,
 305              'merchant_uri' => $merchant_uri,
 306              'bank_account_uri' => $bank_account_uri,
 307              'name' => $name,
 308              'meta' => $meta,
 309              ));
 310      }
 311  
 312      /*
 313       * Create a callback.
 314       *
 315       * @param string url URL of callback.
 316       */
 317      public function createCallback(
 318          $url
 319      )
 320      {
 321          return $this->callbacks->create(array(
 322              'url' => $url
 323          ));
 324      }
 325  }