Posted by: Eric Hansen
Now that we can add users to our marketplace and store their credit cards for use to purchase things, lets make the magic happen! This will be a shorter tutorial than most but still beneficial (what’s the point of processing credit cards if we don’t want money, right?).
Getting the Amount
For sake of argument this will be very simplistic (i.e.: no fees or anything will be taken out). To make this happen, we need the buyer’s e-mail, and optionally (but heavily recommended by me) a card URI to charge the money to. Also, we’ll be working with USD currency throughout this, as I’m not sure if that makes a big difference.
We’ll use a hard coded value for this example, and you’ll see why in a minute. So, lets say we want to charge a client’s card $500.00. You can either pass the value to the below function as a floating-point (500.00) or in cents (50000):
def charge(self, email, amount): if str(amount).find(".") != -1: amount = int(str(amount).replace(".", "")) else: amount = int(amount) * 100 buyer = self.search_email(email) return buyer.debit(amount=amount, appears_on_statement_as=self.getmarketplace())
You might be wondering why we strip out the “.” from 500.00. This is because Balanced requires all money references to be in cents (so $0.01 = 1, $0.10 = 10, $1.00 = 100). This isn’t all that difficult to work with and actually makes it easier in the end as long as you remember you’re working with cents.
Charging the Card
To debit (or charge) a card, we an instance of the client we are to charge. For that we go back to the previous lesson and use our search_email() function. Once we have the reference to that, we can now call a debit on the client’s account with the amount to be charged. appears_on_statement_as is an optional field that when set will tell your bank to show ‘this’ instead of the default (which at the time of this writing can either be BALANCED or POUNDPAY). I’ll show the getmarketplace() call in a bit, but I wanted to cover something else here first.
The reason why we aren’t specifying a card to charge directly is that if no source_uri is provided, it will use the most recently added card to the client’s account. However, if you did want to specify a specific card, you would just add “source_uri=card.uri” (assuming the card’s object is stored in variable ‘card’). If you’re interested in knowing what else you can pass to this call, look at these lines: https://github.com/balanced/balanced-python/blob/master/balanced/resources.py#L512-521
getmarketplace() is a shorthand one-liner I wrote to get the name of the marketplace:
def getmarketplace(self): return format(balanced.Marketplace.my_marketplace.name)
Placing a Hold on a Charge
There will be times where you want to make sure all the information is legit (or you want to act like PayPal and keep funds unavailable for an additional 21 days after a completed transaction), and this is where placing a hold comes in. Note though that if you want a hold to be placed, it has to be called before the debit() call. To create a hold, you essentially replace “debit” with “hold” as seen in the charge() function, then call a capture() on the hold URI instead of debit(). All the variables are the same, but this time amount will be the amount you want to hold back.
I’m going to devote an entire post on fees regarding Balanced, but I want to provide a little overview here, first. There are 2 fees imposed on transactions: 2.9%+30 cent processing and 25 cent ACH deposit. There’s a reason why this is important.
For example, say you want to charge your client $1.00. Initially a fee total of $0.33 (rounded up to the nearest cent). The 30 cents comes from a holding fee which is imposed on every transaction regardless of if you actually call hold() or not. 2.9% is the processing fee of the transaction. The ACH deposit comes further down the line.
When a transaction is complete and the hold is gone, the money goes into an escrow portion of the marketplace. This is basically all the money that has been transacted but not yet deposited into the marketplace itself. Note though that once you take money from escrow and deposit it into the marketplace, that’s when the 25-cent ACH deposit occurs. This is a per-transaction (so if you build up 5 transactions into escrow and transfer all that into the marketplace at once, the deposit fee will still be 25 cents).
The reason why this is important is that currently Balanced doesn’t withdraw the fees of transactions immediately like PayPal does, but instead accumulates them over the course of a month. Then at the end of that period money is transferred from the bank account associated with the marketplace to Balanced to pay off the fees. So, as long as you are either great at book keeping or don’t touch that money (much), you will be fine. This is something that can throw people off though (I know it did me).