Customers

Payment gateways allow you to store information about your customers. They let you store credit cards securely so that you can remember cards without actually storing the sensitive information on your server. If your database is compromised you won’t leak all of your customers’ information.

We have two objects that you can use to manage your customers’ data.

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'

Todo

Are the credit card fields required when creating a Customer? Dinero doesn’t really require it, but Authorize.Net seems to require you put either a credit card or a bank account (see page 14 of Authorize.Net’s CIM XML Guide).

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()

Note

When you create a CreditCard, it will be validated. This is quite useful if you are going to store a credit card and charge it later when you don’t have access to the user to fix the information.

address and zip are required by Visa when doing a Zero-Dollar Authorization. This is a special process for validating that a card is real without actually charging money to it. For other credit card types, 1¢ is usually charged and immediately voided when validating a credit card.

When you are testing your payments application, you may need to input credit cards that validate. Here is a list of test credit card numbers.

API

Todo

Provide a list of fields that an instance will always have for Customer and CreditCard.

Customer

• customer_id
• first_name
• last_name
• email
• cards

Card

• customer_id
• card_id
• last_4

class dinero.Customer(customer_id, **kwargs)

A Customer object stores information about your customers.

classmethod create(email, **kwargs)

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])

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

save()

Saves changes to a customer object.

delete()

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)

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)

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

save()

Save changes to a card to the gateway.

delete()

Delete a card from the gateway.