English
资源说明：Gateway-agnostic payment processing for Python
dinero
======
Gateway-agnostic payment processing library for Python.
This library aims to be a minimal, pythonic, and highly usable payment
processing library. It has a simple API and it hides the differences between
payment processors from the user.
USAGE
-----
The API for ``dinero`` is simple to use.
Configuration
~~~~~~~~~~~~~
``dinero`` allows for more than one payment gateway configuration.
::
import dinero
dinero.configure({
'auth.net': { # the name for this gateway
'default': True, # the default gateway
'type': 'dinero.gateways.AuthorizeNet' # the gateway path
# ... gateway-specific configuration
}})
For Django projects, just include this in your ``settings.py``.
Transaction Objects
~~~~~~~~~~~~~~~~~~~
The following code will charge a customer's credit card::
transaction = dinero.Transaction.create(
price=2000,
number='4111111111111111',
month='12',
year='2012',
)
``price``, ``number``, ``month``, and ``year`` are the only required arguments,
additional optional arguments are
- first_name
- last_name
- zip
- address
- city
- state
- cvv
- customer_id
- email
``dinero.Transaction.create`` returns a Transaction object.
**Note**: despite the confusion that may arise, it is possible to associate a
transaction with a customer (id, email) *without* creating a ``Customer``
object. This is so that transactions can be associated with a table in your
system without incurring the overhead of storing credit cards and customer
information in your gateway. In braintree, this is accomplish by storing the
``customer_id`` in ``custom_fields``.
Transaction objects contain data about the payment. Every transaction object
has a ``transaction_id`` and a ``price``. Additionally, transaction objects
have a ``to_dict`` method which returns a dictionary of data which can be passed
to ``Transaction.from_dict`` to restore the Transaction object. This is useful
for caching the transaction data.
After creating a payment, you can retrieve it using
``dinero.Transaction.retrieve``::
transaction = dinero.Transaction.retrieve(
transaction_id = '1234567'
)
``dinero.Transaction.retrieve`` also returns a Transaction object.
In order to refund or cancel a payment, there is a ``refund`` method on
Transaction objects::
transaction.refund()
Delayed settlement
^^^^^^^^^^^^^^^^^^
A transaction can be submitted with ``settle=False`` for an authorization-only
transaction. Later, the transaction can be ``settle()`` ed::
transaction = dinero.Transaction.create(
...
settle=False
)
# Up to 30 days later...
transaction.settle()
TODO: braintree support
Customer Objects
~~~~~~~~~~~~~~~~
You can also create transactions using a Customer object. A Customer
object, much like the gateway configuration, can have multiple named
accounts, one of which should be declared the "default"::
customer = dinero.Customer.create(
# email is used as a unique identifier for this customer
email='joeyjoejoejunior@example.com',
# these are all optional
first_name='Joey',
last_name='Shabadoo',
company='Shabadoo, Inc.',
phone='000-000-0000',
fax='000-000-0001',
address='123 somewhere st',
state='SW',
city='somewhere',
zip='12345',
country='US', # this is the 2-letter country code
# credit card information is required
number='4111-1111-1111-1111', # dinero removes all symbols *except X*
year=2012, # Why? Authorize.net expects credit card numbers in the form
month=2, # "XXXX1111" when updating payment information
)
# the most important value:
customer_id = customer.customer_id
# and later, to update some information
customer = dinero.Customer.retrieve(customer_id)
customer.company = 'Joey Junior, Inc.'
customer.save()
# you can update the CC, too
customer = dinero.Customer.retrieve(customer_id)
customer.number = '4222-2222-2222-2222'
customer.year = '2012'
customer.month = '02'
customer.save()
The credit card information is required, at least on Authorize.net. So,
assuming you've got a customer object, you can now make transactions against
it::
customer = dinero.Customer.create(
# minimum information to create a new account
email='joeyjoejoejunior@example.com',
number='4111-1111-1111-1111',
year='2012',
month='02',
)
transaction = dinero.Transaction.create(
price=2000,
customer=customer
)
Multiple Cards
^^^^^^^^^^^^^^
Like this::
customer = dinero.Customer.retrieve(...)
print customer.cards # existing cards
cc = customer.add_card(
number='4111-1111-1111-1111',
year='2012',
month='02',
)
# charge the new card
dinero.Transaction.create(
price=12,
cc=cc,
)
TESTING
-------
::
$ pip install pytest
...
$ py.test
本源码包内暂不包含可直接显示的源代码文件，请下载源码包。
