dinero - payment processing for Python¶

Merchant Account¶

A merchant account is a special type of bank account that can receive credit card transactions. To protect against fraud, opening a merchant account is something of an involved process.

Payment Gateway¶

Payment gateways are what communicate between the credit card processors and your merchant account. There are several credit card processors these days, but the major ones include Authorize.Net, Braintree Payments, and Stripe.

Braintree and Stripe both offer accounts that don’t require merchant accounts. If you are familiar with Square, this is quite similar. These accounts are more convenient in that you don’t have to go through the hassle of getting a merchant account and you don’t have to pay the merchant account fees. However, the pricing for this type of account is generally higher per transaction (almost always 2.9% + 30¢ per transaction).

Stripe and merchant account-less Braintree accounts are good for companies that are just starting out who don’t expect to have large transactions. Often it is cheaper to have one of these accounts because the high transaction fees are still smaller than the monthly fees associated with merchant accounts.

Authorize.Net or merchant account-backed Braintree accounts are more suitable for website that expect high volume or high priced transactions, or for companies that also want to do offline payments as well.

1. Configure¶

The first thing you need to do in order to use dinero is to configure your gateways(s). The following example would be configuration for an Authorize.Net gateway:

import dinero

dinero.configure({
    # a name that you can remember
    'auth.net': {
        'type': 'dinero.gateways.AuthorizeNet',
        'default': True,
        # Gateway specific configuration
        'login_id': 'XXX',
        'transaction_key': 'XXX',
    }
})

2. Make Transactions¶

Now that you have a gateway configured, you can create transactions.

transcation = dinero.Transaction.create(
    price=2000,
    number='4111111111111111',
    month='12',
    year='2012',
)

3. Profit¶

Well that’s up to you now isn’t it.

Delayed Settlement¶

By default, dinero will automatically submit a transaction for settlement, however you can override this by setting the settle argument to False. When you need to settle a transaction, you can call Transaction.settle():

transaction = dinero.Transaction.create(
    price=200,
    number='4111111111111111',
    month='12',
    year='2015',
    settle=False,
)

...

transaction.settle()

If you need to cancel a transaction instead of settling it, just call Transaction.refund().

API¶

class dinero.Transaction(gateway_name, price, transaction_id, **kwargs)[source]¶

Transaction is an abstraction over payments in a gateway. This is the interface for creating payments.

classmethod create(price, **kwargs)[source]¶

Creates a payment. This method will actually charge your customer. create() can be called in several different ways.

You can call this with the credit card information directly.

Transaction.create(
    price=200,
    number='4111111111111111',
    year='2015',
    month='12',

    # optional
    first_name='John',
    last_name='Smith,'
    zip='12345',
    address='123 Elm St',
    city='Denver',
    state='CO',
    cvv='900',
    email='johnsmith@example.com',
)

If you have a dinero.Customer object, you can create a transaction against the customer.

customer = Customer.create(
    ...
)

Transaction.create(
    price=200,
    customer=customer,
)

Other payment options include card and check. See dinero.CreditCard for more information.

classmethod retrieve(transaction_id[, gateway_name=None])[source]¶

Fetches a transaction object from the gateway.

refund([amount=None])[source]¶

If amount is None dinero will refund the full price of the transaction.

Payment gateways often allow you to refund only a certain amount of money from a transaction. Refund abstracts the difference between refunding and voiding a payment so that normally you don’t need to worry about it. However, please note that you can only refund the entire amount of a transaction before it is settled.

settle([amount=None])[source]¶

If you create a transaction without settling it, you can settle it with this method. It is possible to settle only part of a transaction. If amount is None, the full transaction price is settled.

Customers¶

The Customer class provides an interface quite similar to Transaction. To create a customer, you use Customer.create():

>>> customer = Customer.create(
        email='bill@example.com',
        number='4111111111111111',
        cvv='900',
        address='123 Elm St',
        zip='12345',
    )
>>> customer.customer_id
'1234567890'
>>> customer.card_id
'0000101010'

Similarly, you can also retrieve customers. However, whereas transactions are not really editable, if you want to update a customer’s information you can. Just call the Customer.save() method when you have made your changes.

>>> customer = Customer.retrieve('1234567890')
>>> customer.email = 'fred@example.com'
>>> customer.save()

You wouldn’t really have a use for storing a customer’s payment data if you weren’t actually going to use it. If you want to charge a customer, Transaction.create() accepts a Customer object:

customer = Customer.retrieve('1234567890')

transaction = Transaction.create(
    price=200,
    customer=customer,
)

Credit Cards¶

Every Customer also has list of credit cards that can be accessed at customer.cards.

When you create your Customer, it will create the first card:

>>> customer = Customer.create(
        email='bill@example.com',
        number='4111111111111111',
        cvv='900',
        address='123 Elm St',
        zip='12345',
    )
>>> card = customer.cards[0]
>>> card.last_4
'1111'

If you have a secondary card, you can add it using Customer.add_card().

customer.add_card(
    first_name='John',
    last_name='Smith',
    number='4222222222222',
    cvv='900',
    address='123 Elm St',
    zip='12345',
)

The CreditCard class is editable like Customer:

card.first_name = 'Fred'
card.save()

API¶

class dinero.Customer(customer_id, **kwargs)[source]¶

A Customer object stores information about your customers.

classmethod create(email, **kwargs)[source]¶

Creates and stores a customer object. When you first create a customer, you are required to also pass in arguments for a credit card.

Customer.create(
    email='bill@example.com',

    # required for credit card
    number='4111111111111111',
    cvv='900',
    month='12',
    year='2015',
    address='123 Elm St.',
    zip='12345',
)

This method also accepts gateway_name.

classmethod retrieve(customer_id[, gateway_name=None])[source]¶

Fetches a customer object from the gateway. This optionally accepts a gateway_name parameter.

save()[source]¶

Saves changes to a customer object.

delete()[source]¶

Deletes a customer object from the gateway.

cards¶

Contains a list of all the cards associated with a customer. This is populated by create() and retrieve() and appended to by add_card().

add_card(*args, **kwargs)[source]¶

The first credit card is added when you call create(), but you can add more cards using this method.

customer.add_card(
    number='4222222222222',
    cvv='900',
    month='12'
    year='2015'
    address='123 Elm St',
    zip='12345',
)

class dinero.CreditCard(customer_id, card_id, **kwargs)[source]¶

A representation of a credit card to be stored in the gateway.

save()[source]¶

Save changes to a card to the gateway.

delete()[source]¶

Delete a card from the gateway.