digideskio / stripe-android

Stripe Android bindings

##stripe-android

Stripe-android makes it easy to collect credit card information without having sensitive details touch your server.

These Stripe Android bindings can be used to generate tokens in your Android application. If you are building an Android application that charges a credit card, you should use stripe-android to make sure you don't pass credit card information to your server (and, so, are PCI compliant).

##Installation

1. Clone the git repository.
2. Be sure you've installed the Android SDK with API Level 17 and android-support-v4
3. Import the stripe folder into Eclipse.
4. In your project settings, add the stripe project under the "Libraries" section of the "Android" category.

##setPublishableKey

A publishable key is required to identify your website when communicating with Stripe. Remember to replace the test key with your live key in production. You can get all your keys from your account page. This tutorial explains this flow in more detail.

new Stripe("YOUR_PUBLISHABLE_KEY");

or

new Stripe().setPublishableKey("YOUR_PUBLISHABLE_KEY");

##createToken

createToken converts sensitive card data to a single-use token which you can safely pass to your server to charge the user. The tutorial explains this flow in more detail.

stripe.createToken(
    new Card("4242424242424242", 12, 2013, "123"),
    tokenCallback
);    

The first argument to createToken is a Card object. A Card contains the following fields:

• number: card number as a string without any separators, e.g. '4242424242424242'.
• expMonth: integer representing the card's expiration month, e.g. 12.
• expYear: integer representing the card's expiration year, e.g. 2013.

The following field is optional but recommended to help prevent fraud:

• cvc: card security code as a string, e.g. '123'.

The following fields are entirely optional — they cannot result in a token creation failing:

• name: cardholder name.
• addressLine1: billing address line 1.
• addressLine2: billing address line 2.
• addressCity: billing address city.
• addressState: billing address state.
• addressZip: billing zip as a string, e.g. '94301'.
• addressCountry: billing address country.

The second argument tokenCallback is a callback you provide to handle responses from Stripe. It should send the token to your server for processing onSuccess, and notify the user onError.

Here's a sample implementation of the token callback:

stripe.createToken(
    card,
    new TokenCallback() {
        public void onSuccess(Token token) {                
            // Send token to your own web service
            MyServer.chargeToken(token);
        }
        public void onError(Exception error) {
            Toast.makeText(getContext(), 
                error.getLocalizedString(getContext()), 
                Toast.LENGTH_LONG).show();
        }
    }
);

createToken is an asynchronous call – it returns immediately and invokes the callback on the UI thread when it receives a response from Stripe's servers.

#Client-side validation helpers

The Card object allows you to validate user input before you send the information to Stripe.

##validateNumber

Checks that the number is formatted correctly and passes the Luhn check.

##validateExpiryDate

Checks whether or not the expiration date represents an actual month in the future.

##validateCVC

Checks whether or not the supplied number could be a valid verification code.

##validateCard

Convenience method to validate card number, expiry date and CVC.

#Retrieving information about a token

If you're implementing a complex workflow, you may want to know if you've already charged a token (since they can only be charged once). You can call requestToken with a token id and callbacks to find out whether or not the token has already been used. This will return an object with the same structure as the object returned from createToken.

stripe.requestToken(
    tokenID,
    new TokenCallback() {
        public void onSuccess(Token token) {                
            if (token.getUsed()) {
                Log.d("Token has already been charged.");
            }
        }
        public void onError(Exception error) {
            // handle error
        }
    });

#Building the example project

If you'd like to build the example Android project:

1. Clone the git repository.
2. Be sure you've installed the Android SDK with API Level 17 and android-support-v4
3. Import the example and stripe folders into Eclipse.
4. Replace the value of PUBLISHABLE_KEY in PaymentActivity with your stripe test key.
5. Build and run the project on your device or in the Android emulator.