simplify

Package simplify |
[hide private]
[frames] | no frames]

# Source Code for Package simplify

       1
       2  #
       3  # Copyright (c) 2013 - 2022 MasterCard International Incorporated
       4  # All rights reserved.
       5  #
       6  # Redistribution and use in source and binary forms, with or without modification, are
       7  # permitted provided that the following conditions are met:
       8  #
       9  # Redistributions of source code must retain the above copyright notice, this list of
      10  # conditions and the following disclaimer.
      11  # Redistributions in binary form must reproduce the above copyright notice, this list of
      12  # conditions and the following disclaimer in the documentation and/or other materials
      13  # provided with the distribution.
      14  # Neither the name of the MasterCard International Incorporated nor the names of its
      15  # contributors may be used to endorse or promote products derived from this software
      16  # without specific prior written permission.
      17  # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
      18  # EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
      19  # OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
      20  # SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
      21  # INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
      22  # TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
      23  # OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
      24  # IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
      25  # IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
      26  # SUCH DAMAGE.
      27  #
      28
      29
      30  try:
      31      # For Python 3.0 and later
      32      from urllib.request import Request, urlopen
      33      from urllib.parse import quote
      34      from urllib.error import URLError, HTTPError
      35  except ImportError:
      36      # Fall back to Python 2's urllib2
      37      from urllib2 import Request, urlopen, quote, URLError, HTTPError
      38
      39  import sys
      40  import base64
      41  import json
      42  import hmac
      43  import hashlib
      44  import time
      45  import random
      46
      47
      48  from simplify.constants import Constants
      49  from simplify.domain import DomainFactory, Domain
      50
      51  ################################################################################
      52  # Constants
      53  ################################################################################
      54
      55  HTTP_SUCCESS = 200
      56  HTTP_REDIRECTED = 302
      57  HTTP_UNAUTHORIZED = 401
      58  HTTP_NOT_FOUND = 404
      59  HTTP_NOT_ALLOWED = 405
      60  HTTP_BAD_REQUEST = 400
      61
      62  HTTP_METHOD_POST = "POST"
      63  HTTP_METHOD_PUT = "PUT"
      64  HTTP_METHOD_GET = "GET"
      65  HTTP_METHOD_DELETE = "DELETE"
      66
      67
      68  ################################################################################
      69  # Global variables
      70  ################################################################################
      71
      72
      73  public_key = None
      74  private_key = None
      75  api_base_sandbox_url = Constants.api_base_sandbox_url
      76  api_base_live_url = Constants.api_base_live_url
      77  oauth_base_url = Constants.oauth_base_url
      78  user_agent = None
      79
      80
      81  ################################################################################
      82  # Utilities
      83  ################################################################################
      84
      85 -def build_query_string(criteria):
      86
      87      if criteria == None:
      88          return ''
      89
      90      query_string = []
      91      if 'max' in criteria:
      92          query_string.append("max=" + str(criteria['max']))
      93
      94      if 'offset' in criteria:
      95          query_string.append("offset=" + str(criteria['offset']))
      96
      97      if 'sorting' in criteria:
      98          for key, value in list(criteria['sorting'].items()):
      99              query_string.append("sorting[" + key + "]=" + quote(str(value)))
     100
     101      if 'filter' in criteria:
     102          for key, value in list(criteria['filter'].items()):
     103              query_string.append("filter[" + key + "]=" + quote(str(value)))
     104
     105      return '&'.join(query_string)
     106
     107 -def handle_http_error(response_body, response_code):
     108
     109      if response_code == HTTP_REDIRECTED:  # this shouldn't happen - if it does it's our problem
     110          raise BadRequestError("Unexpected response code returned from the API, have you got the correct URL?", response_code, response_body)
     111      elif response_code == HTTP_BAD_REQUEST:
     112          raise BadRequestError("Bad request", response_code, response_body)
     113
     114      elif response_code == HTTP_UNAUTHORIZED:
     115          raise AuthenticationError("You are not authorized to make this request.  Are you using the correct API keys?", response_code, response_body)
     116
     117      elif response_code == HTTP_NOT_FOUND:
     118          raise ObjectNotFoundError("Object not found", response_code, response_body)
     119
     120      elif response_code == HTTP_NOT_ALLOWED:
     121          raise NotAllowedError("Operation not allowed", response_code, response_body)
     122
     123      elif response_code < 500:
     124          raise BadRequestError("Bad request", response_code, response_body)
     125
     126      else:
     127          raise SysError("An unexpected error has been raised.  Looks like there's something wrong at our end." , response_code, response_body)
     128
     129
     130  ################################################################################
     131  # Authentication
     132  ################################################################################
     133
     134 -class Authentication:
     135
     136      """
     137          Holds authentication information used when accessing the API.
     138
     139          @ivar public_key: Public key used to access the API.
     140          @ivar private_key: Private key used to access the API.
     141          @ivar access_token: OAuth token used to access the API.
     142      """
     143
     144 -    def __init__(self, **kwargs):
     145          """
     146              Constructs an Authentication object.
     147
     148              @param kwargs: contains initial values for the instance variables.  Valid keywords
     149                     are public_key, private_key and access_token.  If no value is passed for
     150                     public_key or its value is None then simplify.public_key is used.  If no
     151                     value is passed for private_key or its value is None then simplify.private_key
     152                     is used.
     153              @return: an Authentication object
     154          """
     155
     156          self.public_key = kwargs['public_key'] if 'public_key' in kwargs else None
     157          if self.public_key == None:
     158              global public_key
     159              self.public_key = public_key
     160
     161          self.private_key = kwargs['private_key'] if 'private_key' in kwargs else None
     162          if self.private_key == None:
     163              global private_key
     164              self.private_key = private_key
     165
     166          self.access_token = kwargs['access_token'] if 'access_token' in kwargs else None
     167
     168
     169 -class AccessToken(Domain):
     170      """
     171          OAuth access token.
     172
     173          @ivar access_token: Access token used when making an API call authenticated using OAuth
     174          @ivar refresh_token: Token used when refreshing an access token.
     175          @ivar expires_in: Number of seconds from the time the token was created till it expires.
     176      """
     177
     178      @staticmethod
     179 -    def create(auth_code, redirect_uri, *auth_args):
     180          """
     181            Creates an AccessToken object.
     182
     183            @param auth_codes: OAuth authentication code.
     184            @param redirect_uri: URI to which OAuth requests are redirected.
     185            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
     186            @return: an AccessToken object object
     187          """
     188
     189          props = {
     190              'grant_type' : 'authorization_code',
     191              'code' : auth_code,
     192              'redirect_uri' : redirect_uri
     193          }
     194
     195          h = PaymentsApi().send_auth_request(props, 'token', PaymentsApi.create_auth_object(auth_args))
     196          return AccessToken(h)
     197
     198
     199 -    def refresh(self, *auth_args):
     200          """
     201            Refreshes an AccessToken object.  If successful the access_token, refresh_token and expires_in attributes are updated.
     202
     203            @param auth_args: an Authentication object used for the API call.  If no value is passed the global keys simplify.public_key and simplify.private_key are used.
     204          """
     205
     206          rt = self['refresh_token']
     207          if not rt:
     208              raise IllegalArgumentError("Cannot refresh access token; refresh token is invalid.")
     209
     210          props = {
     211              'grant_type' : 'refresh_token',
     212              'refresh_token' : rt
     213          }
     214
     215          h = PaymentsApi().send_auth_request(props, 'token', PaymentsApi.create_auth_object(auth_args))
     216          self.__dict__.update(h)
     217
     218
     219 -    def revoke(self, *auth_args):
     220          """
     221            Revokes an AccessToken object.
     222
     223            @param auth_args: an Authentication object used for the API call.  If no value is passed the global keys simplify.public_key and simplify.private_key are used.
     224          """
     225
     226          token = self['access_token']
     227          if not token:
     228              raise IllegalArgumentError("Cannot revoke access token; access token is invalid.")
     229
     230          props = {
     231              'token' : token,
     232              'refresh_token' : token
     233          }
     234
     235          h = PaymentsApi().send_auth_request(props, 'revoke', PaymentsApi.create_auth_object(auth_args))
     236          self.__dict__.clear()
     237
     238
     239  ################################################################################
     240  # Exceptions
     241  ################################################################################
     242
     243
     244 -class ApiError(Exception):
     245      """
     246         Base class for all API errors.
     247
     248         @ivar status: HTTP status code (or None if there is no status).
     249         @ivar reference: reference for the error (or None if there is no reference).
     250         @ivar error_code: string code for the error (or None if there is no error code).
     251         @ivar message: string description of the error (or None if there is no message).
     252         @ivar error_data: dictionary containing all the error data (or None if there is no data)
     253      """
     254
     255 -    def __init__(self, message=None, status=500, error_data=None):
     256          self.status = status
     257
     258          self.error_data = json.loads(error_data) if error_data else {}
     259          err = self.error_data['error'] if 'error' in self.error_data else {}
     260
     261          self.reference = self.error_data['reference'] if 'reference' in self.error_data else None
     262          self.error_code = err['code'] if 'code' in err else None
     263          self.message = err['message'] if 'code' in err else message
     264          super(ApiError, self).__init__(self.message)
     265
     266
     267 -    def describe(self):
     268          """
     269             Returns a string describing the error.
     270             @return: a string describing the error.
     271          """
     272          return "{0}: \"{1}\" (status: {2}, error code: {3}, reference: {4})".format(self.__class__.__name__, self.message, self.status, self.error_code, self.reference)
     273
     274
     275 -class IllegalArgumentError(ValueError):
     276      """
     277         Error raised when passing illegal arguments.
     278      """
     279      pass
     280
     281 -class ApiConnectionError(ApiError):
     282      """
     283         Error raised when there are communication errors contacting the API.
     284      """
     285      pass
     286
     287 -class AuthenticationError(ApiError):
     288      """
     289         Error raised where there are problems authentication a request.
     290      """
     291      pass
     292
     293 -class BadRequestError(ApiError):
     294
     295      """
     296         Error raised when the request contains errors.
     297
     298         @ivar has_field_errors: boolean indicating whether there are field errors.
     299         @ivar field_errors: a list containing all field errors.
     300      """
     301
     302 -    class FieldError:
     303          """
     304              Represents a single error in a field of data sent in a request to the API.
     305
     306              @ivar field_name: the name of the field with the error.
     307              @ivar error_code: a string code for the error.
     308              @ivar message: a string description of the error.
     309          """
     310 -        def __init__(self, error_data):
     311              self.field_name = error_data['field']
     312              self.error_code = error_data['code']
     313              self.message = error_data['message']
     314
     315 -        def __str__(self):
     316              return "Field error: {0} \"{1}\" ({2})".format(self.field_name, self.message, self.error_code)
     317
     318
     319 -    def __init__(self, message, status = 400, error_data = None):
     320          super(BadRequestError, self).__init__(message, status, error_data)
     321
     322          self.field_errors = []
     323          err = self.error_data['error'] if 'error' in self.error_data else {}
     324          field_errors = err['fieldErrors'] if 'fieldErrors' in err else []
     325          for field_error in field_errors:
     326              self.field_errors.append(BadRequestError.FieldError(field_error))
     327          self.has_field_errors = len(self.field_errors) > 0
     328
     329 -    def describe(self):
     330          """
     331             Returns a string describing the error.
     332             @return: a string describing the error.
     333          """
     334          txt = ApiError.describe(self)
     335          for field_error in self.field_errors:
     336              txt = txt + "\n" + str(field_error)
     337          return txt + "\n"
     338
     339 -class ObjectNotFoundError(ApiError):
     340      """
     341         Error raised when a requested object cannot be found.
     342      """
     343      pass
     344
     345 -class NotAllowedError(ApiError):
     346      """
     347         Error raised when a request was not allowed.
     348      """
     349      pass
     350
     351 -class SysError(ApiError):
     352      """
     353         Error raised when there was a system error processing a request.
     354      """
     355      pass
     356
     357
     358  ################################################################################
     359  # Http - handles the HTTP requests
     360  ################################################################################
     361
     362 -class Http:
     363 -    def __init__(self):
     364          pass
     365
     366 -    def request(self, auth, url, method, params = None):
     367
     368          if params is None:
     369              params = {}
     370
     371          jws_signature = Jws.encode(url, auth, params, method == HTTP_METHOD_POST or method == HTTP_METHOD_PUT)
     372
     373          if method == HTTP_METHOD_POST:
     374              request = Request(url, jws_signature)
     375              request.add_header("Content-Type", "application/json")
     376
     377          elif method == HTTP_METHOD_PUT:
     378              request = Request(url, jws_signature)
     379              request.add_header("Content-Type", "application/json")
     380
     381          elif method == HTTP_METHOD_DELETE:
     382              request = Request(url)
     383              request.add_header("Authorization", b"JWS " + jws_signature)
     384              request.get_method = lambda: HTTP_METHOD_DELETE
     385
     386          elif method == HTTP_METHOD_GET:
     387              request = Request(url)
     388              request.add_header("Authorization", b"JWS " + jws_signature)
     389
     390          else:
     391              raise ApiConnectionError("HTTP Method {0} not recognised".format(method))
     392
     393          request.add_header("Accept", "application/json")
     394          global user_agent
     395
     396          user_agent_hdr = "Python-SDK/" + Constants.version
     397          if user_agent != None:
     398              user_agent_hdr = user_agent_hdr + " " + user_agent
     399          request.add_header("User-Agent", user_agent_hdr)
     400
     401          try:
     402              response = urlopen(request)
     403              response_body = response.read()
     404              response_code = response.code
     405          except HTTPError as err:
     406              response_body = err.read()
     407              response_code = err.code
     408          except URLError as err:
     409              msg = "Looks like there's a problem connecting to the API endpoint: {0}\nError: {1}".format(url, str(err))
     410              raise ApiConnectionError(msg)
     411
     412          return response_body, response_code
     413
     414
     415 -    def auth_request(self, auth, url, params):
     416
     417          jws_signature = Jws.auth_encode(url, auth, params)
     418
     419          request = Request(url, jws_signature)
     420          request.add_header("Content-Type", "application/json")
     421          request.add_header("Accept", "application/json")
     422
     423          global user_agent
     424          user_agent_hdr = "Python-SDK/" + Constants.version
     425          if user_agent != None:
     426              user_agent_hdr = user_agent_hdr + " " + user_agent
     427          request.add_header("User-Agent", user_agent_hdr)
     428
     429          try:
     430              response = urlopen(request)
     431              response_body = response.read()
     432              response_code = response.code
     433          except HTTPError as err:
     434              response_body = err.read()
     435              response_code = err.code
     436          except URLError as err:
     437              msg = "Looks like there's a problem connecting to the API endpoint: {0}\nError: {1}".format(url, str(err))
     438              raise ApiConnectionError(msg)
     439
     440          return response_body, response_code
     441
     442
     443  ################################################################################
     444  # JWS WebHook Utils
     445  ################################################################################
     446
     447 -class Jws:
     448
     449      NUM_HEADERS = 7
     450      ALGORITHM = 'HS256'
     451      TYPE = 'JWS'
     452      HDR_URI = 'api.simplifycommerce.com/uri'
     453      HDR_TIMESTAMP = 'api.simplifycommerce.com/timestamp'
     454      HDR_NONCE = 'api.simplifycommerce.com/nonce'
     455      HDR_TOKEN = "api.simplifycommerce.com/token"
     456      HDR_UNAME = 'uname'
     457      HDR_ALGORITHM = 'alg'
     458      HDR_TYPE = 'typ'
     459      HDR_KEY_ID = 'kid'
     460      TIMESTAMP_MAX_DIFF = 1000 * 60 * 5   # 5 minutes
     461
     462 -    def __init__(self):
     463          pass
     464
     465      @staticmethod
     466 -    def encode(url, auth, params, has_payload):
     467
     468          jws_hdr = {'typ': Jws.TYPE,
     469                     'alg': Jws.ALGORITHM,
     470                     'kid': auth.public_key,
     471                     Jws.HDR_URI: url,
     472                     Jws.HDR_TIMESTAMP: int(round(time.time() * 1000)),
     473                     Jws.HDR_NONCE: str(random.randint(1, 10*1000))}
     474
     475          token = auth.access_token
     476          if token:
     477              jws_hdr[Jws.HDR_TOKEN] = token
     478
     479          encoded_json = Jws().encode_json(jws_hdr)
     480          header = base64.urlsafe_b64encode(encoded_json)
     481          header = header.rstrip(b'=')
     482          payload = b''
     483          if has_payload:
     484              payload = Jws().encode_json(params)
     485              payload = base64.urlsafe_b64encode(payload).rstrip(b'=')
     486
     487          msg = header + b'.' + payload
     488          signature = Jws().sign(auth.private_key, msg)
     489          return msg + b'.' + signature
     490
     491
     492      @staticmethod
     493 -    def auth_encode(url, auth, params):
     494
     495          jws_hdr = {'typ': Jws.TYPE,
     496                     'alg': Jws.ALGORITHM,
     497                     'kid': auth.public_key,
     498                     Jws.HDR_URI: url,
     499                     Jws.HDR_TIMESTAMP: int(round(time.time() * 1000)),
     500                     Jws.HDR_NONCE: str(random.randint(1, 10*1000))}
     501
     502          encoded_json = Jws().encode_json(jws_hdr)
     503          header = base64.urlsafe_b64encode(encoded_json).rstrip(b'=')
     504
     505          # Convert map to param string
     506          payload = '&'.join([ "%s=%s" % (k,v) for k,v in list(params.items())])
     507          payload = base64.urlsafe_b64encode(payload).restrip(b'=')
     508
     509          msg = header + b'.' + payload
     510          signature = Jws().sign(auth.private_key, msg)
     511          return msg + b'.' + signature
     512
     513
     514      @staticmethod
     515 -    def decode(params, auth):
     516
     517          global public_key
     518          public_api_key = auth.public_key if auth.public_key else public_key
     519
     520          if not public_api_key:
     521              raise IllegalArgumentError("Must have a valid public key to connect to the API")
     522
     523          global private_key
     524          private_api_key = auth.private_key if auth.private_key else private_key
     525
     526          if not private_api_key:
     527              raise IllegalArgumentError("Must have a valid private key to connect to the API")
     528
     529          if not 'payload' in params:
     530              raise IllegalArgumentError("Event data is missing payload")
     531
     532          payload = params['payload'].strip()
     533          data = payload.split('.')
     534          if len(data) != 3:
     535              raise IllegalArgumentError("Incorrectly formatted JWS message")
     536
     537          msg = "{0}.{1}".format(data[0], data[1])
     538          header = Jws().safe_base64_decode(data[0])
     539          payload = Jws().safe_base64_decode(data[1])
     540          signature = data[2]
     541
     542          url = None
     543          if 'url' in params:
     544              url = params['url']
     545          Jws().verify(header, url, public_api_key)
     546
     547          if signature != Jws().sign(private_api_key, msg):
     548              raise AuthenticationError("JWS signature does not match")
     549
     550          return json.loads(payload)
     551
     552 -    def sign(self, private_api_key, msg):
     553          decoded_private_api_key = Jws().safe_base64_decode(private_api_key)
     554          signature =  hmac.new(decoded_private_api_key, msg, hashlib.sha256).digest()
     555          return base64.urlsafe_b64encode(signature).rstrip(b'=')
     556
     557 -    def verify(self, header, url, public_api_key):
     558
     559          hdr = json.loads(header)
     560
     561          if len(hdr) != Jws.NUM_HEADERS:
     562              raise AuthenticationError("Incorrect number of JWS header parameters - found {0} but expected {1}".format(len(hdr), Jws.NUM_HEADERS))
     563
     564          if not Jws.HDR_ALGORITHM in hdr:
     565              raise AuthenticationError("Missing algorithm header")
     566
     567          if hdr[Jws.HDR_ALGORITHM] != Jws.ALGORITHM:
     568              raise AuthenticationError("Incorrect algorithm - found {0} but required {1}".format(hdr[Jws.HDR_ALGORITHM], Jws.ALGORITHM))
     569
     570          if not Jws.HDR_TYPE in hdr:
     571              raise AuthenticationError("Missing type header")
     572
     573          if hdr[Jws.HDR_TYPE] != Jws.TYPE:
     574              raise AuthenticationError("Incorrect type - found {0} but required {JWS_TYPE}".format(hdr[Jws.HDR_TYPE], Jws.TYPE))
     575
     576          if not Jws.HDR_KEY_ID in hdr:
     577              raise AuthenticationError("Missing Key ID")
     578
     579          # keys don't match and it is a live key
     580          if hdr[Jws.HDR_KEY_ID] != public_api_key and public_api_key.startswith("lvpb"):
     581              raise AuthenticationError("Invalid Key ID")
     582
     583          if not Jws.HDR_NONCE in hdr:
     584              raise AuthenticationError("Missing nonce")
     585
     586          if not Jws.HDR_URI in hdr:
     587              raise AuthenticationError("Missing URI")
     588
     589          if url != None and hdr[Jws.HDR_URI] != url:
     590              raise AuthenticationError("Incorrect URL - found {0} but required {1}".format(hdr[Jws.HDR_URI], url))
     591
     592          if not Jws.HDR_TIMESTAMP in hdr:
     593              raise AuthenticationError("Missing timestamp")
     594
     595          if not Jws.HDR_UNAME in hdr:
     596              raise AuthenticationError("Missing username")
     597
     598          # calculate time difference between when the request was created and now
     599          time_now = int(round(time.time() * 1000))
     600          timestamp = int(hdr[Jws.HDR_TIMESTAMP])
     601          diff = time_now - timestamp
     602
     603          if diff > Jws.TIMESTAMP_MAX_DIFF:
     604              raise AuthenticationError("Invalid timestamp, the event has expired")
     605
     606 -    def safe_base64_decode(self, url):
     607
     608          length = len(url) % 4
     609          if length == 2:
     610              return base64.urlsafe_b64decode(url + b'==')
     611          if length == 3:
     612              return base64.urlsafe_b64decode(url + b'=')
     613
     614          return base64.urlsafe_b64decode(url)
     615
     616 -    def encode_json(self, json_str):
     617
     618          try:
     619              return json.dumps(json_str).encode('utf-8')
     620          except Exception:
     621              raise ApiError("Invalid format for JSON request")
     622
     623
     624  ################################################################################
     625  # PaymentsApi
     626  ################################################################################
     627
     628 -class PaymentsApi:
     629
     630
     631 -    def __init__(self):
     632          pass
     633
     634      @staticmethod
     635 -    def create_auth_object(auth_args):
     636
     637          global public_key
     638          global private_key
     639
     640          if len(auth_args) == 0:
     641              auth = Authentication(public_key = public_key, private_key = private_key)
     642
     643          elif len(auth_args) == 1:
     644              auth = auth_args[0]
     645              if not isinstance(auth, Authentication):
     646                  raise IllegalArgumentError("Invalid Authentication object passed")
     647
     648          elif len(auth_args) == 2:
     649              public_api_key = auth_args[0]
     650              if public_api_key == None:
     651                  public_api_key = public_key
     652              private_api_key = auth_args[1]
     653              if private_api_key == None:
     654                  private_api_key = private_key
     655              auth = Authentication(public_key = public_api_key, private_key = private_api_key)
     656
     657          else:
     658              raise IllegalArgumentError("Invalid authentication arguments passed")
     659
     660          return auth
     661
     662
     663      @staticmethod
     664 -    def check_auth(auth):
     665
     666          if auth == None:
     667              raise IllegalArgumentError("Missing authentication object")
     668
     669          if auth.public_key == None:
     670              raise IllegalArgumentError("Must have a valid public key to connect to the API")
     671
     672          if auth.private_key == None:
     673              raise IllegalArgumentError("Must have a valid private key to connect to the API")
     674
     675
     676
     677      @staticmethod
     678 -    def create(object_type, auth_args, params):
     679
     680          auth = PaymentsApi.create_auth_object(auth_args)
     681          url = PaymentsApi.build_request_url(object_type)
     682          response = PaymentsApi().execute(object_type, auth, url, HTTP_METHOD_POST, params)
     683
     684          return response
     685
     686      @staticmethod
     687 -    def list(object_type, auth_args, criteria):
     688
     689          auth = PaymentsApi.create_auth_object(auth_args)
     690          url = PaymentsApi.build_request_url(object_type)
     691          query_string = build_query_string(criteria)
     692          if len(query_string) > 0:
     693              url = url + '?' + query_string
     694          response = PaymentsApi().execute(object_type, auth, url, HTTP_METHOD_GET)
     695
     696          return response
     697
     698      @staticmethod
     699 -    def find(object_type, auth_args, object_id):
     700
     701          auth = PaymentsApi.create_auth_object(auth_args)
     702          if not object_id:
     703              raise IllegalArgumentError("object_object_id is a required field")
     704
     705          url = PaymentsApi.build_request_url(object_type, object_id)
     706          response = PaymentsApi().execute(object_type, auth, url, HTTP_METHOD_GET)
     707
     708          return response
     709
     710      @staticmethod
     711 -    def update(object_type, auth_args, object_id, params):
     712
     713          auth = PaymentsApi.create_auth_object(auth_args)
     714          if not object_id:
     715              raise IllegalArgumentError("object_id is a required field")
     716
     717          url = PaymentsApi.build_request_url(object_type, object_id)
     718          response = PaymentsApi().execute(object_type, auth, url, HTTP_METHOD_PUT, params)
     719
     720          return response
     721
     722      @staticmethod
     723 -    def delete(object_type, auth_args, object_id):
     724
     725          auth = PaymentsApi.create_auth_object(auth_args)
     726          if not object_id:
     727              raise IllegalArgumentError("object_id is a required field")
     728
     729          url = PaymentsApi.build_request_url(object_type, object_id)
     730          response = PaymentsApi().execute(object_type, auth, url, HTTP_METHOD_DELETE)
     731
     732          return response
     733
     734 -    def decode(self, auth_args, params):
     735
     736          auth = PaymentsApi.create_auth_object(auth_args)
     737          PaymentsApi.check_auth(auth)
     738
     739          return Jws.decode(params, auth)
     740
     741
     742 -    def execute(self, object_type, auth, url_suffix, method, params = None):
     743
     744          if params is None:
     745              params = {}
     746
     747          PaymentsApi.check_auth(auth)
     748
     749          http = Http()
     750
     751          global api_base_sandbox_url
     752          global api_base_live_url
     753
     754          base_url = api_base_sandbox_url
     755          if auth.public_key.startswith('lvpb'):
     756              base_url = api_base_live_url
     757          url = base_url + "/" + url_suffix
     758
     759          response_body, response_code = http.request(auth, url, method, params)
     760
     761          if not response_code == HTTP_SUCCESS:
     762              handle_http_error(response_body, response_code)
     763
     764          try:
     765              response = json.loads(response_body)
     766          except Exception:
     767              raise SysError("Invalid response format returned.  Have you got the correct URL {0} \n HTTP Status: {1}".format(url, response_code))
     768
     769          if "list" in response:
     770              obj = DomainFactory.factory("domain")
     771              obj.list = [DomainFactory.factory(object_type, values) for values in response["list"]]
     772              obj.total = response["total"]
     773              return obj
     774          else:
     775              return DomainFactory.factory(object_type, response)
     776
     777
     778 -    def send_auth_request(self, props, context, auth):
     779
     780          PaymentsApi.check_auth(auth)
     781
     782          http = Http()
     783
     784          global oauth_base_url
     785
     786          url = oauth_base_url + "/" + context
     787
     788          response_body, response_code = http.auth_request(auth, url, props)
     789
     790
     791          try:
     792              response = json.loads(response_body)
     793          except Exception:
     794              raise SysError("Invalid response format returned.  Have you got the correct URL {0} \n HTTP Status: {1}".format(url, response_code))
     795
     796          if response_code == HTTP_SUCCESS:
     797              return response
     798          elif response_code == HTTP_REDIRECTED:
     799              raise BadRequestError("", response_code)
     800          elif response_code >= HTTP_BAD_REQUEST:
     801              error_code = response['error']
     802              error_desc = response['error_description']
     803              if error_code == 'invalid_request':
     804                  raise BadRequestError("", response_code, self.get_oauth_error("Error during OAuth request", error_code, error_desc))
     805              elif error_code == 'access_denied':
     806                  raise AuthenticationError("", response_code, self.get_oauth_error("Access denied for OAuth request", error_code, error_desc))
     807              elif error_code == 'invalid_client':
     808                  raise AuthenticationError("", response_code, self.get_oauth_error("Invalid client ID in OAuth request", error_code, error_desc))
     809              elif error_code == 'unauthorized_client':
     810                  raise AuthenticationError("", response_code, self.get_oauth_error("Unauthorized client in OAuth request", error_code, error_desc))
     811              elif error_code == 'unsupported_grant_type':
     812                  raise BadRequestError("", response_code, self.get_oauth_error("Unsupported grant type in OAuth request", error_code, error_desc))
     813              elif error_code == 'invalid_scope':
     814                  raise BadRequestError("", response_code, self.get_oauth_error("Invalid scope in OAuth request", error_code, error_desc))
     815              else:
     816                  raise BadRequestError("", e.response_code, self.get_oauth_error("Unknown OAuth error", error_code, error_desc))
     817              end
     818          elif response_code < 500:
     819              raise BadRequestError("Bad request", response_code, {})
     820          else:
     821              raise SysError("Bad request", response_code, {})
     822
     823
     824 -    def get_oauth_error(self, msg, error_code, error_desc):
     825          return  """{"error" : {"code" : "oauth_error", "message" : "%s, error code '%s', description '%s'" }}"""  % (msg, error_code, error_desc)
     826
     827
     828      @classmethod
     829 -    def build_request_url(cls, object_type,  object_id = ''):
     830
     831          url = object_type
     832          if object_id:
     833              url = "{0}/{1}".format(url, object_id)
     834
     835          return url
     836
     837
     838
     839  ################################################################################
     840  # Domain classes
     841  ################################################################################
     842
     843
     844 -class Event(Domain):
     845
     846      """
     847         A Event object.
     848      """
     849
     850      @staticmethod
     851 -    def create(params, *auth_args):
     852
     853          """
     854            Create an Event object.
     855            @param params: a dict of parameters; valid keys are:
     856                 - C{payload}:  The raw JWS message payload. B{required}
     857                 - C{url}: The URL for the webhook.  If present it must match the URL registered for the webhook.
     858            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
     859                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
     860            @return: an Event object
     861          """
     862
     863          obj = PaymentsApi().decode(auth_args, params)
     864
     865          if not 'event' in obj:
     866              raise ApiError("Incorrect data in webhook event")
     867
     868          return DomainFactory.factory('event', obj['event'])
     869
     870 -class Authorization(Domain):
     871      """
     872         A Authorization object.
     873      """
     874
     875
     876      @staticmethod
     877 -    def create(params, *auth_args):
     878          """
     879            Creates an Authorization object
     880            @param params: a dict of parameters; valid keys are:
     881                - C{amount}:  Amount of the payment (in the smallest unit of your currency). Example: 100 = $1.00 B{required }
     882                - C{card => addressCity}:  City of the cardholder. [max length: 50, min length: 2]
     883                - C{card => addressCountry}:  Country code (ISO-3166-1-alpha-2 code) of residence of the cardholder. [max length: 2, min length: 2]
     884                - C{card => addressLine1}:  Address of the cardholder. [max length: 255]
     885                - C{card => addressLine2}:  Address of the cardholder if needed. [max length: 255]
     886                - C{card => addressState}:  State of residence of the cardholder. State abbreviations should be used. [max length: 255]
     887                - C{card => addressZip}:  Postal code of the cardholder. The postal code size is between 5 and 9 characters in length and only contains numbers or letters. [max length: 32]
     888                - C{card => cvc}:  CVC security code of the card. This is the code on the back of the card. Example: 123
     889                - C{card => expMonth}:  Expiration month of the card. Format is MM. Example: January = 01 [min value: 1, max value: 12]
     890                - C{card => expYear}:  Expiration year of the card. Format is YY. Example: 2013 = 13 [min value: 0, max value: 99]
     891                - C{card => name}:  Name as it appears on the card. [max length: 50, min length: 2]
     892                - C{card => number}:  Card number as it appears on the card. [max length: 19, min length: 13]
     893                - C{currency}:  Currency code (ISO-4217) for the transaction. Must match the currency associated with your account. [default: USD] B{required }
     894                - C{customer}:  ID of customer. If specified, card on file of customer will be used.
     895                - C{description}:  Free form text field to be used as a description of the payment. This field is echoed back with the payment on any find or list operations. [max length: 1024]
     896                - C{order => commodityCode}:  Standard classification code for products and services. [max length: 5]
     897                - C{order => customer}:  ID of the customer associated with the order.
     898                - C{order => customerEmail}:  Customer email address.
     899                - C{order => customerName}:  Customer name.
     900                - C{order => customerNote}:  Additional notes provided by the customer. [max length: 255]
     901                - C{order => customerReference}:  A merchant reference for the customer.
     902                - C{order => items => amount}:  Cost of the item.
     903                - C{order => items => description}:  Description of the item.
     904                - C{order => items => name}:  Item name.
     905                - C{order => items => product}:  Product information associated with the item.
     906                - C{order => items => quantity}:  Quantity of the item contained in the order [min value: 1, max value: 999999, default: 1] B{required }
     907                - C{order => items => reference}:  A merchant reference for the item. [max length: 255]
     908                - C{order => items => tax}:  Taxes associated with the item.
     909                - C{order => merchantNote}:  Additional notes provided by the merchant. [max length: 255]
     910                - C{order => payment}:  ID of the payment associated with the order.
     911                - C{order => reference}:  A merchant reference for the order. [max length: 255]
     912                - C{order => shippingAddress => city}:  City, town, or municipality. [max length: 255, min length: 2]
     913                - C{order => shippingAddress => country}:  2-character country code. [max length: 2, min length: 2]
     914                - C{order => shippingAddress => line1}:  Street address. [max length: 255]
     915                - C{order => shippingAddress => line2}:  (Opt) Street address continued. [max length: 255]
     916                - C{order => shippingAddress => name}:  Name of the entity being shipped to. [max length: 255]
     917                - C{order => shippingAddress => state}:  State or province. [max length: 255]
     918                - C{order => shippingAddress => zip}:  Postal code. [max length: 32]
     919                - C{order => shippingFromAddress => city}:  City, town, or municipality. [max length: 255, min length: 2]
     920                - C{order => shippingFromAddress => country}:  2-character country code. [max length: 2, min length: 2]
     921                - C{order => shippingFromAddress => line1}:  Street address. [max length: 255]
     922                - C{order => shippingFromAddress => line2}:  (Opt) Street address continued. [max length: 255]
     923                - C{order => shippingFromAddress => name}:  Name of the entity performing the shipping. [max length: 255]
     924                - C{order => shippingFromAddress => state}:  State or province. [max length: 255]
     925                - C{order => shippingFromAddress => zip}:  Postal code. [max length: 32]
     926                - C{order => shippingName}:  Name of the entity being shipped to.
     927                - C{order => source}:  Order source. [default: WEB] B{required }
     928                - C{order => status}:  Status of the order. [default: INCOMPLETE] B{required }
     929                - C{reference}:  Custom reference field to be used with outside systems.
     930                - C{replayId}:  An identifier that can be sent to uniquely identify a payment request to facilitate retries due to I/O related issues. This identifier must be unique for your account (sandbox or live) across all of your payments. If supplied, we will check for a payment on your account that matches this identifier, and if one is found we will attempt to return an identical response of the original request. [max length: 50, min length: 1]
     931                - C{statementDescription => name}:  Merchant name B{required }
     932                - C{statementDescription => phoneNumber}:  Merchant contact phone number.
     933                - C{token}:  If specified, card associated with card token will be used. [max length: 255]
     934            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
     935                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
     936            @param private_api_key: Private key to use for the API call. If C{None}, the value of C{simplify.private_key} will be used.
     937            @return: a Authorization object
     938          """
     939          return PaymentsApi.create("authorization", auth_args, params)
     940
     941 -    def delete(self, *auth_args):
     942          """
     943              Delete this object
     944              @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
     945                  For backwards compatibility the public and private keys may be passed instead of an Authentication object.
     946          """
     947          return PaymentsApi.delete("authorization", auth_args, self.object_id)
     948
     949      @staticmethod
     950 -    def list(criteria = None, *auth_args):
     951          """
     952            Retrieve Authorization objects.
     953            @param criteria: a dict of parameters; valid keys are:
     954                 - C{filter}  <table class="filter_list"><tr><td>filter.id</td><td>Filter by the Authorization Id</td></tr><tr><td>filter.replayId</td><td>Filter by the compoundReplayId</td></tr><tr><td>filter.last4</td><td>Filter by the card number (last 4 digits)</td></tr><tr><td>filter.amount</td><td>Filter by the transaction amount (in the smallest unit of your currency)</td></tr><tr><td>filter.text</td><td>Filter by the description of the authorization</td></tr><tr><td>filter.amountMin & filter.amountMax</td><td>The filter amountMin must be used with amountMax to find authorizations with authorization values between the min and max</td></tr><tr><td>filter.dateCreatedMin<sup>*</sup></td><td>Filter by the minimum created date you are searching for - Date in UTC millis</td></tr><tr><td>filter.dateCreatedMax<sup>*</sup></td><td>Filter by the maximum created date you are searching for - Date in UTC millis</td></tr><tr><td>filter.deposit</td><td>Filter by the deposit id</td></tr><tr><td>filter.customer</td><td>Filter using the Id of the customer to find the authorizations for that customer</td></tr><tr><td>filter.status</td><td>Filter by the authorization status text</td></tr><tr><td>filter.authCode</td><td>Filter by the authorization code (Not the authorization ID)</td></tr><tr><td>filter.q</td><td>You can use this to filter by the ID, the authCode or the amount of the authorization</td></tr></table><br><sup>*</sup>Use dateCreatedMin with dateCreatedMax in the same filter if you want to search between two created dates
     955                 - C{max}  Allows up to a max of 50 list items to return. [min value: 0, max value: 50, default: 20]
     956                 - C{offset}  Used in pagination of the list. This is the start offset of the page. [min value: 0, default: 0]
     957                 - C{sorting}  Allows for ascending or descending sorting of the list. The value maps properties to the sort direction (either C{asc} for ascending or C{desc} for descending).  Sortable properties are:  C{dateCreated} C{amount} C{id} C{description} C{paymentDate}.
     958            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
     959                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
     960            @return: an object which contains the list of Authorization objects in the <code>list</code> property and the total number
     961                     of objects available for the given criteria in the <code>total</code> property.
     962          """
     963          return PaymentsApi.list("authorization", auth_args, criteria)
     964
     965      @staticmethod
     966 -    def find(object_id, *auth_args):
     967          """
     968            Retrieve a Authorization object from the API
     969            @param object_id: ID of object to retrieve
     970            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
     971                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
     972            @return: a Authorization object
     973          """
     974          return PaymentsApi.find("authorization", auth_args, object_id)
     975
     976 -class CardToken(Domain):
     977      """
     978         A CardToken object.
     979      """
     980
     981
     982      @staticmethod
     983 -    def create(params, *auth_args):
     984          """
     985            Creates an CardToken object
     986            @param params: a dict of parameters; valid keys are:
     987                - C{authenticatePayer}:  Set as true to create CardToken for EMV 3DS transaction. [default: false]
     988                - C{callback}:  The URL callback for the cardtoken
     989                - C{card => addressCity}:  City of the cardholder. [max length: 50, min length: 2]
     990                - C{card => addressCountry}:  Country code (ISO-3166-1-alpha-2 code) of residence of the cardholder. [max length: 2, min length: 2]
     991                - C{card => addressLine1}:  Address of the cardholder. [max length: 255]
     992                - C{card => addressLine2}:  Address of the cardholder if needed. [max length: 255]
     993                - C{card => addressState}:  State of residence of the cardholder. State abbreviations should be used. [max length: 255]
     994                - C{card => addressZip}:  Postal code of the cardholder. The postal code size is between 5 and 9 in length and only contain numbers or letters. [max length: 32]
     995                - C{card => cvc}:  CVC security code of the card. This is the code on the back of the card. Example: 123
     996                - C{card => expMonth}:  Expiration month of the card. Format is MM. Example: January = 01 [min value: 1, max value: 12]
     997                - C{card => expYear}:  Expiration year of the card. Format is YY. Example: 2013 = 13 [min value: 0, max value: 99]
     998                - C{card => name}:  Name as appears on the card. [max length: 50, min length: 2]
     999                - C{card => number}:  Card number as it appears on the card. [max length: 19, min length: 13]
    1000                - C{key}:  Key used to create the card token.
    1001                - C{secure3DRequestData => amount}:  Amount of the subsequent transaction in the smallest unit of your currency. Example: 100 = $1.00 B{required }
    1002                - C{secure3DRequestData => authOnly}:  Specifies if the subsequent transaction is going to be a Payment or an Authorization (to be Captured later). If false or not specified, it refers to a Payment, otherwise it refers to an Authorization.
    1003                - C{secure3DRequestData => currency}:  Currency code (ISO-4217). Must match the currency associated with your account. B{required }
    1004                - C{secure3DRequestData => description}:  A description of the transaction. [max length: 256]
    1005                - C{secure3DRequestData => id}:  3D Secure data ID.
    1006                - C{source}:  Card Token Source [default: API]
    1007            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1008                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1009            @param private_api_key: Private key to use for the API call. If C{None}, the value of C{simplify.private_key} will be used.
    1010            @return: a CardToken object
    1011          """
    1012          return PaymentsApi.create("cardToken", auth_args, params)
    1013
    1014      @staticmethod
    1015 -    def find(object_id, *auth_args):
    1016          """
    1017            Retrieve a CardToken object from the API
    1018            @param object_id: ID of object to retrieve
    1019            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1020                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1021            @return: a CardToken object
    1022          """
    1023          return PaymentsApi.find("cardToken", auth_args, object_id)
    1024
    1025 -    def update(self, *auth_args):
    1026          """
    1027            Updates this object
    1028
    1029            The properties that can be updated:
    1030              - C{device => browser} The User-Agent header of the browser the customer used to place the order B{(required)}
    1031
    1032              - C{device => ipAddress} The IP address of the device used by the payer, in nnn.nnn.nnn.nnn format. B{(required)}
    1033
    1034              - C{device => language} The language supported for the payer's browser as defined in IETF BCP47.
    1035
    1036              - C{device => screenHeight} The total height of the payer's browser screen in pixels.
    1037
    1038              - C{device => screenWidth} The total width of the payer's browser screen in pixels.
    1039
    1040              - C{device => timeZone} The timezone of the device used by the payer, in Zone ID format. Example: "Europe/Dublin" B{(required)}
    1041
    1042              - C{key} The public key of the merchant to be used for the token
    1043
    1044            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1045                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1046            @return: a CardToken object.
    1047          """
    1048          return PaymentsApi.update("cardToken", auth_args, self.object_id, self.to_dict())
    1049
    1050 -class Coupon(Domain):
    1051      """
    1052         A Coupon object.
    1053      """
    1054
    1055
    1056      @staticmethod
    1057 -    def create(params, *auth_args):
    1058          """
    1059            Creates an Coupon object
    1060            @param params: a dict of parameters; valid keys are:
    1061                - C{amountOff}:  Amount off of the price of the product in the smallest units of the currency of the merchant. While this field is optional, you must provide either amountOff or percentOff for a coupon. Example: 100 = $1.00 [min value: 1]
    1062                - C{couponCode}:  Code that identifies the coupon to be used. [min length: 2] B{required }
    1063                - C{description}:  A brief section that describes the coupon.
    1064                - C{durationInMonths}:  DEPRECATED - Duration in months that the coupon will be applied after it has first been selected. [min value: 1, max value: 9999]
    1065                - C{endDate}:  Last date of the coupon in UTC millis that the coupon can be applied to a subscription. This ends at 23:59:59 of the merchant timezone.
    1066                - C{maxRedemptions}:  Maximum number of redemptions allowed for the coupon. A redemption is defined as when the coupon is applied to the subscription for the first time. [min value: 1]
    1067                - C{numTimesApplied}:  The number of times a coupon will be applied on a customer's subscription. [min value: 1, max value: 9999]
    1068                - C{percentOff}:  Percentage off of the price of the product. While this field is optional, you must provide either amountOff or percentOff for a coupon. The percent off is a whole number. [min value: 1, max value: 100]
    1069                - C{startDate}:  First date of the coupon in UTC millis that the coupon can be applied to a subscription. This starts at midnight of the merchant timezone. B{required }
    1070            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1071                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1072            @param private_api_key: Private key to use for the API call. If C{None}, the value of C{simplify.private_key} will be used.
    1073            @return: a Coupon object
    1074          """
    1075          return PaymentsApi.create("coupon", auth_args, params)
    1076
    1077 -    def delete(self, *auth_args):
    1078          """
    1079              Delete this object
    1080              @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1081                  For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1082          """
    1083          return PaymentsApi.delete("coupon", auth_args, self.object_id)
    1084
    1085      @staticmethod
    1086 -    def list(criteria = None, *auth_args):
    1087          """
    1088            Retrieve Coupon objects.
    1089            @param criteria: a dict of parameters; valid keys are:
    1090                 - C{filter}  <table class="filter_list"><tr><td>filter.id</td><td>Filter by the coupon Id</td></tr><tr><td>filter.text</td><td>Filter by the coupon code</td></tr><tr><td>filter.dateCreatedMin<sup>*</sup></td><td>Filter by the minimum created date you are searching for - Date in UTC millis</td></tr><tr><td>filter.dateCreatedMax<sup>*</sup></td><td>Filter by the maximum created date you are searching for - Date in UTC millis</td></tr><tr><td>filter.startDateMin</td><td>Filter by the minimum coupon start date you are searching for - Date in UTC millis</td></tr><tr><td>filter.startDateMax</td><td>Filter by the maximum coupon start date you are searching for - Date in UTC millis</td></tr><tr><td>filter.endDateMin</td><td>Filter by the minimum coupon end date you are searching for - Date in UTC millis</td></tr><tr><td>filter.endDateMax</td><td>Filter by the maximum coupon end date you are searching for - Date in UTC millis</td></tr></table><br><sup>*</sup>Use dateCreatedMin with dateCreatedMax in the same filter if you want to search between two created dates
    1091                 - C{max}  Allows up to a max of 50 list items to return. [min value: 0, max value: 50, default: 20]
    1092                 - C{offset}  Used in paging of the list.  This is the start offset of the page. [min value: 0, default: 0]
    1093                 - C{sorting}  Allows for ascending or descending sorting of the list. The value maps properties to the sort direction (either C{asc} for ascending or C{desc} for descending).  Sortable properties are:  C{dateCreated} C{maxRedemptions} C{timesRedeemed} C{id} C{startDate} C{endDate} C{percentOff} C{couponCode} C{durationInMonths} C{numTimesApplied} C{amountOff}.
    1094            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1095                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1096            @return: an object which contains the list of Coupon objects in the <code>list</code> property and the total number
    1097                     of objects available for the given criteria in the <code>total</code> property.
    1098          """
    1099          return PaymentsApi.list("coupon", auth_args, criteria)
    1100
    1101      @staticmethod
    1102 -    def find(object_id, *auth_args):
    1103          """
    1104            Retrieve a Coupon object from the API
    1105            @param object_id: ID of object to retrieve
    1106            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1107                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1108            @return: a Coupon object
    1109          """
    1110          return PaymentsApi.find("coupon", auth_args, object_id)
    1111
    1112 -    def update(self, *auth_args):
    1113          """
    1114            Updates this object
    1115
    1116            The properties that can be updated:
    1117              - C{endDate} The ending date in UTC millis for the coupon. This must be after the starting date of the coupon.
    1118
    1119              - C{maxRedemptions} Maximum number of redemptions allowed for the coupon. A redemption is defined as when the coupon is applied to the subscription for the first time. [min value: 1]
    1120
    1121            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1122                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1123            @return: a Coupon object.
    1124          """
    1125          return PaymentsApi.update("coupon", auth_args, self.object_id, self.to_dict())
    1126
    1127 -class Customer(Domain):
    1128      """
    1129         A Customer object.
    1130      """
    1131
    1132
    1133      @staticmethod
    1134 -    def create(params, *auth_args):
    1135          """
    1136            Creates an Customer object
    1137            @param params: a dict of parameters; valid keys are:
    1138                - C{card => addressCity}:  City of the cardholder. B{required }
    1139                - C{card => addressCountry}:  Country code (ISO-3166-1-alpha-2 code) of residence of the cardholder. B{required }
    1140                - C{card => addressLine1}:  Address of the cardholder B{required }
    1141                - C{card => addressLine2}:  Address of the cardholder if needed. B{required }
    1142                - C{card => addressState}:  State of residence of the cardholder. State abbreviations should be used. B{required }
    1143                - C{card => addressZip}:  Postal code of the cardholder. The postal code size is between 5 and 9 in length and only contain numbers or letters. B{required }
    1144                - C{card => cvc}:  CVC security code of the card. This is the code on the back of the card. Example: 123 B{required }
    1145                - C{card => expMonth}:  Expiration month of the card. Format is MM. Example: January = 01 B{required }
    1146                - C{card => expYear}:  Expiration year of the card. Format is YY. Example: 2013 = 13 B{required }
    1147                - C{card => id}:  ID of card. Unused during customer create.
    1148                - C{card => name}:  Name as appears on the card. B{required }
    1149                - C{card => number}:  Card number as it appears on the card. [max length: 19, min length: 13]
    1150                - C{email}:  Email address of the customer B{required }
    1151                - C{name}:  Customer name [max length: 50, min length: 2] B{required }
    1152                - C{reference}:  Reference field for external applications use.
    1153                - C{subscriptions => amount}:  Amount of payment in the smallest unit of your currency. Example: 100 = $1.00
    1154                - C{subscriptions => billingCycle}:  How the plan is billed to the customer. Values must be AUTO (indefinitely until the customer cancels) or FIXED (a fixed number of billing cycles). [default: AUTO]
    1155                - C{subscriptions => billingCycleLimit}:  The number of fixed billing cycles for a plan. Only used if the billingCycle parameter is set to FIXED. Example: 4
    1156                - C{subscriptions => coupon}:  Coupon associated with the subscription for the customer.
    1157                - C{subscriptions => currency}:  Currency code (ISO-4217). Must match the currency associated with your account.
    1158                - C{subscriptions => currentPeriodEnd}:  End date of subscription's current period
    1159                - C{subscriptions => currentPeriodStart}:  Start date of subscription's current period
    1160                - C{subscriptions => customer}:  The customer ID to create the subscription for. Do not supply this when creating a customer.
    1161                - C{subscriptions => frequency}:  Frequency of payment for the plan. Used in conjunction with frequencyPeriod. Valid values are "DAILY", "WEEKLY", "MONTHLY" and "YEARLY".
    1162                - C{subscriptions => frequencyPeriod}:  Period of frequency of payment for the plan. Example: if the frequency is weekly, and periodFrequency is 2, then the subscription is billed bi-weekly.
    1163                - C{subscriptions => name}:  Name describing subscription [max length: 50]
    1164                - C{subscriptions => plan}:  The plan ID that the subscription should be created from.
    1165                - C{subscriptions => quantity}:  Quantity of the plan for the subscription. [min value: 1]
    1166                - C{subscriptions => renewalReminderLeadDays}:  If set, how many days before the next billing cycle that a renewal reminder is sent to the customer. If null, then no emails are sent. Minimum value is 7 if set.
    1167                - C{subscriptions => source}:  Source of where subscription was created
    1168                - C{token}:  If specified, card associated with card token will be used
    1169            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1170                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1171            @param private_api_key: Private key to use for the API call. If C{None}, the value of C{simplify.private_key} will be used.
    1172            @return: a Customer object
    1173          """
    1174          return PaymentsApi.create("customer", auth_args, params)
    1175
    1176 -    def delete(self, *auth_args):
    1177          """
    1178              Delete this object
    1179              @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1180                  For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1181          """
    1182          return PaymentsApi.delete("customer", auth_args, self.object_id)
    1183
    1184      @staticmethod
    1185 -    def list(criteria = None, *auth_args):
    1186          """
    1187            Retrieve Customer objects.
    1188            @param criteria: a dict of parameters; valid keys are:
    1189                 - C{filter}  <table class="filter_list"><tr><td>filter.id</td><td>Filter by the customer Id</td></tr><tr><td>filter.text</td><td>Can use this to filter by the name, email or reference for the customer</td></tr><tr><td>filter.dateCreatedMin<sup>*</sup></td><td>Filter by the minimum created date you are searching for - Date in UTC millis</td></tr><tr><td>filter.dateCreatedMax<sup>*</sup></td><td>Filter by the maximum created date you are searching for - Date in UTC millis</td></tr></table><br><sup>*</sup>Use dateCreatedMin with dateCreatedMax in the same filter if you want to search between two created dates
    1190                 - C{max}  Allows up to a max of 50 list items to return. [min value: 0, max value: 50, default: 20]
    1191                 - C{offset}  Used in paging of the list.  This is the start offset of the page. [min value: 0, default: 0]
    1192                 - C{sorting}  Allows for ascending or descending sorting of the list. The value maps properties to the sort direction (either C{asc} for ascending or C{desc} for descending).  Sortable properties are:  C{dateCreated} C{id} C{name} C{email} C{reference}.
    1193            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1194                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1195            @return: an object which contains the list of Customer objects in the <code>list</code> property and the total number
    1196                     of objects available for the given criteria in the <code>total</code> property.
    1197          """
    1198          return PaymentsApi.list("customer", auth_args, criteria)
    1199
    1200      @staticmethod
    1201 -    def find(object_id, *auth_args):
    1202          """
    1203            Retrieve a Customer object from the API
    1204            @param object_id: ID of object to retrieve
    1205            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1206                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1207            @return: a Customer object
    1208          """
    1209          return PaymentsApi.find("customer", auth_args, object_id)
    1210
    1211 -    def update(self, *auth_args):
    1212          """
    1213            Updates this object
    1214
    1215            The properties that can be updated:
    1216              - C{card => addressCity} City of the cardholder. B{(required)}
    1217
    1218              - C{card => addressCountry} Country code (ISO-3166-1-alpha-2 code) of residence of the cardholder. B{(required)}
    1219
    1220              - C{card => addressLine1} Address of the cardholder. B{(required)}
    1221
    1222              - C{card => addressLine2} Address of the cardholder if needed. B{(required)}
    1223
    1224              - C{card => addressState} State of residence of the cardholder. State abbreviations should be used. B{(required)}
    1225
    1226              - C{card => addressZip} Postal code of the cardholder. The postal code size is between 5 and 9 in length and only contain numbers or letters. B{(required)}
    1227
    1228              - C{card => cvc} CVC security code of the card. This is the code on the back of the card. Example: 123 B{(required)}
    1229
    1230              - C{card => expMonth} Expiration month of the card. Format is MM.  Example: January = 01 B{(required)}
    1231
    1232              - C{card => expYear} Expiration year of the card. Format is YY. Example: 2013 = 13 B{(required)}
    1233
    1234              - C{card => id} ID of card. If present, card details for the customer will not be updated. If not present, the customer will be updated with the supplied card details.
    1235
    1236              - C{card => name} Name as appears on the card. B{(required)}
    1237
    1238              - C{card => number} Card number as it appears on the card. [max length: 19, min length: 13]
    1239
    1240              - C{email} Email address of the customer B{(required)}
    1241
    1242              - C{name} Customer name [max length: 50, min length: 2] B{(required)}
    1243
    1244              - C{reference} Reference field for external applications use.
    1245
    1246              - C{token} If specified, card associated with card token will be added to the customer
    1247
    1248            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1249                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1250            @return: a Customer object.
    1251          """
    1252          return PaymentsApi.update("customer", auth_args, self.object_id, self.to_dict())
    1253
    1254 -class FraudCheck(Domain):
    1255      """
    1256         A FraudCheck object.
    1257      """
    1258
    1259
    1260      @staticmethod
    1261 -    def create(params, *auth_args):
    1262          """
    1263            Creates an FraudCheck object
    1264            @param params: a dict of parameters; valid keys are:
    1265                - C{amount}:  Amount of the transaction to be checked for fraud (in the smallest unit of your currency). Example: 100 = $1.00. This field is required if using â€œfullâ€ or â€œadvancedâ€ mode.
    1266                - C{card => addressCity}:  City of the cardholder. [max length: 50, min length: 2]
    1267                - C{card => addressCountry}:  Country code (ISO-3166-1-alpha-2 code) of residence of the cardholder. [max length: 2, min length: 2]
    1268                - C{card => addressLine1}:  Address of the cardholder. [max length: 255]
    1269                - C{card => addressLine2}:  Address of the cardholder if needed. [max length: 255]
    1270                - C{card => addressState}:  State of residence of the cardholder. State abbreviations should be used. [max length: 255]
    1271                - C{card => addressZip}:  Postal code of the cardholder. The postal code size is between 5 and 9 characters in length and only contains numbers or letters. [max length: 32]
    1272                - C{card => cvc}:  CVC security code of the card. This is the code on the back of the card. Example: 123
    1273                - C{card => expMonth}:  Expiration month of the card. Format is MM. Example: January = 01 [min value: 1, max value: 12]
    1274                - C{card => expYear}:  Expiration year of the card. Format is YY. Example: 2013 = 13 [min value: 0, max value: 99]
    1275                - C{card => name}:  Name as it appears on the card. [max length: 50, min length: 2]
    1276                - C{card => number}:  Card number as it appears on the card. [max length: 19, min length: 13]
    1277                - C{currency}:  Currency code (ISO-4217) for the transaction to be checked for fraud. This field is required if using â€œfullâ€ or â€œadvancedâ€ mode.
    1278                - C{description}:  - Description of the fraud check. [max length: 255]
    1279                - C{ipAddress}:  IP Address of the customer for which the fraud check is to be done. [max length: 45]
    1280                - C{mode}:  Fraud check mode.  â€œsimpleâ€ only does an AVS and CVC check; â€œadvancedâ€ does a complete fraud check, running the input against the set up rules. [valid values: simple, advanced, full, SIMPLE, ADVANCED, FULL] B{required }
    1281                - C{sessionId}:  Session ID used during data collection. [max length: 255]
    1282                - C{token}:  Card token representing card details for the card to be checked. [max length: 255]
    1283            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1284                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1285            @param private_api_key: Private key to use for the API call. If C{None}, the value of C{simplify.private_key} will be used.
    1286            @return: a FraudCheck object
    1287          """
    1288          return PaymentsApi.create("fraudCheck", auth_args, params)
    1289
    1290      @staticmethod
    1291 -    def list(criteria = None, *auth_args):
    1292          """
    1293            Retrieve FraudCheck objects.
    1294            @param criteria: a dict of parameters; valid keys are:
    1295                 - C{filter}  Filters to apply to the list.
    1296                 - C{max}  Allows up to a max of 50 list items to return. [min value: 0, max value: 50, default: 20]
    1297                 - C{offset}  Used in paging of the list.  This is the start offset of the page. [min value: 0, default: 0]
    1298                 - C{sorting}  Allows for ascending or descending sorting of the list. The value maps properties to the sort direction (either C{asc} for ascending or C{desc} for descending).  Sortable properties are:  C{amount} C{dateCreated} C{fraudResult}.
    1299            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1300                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1301            @return: an object which contains the list of FraudCheck objects in the <code>list</code> property and the total number
    1302                     of objects available for the given criteria in the <code>total</code> property.
    1303          """
    1304          return PaymentsApi.list("fraudCheck", auth_args, criteria)
    1305
    1306      @staticmethod
    1307 -    def find(object_id, *auth_args):
    1308          """
    1309            Retrieve a FraudCheck object from the API
    1310            @param object_id: ID of object to retrieve
    1311            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1312                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1313            @return: a FraudCheck object
    1314          """
    1315          return PaymentsApi.find("fraudCheck", auth_args, object_id)
    1316
    1317 -    def update(self, *auth_args):
    1318          """
    1319            Updates this object
    1320
    1321            The properties that can be updated:
    1322              - C{integratorAuthCode} Authorization code for the transaction. [max length: 255]
    1323
    1324              - C{integratorAvsAddressResponse} AVS address response. [max length: 255]
    1325
    1326              - C{integratorAvsZipResponse} AVS zip response. [max length: 255]
    1327
    1328              - C{integratorCvcResponse} CVC response. [max length: 255]
    1329
    1330              - C{integratorDeclineReason} Reason for the decline if applicable. [max length: 255]
    1331
    1332              - C{integratorTransactionRef} Reference id for the transaction. [max length: 255] B{(required)}
    1333
    1334              - C{integratorTransactionStatus} Status of the transaction, valid values are "APPROVED", "DECLINED", "SETTLED", "REFUNDED" or "VOIDED".
    1335
    1336            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1337                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1338            @return: a FraudCheck object.
    1339          """
    1340          return PaymentsApi.update("fraudCheck", auth_args, self.object_id, self.to_dict())
    1341
    1342 -class Invoice(Domain):
    1343      """
    1344         A Invoice object.
    1345      """
    1346
    1347
    1348      @staticmethod
    1349 -    def create(params, *auth_args):
    1350          """
    1351            Creates an Invoice object
    1352            @param params: a dict of parameters; valid keys are:
    1353                - C{billingAddress => city}:  Billing address city of the location where the goods or services were supplied. [max length: 255, min length: 2]
    1354                - C{billingAddress => country}:  Billing address country of the location where the goods or services were supplied. [max length: 2, min length: 2]
    1355                - C{billingAddress => line1}:  Billing address line 1 of the location where the goods or services were supplied. [max length: 255]
    1356                - C{billingAddress => line2}:  Billing address line 2 of the location where the goods or services were supplied. [max length: 255]
    1357                - C{billingAddress => name}:  Billing address name of the location where the goods or services were supplied. Will use the customer name if not provided. [max length: 255]
    1358                - C{billingAddress => state}:  Billing address state of the location where the goods or services were supplied. [max length: 255]
    1359                - C{billingAddress => zip}:  Billing address zip of the location where the goods or services were supplied. [max length: 32]
    1360                - C{businessAddress => city}:  Address city of the business that is sending the invoice. [max length: 255, min length: 2]
    1361                - C{businessAddress => country}:  Address country of the business that is sending the invoice. [max length: 2, min length: 2]
    1362                - C{businessAddress => line1}:  Address line 1 of the business that is sending the invoice. [max length: 255]
    1363                - C{businessAddress => line2}:  Address line 2 of the business that is sending the invoice. [max length: 255]
    1364                - C{businessAddress => name}:  The name of the business that is sending the invoice. [max length: 255]
    1365                - C{businessAddress => state}:  Address state of the business that is sending the invoice. [max length: 255]
    1366                - C{businessAddress => zip}:  Address zip of the business that is sending the invoice. [max length: 32]
    1367                - C{currency}:  Currency code (ISO-4217). Must match the currency associated with your account. [max length: 3, min length: 3]
    1368                - C{customer}:  The customer ID of the customer we are invoicing.  This is optional if invoiceToCopy or a name and email are provided
    1369                - C{customerTaxNo}:  The tax number or VAT id of the person to whom the goods or services were supplied. [max length: 255]
    1370                - C{discountRate}:  The discount percent as a decimal e.g. 12.5.  This is used to calculate the discount amount which is subtracted from the total amount due before any tax is applied. [max length: 6]
    1371                - C{dueDate}:  The date invoice payment is due.  If a late fee is provided this will be added to the invoice total is the due date has past.
    1372                - C{email}:  The email of the customer we are invoicing.  This is optional if customer or invoiceToCopy is provided.  A new customer will be created using the the name and email.
    1373                - C{invoiceId}:  User defined invoice id. If not provided the system will generate a numeric id. [max length: 255]
    1374                - C{invoiceLanguage}:  The language in which invoice will be displayed. [max length: 5, min length: 5]
    1375                - C{invoiceToCopy}:  The id of an existing invoice to be copied.  This is optional if customer or a name and email are provided
    1376                - C{items => amount}:  Amount of the invoice item (the smallest unit of your currency). Example: 100 = $1.00 B{required }
    1377                - C{items => description}:  The description of the invoice item. [max length: 1024]
    1378                - C{items => invoice}:  The ID of the invoice this item belongs to.
    1379                - C{items => product}:  The product this invoice item refers to.
    1380                - C{items => quantity}:  Quantity of the item.  This total amount of the invoice item is the amount * quantity. [min value: 1, max value: 999999, default: 1]
    1381                - C{items => reference}:  User defined reference field. [max length: 255]
    1382                - C{items => tax}:  The tax ID of the tax charge in the invoice item.
    1383                - C{lateFee}:  The late fee amount that will be added to the invoice total is the due date is past due.  Value provided must be in the smallest unit of your currency. Example: 100 = $1.00
    1384                - C{memo}:  A memo that is displayed to the customer on the invoice payment screen. [max length: 4000]
    1385                - C{name}:  The name of the customer we are invoicing.  This is optional if customer or invoiceToCopy is provided.  A new customer will be created using the the name and email. [max length: 50, min length: 2]
    1386                - C{note}:  This field can be used to store a note that is not displayed to the customer. [max length: 4000]
    1387                - C{reference}:  User defined reference field. [max length: 255]
    1388                - C{shippingAddress => city}:  Address city of the location where the goods or services were supplied. [max length: 255, min length: 2]
    1389                - C{shippingAddress => country}:  Address country of the location where the goods or services were supplied. [max length: 2, min length: 2]
    1390                - C{shippingAddress => line1}:  Address line 1 of the location where the goods or services were supplied. [max length: 255]
    1391                - C{shippingAddress => line2}:  Address line 2 of the location where the goods or services were supplied. [max length: 255]
    1392                - C{shippingAddress => name}:  Address name of the location where the goods or services were supplied. [max length: 255]
    1393                - C{shippingAddress => state}:  Address state of the location where the goods or services were supplied. [max length: 255]
    1394                - C{shippingAddress => zip}:  Address zip of the location where the goods or services were supplied. [max length: 32]
    1395                - C{suppliedDate}:  The date on which the goods or services were supplied.
    1396                - C{taxNo}:  The tax number or VAT id of the person who supplied the goods or services. [max length: 255]
    1397                - C{type}:  The type of invoice.  One of WEB or MOBILE. [valid values: WEB, MOBILE, default: WEB]
    1398            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1399                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1400            @param private_api_key: Private key to use for the API call. If C{None}, the value of C{simplify.private_key} will be used.
    1401            @return: a Invoice object
    1402          """
    1403          return PaymentsApi.create("invoice", auth_args, params)
    1404
    1405 -    def delete(self, *auth_args):
    1406          """
    1407              Delete this object
    1408              @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1409                  For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1410          """
    1411          return PaymentsApi.delete("invoice", auth_args, self.object_id)
    1412
    1413      @staticmethod
    1414 -    def list(criteria = None, *auth_args):
    1415          """
    1416            Retrieve Invoice objects.
    1417            @param criteria: a dict of parameters; valid keys are:
    1418                 - C{filter}  <table class="filter_list"><tr><td>filter.id</td><td>Filter by the invoice Id</td></tr><tr><td>filter.amount</td><td>Filter by the invoice amount (in the smallest unit of your currency)</td></tr><tr><td>filter.text</td><td>Filter by the name of the invoice</td></tr><tr><td>filter.dateCreatedMin<sup>*</sup></td><td>Filter by the minimum created date you are searching for - Date in UTC millis</td></tr><tr><td>filter.dateCreatedMax<sup>*</sup></td><td>Filter by the maximum created date you are searching for - Date in UTC millis</td></tr><tr><td>filter.datePaidMin<sup>*</sup></td><td>Filter by the minimum invoice paid date you are searching for - Date in UTC millis</td></tr><tr><td>filter.datePaidMax<sup>*</sup></td><td>Filter by the maximum invoice paid date you are searching for - Date in UTC millis</td></tr><tr><td>filter.status</td><td>Filter by the status of the invoice</td></tr><tr><td>filter.statuses</td><td>Filter by multiple statuses of different invoices</td></tr><tr><td>filter.customer</td><td>Filter using the Id of the customer linked to the invoice</td></tr><tr><td>filter.type</td><td>Filter by the invoice type</td></tr><tr><td>filter.types</td><td>Filter by multiple invoice types</td></tr><tr><td>filter.invoiceId</td><td>Filter by the user defined invoice id</td></tr><tr><td>filter.reference</td><td>Filter by the invoice reference text</td></tr></table><br><sup>*</sup>The filters datePaidMin and datePaidMax can be used in the same filter if you want to search between the two dates. The same is for dateCreatedMin/dateCreatedMax.
    1419                 - C{max}  Allows up to a max of 50 list items to return. [min value: 0, max value: 50, default: 20]
    1420                 - C{offset}  Used in paging of the list.  This is the start offset of the page. [min value: 0, default: 0]
    1421                 - C{sorting}  Allows for ascending or descending sorting of the list. The value maps properties to the sort direction (either C{asc} for ascending or C{desc} for descending).  Sortable properties are:  C{id} C{invoiceDate} C{dueDate} C{datePaid} C{customer} C{status} C{dateCreated}.
    1422            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1423                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1424            @return: an object which contains the list of Invoice objects in the <code>list</code> property and the total number
    1425                     of objects available for the given criteria in the <code>total</code> property.
    1426          """
    1427          return PaymentsApi.list("invoice", auth_args, criteria)
    1428
    1429      @staticmethod
    1430 -    def find(object_id, *auth_args):
    1431          """
    1432            Retrieve a Invoice object from the API
    1433            @param object_id: ID of object to retrieve
    1434            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1435                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1436            @return: a Invoice object
    1437          """
    1438          return PaymentsApi.find("invoice", auth_args, object_id)
    1439
    1440 -    def update(self, *auth_args):
    1441          """
    1442            Updates this object
    1443
    1444            The properties that can be updated:
    1445              - C{billingAddress => city} Billing address city of the location where the goods or services were supplied. [max length: 255, min length: 2]
    1446
    1447              - C{billingAddress => country} Billing address country of the location where the goods or services were supplied. [max length: 2, min length: 2]
    1448
    1449              - C{billingAddress => line1} Billing address line 1 of the location where the goods or services were supplied. [max length: 255]
    1450
    1451              - C{billingAddress => line2} Billing address line 2 of the location where the goods or services were supplied. [max length: 255]
    1452
    1453              - C{billingAddress => name} Billing address name of the location where the goods or services were supplied. [max length: 255]
    1454
    1455              - C{billingAddress => state} Billing address state of the location where the goods or services were supplied. [max length: 255]
    1456
    1457              - C{billingAddress => zip} Billing address zip of the location where the goods or services were supplied. [max length: 32]
    1458
    1459              - C{businessAddress => city} Business address city of the business that is sending the invoice. [max length: 255, min length: 2]
    1460
    1461              - C{businessAddress => country} Business address country of the business that is sending the invoice. [max length: 2, min length: 2]
    1462
    1463              - C{businessAddress => line1} Business address line 1 of the business that is sending the invoice. [max length: 255]
    1464
    1465              - C{businessAddress => line2} Business address line 2 of the business that is sending the invoice. [max length: 255]
    1466
    1467              - C{businessAddress => name} Business address name of the business that is sending the invoice. [max length: 255]
    1468
    1469              - C{businessAddress => state} Business address state of the business that is sending the invoice. [max length: 255]
    1470
    1471              - C{businessAddress => zip} Business address zip of the business that is sending the invoice. [max length: 32]
    1472
    1473              - C{currency} Currency code (ISO-4217). Must match the currency associated with your account. [max length: 3, min length: 3]
    1474
    1475              - C{customerTaxNo} The tax number or VAT id of the person to whom the goods or services were supplied. [max length: 255]
    1476
    1477              - C{datePaid} This is the date the invoice was PAID in UTC millis.
    1478
    1479              - C{discountRate} The discount percent as a decimal e.g. 12.5.  This is used to calculate the discount amount which is subtracted from the total amount due before any tax is applied. [max length: 6]
    1480
    1481              - C{dueDate} The date invoice payment is due.  If a late fee is provided this will be added to the invoice total is the due date has past.
    1482
    1483              - C{email} The email of the customer we are invoicing.  This is optional if customer or invoiceToCopy is provided.  A new customer will be created using the the name and email.
    1484
    1485              - C{invoiceId} User defined invoice id. If not provided the system will generate a numeric id. [max length: 255]
    1486
    1487              - C{invoiceLanguage} The language in which invoice will be displayed. [max length: 5, min length: 5]
    1488
    1489              - C{items => amount} Amount of the invoice item in the smallest unit of your currency. Example: 100 = $1.00 B{(required)}
    1490
    1491              - C{items => description} The description of the invoice item. [max length: 1024]
    1492
    1493              - C{items => invoice} The ID of the invoice this item belongs to.
    1494
    1495              - C{items => product} The Id of the product this item refers to.
    1496
    1497              - C{items => quantity} Quantity of the item.  This total amount of the invoice item is the amount * quantity. [min value: 1, max value: 999999, default: 1]
    1498
    1499              - C{items => reference} User defined reference field. [max length: 255]
    1500
    1501              - C{items => tax} The tax ID of the tax charge in the invoice item.
    1502
    1503              - C{lateFee} The late fee amount that will be added to the invoice total is the due date is past due.  Value provided must be in the smallest unit of your currency. Example: 100 = $1.00
    1504
    1505              - C{memo} A memo that is displayed to the customer on the invoice payment screen. [max length: 4000]
    1506
    1507              - C{name} The name of the customer we are invoicing.  This is optional if customer or invoiceToCopy is provided.  A new customer will be created using the the name and email. [max length: 50, min length: 2]
    1508
    1509              - C{note} This field can be used to store a note that is not displayed to the customer. [max length: 4000]
    1510
    1511              - C{payment} The ID of the payment.  Use this ID to query the /payment API. [max length: 255]
    1512
    1513              - C{reference} User defined reference field. [max length: 255]
    1514
    1515              - C{sendMail} Boolean flag.  If true the invoice will be sent to the customer if the invoice is in an OPEN state. [default: false] B{(required)}
    1516
    1517              - C{shippingAddress => city} Address city of the location where the goods or services were supplied. [max length: 255, min length: 2]
    1518
    1519              - C{shippingAddress => country} Address country of the location where the goods or services were supplied. [max length: 2, min length: 2]
    1520
    1521              - C{shippingAddress => line1} Address line 1 of the location where the goods or services were supplied. [max length: 255]
    1522
    1523              - C{shippingAddress => line2} Address line 2 of the location where the goods or services were supplied. [max length: 255]
    1524
    1525              - C{shippingAddress => name} Address name of the location where the goods or services were supplied. [max length: 255]
    1526
    1527              - C{shippingAddress => state} Address state of the location where the goods or services were supplied. [max length: 255]
    1528
    1529              - C{shippingAddress => zip} Address zip of the location where the goods or services were supplied. [max length: 32]
    1530
    1531              - C{status} New status of the invoice.
    1532
    1533              - C{suppliedDate} The date on which the goods or services were supplied.
    1534
    1535              - C{taxNo} The tax number or VAT id of the person who supplied the goods or services. [max length: 255]
    1536
    1537            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1538                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1539            @return: a Invoice object.
    1540          """
    1541          return PaymentsApi.update("invoice", auth_args, self.object_id, self.to_dict())
    1542
    1543 -class InvoiceItem(Domain):
    1544      """
    1545         A InvoiceItem object.
    1546      """
    1547
    1548
    1549      @staticmethod
    1550 -    def create(params, *auth_args):
    1551          """
    1552            Creates an InvoiceItem object
    1553            @param params: a dict of parameters; valid keys are:
    1554                - C{amount}:  Amount of the invoice item in the smallest unit of your currency. Example: 100 = $1.00 B{required }
    1555                - C{description}:  Individual items of an invoice [max length: 1024]
    1556                - C{invoice}:  The ID of the invoice this item belongs to.
    1557                - C{product}:  Product ID this item relates to.
    1558                - C{quantity}:  Quantity of the item.  This total amount of the invoice item is the amount * quantity. [min value: 1, max value: 999999, default: 1]
    1559                - C{reference}:  User defined reference field. [max length: 255]
    1560                - C{tax}:  The tax ID of the tax charge in the invoice item.
    1561            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1562                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1563            @param private_api_key: Private key to use for the API call. If C{None}, the value of C{simplify.private_key} will be used.
    1564            @return: a InvoiceItem object
    1565          """
    1566          return PaymentsApi.create("invoiceItem", auth_args, params)
    1567
    1568 -    def delete(self, *auth_args):
    1569          """
    1570              Delete this object
    1571              @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1572                  For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1573          """
    1574          return PaymentsApi.delete("invoiceItem", auth_args, self.object_id)
    1575
    1576      @staticmethod
    1577 -    def find(object_id, *auth_args):
    1578          """
    1579            Retrieve a InvoiceItem object from the API
    1580            @param object_id: ID of object to retrieve
    1581            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1582                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1583            @return: a InvoiceItem object
    1584          """
    1585          return PaymentsApi.find("invoiceItem", auth_args, object_id)
    1586
    1587 -    def update(self, *auth_args):
    1588          """
    1589            Updates this object
    1590
    1591            The properties that can be updated:
    1592              - C{amount} Amount of the invoice item in the smallest unit of your currency. Example: 100 = $1.00 [min value: 1]
    1593
    1594              - C{description} Individual items of an invoice
    1595
    1596              - C{quantity} Quantity of the item.  This total amount of the invoice item is the amount * quantity. [min value: 1, max value: 999999]
    1597
    1598              - C{reference} User defined reference field.
    1599
    1600              - C{tax} The tax ID of the tax charge in the invoice item.
    1601
    1602            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1603                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1604            @return: a InvoiceItem object.
    1605          """
    1606          return PaymentsApi.update("invoiceItem", auth_args, self.object_id, self.to_dict())
    1607
    1608 -class Payment(Domain):
    1609      """
    1610         A Payment object.
    1611      """
    1612
    1613
    1614      @staticmethod
    1615 -    def create(params, *auth_args):
    1616          """
    1617            Creates an Payment object
    1618            @param params: a dict of parameters; valid keys are:
    1619                - C{amount}:  Amount of the payment (in the smallest unit of your currency). Example: 100 = $1.00
    1620                - C{authorization}:  The ID of the authorization being used to capture the payment.
    1621                - C{card => addressCity}:  City of the cardholder. [max length: 50, min length: 2]
    1622                - C{card => addressCountry}:  Country code (ISO-3166-1-alpha-2 code) of residence of the cardholder. [max length: 2, min length: 2]
    1623                - C{card => addressLine1}:  Address of the cardholder. [max length: 255]
    1624                - C{card => addressLine2}:  Address of the cardholder if needed. [max length: 255]
    1625                - C{card => addressState}:  State of residence of the cardholder. State abbreviations should be used. [max length: 255]
    1626                - C{card => addressZip}:  Postal code of the cardholder. The postal code size is between 5 and 9 in length and only contain numbers or letters. [max length: 32]
    1627                - C{card => cvc}:  CVC security code of the card. This is the code on the back of the card. Example: 123
    1628                - C{card => expMonth}:  Expiration month of the card. Format is MM. Example: January = 01 [min value: 1, max value: 12]
    1629                - C{card => expYear}:  Expiration year of the card. Format is YY. Example: 2013 = 13 [min value: 0, max value: 99]
    1630                - C{card => name}:  Name as it appears on the card. [max length: 50, min length: 2]
    1631                - C{card => number}:  Card number as it appears on the card. [max length: 19, min length: 13]
    1632                - C{currency}:  Currency code (ISO-4217) for the transaction. Must match the currency associated with your account. [default: USD] B{required }
    1633                - C{customer}:  ID of customer. If specified, card on file of customer will be used.
    1634                - C{description}:  Free form text field to be used as a description of the payment. This field is echoed back with the payment on any find or list operations. [max length: 1024]
    1635                - C{invoice}:  ID of invoice for which this payment is being made.
    1636                - C{order => commodityCode}:  Standard classification code for products and services. [max length: 5]
    1637                - C{order => customer}:  ID of the customer associated with the order.
    1638                - C{order => customerEmail}:  Customer email address.
    1639                - C{order => customerName}:  Customer name.
    1640                - C{order => customerNote}:  Additional notes provided by the customer. [max length: 255]
    1641                - C{order => customerReference}:  A merchant reference for the customer.
    1642                - C{order => items => amount}:  Cost of the item.
    1643                - C{order => items => description}:  Description of the item.
    1644                - C{order => items => name}:  Item name.
    1645                - C{order => items => product}:  Product information associated with the item.
    1646                - C{order => items => quantity}:  Quantity of the item contained in the order [min value: 1, max value: 999999, default: 1] B{required }
    1647                - C{order => items => reference}:  A merchant reference for the item. [max length: 255]
    1648                - C{order => items => tax}:  Taxes associated with the item.
    1649                - C{order => merchantNote}:  Additional notes provided by the merchant. [max length: 255]
    1650                - C{order => payment}:  ID of the payment associated with the order.
    1651                - C{order => reference}:  A merchant reference for the order. [max length: 255]
    1652                - C{order => shippingAddress => city}:  City, town, or municipality. [max length: 255, min length: 2]
    1653                - C{order => shippingAddress => country}:  2-character country code. [max length: 2, min length: 2]
    1654                - C{order => shippingAddress => line1}:  Street address. [max length: 255]
    1655                - C{order => shippingAddress => line2}:  (Opt) Street address continued. [max length: 255]
    1656                - C{order => shippingAddress => name}:  Name of the entity being shipped to. [max length: 255]
    1657                - C{order => shippingAddress => state}:  State or province. [max length: 255]
    1658                - C{order => shippingAddress => zip}:  Postal code. [max length: 32]
    1659                - C{order => shippingFromAddress => city}:  City, town, or municipality. [max length: 255, min length: 2]
    1660                - C{order => shippingFromAddress => country}:  2-character country code. [max length: 2, min length: 2]
    1661                - C{order => shippingFromAddress => line1}:  Street address. [max length: 255]
    1662                - C{order => shippingFromAddress => line2}:  (Opt) Street address continued. [max length: 255]
    1663                - C{order => shippingFromAddress => name}:  Name of the entity performing the shipping. [max length: 255]
    1664                - C{order => shippingFromAddress => state}:  State or province. [max length: 255]
    1665                - C{order => shippingFromAddress => zip}:  Postal code. [max length: 32]
    1666                - C{order => shippingName}:  Name of the entity being shipped to.
    1667                - C{order => source}:  Order source. [default: WEB] B{required }
    1668                - C{order => status}:  Status of the order. [default: INCOMPLETE] B{required }
    1669                - C{reference}:  Custom reference field to be used with outside systems.
    1670                - C{replayId}:  An identifier that can be sent to uniquely identify a payment request to facilitate retries due to I/O related issues. This identifier must be unique for your account (sandbox or live) across all of your payments. If supplied, we will check for a payment on your account that matches this identifier. If found will attempt to return an identical response of the original request. [max length: 50, min length: 1]
    1671                - C{statementDescription => name}:  Merchant name. B{required }
    1672                - C{statementDescription => phoneNumber}:  Merchant contact phone number.
    1673                - C{taxExempt}:  Specify true to indicate that the payment is tax-exempt.
    1674                - C{token}:  If specified, card associated with card token will be used. [max length: 255]
    1675            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1676                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1677            @param private_api_key: Private key to use for the API call. If C{None}, the value of C{simplify.private_key} will be used.
    1678            @return: a Payment object
    1679          """
    1680          return PaymentsApi.create("payment", auth_args, params)
    1681
    1682      @staticmethod
    1683 -    def list(criteria = None, *auth_args):
    1684          """
    1685            Retrieve Payment objects.
    1686            @param criteria: a dict of parameters; valid keys are:
    1687                 - C{filter}  <table class="filter_list"><tr><td>filter.id</td><td>Filter by the payment Id</td></tr><tr><td>filter.replayId</td><td>Filter by the compoundReplayId</td></tr><tr><td>filter.last4</td><td>Filter by the card number (last 4 digits)</td></tr><tr><td>filter.amount</td><td>Filter by the payment amount (in the smallest unit of your currency)</td></tr><tr><td>filter.text</td><td>Filter by the description of the payment</td></tr><tr><td>filter.amountMin & filter.amountMax</td><td>The filter amountMin must be used with amountMax to find payments with payments amounts between the min and max figures</td></tr><tr><td>filter.dateCreatedMin<sup>*</sup></td><td>Filter by the minimum created date you are searching for - Date in UTC millis</td></tr><tr><td>filter.dateCreatedMax<sup>*</sup></td><td>Filter by the maximum created date you are searching for - Date in UTC millis</td></tr><tr><td>filter.deposit</td><td>Filter by the deposit id connected to the payment</td></tr><tr><td>filter.customer</td><td>Filter using the Id of the customer to find the payments for that customer</td></tr><tr><td>filter.status</td><td>Filter by the payment status text</td></tr><tr><td>filter.reference</td><td>Filter by the payment reference text</td></tr><tr><td>filter.authCode</td><td>Filter by the payment authorization code (Not the authorization ID)</td></tr><tr><td>filter.q</td><td>You can use this to filter by the Id, the authCode or the amount of the payment</td></tr></table><br><sup>*</sup>Use dateCreatedMin with dateCreatedMax in the same filter if you want to search between two created dates
    1688                 - C{max}  Allows up to a max of 50 list items to return. [min value: 0, max value: 50, default: 20]
    1689                 - C{offset}  Used in paging of the list.  This is the start offset of the page. [min value: 0, default: 0]
    1690                 - C{sorting}  Allows for ascending or descending sorting of the list. The value maps properties to the sort direction (either C{asc} for ascending or C{desc} for descending).  Sortable properties are:  C{dateCreated} C{createdBy} C{amount} C{id} C{description} C{paymentDate}.
    1691            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1692                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1693            @return: an object which contains the list of Payment objects in the <code>list</code> property and the total number
    1694                     of objects available for the given criteria in the <code>total</code> property.
    1695          """
    1696          return PaymentsApi.list("payment", auth_args, criteria)
    1697
    1698      @staticmethod
    1699 -    def find(object_id, *auth_args):
    1700          """
    1701            Retrieve a Payment object from the API
    1702            @param object_id: ID of object to retrieve
    1703            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1704                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1705            @return: a Payment object
    1706          """
    1707          return PaymentsApi.find("payment", auth_args, object_id)
    1708
    1709 -    def update(self, *auth_args):
    1710          """
    1711            Updates this object
    1712
    1713            The properties that can be updated:
    1714            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1715                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1716            @return: a Payment object.
    1717          """
    1718          return PaymentsApi.update("payment", auth_args, self.object_id, self.to_dict())
    1719
    1720 -class Plan(Domain):
    1721      """
    1722         A Plan object.
    1723      """
    1724
    1725
    1726      @staticmethod
    1727 -    def create(params, *auth_args):
    1728          """
    1729            Creates an Plan object
    1730            @param params: a dict of parameters; valid keys are:
    1731                - C{amount}:  Amount of payment for the plan in the smallest unit of your currency. Example: 100 = $1.00 B{required }
    1732                - C{billingCycle}:  How the plan is billed to the customer. Values must be AUTO (indefinitely until the customer cancels) or FIXED (a fixed number of billing cycles). [default: AUTO]
    1733                - C{billingCycleLimit}:  The number of fixed billing cycles for a plan. Only used if the billingCycle parameter is set to FIXED. Example: 4
    1734                - C{currency}:  Currency code (ISO-4217) for the plan. Must match the currency associated with your account. [default: USD] B{required }
    1735                - C{frequency}:  Frequency of payment for the plan. Used in conjunction with frequencyPeriod. Valid values are "DAILY", "WEEKLY", "MONTHLY" and "YEARLY". [default: MONTHLY] B{required }
    1736                - C{frequencyPeriod}:  Period of frequency of payment for the plan. Example: if the frequency is weekly, and periodFrequency is 2, then the subscription is billed bi-weekly. [min value: 1, default: 1] B{required }
    1737                - C{name}:  Name of the plan [max length: 50, min length: 2] B{required }
    1738                - C{renewalReminderLeadDays}:  If set, how many days before the next billing cycle that a renewal reminder is sent to the customer. If null, then no emails are sent. Minimum value is 7 if set.
    1739                - C{trialPeriod}:  Plan free trial period selection.  Must be Days, Weeks, or Month [default: NONE] B{required }
    1740                - C{trialPeriodQuantity}:  Quantity of the trial period.  Must be greater than 0 and a whole number. [min value: 1]
    1741            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1742                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1743            @param private_api_key: Private key to use for the API call. If C{None}, the value of C{simplify.private_key} will be used.
    1744            @return: a Plan object
    1745          """
    1746          return PaymentsApi.create("plan", auth_args, params)
    1747
    1748 -    def delete(self, *auth_args):
    1749          """
    1750              Delete this object
    1751              @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1752                  For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1753          """
    1754          return PaymentsApi.delete("plan", auth_args, self.object_id)
    1755
    1756      @staticmethod
    1757 -    def list(criteria = None, *auth_args):
    1758          """
    1759            Retrieve Plan objects.
    1760            @param criteria: a dict of parameters; valid keys are:
    1761                 - C{filter}  <table class="filter_list"><tr><td>filter.id</td><td>Filter by the plan Id</td></tr><tr><td>filter.text</td><td>Filter by the name of the plan</td></tr><tr><td>filter.frequency</td><td>Filter by the frequency of the plan</td></tr><tr><td>filter.amountMin & filter.amountMax</td><td>The filter amountMin must be used with amountMax to find plans with plan values between the min and max figures</td></tr><tr><td>filter.dateCreatedMin<sup>*</sup></td><td>Filter by the minimum created date you are searching for - Date in UTC millis</td></tr><tr><td>filter.dateCreatedMax<sup>*</sup></td><td>Filter by the maximum created date you are searching for - Date in UTC millis</td></tr><tr><td>filter.q</td><td>You can use this to filter by the Id, the name or the amount of the plan</td></tr></table><br><sup>*</sup>Use dateCreatedMin with dateCreatedMax in the same filter if you want to search between two created dates
    1762                 - C{max}  Allows up to a max of 50 list items to return. [min value: 0, max value: 50, default: 20]
    1763                 - C{offset}  Used in paging of the list.  This is the start offset of the page. [min value: 0, default: 0]
    1764                 - C{sorting}  Allows for ascending or descending sorting of the list. The value maps properties to the sort direction (either C{asc} for ascending or C{desc} for descending).  Sortable properties are:  C{dateCreated} C{amount} C{frequency} C{name} C{id}.
    1765            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1766                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1767            @return: an object which contains the list of Plan objects in the <code>list</code> property and the total number
    1768                     of objects available for the given criteria in the <code>total</code> property.
    1769          """
    1770          return PaymentsApi.list("plan", auth_args, criteria)
    1771
    1772      @staticmethod
    1773 -    def find(object_id, *auth_args):
    1774          """
    1775            Retrieve a Plan object from the API
    1776            @param object_id: ID of object to retrieve
    1777            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1778                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1779            @return: a Plan object
    1780          """
    1781          return PaymentsApi.find("plan", auth_args, object_id)
    1782
    1783 -    def update(self, *auth_args):
    1784          """
    1785            Updates this object
    1786
    1787            The properties that can be updated:
    1788              - C{name} Name of the plan. [min length: 2] B{(required)}
    1789
    1790            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1791                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1792            @return: a Plan object.
    1793          """
    1794          return PaymentsApi.update("plan", auth_args, self.object_id, self.to_dict())
    1795
    1796 -class Refund(Domain):
    1797      """
    1798         A Refund object.
    1799      """
    1800
    1801
    1802      @staticmethod
    1803 -    def create(params, *auth_args):
    1804          """
    1805            Creates an Refund object
    1806            @param params: a dict of parameters; valid keys are:
    1807                - C{amount}:  Amount of the refund in the smallest unit of your currency. Example: 100 = $1.00 B{required }
    1808                - C{payment}:  ID of the payment for the refund
    1809                - C{reason}:  Reason for the refund
    1810                - C{reference}:  Custom reference field to be used with outside systems.
    1811                - C{replayId}:  An identifier that can be sent to uniquely identify a refund request to facilitate retries due to I/O related issues. This identifier must be unique for your account (sandbox or live) across all of your refunds. If supplied, we will check for a refund on your account that matches this identifier. If found we will return an identical response to that of the original request. [max length: 50, min length: 1]
    1812                - C{statementDescription => name}:  Merchant name. B{required }
    1813                - C{statementDescription => phoneNumber}:  Merchant contact phone number.
    1814            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1815                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1816            @param private_api_key: Private key to use for the API call. If C{None}, the value of C{simplify.private_key} will be used.
    1817            @return: a Refund object
    1818          """
    1819          return PaymentsApi.create("refund", auth_args, params)
    1820
    1821      @staticmethod
    1822 -    def list(criteria = None, *auth_args):
    1823          """
    1824            Retrieve Refund objects.
    1825            @param criteria: a dict of parameters; valid keys are:
    1826                 - C{filter}  <table class="filter_list"><tr><td>filter.id</td><td>Filter by the refund Id</td></tr><tr><td>filter.text</td><td>Filter by the refund description text</td></tr><tr><td>filter.replayId</td><td>Filter by the compoundReplayId</td></tr><tr><td>filter.authCode</td><td>Filter by the authorization code (Not authorization ID)</td></tr><tr><td>filter.amount</td><td>Filter by the refund amount (in the smallest unit of your currency)</td></tr><tr><td>filter.dateCreatedMin<sup>*</sup></td><td>Filter by the minimum created date you are searching for - Date in UTC millis</td></tr><tr><td>filter.dateCreatedMax<sup>*</sup></td><td>Filter by the maximum created date you are searching for - Date in UTC millis</td></tr><tr><td>filter.deposit</td><td>Filter by the deposit id</td></tr><tr><td>filter.q</td><td>You can use this to filter by the Id, the authCode or the amount of the refund</td></tr></table><br><sup>*</sup>Use dateCreatedMin with dateCreatedMax in the same filter if you want to search between two created dates
    1827                 - C{max}  Allows up to a max of 50 list items to return. [min value: 0, max value: 50, default: 20]
    1828                 - C{offset}  Used in paging of the list.  This is the start offset of the page. [min value: 0, default: 0]
    1829                 - C{sorting}  Allows for ascending or descending sorting of the list. The value maps properties to the sort direction (either C{asc} for ascending or C{desc} for descending).  Sortable properties are:  C{id} C{amount} C{description} C{dateCreated} C{paymentDate}.
    1830            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1831                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1832            @return: an object which contains the list of Refund objects in the <code>list</code> property and the total number
    1833                     of objects available for the given criteria in the <code>total</code> property.
    1834          """
    1835          return PaymentsApi.list("refund", auth_args, criteria)
    1836
    1837      @staticmethod
    1838 -    def find(object_id, *auth_args):
    1839          """
    1840            Retrieve a Refund object from the API
    1841            @param object_id: ID of object to retrieve
    1842            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1843                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1844            @return: a Refund object
    1845          """
    1846          return PaymentsApi.find("refund", auth_args, object_id)
    1847
    1848 -class Subscription(Domain):
    1849      """
    1850         A Subscription object.
    1851      """
    1852
    1853
    1854      @staticmethod
    1855 -    def create(params, *auth_args):
    1856          """
    1857            Creates an Subscription object
    1858            @param params: a dict of parameters; valid keys are:
    1859                - C{amount}:  Amount of the payment in the smallest unit of your currency. Example: 100 = $1.00
    1860                - C{billingCycle}:  How the plan is billed to the customer. Values must be AUTO (indefinitely until the customer cancels) or FIXED (a fixed number of billing cycles). [default: AUTO]
    1861                - C{billingCycleLimit}:  The number of fixed billing cycles for a plan. Only used if the billingCycle parameter is set to FIXED. Example: 4
    1862                - C{coupon}:  Coupon ID associated with the subscription
    1863                - C{currency}:  Currency code (ISO-4217). Must match the currency associated with your account.
    1864                - C{currentPeriodEnd}:  End date of subscription's current period
    1865                - C{currentPeriodStart}:  Start date of subscription's current period
    1866                - C{customer}:  Customer that is enrolling in the subscription.
    1867                - C{frequency}:  Frequency of payment for the plan. Used in conjunction with frequencyPeriod. Valid values are "DAILY", "WEEKLY", "MONTHLY" and "YEARLY".
    1868                - C{frequencyPeriod}:  Period of frequency of payment for the plan. Example: if the frequency is weekly, and periodFrequency is 2, then the subscription is billed bi-weekly.
    1869                - C{name}:  Name describing subscription [max length: 50]
    1870                - C{plan}:  The ID of the plan that should be used for the subscription.
    1871                - C{quantity}:  Quantity of the plan for the subscription. [min value: 1]
    1872                - C{renewalReminderLeadDays}:  If set, how many days before the next billing cycle that a renewal reminder is sent to the customer. If null, then no emails are sent. Minimum value is 7 if set.
    1873                - C{source}:  Source of where subscription was created
    1874            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1875                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1876            @param private_api_key: Private key to use for the API call. If C{None}, the value of C{simplify.private_key} will be used.
    1877            @return: a Subscription object
    1878          """
    1879          return PaymentsApi.create("subscription", auth_args, params)
    1880
    1881 -    def delete(self, *auth_args):
    1882          """
    1883              Delete this object
    1884              @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1885                  For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1886          """
    1887          return PaymentsApi.delete("subscription", auth_args, self.object_id)
    1888
    1889      @staticmethod
    1890 -    def list(criteria = None, *auth_args):
    1891          """
    1892            Retrieve Subscription objects.
    1893            @param criteria: a dict of parameters; valid keys are:
    1894                 - C{filter}  <table class="filter_list"><tr><td>filter.customer</td><td>Filter by the Id of the customer with the subscription</td></tr><tr><td>filter.plan</td><td>Filter by the Id of the plan linked to the subscription</td></tr><tr><td>filter.dateCreatedMin<sup>*</sup></td><td>Filter by the minimum created date you are searching for - Date in UTC millis</td></tr><tr><td>filter.dateCreatedMax<sup>*</sup></td><td>Filter by the maximum created date you are searching for - Date in UTC millis</td></tr><tr><td>filter.q</td><td>You can use this to filter by the Id, the name or the amount of the subscription</td></tr></table><br><sup>*</sup>Use dateCreatedMin with dateCreatedMax in the same filter if you want to search between two created dates
    1895                 - C{max}  Allows up to a max of 50 list items to return. [min value: 0, max value: 50, default: 20]
    1896                 - C{offset}  Used in paging of the list.  This is the start offset of the page. [min value: 0, default: 0]
    1897                 - C{sorting}  Allows for ascending or descending sorting of the list. The value maps properties to the sort direction (either C{asc} for ascending or C{desc} for descending).  Sortable properties are:  C{dateCreated} C{id} C{plan}.
    1898            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1899                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1900            @return: an object which contains the list of Subscription objects in the <code>list</code> property and the total number
    1901                     of objects available for the given criteria in the <code>total</code> property.
    1902          """
    1903          return PaymentsApi.list("subscription", auth_args, criteria)
    1904
    1905      @staticmethod
    1906 -    def find(object_id, *auth_args):
    1907          """
    1908            Retrieve a Subscription object from the API
    1909            @param object_id: ID of object to retrieve
    1910            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1911                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1912            @return: a Subscription object
    1913          """
    1914          return PaymentsApi.find("subscription", auth_args, object_id)
    1915
    1916 -    def update(self, *auth_args):
    1917          """
    1918            Updates this object
    1919
    1920            The properties that can be updated:
    1921              - C{amount} Amount of the payment in the smallest unit of your currency. Example: 100 = $1.00
    1922
    1923              - C{billingCycle} How the plan is billed to the customer. Values must be AUTO (indefinitely until the customer cancels) or FIXED (a fixed number of billing cycles). [default: AUTO]
    1924
    1925              - C{billingCycleLimit} The number of fixed billing cycles for a plan. Only used if the billingCycle parameter is set to FIXED. Example: 4
    1926
    1927              - C{coupon} Coupon being assigned to this subscription
    1928
    1929              - C{currency} Currency code (ISO-4217). Must match the currency associated with your account.
    1930
    1931              - C{currentPeriodEnd} End date of subscription's current period
    1932
    1933              - C{currentPeriodStart} Start date of subscription's current period
    1934
    1935              - C{frequency} Frequency of payment for the plan. Used in conjunction with frequencyPeriod. Valid values are "DAILY", "WEEKLY", "MONTHLY" and "YEARLY".
    1936
    1937              - C{frequencyPeriod} Period of frequency of payment for the plan. Example: if the frequency is weekly, and periodFrequency is 2, then the subscription is billed bi-weekly. [min value: 1]
    1938
    1939              - C{name} Name describing subscription
    1940
    1941              - C{plan} Plan that should be used for the subscription.
    1942
    1943              - C{prorate} Whether to prorate existing subscription. [default: true] B{(required)}
    1944
    1945              - C{quantity} Quantity of the plan for the subscription. [min value: 1]
    1946
    1947              - C{renewalReminderLeadDays} If set, how many days before the next billing cycle that a renewal reminder is sent to the customer. If null or 0, no emails are sent. Minimum value is 7 if set.
    1948
    1949            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1950                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1951            @return: a Subscription object.
    1952          """
    1953          return PaymentsApi.update("subscription", auth_args, self.object_id, self.to_dict())
    1954
    1955 -class Tax(Domain):
    1956      """
    1957         A Tax object.
    1958      """
    1959
    1960
    1961      @staticmethod
    1962 -    def create(params, *auth_args):
    1963          """
    1964            Creates an Tax object
    1965            @param params: a dict of parameters; valid keys are:
    1966                - C{label}:  The label of the tax object. [max length: 255] B{required }
    1967                - C{rate}:  The tax rate.  Decimal value up three decimal places.  e.g 12.501. [max length: 6] B{required }
    1968            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1969                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1970            @param private_api_key: Private key to use for the API call. If C{None}, the value of C{simplify.private_key} will be used.
    1971            @return: a Tax object
    1972          """
    1973          return PaymentsApi.create("tax", auth_args, params)
    1974
    1975 -    def delete(self, *auth_args):
    1976          """
    1977              Delete this object
    1978              @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1979                  For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1980          """
    1981          return PaymentsApi.delete("tax", auth_args, self.object_id)
    1982
    1983      @staticmethod
    1984 -    def list(criteria = None, *auth_args):
    1985          """
    1986            Retrieve Tax objects.
    1987            @param criteria: a dict of parameters; valid keys are:
    1988                 - C{filter}  <table class="filter_list"><tr><td>filter.id</td><td>Filter by the Id of the tax</td></tr><tr><td>filter.label</td><td>Filter by the label(name) of the tax</td></tr></table>
    1989                 - C{max}  Allows up to a max of 50 list items to return. [min value: 0, max value: 50, default: 20]
    1990                 - C{offset}  Used in paging of the list.  This is the start offset of the page. [min value: 0, default: 0]
    1991                 - C{sorting}  Allows for ascending or descending sorting of the list. The value maps properties to the sort direction (either C{asc} for ascending or C{desc} for descending).  Sortable properties are:  C{id} C{label}.
    1992            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    1993                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    1994            @return: an object which contains the list of Tax objects in the <code>list</code> property and the total number
    1995                     of objects available for the given criteria in the <code>total</code> property.
    1996          """
    1997          return PaymentsApi.list("tax", auth_args, criteria)
    1998
    1999      @staticmethod
    2000 -    def find(object_id, *auth_args):
    2001          """
    2002            Retrieve a Tax object from the API
    2003            @param object_id: ID of object to retrieve
    2004            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    2005                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    2006            @return: a Tax object
    2007          """
    2008          return PaymentsApi.find("tax", auth_args, object_id)
    2009
    2010 -class TransactionReview(Domain):
    2011      """
    2012         A TransactionReview object.
    2013      """
    2014
    2015
    2016      @staticmethod
    2017 -    def create(params, *auth_args):
    2018          """
    2019            Creates an TransactionReview object
    2020            @param params: a dict of parameters; valid keys are:
    2021            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    2022                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    2023            @param private_api_key: Private key to use for the API call. If C{None}, the value of C{simplify.private_key} will be used.
    2024            @return: a TransactionReview object
    2025          """
    2026          return PaymentsApi.create("transactionReview", auth_args, params)
    2027
    2028 -    def delete(self, *auth_args):
    2029          """
    2030              Delete this object
    2031              @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    2032                  For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    2033          """
    2034          return PaymentsApi.delete("transactionReview", auth_args, self.object_id)
    2035
    2036      @staticmethod
    2037 -    def list(criteria = None, *auth_args):
    2038          """
    2039            Retrieve TransactionReview objects.
    2040            @param criteria: a dict of parameters; valid keys are:
    2041            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    2042                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    2043            @return: an object which contains the list of TransactionReview objects in the <code>list</code> property and the total number
    2044                     of objects available for the given criteria in the <code>total</code> property.
    2045          """
    2046          return PaymentsApi.list("transactionReview", auth_args, criteria)
    2047
    2048      @staticmethod
    2049 -    def find(object_id, *auth_args):
    2050          """
    2051            Retrieve a TransactionReview object from the API
    2052            @param object_id: ID of object to retrieve
    2053            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    2054                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    2055            @return: a TransactionReview object
    2056          """
    2057          return PaymentsApi.find("transactionReview", auth_args, object_id)
    2058
    2059 -    def update(self, *auth_args):
    2060          """
    2061            Updates this object
    2062
    2063            The properties that can be updated:
    2064            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    2065                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    2066            @return: a TransactionReview object.
    2067          """
    2068          return PaymentsApi.update("transactionReview", auth_args, self.object_id, self.to_dict())
    2069
    2070 -class Webhook(Domain):
    2071      """
    2072         A Webhook object.
    2073      """
    2074
    2075
    2076      @staticmethod
    2077 -    def create(params, *auth_args):
    2078          """
    2079            Creates an Webhook object
    2080            @param params: a dict of parameters; valid keys are:
    2081                - C{url}:  Endpoint URL B{required }
    2082            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    2083                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    2084            @param private_api_key: Private key to use for the API call. If C{None}, the value of C{simplify.private_key} will be used.
    2085            @return: a Webhook object
    2086          """
    2087          return PaymentsApi.create("webhook", auth_args, params)
    2088
    2089 -    def delete(self, *auth_args):
    2090          """
    2091              Delete this object
    2092              @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    2093                  For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    2094          """
    2095          return PaymentsApi.delete("webhook", auth_args, self.object_id)
    2096
    2097      @staticmethod
    2098 -    def list(criteria = None, *auth_args):
    2099          """
    2100            Retrieve Webhook objects.
    2101            @param criteria: a dict of parameters; valid keys are:
    2102                 - C{filter}  Filters to apply to the list.
    2103                 - C{max}  Allows up to a max of 50 list items to return. [min value: 0, max value: 50, default: 20]
    2104                 - C{offset}  Used in paging of the list.  This is the start offset of the page. [min value: 0, default: 0]
    2105                 - C{sorting}  Allows for ascending or descending sorting of the list. The value maps properties to the sort direction (either C{asc} for ascending or C{desc} for descending).  Sortable properties are:  C{dateCreated}.
    2106            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    2107                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    2108            @return: an object which contains the list of Webhook objects in the <code>list</code> property and the total number
    2109                     of objects available for the given criteria in the <code>total</code> property.
    2110          """
    2111          return PaymentsApi.list("webhook", auth_args, criteria)
    2112
    2113      @staticmethod
    2114 -    def find(object_id, *auth_args):
    2115          """
    2116            Retrieve a Webhook object from the API
    2117            @param object_id: ID of object to retrieve
    2118            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    2119                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    2120            @return: a Webhook object
    2121          """
    2122          return PaymentsApi.find("webhook", auth_args, object_id)
    2123
    2124 -    def update(self, *auth_args):
    2125          """
    2126            Updates this object
    2127
    2128            The properties that can be updated:
    2129              - C{url} Endpoint URL B{(required)}
    2130
    2131            @param auth_args: an Authentication object used for the API call.  If no value is passed the gloabl keys simplify.public_key and simplify.private_key are used.
    2132                For backwards compatibility the public and private keys may be passed instead of an Authentication object.
    2133            @return: a Webhook object.
    2134          """
    2135          return PaymentsApi.update("webhook", auth_args, self.object_id, self.to_dict())
    2136