+++++++++++++++++++++
Payment API
+++++++++++++++++++++

.. contents::

------------
Crash Course
------------

*(Note: This is an example using Authorize.net)*

First, import the payment module:

    >>> from paypy.payment import Payment

Options (fields) are passed to the adapter of the payment library by
way of a dictionary:

    >>> options = {'amount'     : '.01',
    ...            'card_num'   : 4111111111111111,
    ...            'exp_date'   : '02/16',
    ...            'first_name' : 'Babbock',
    ...            'last_name'  : 'Narwal',
    ...            'phone'      : '(352) 818-8035',
    ...            'address'    : '42 Circle Rd.',
    ...            'city'       : 'Chicago',
    ...            'state'      : 'Illinois',
    ...            'country'    : 'US',
    ...            'zip'        : '92009',
    ...            'customer_ip': '0.0.0.0',
    ...            'tran_key'   : 'your_developer_key',
    ...            'login'      : 'your_developer_login_id',
    ...            'testing'    : True
    ...            }

Setting the ``testing`` key to ``True`` will tell the payment library
to use the ``test.authorize.net/gateway/transact.dll`` endpoint
URL. There is a difference between having your merchant account in
test mode and using a completely separate account specifically for
testing.

Because Authorize.net merchant accounts may be used by multiple
applications/websites the design choice was to stick with the
developer test accounts for testing. (to get one, go here: http://developer.authorize.net/testaccount/)

You can then instantiate the payment class with the provided options
and call the ``process()`` method:

    >>> payment = Payment(options)
    >>> results = payment.process()

Note: you may also specify the adapter you wish to use by providing a
second argument (argument key is ``adapter``) with the name of the
adapter you wish to use. The library will default to the Authorize.net
adapter if none is provided.

Results are given back as an object with important fields assigned to
the result object. You can access the response code
(``results.code``), type of response (``results.type``), the hash,
transaction ID, the raw result string, and a few others.

    >>> print str(results)
    This transaction has been approved.
    >>> print results.code
    1
    >>> print results.type
    approved
    >>> print results.transaction_id
    2155132413

---
API
---

The API is simple, you instantiate the payment library with a given
set of options (fields) and an optional specifier for the type of
adapter to use as a second argument (if not provided it defaults to
using the *authnet* adapter). The payment object then exposes only two
methods: ``process()`` and ``set_fields(key, value)``. The
``set_fields`` method is used when you wish to amend the options
dictionary *after* instantiating with the options dictionary.

Calling the object's ``process()`` method will submit the configured
transaction to the gateway and return a result object.

The standard fields common to all adapters are:

#. card_num
#. exp_date
#. cvv
#. description
#. amount
#. tax
#. shipping
#. first_name
#. last_name
#. company
#. address
#. city
#. state
#. zip
#. email
#. phone
#. fax
#. ship_to_first_name
#. ship_to_last_name
#. ship_to_company
#. ship_to_address
#. ship_to_city
#. ship_to_state
#. ship_to_zip

The ``testing`` field (not included above) defaults, in all adapters,
to ``False``.

Gateway specific fields and configuration are documented below.

----------------
Gateway Specific
----------------

Authorize.net
=============

Google
======

Not yet implemented.

PayPal
======

Not yet implemented.
