Cicero API – Accepting Credit and Debit Card Payments with Stripe

By azavea on August 1st, 2012

Until recently any client who wanted to purchase Cicero API credits would contact us directly and request that the credits be added to their account. We then issued the client an invoice to be paid by check.  In order to enable customers to purchase credits immediately (at any time of day), eliminate the need for us to process orders by phone, and deposit paper checks, we decided to implement online payment processing accessible via the user account pages.

We considered PayPal, Google Payments and several other online payment processing services, but after extensive research we decided to go with Stripe, a secure online payment system. Despite being the “new kid on the block”, Stripe has quickly established itself as a super secure and easy-to-use alternative to some of the more well-known payment processing services available.

Processing online payments with Stripe is simple and secure. Great documentation, easy-to-use wrappers, and an extensive testing framework make developing applications a pleasure. The intuitive online dashboard makes it easy to manage and visualize customers, payments, and refunds.

How it works

After creating an account and obtaining an API key, you create a form on your website to collect your user’s payment information. Stripe’s JavaScript API is used to securely submit this data to Stripe’s servers. If the card info is valid, Stripe returns a single-use token that can be passed onto your backend to charge the customer. With this process, none of the user’s card information is sent to your servers, and the customer is never redirected to a third-party site to pay.

Stripe API libraries exist for over a dozen programming applications and frameworks. We use Stripe’s Python library to create and update customer records with contact and card information. As part of this step, Stripe checks the billing address against the information on the card (although not all banks support this).

If any of the fraud checks fail, we do not attempt to charge the customer. Otherwise, the card is charged and API credits are added to the user’s account.

For added redundancy, we also take advantage of Stripe’s webhooks. They send a web request to our Cicero servers, and we mark the payment confirmed. In the unlikely event that, say, the plug got pulled on our server right as a charge was being made, we would be able to add the credits upon receiving notification from Stripe that the payment went through successfully. (If our servers were to be down, Stripe would keep retrying the request until they come back up and an “OK” response is received.)


There is a way to test just about anything without anyone being charged real money. Developers can use a test account dashboard, API keys, and credit card numbers. Writing unit tests is easy because there are special card numbers to test each type of error, such as a declined card or mismatched ZIP code.


The fee is 30 cents plus 2.9%. The customer’s country and type of card used do not matter. Volume discounts are offered for merchants that charge over $1 million per year.

Stripe Caveats

  • Only a customer’s last card used is stored in Stripe. This makes it easy to allow the user to use their previous card instead of reentering all of the information. However, if he or she wanted to use the a card used for an order before the last, it would have to be reentered.
  • Payments are disbursed with a seven-day float. This is not a major issue for us, but could be for a reseller taking a high-volume special order with a short lead time, for example. Waiting a week to get paid is certainly better than other providers that can sometimes freeze your account without warning.
  • Stripe is not yet available outside the United States.
Overall, Stripe’s transparency and ease-of-use from both a development and billing perspective makes it a great option. It is certainly worth looking into for anyone looking to accept payments online.