Authorize.Net ARB Integration
=============================

The ARBProcessor provides support for Authorize.net's Automated Recurring
Billing (ARB) API, which makes it possible to manage subscription-based
payments via an XML API.

See http://www.authorize.net/support/ARB_guide.pdf for API documentation
including prerequisites for using ARB, and details of what parameters may
be specified.

Transaction Keys
----------------

Each ARB transaction must be accompanied by a merchant login and a
"transaction key".  This key is obtained from the merchant interface.  After
importing the ARBProcessor class you must pass it your login and transaction
key:

    >>> from getpaid.authorizedotnet.subscription import ARBProcessor
    >>> arb = ARBProcessor(server=SERVER_NAME, login=LOGIN, key=KEY)

Creating a subscription
-----------------------

To create a new subscription, use the ``create`` method.

    >>> from time import gmtime, strftime
    >>> today = strftime("%Y-%m-%d", gmtime())
    >>> exp_date = strftime("%Y-%m", gmtime())
    >>> import random
    >>> amount = '%.2f' % random.uniform(0,100)

    >>> result = arb.create(refId = '1234',
    ...                     subscription = {
    ...                          'name': '1234',
    ...                          'paymentSchedule': {
    ...                              'interval': {
    ...                                  'length': 1,
    ...                                  'unit': 'months', },
    ...                              'startDate': today,
    ...                              'totalOccurrences': 12,
    ...                              'trialOccurrences': 0, },
    ...                          'amount': amount,
    ...                          'trialAmount': '0',
    ...                          'payment': {
    ...                              'creditCard': {
    ...                                  'cardNumber': '4007000000027',
    ...                                  'expirationDate': exp_date,
    ...                                  'cardCode': '111', },
    ...                              },
    ...                          'billTo': {
    ...                              'firstName': 'Harvey',
    ...                              'lastName': 'Frank', },
    ...                          },
    ...                      )

It returns a dictionary which contains details about the transaction.

    >>> result['refId']
    '1234'
    >>> result['messages']['resultCode']
    'Ok'
    >>> result['messages']['message']['code']
    '123456'
    >>> result['messages']['message']['text']
    'Successful.'
    >>> subscriptionId = result['subscriptionId']
    >>> subscriptionId
    '123456'

Updating a subscription
-----------------------

To update an existing subscription, use the ``update`` method.  This accepts
the same parameters as ``create``, but all are optional except for the
subscriptionId.

    >>> result = arb.update(subscriptionId = subscriptionId,
    ...                     subscription = {
    ...                          'paymentSchedule': {
    ...                              'totalOccurrences': 6, },
    ...                          },
    ...                      )
    >>> result['messages']['resultCode']
    'Ok'

Trying to update a non-existent subscription results in an error code.

    >>> result = arb.update(subscriptionId = '1',
    ...                     subscription = {
    ...                          'paymentSchedule': {
    ...                              'totalOccurrences': 6, },
    ...                          },
    ...                     )
    >>> result['messages']['resultCode']
    'Error'
    >>> result['messages']['message']['text']
    'The subscription cannot be found.'

Canceling a subscription
------------------------

To cancel an existing subscription, use the ``cancel`` method.

    >>> result = arb.cancel(subscriptionId = subscriptionId)
    >>> result['messages']['resultCode']
    'Ok'

Trying to cancel a non-existent subscription results in an error code.

    >>> result = arb.cancel(subscriptionId = '1')
    >>> result['messages']['resultCode']
    'Error'
    >>> result['messages']['message']['text']
    'The subscription cannot be found.'
