Posted by: Eric Hansen
In my previous article I wrote an introduction about Balanced Payments (BP) and why I chose them to handle credit card processing. This time, I’m going to go over how to add a client (or buyer) to your marketplace.
First, a couple of terms to clarify:
Marketplace – Think of this as your business. This will hold all the information regarding buyers, credit cards, transactions, etc…
Buyer - This is the term BP uses for people who will be paying you for your good/service/product/etc… For sake of this series I’ll be calling them clients.
Debit - To handle incoming and outgoing transactions BP uses the terms debit and credit. It took me a little bit to remember which was which, but once I got the hang of it, it made everything easier.
These guides will assume you are using Python to develop, and that you are using the test marketplace you’re given the option to set up on signup, and it’s populated with data. You can always create new test marketplaces whenever you want, and you can create new ones even when you go live. Test marketplaces differ from live ones in that 1) you don’t gain any earnings from it and 2) if there’s no activity for 90 days, the test marketplace is purged.
The first thing you need to do is install the balanced-python module/library: https://github.com/balanced/balanced-python Once you get that directory, just run the setup.py script:
python setup.py install
This will let us import all the needed functions, classes, etc… and start enjoying the use of BP.
What I advise is to create a class file, that has this in it:
self.key = "(enter your API key here)"
This will make it easier in the end when we expand this class. Now, in order to add a client to your marketplace, you need at least two items: their e-mail and a card URI. Getting their e-mail is easy, but the card URI is a little more tricky as you need to create a balanced.Marketplace.my_marketplace.card instance. So I’ll show you how to do this. Add this function into your class:
def addCC(self, name, number, exp_month, exp_year, cvv = None): card = None try: card = balanced.Marketplace.my_marketplace.create_card( name=name, card_number=number, expiration_month=exp_month, expiration_year=exp_year, security_code=cvv) except Exception as e: if e.status_code == 400: print e.description elif e.status_code == 402: print e.description elif e.status_code == 409: print e.description return card
There are 4 items required to add a card to the marketplace: name (the name on the card), card number, expiration month and year. The security code (CVV2) is not required, but I always require it for validation and verification. The exception print statements are mostly there for debugging and for you to handle as you please. On success, card will now be a reference to the card stored on BP’s servers, including the card URI. This is one of the ways they handle PCI compliance for you, as you’re not storing any sensitive data on your servers.
Now that we have the card object ready to be added to a client, we must create the client in our marketplace. First, the addClient() function:
def addClient(self, cardUri, email = None): try: client = balanced.Marketplace.my_marketplace.create_buyer(email, cardUri) return True except balanced.exc.HttpError as e: if e.category_code == "duplicate-email-address": buyer = balanced.Account.query.filter(email_address=email) print buyer buyer = buyer buyer.add_card(cardUri) else: print e return False
This function is pretty self-explanatory for the most part. We require the card URI, but (as a recent change has been made) e-mail addresses are optional (they used to be used as the unique ID for each client). We attempt to create a client and return True on success, but if there’s an issue we have to handle it from there. Primarily as long as you can add a card successfully, the most likely issue you’ll run into in adding a client is a duplicate-email-address. This is why I always try to enforce setting an e-mail, because as long as the e-mail for a client is not null, this exception will pop up. If a duplicate e-mail is found, it instead adds the card to the account. I’ll go into filter() more in the next article, but it can prove to be quite useful.
Lastly is the method to two the above two together: register_buyer():
def register_buyer(self): name = raw_input("Name on card: ") email = raw_input("E-mail address: ") cc = raw_input("Credit Card #: ") month = raw_input("Month expiration: ") year = raw_input("Year expiration: ") cvv = raw_input("CVV2 #: ") card = self.addCC(name, cc, month, year, cvv) if not card: sys.exit("Unable to create card.") buyer = self.addClient(email, card.uri) if not buyer: sys.exit("Unable to create user in system.") return "%s has been registered to %s" % (cc, name)
This function doesn’t take any parameters (though you could supplement the continuous raw_input()’s for arguments). It first attempts to create a card with the information provided. On success, it will then attempt to tie that card to a client (whether by creating and adding it to it’s account, or just adding it if the client exists already). On success it will return a message saying that the credit card has been registered to the individual.
To get an idea as to what is required and optional for each call, BP has a collection of resources found here: https://github.com/balanced/balanced-api/tree/master/resources It provides all the possible fields, what they’re meant for, if it’s optional or not, and more.