Introduction​

This document provides knowledge in building the iOS app that accepts payment in iOS devices, with built-in support for Apple Pay.

If you want to build a mobile app like Lyft and enable people to make purchases directly in your app, our iOS libraries can help. The library also supports Apple Pay so that your users can make frictionless payments without having to enter in their credit card info.

Accepting payments in your app involves 3 steps:

1. Collecting credit card information from your customer
2. Converting the credit card information to a single-use token
3. Sending this token to your server to create a charge

Getting started​

Install the library​

Using CocoaPods​

We recommend using CocoaPods to install the Stripe iOS library since it makes it easy to keep your app’s dependencies up-to-date.

If you have not set up CocoaPods before, we recommend following the installation instructions on the CocoaPods site, then add pod ‘Stripe’ to your Podfile, and run pod install.

Note:
Use the .xcworkspace file to open your project in Xcode instead of the .xcodeproj file.

Using Carthage​

To use Carthage, simply add github “stripe/stripe-ios” to your Cartfile and follow the Carthage Installation instructions.

Using manual installation​

We publish our SDK as a static framework that you can copy directly into your app without any additional tools. To manually install the library, do the following:

1. Head to our releases page and downloads the framework that is right for you.
2. Unzip the file you downloaded.
3. In Xcode, with your project open, click File > Add files.
4. Select Stripe.framework in the directory you just unzipped.
5. Make sure Copy items if needed is checked.
6. Click Add.
7. In your project settings, go to the Build Settings tab, and under Other Linker Flags, make sure -ObjC is present.

Configure API keys​

First, configure Stripe with your published API key. We recommend doing this in your AppDelegate’s application:didFinishLaunchingWithOptions method so that it will be set for the entire lifecycle of your app.

Example in Swift​

// AppDelegate.swift

import Stripe

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?)
-> Bool {
        Stripe.setDefaultPublishableKey("pk_test_6pRNASCoBOKtIshFeQd4XMUh")
        return true
    }
}

Example in Objective-C​

// AppDelegate.m

#import "AppDelegate.h"
#import <Stripe/Stripe.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [Stripe setDefaultPublishableKey:@"pk_test_6pRNASCoBOKtIshFeQd4XMUh"];
    return YES;
}

@end

Note:
We have placed your test publishable API key as the StripePublishableKey constant in the above snippet. You will need to swap it out with your live publishable key in production. You can see all your API keys in your dashboard.

Collecting credit card information​

There are three ways to obtain payment details from the user:

1. Use the Apple Pay framework to access your users’ stored payment information.
2. Use our pre-built form component, STPPaymentCardTextField to collect new credit card details.
3. Build your own credit card form from scratch.

Since Apple Pay supports only certain credit cards on the latest iOS devices, we recommend using Apple Pay in combination with option 2 or option 3 as a fallback on devices where Apple Pay is not available.

Using Apple Pay​

With Apple Pay, you are able to access payment information stored on your customer’ iOS devices.

After setting up the merchant ID, you need to generate a PKPaymentRequest to submit to Apple. We have provided a convenient method to generate one with reasonable defaults. All you need to do is set the paymentSummaryItems property to an array of PKPaymentSummaryItems . These are analogous to line items on a receipt and are used to explain your charge to the user. For more details, see the PKPaymentRequest documentation.

Now that you have created the request, the next step is to query the device to see if Apple Pay is available; that is, if your app is running on the latest hardware and the user has added a valid credit card. YOUR_APPLE_MERCHANT_ID is an identifier that you obtain directly from Apple. If Apple Pay is available, you should create and display the payment request view controller. To do so, follow the below code:

Example in Swift​

// ViewController.swift

guard let request = Stripe.paymentRequestWithMerchantIdentifier("YOUR_APPLE_MERCHANT_ID") else {
    // request will be nil if running on < iOS8
    return
}
request.paymentSummaryItems = [
    PKPaymentSummaryItem(label: "Premium Llama Food", amount: 10.0)
]

if (Stripe.canSubmitPaymentRequest(request)) {
    let paymentController = PKPaymentAuthorizationViewController(paymentRequest: request)
    presentViewController(paymentController, animated: true, completion: nil)
} else {
    // Show the user your own credit card form (see options 2 or 3)

}

Example in Objective-C​

// ViewController.m

PKPaymentRequest *request = [Stripe paymentRequestWithMerchantIdentifier:"YOUR_APPLE_MERCHANT_ID"];
NSString *label = @"Premium Llama Food";
NSDecimalNumber *amount = [NSDecimalNumber decimalNumberWithString:@"10.00"];
request.paymentSummaryItems = @[
[PKPaymentSummaryItem summaryItemWithLabel:label
                                    amount:amount]
];

if ([Stripe canSubmitPaymentRequest:request]) {
    PKPaymentAuthorizationViewController *paymentController;
    paymentController = [[PKPaymentAuthorizationViewController alloc] initWithPaymentRequest:paymentRequest];
    paymentController.delegate = self;
    [self presentViewController:paymentController animated:YES completion:nil];

} else {
// Show the user your own credit card form (see options 2 or 3)
}

Note that ViewController is a PKPaymentAuthorizationViewControllerDelegate. By implementing this protocol, the PKPayment is handled to return the authorization controller.

Example in Swift​

// ViewController.swift

func paymentAuthorizationViewController(controller: PKPaymentAuthorizationViewController, didAuthorizePayment payment:
PKPayment, completion: (PKPaymentAuthorizationStatus) -> Void) {
/*
We'll implement this method below in 'Creating a single-use token'.
Note that we've also been given a block that takes a PKPaymentAuthorizationStatus. 
We'll call this function with either PKPaymentAuthorizationStatusSuccess or PKPaymentAuthorizationStatusFailure
after all of our asynchronous code is finished executing. 
This is how the PKPaymentAuthorizationViewController knows when and how to update its UI.
*/
handlePaymentAuthorizationWithPayment(payment, completi
on: nil)
}

func paymentAuthorizationViewControllerDidFinish(controller: PKPaymentAuthorizationViewController) {
    dismissViewControllerAnimated(true, completion: nil)
}

Example in Objective-C​

// ViewController.m

- (void)paymentAuthorizationViewController:(PKPaymentAuthorizationViewController *)controller
                       didAuthorizePayment:(PKPayment *)payment
                                completion:(void (^)(PKPaymentAuthorizationStatus))completion {
/*
We'll implement this method below in 'Creating a single-use token'.
Note that we've also been given a block that takes a PKPaymentAuthorizationStatus. 
We'll call this function with either PKPaymentAuthorizationStatusSuccess or PKPaymentAuthorizationStatusFailure
after all of our asynchronous code is finished executing. 
This is how the PKPaymentAuthorizationViewController knows when and how to update its UI.
*/
[self handlePaymentAuthorizationWithPayment:payment completion:completion];
}

- (void)paymentAuthorizationViewControllerDidFinish:(PKPaymentAuthorizationViewController *)controller {
[self dismissViewControllerAnimated:YES completion:nil]
;
}

To implement optional PKPaymentAuthorizationViewControllerDelegate methods for customer events (such as, to recalculate shipping costs based on user selection, see the PKPaymentAuthorizationViewController documentation.

Important:
Before doing the next step, make sure the controller has returned with a PKPayment.

Using STPPPaymentCardTextField​

To use our pre-built form component, you need to create a view controller called PaymentViewController and add an STPPaymentCardTextField property to it.

Example in Swift​

// PaymentViewController.swift

class PaymentViewController: UIViewController, STPPaymentCardTextFieldDelegate {
    let paymentTextField = STPPaymentCardTextField()
}

Example in Objective-C
// PaymentViewController.m

#import "PaymentViewController.h"

@interface PaymentViewController ()<STPPaymentCardTextField Delegate>
@property(nonatomic) STPPaymentCardTextField *paymentTextField;
@end

To instantiate the STPPaymentCardTextField, set the PaymentViewController as its STPPaymentCardTextFieldDelegate and add it to your view.

Example in Swift​

// PaymentViewController.swift

override func viewDidLoad() {
    super.viewDidLoad();
    paymentTextField.frame = CGRectMake(15, 15, CGRectGetWidth(self.view.frame) - 30, 44)
    paymentTextField.delegate = self
    view.addSubview(paymentTextField)
}

Example in Objective-C​

// PaymentViewController.m

- (void)viewDidLoad {
    [super viewDidLoad];
    self.paymentTextField = [[STPPaymentCardTextField alloc] initWithFrame:CGRectMake(15, 15, CGRectGetWidth(self.view.frame) - 30, 44)];
    self.paymentTextField.delegate = self;
    [self.view addSubview:self.paymentTextField];
}

By adding an STPPaymentCardTextField to the controller, your app is enabled to accept card numbers, expiration dates, and CVCs. It will also format the input and validate that input on-the-fly.

When a user enters text into this field, the paymentCardTextFieldidChange method will be called on our view controller. In this callback, we can enable a save button to allow users to submit their valid cards if the form is valid.

Example in Swift​

func paymentCardTextFieldDidChange(textField: STPPaymentCardTextField) {
    // Toggle navigation, for example
    saveButton.enabled = textField.isValid
}

Example in Objective-C​

- (void)paymentCardTextFieldDidChange:(STPPaymentCardTextField *)textField { {
    // Toggle navigation, for example
    self.saveButton.enabled = textField.isValid;
}

Building your own form​

To build your own form, make sure you will at least be able to collect your customer’s card numbers and expiration dates. We recommend you to also collect the CVC to prevent fraudulent. The user’s name and billing address are optional and would benefit you in terms of fraud protection.

Creating tokens​

Our libraries shoulder the burden of PCI compliance by helping you avoid the need to send card data directly to your server. Instead, our libraries send credit card directly to our servers where we can then convert them to tokens. You can charge these tokens later in your server-side code.

Using PKPayment (Apple Pay)​

After your PKPayment has arrived, you can turn it into a single-use Stripe token with a simple method call by using the following code.

Example in Swift​

// ViewController.swift

func handlePaymentAuthorizationWithPayment(payment: PKPayment, completion: PKPaymentAuthorizationStatus -> ()) {
    STPAPIClient.sharedClient().createTokenWithPayment(payment) { (token, error) -> Void in
        if error != nil {
            completion(PKPaymentAuthorizationStatus.Failure)
            return
        }
        /*
        We'll implement this below in "Sending the token to your server".
        Notice that we're passing the completion block through.
        See the above comment in didAuthorizePayment to learn why.
        */
        createBackendChargeWithToken(token, completion: completion)
    }
}

Example in Objective-C​

// ViewController.m

- (void)handlePaymentAuthorizationWithPayment:(PKPayment *) payment
                                   completion:(void (^)(PKPaymentAuthorizationStatus))completion {
    [[STPAPIClient sharedClient] createTokenWithPayment:payment
        completion:^(STPToken *token, NSError *error) {
            if (error) {
                completion(PKPaymentAuthorizationStatus Failure);
                return;
            }
            /*
            We'll implement this below in "Sending the token to your server".
            Notice that we're passing the completion block through.
            See the above comment in didAuthorizePayment to learn why.
            */
            [self createBackendChargeWithToken:token completion:completion];
        }];
}

Using STPCardParams​

If you choose to use STPPaymentCardTextField or your own form, you can assemble the data into an STPCardParams object. After you have collected the card number, expiration dates, and CVC, package them up in an STPCardParams object and invoke the createTokenWithCard method on the STPAIClient class, instructing the library to send off the credit card data to Stripe and return a token.

To do so, add the below code to your program.

Example in Swift​

@IBAction func save(sender: UIButton) {
    if let card = paymentTextField.card {
        STPAPIClient.sharedClient().createTokenWithCard(card) { (token, error) -> Void in
            if let error = error {
                handleError(error)
            }
            else if let token = token {
                createBackendChargeWithToken(token) { status in

                    ...
                }
            }
        }
    }
}

Example in Objective-C​

- (IBAction)save:(UIButton *)sender {
    [[STPAPIClient sharedClient]
        createTokenWithCard:self.paymentTextField.card completion:^(STPToken *token, NSError *error) {
            if (error) {
                [self handleError:error];
            } else {
                [self createBackendChargeWithToken:token completion:^(PKPaymentAuthorizationStatus status) {
                    ...
                }];
            }
    }];
}

Note:
In the example above, the createTokenWithCard is called when a save button is tapped. It is important that the createToken is not called before user has finished entering their card details.

It is up to you to handle error messages and show activity indicators while creating the token.

Sending the token to your server​

The block you gave to createToken in the previous steps is called whenever Stripe returns with a token (or error). To charge the card, you need to send the token off to your server.

Here is how it looks for a token created with Apple Pay.

Example in Swift​

// ViewController.swift

func createBackendChargeWithToken(token: STPToken, completion: PKPaymentAuthorizationStatus -> ()) {
    let url = NSURL(string: "https://example.com/token")!
    let request = NSMutableURLRequest(URL: url)
    request.HTTPMethod = "POST"
    let body = "stripeToken=(token.tokenId)"
    request.HTTPBody = body.dataUsingEncoding(NSUTF8StringEncoding)
    let configuration = NSURLSessionConfiguration.ephemeralSessionConfiguration()
    let session = NSURLSession(configuration: configuration)
    let task = session.dataTaskWithRequest(request) { (data, response, error) -> Void in
        if error != nil {
            completion(PKPaymentAuthorizationStatus.Failure)
        }
        else {
            completion(PKPaymentAuthorizationStatus.Success)
        }
    }
    task.resume()
}

Example in Objective-C​

// ViewController.m

- (void)createBackendChargeWithToken:(STPToken *)token
                          completion:(void (^)(PKPaymentAuthorizationStatus))completion {
    NSURL *url = [NSURL URLWithString:@"https://example.com /token"];
    NSMutableURLRequest *request = [[NSMutableURLRequest alloc] initWithURL:url];
    request.HTTPMethod = @"POST";
    NSString *body = [NSString stringWithFormat:@"stripeToken=%@", token.tokenId];
    request.HTTPBody = [body dataUsingEncoding:NSUTF8StringEncoding];
    NSURLSessionConfiguration *configuration = [NSURLSessionConfiguration defaultSessionConfiguration];
    NSURLSession *session = [NSURLSession sessionWithConfiguration:configuration];
    NSURLSessionDataTask *task =
    [session dataTaskWithRequest:request
        completionHandler:^(NSData *data,
                            NSURLResponse *response,
                            NSError *error) {
            if (error) {
                completion(PKPaymentAuthorizationStatusFailure);
            } else {
                completion(PKPaymentAuthorizationStatusSuccess);
            }
        }];
    [task resume];
}

Note:
The completion callback above is Apple Pay-specific. If you are not using Apple Pay, the code is still mostly the same, but you would want to implement custom error and success handling.

On the server, implement an endpoint that will accept the stripeToken parameter. Make sure any communication with your server is SSL-secured to prevent eavesdropping.

After you have a Stripe token representing a card on your server, charge it, save it for charging later, or sign up for a subscription.

For more details, see the full example application.

Introduction​

This documentation provides knowledge in developing Stripe mobile payment inside any Android app. If you need help or have any questions after reading this documentation, we recommend you to check out our answers for common Android questions or contact other developers in #stripe on freenode.

Stripe has created a Java library for Android, allowing you to easily submit payments from an Android app. Our library eliminates the need to send card data directly to your server. Instead, it sends the card data directly to our servers, where we can convert them to tokens.

Your app will receive the token back, and will then be able to send the token to an endpoint on your server, where it can be used to process a payment, establish recurring billing, or merely saved for later use.

Stripe supports Android back to version 4 (Ice Cream Sandwich), and the library has no external dependencies.

Installation​

There is a difference in installing the Stripe Android library depending on whether you use Android Studio or Eclipse.

For Android Studio, add the following code to your app's build.gradle file, inside the dependencies section:

compile 'com.stripe:stripe-android:+'

For Eclipse, follow these steps:

1. Download the Stripe-Android libraries.
2. Be sure you have installed the Android SDK with a minimum of 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.

Collecting credit card information​

At some point in the flow of your app, you will want to obtain payment details from the user. There are 2 ways to do this: • Use Android Pay to access your customer's stored card information • Build your own credit card form

We recommend you to write your app to offer support for both.

Using Android Pay​

Through Android Pay, you can access payment information stored in your customer's Google accounts. Following are the instructions to integrate your app with Android Pay.

Note: When this documentation was released, Android Pay was still in Beta Version.

Setting up your app​

First, you will need to obtain credentials and a client ID for your app, as explained in the Android Pay API Tutorial. You will also need to set up the latest version of Google Play services.

Collecting payment info via Android Pay​

To use Android Pay in your app, first enable the Android Pay API by adding the following code to the <application> tag of your AndroidManifest.xml:

<application
  ...
  <meta-data
    android:name="com.google.android.gms.wallet.api.enabled"
    android:value="true" />
</application>

In the activity's layout, your application will also need a SupportWalletFragment (the placeholder for the Android Pay purchase button). To create this, add the following code to your program:

<!-- You will need to add the wallet namespace to your enclosing Layout -->
xmlns:wallet="http://schemas.android.com/apk/res-auto"

<fragment
  android:id="@+id/wallet_fragment"
  android:name="com.google.android.gms.wallet.fragment.SupportWalletFragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  wallet:environment="test"
  wallet:fragmentMode="buyButton"/>

After placing the fragment, you need to:

1. Grab a reference to that fragment
2. Create a MaskWalletRequest
3. Initialize the fragment

In the MaskWalletRequest, you are able to specify the amount to charge and what additional information you would like to collect (e.g., the shipping address). This is also where you can specify that you are using Stripe as the processor. Doing so will allow the application to request a Stripe token directly from the wallet.

Before starting the Android Pay flow, use the isReadyToPay() method to check whether the user has the Android Pay app installed and is ready to pay through it. Make sure you have already mastered Google's documentation for information on their UI and branding requirements.

The following code is the Android Pay flow:

public class PaymentActivity extends FragmentActivity implements GoogleApiClient.ConnectionCallbacks,
    GoogleApiClient.OnConnectionFailedListener {

  // You will need to use your live API key even while testing
  public static final String PUBLISHABLE_KEY = "pk_live_XXX";

  // Unique identifiers for asynchronous requests:
  private static final int LOAD_MASKED_WALLET_REQUEST_CODE = 1000;
  private static final int LOAD_FULL_WALLET_REQUEST_CODE = 1001;
  private SupportWalletFragment walletFragment;

  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    Wallet.Payments.isReadyToPay(googleApiClient).setResultCallback(
      new ResultCallback<BooleanResult>() {
        @Override
        public void onResult(@NonNull BooleanResult booleanResult) {
          if (booleanResult.getStatus().isSuccess()) {
            if (booleanResult.getValue()) {
              showAndroidPay();
            } else {
              // Hide Android Pay buttons, show a message that Android Pay
              // cannot be used yet, and display a traditional checkout button
            }
          } else {
            // Error making isReadyToPay call
            Log.e(TAG, "isReadyToPay:" + booleanResult.getStatus());
          }
        }
      });
    ...
  }

  public void showAndroidPay() {
    setContentView(R.layout.payment_activity);
    walletFragment = (SupportWalletFragment) getSupportFragmentManager()
      .findFragmentById(R.id.wallet_fragment);

    MaskedWalletRequest maskedWalletRequest = MaskedWalletRequest.newBuilder()
      // Request credit card tokenization with Stripe:
      .setPaymentMethodTokenizationParameters(
        PaymentMethodTokenizationParameters.newBuilder()
          .setPaymentMethodTokenizationType(PaymentMethodTokenizationType.PAYMENT_GATEWAY)
          .addParameter("gateway", "stripe")
          .addParameter("stripe:publishableKey", PUBLISHABLE_KEY)
          .addParameter("stripe:version", com.stripe.Stripe.VERSION)
          .build())
      .setShippingAddressRequired(true)
      .setEstimatedTotalPrice("20.00")
      .setCurrencyCode("USD")
      .build();

    WalletFragmentInitParams initParams = WalletFragmentInitParams.newBuilder()
      .setMaskedWalletRequest(maskedWalletRequest)
      .setMaskedWalletRequestCode(LOAD_MASKED_WALLET_REQUEST_CODE)
      .build();

    walletFragment.initialize(initParams);
    ...
  }

  public void onStart() { ... }
  public void onStop()  { ... }

  @Override
  protected void onActivityResult(int requestCode, int resultCode, Intent data) { ... }
  @Override public void onConnectionFailed(ConnectionResult connectionResult) {}
  @Override public void onConnected(Bundle bundle) {}
  @Override public void onConnectionSuspended(int i) {}
}

Note:
The price set within the Android app is written as a decimal and is for the Android app only. The token received back will be sent to your server, and the charge request will be made of the Stripe API from there. The actual amount to be charged is requested at that point, and is set as an integer.

The last step of the Android Pay setup process for the app is to connect to the Google Wallet API. This connection handles the case when a user presses the Android Pay purchase button and the payment is processed. To do so, add the following code:

public class PaymentActivity extends FragmentActivity {
  ...
  private GoogleApiClient googleApiClient;

  public void onCreate(Bundle savedInstanceState) {
    ...
    googleApiClient = new GoogleApiClient.Builder(this)
      .addConnectionCallbacks(this)
      .addOnConnectionFailedListener(this)
      .addApi(Wallet.API, new Wallet.WalletOptions.Builder()
        .setEnvironment(WalletConstants.ENVIRONMENT_TEST)
        .setTheme(WalletConstants.THEME_LIGHT)
        .build())
      .build();
  }

  public void onStart() {
    super.onStart();
    googleApiClient.connect();
  }

  public void onStop() {
    super.onStop();
    googleApiClient.disconnect();
  }
}

Once your customer confirms their purchase, the application then needs to create a FullWalletRequest. This will allow the application to request access to the customer's FullWallet, which is where the payment information comes from. To do this, implement onActivityResult:

public class PaymentActivity extends FragmentActivity {
  ...
  @Override
  protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);

    if (requestCode == LOAD_MASKED_WALLET_REQUEST_CODE) {
      if (resultCode == Activity.RESULT_OK) {
        MaskedWallet maskedWallet = data.getParcelableExtra(WalletConstants.EXTRA_MASKED_WALLET);
        FullWalletRequest fullWalletRequest = FullWalletRequest.newBuilder()
          .setCart(Cart.newBuilder()
            .setCurrencyCode("USD")
            .setTotalPrice("20.00")
            .addLineItem(LineItem.newBuilder()
              .setCurrencyCode("USD")
              .setQuantity("1")
              .setDescription("Premium Llama Food")
              .setTotalPrice("20.00")
              .setUnitPrice("20.00")
              .build())
            .build())
          .setGoogleTransactionId(maskedWallet.getGoogleTransactionId())
          .build();
        Wallet.Payments.loadFullWallet(googleApiClient, fullWalletRequest, LOAD_FULL_WALLET_REQUEST_CODE);
      }
    } else if (requestCode == LOAD_FULL_WALLET_REQUEST_CODE) {
      ...
    }
  }
}

Note:
The above example has only one item, but if your customer is purchasing multiple items, you can add multiple items by calling addLineItem additional times.

Creating tokens from Android Pay​

Once your customer allows access to their wallet for payment, the application will be given back a Stripe token. You will then send this token to your server for use through the API.

public class PaymentActivity extends FragmentActivity {
  ...
  // Keep track of your current environment.
  // Change to WalletConstants.ENVIRONMENT_PRODUCTION when ready to go live.
  public static final int mEnvironment = WalletConstants.ENVIRONMENT_TEST;

  @Override
  protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == LOAD_MASKED_WALLET_REQUEST_CODE) {
      ...
    } else if (requestCode == LOAD_FULL_WALLET_REQUEST_CODE) {
      if (resultCode == Activity.RESULT_OK) {
        FullWallet fullWallet = data.getParcelableExtra(WalletConstants.EXTRA_FULL_WALLET);
        String tokenJSON = fullWallet.getPaymentMethodToken().getToken();
        // A token will only be returned in production mode,
        // i.e. WalletConstants.ENVIRONMENT_PRODUCTION
        if (mEnvironment == WalletConstants.ENVIRONMENT_PRODUCTION) {
          com.stripe.model.Token token = com.stripe.model.Token.GSON.fromJson(
            tokenJSON, com.stripe.model.Token.class);
          // TODO: send token to your server
        }
      }
    } else {
      super.onActivityResult(requestCode, resultCode, data);
    }
  }
}

Testing and deploying with Android Pay​

To test your Android Pay flow, use your live Stripe API key, not your test key, in conjunction with the Android Pay test environment, specified by WalletConstants.ENVIRONMENT_TEST.

In test mode, fullWallet.getPaymentMethodToken().getToken() will return the string "TEST_GATEWAY_TOKEN" in place of a JSON string representing a token.

If you want to test your application on a physical device, make sure the device supports NFC. You will also need to add a supported credit card to your Android Pay account.

When you are ready, you can get production access to Android Pay by submitting your APK to Google for review.

Building your own form​

If you plan to build your own form, make sure you will at least be able to collect your customer's card numbers and expiration dates. We recommend you to also collect the CVC to prevent fraud. The user's name and billing address are optional and would benefit you in terms of fraud protection.

Once you have collected a customer's information, you will need to exchange the information for a Stripe token.

Creating and validating cards from customer form​

The first step is to import the Stripe classes before using them:

import com.stripe.android.*;

There are two main classes: Card and Stripe. The Card class contains many useful helpers for validating card input on the client-side before a charge is created.

To construct a Card instance with your customer's payment information, add the following code to your program:

Card card = new Card(
  cardNumber,
  cardExpMonth,
  cardExpYear,
  cardCVC
);
card.validateNumber();
card.validateCVC();

In the above example, the Card instance contains helpers to validate that: • the card number passes the Luhn check • the expiration date is in the future • the CVC looks valid

You will probably want to validate these three things at once, so we have included a validateCard function that does so:

Card card = new Card("4242-4242-4242-4242", 12, 2017, "123");
if ( !card.validateCard() ) {
  // Show errors
}

Creating tokens from a customer form​

The next step is to pass off that sensitive payment information securely to Stripe, where you will exchange it for a token.

You can create tokens using the Stripe instance method createToken, passing in a Card instance and completion callbacks. An asynchronous network request will be executed, and the appropriate callback invoked when it completes.

Card card = new Card("4242424242424242", 12, 2017, "123");
Stripe stripe = new Stripe("pk_test_6pRNASCoBOKtIshFeQd4XMUh");

stripe.createToken(
  card,
  new TokenCallback() {
    public void onSuccess(Token token) {
      // Send token to your server
    }
    public void onError(Exception error) {
      // Show localized error message
      Toast.makeText(getContext(),
        error.getLocalizedString(getContext()),
        Toast.LENGTH_LONG
      ).show();
    }
  }
);

We have placed your test publishable API key as the first argument to Stripe. You will need to swap it out with your live publishable key in production. You can see all your keys after logging into your Stripe dashboard.

Using Tokens​

Using the payment token requires an API call from your server using your secret API key. For security purposes, you should never embed your secret API key in your app.

To do so, you need to set up an endpoint on your server that can receive an HTTP POST call for the token. In the onActivityResult method or the onSuccess callback, you will need to POST the supplied token to your server. Make sure any communication with your server is SSL secured to prevent eavesdropping.

For a full example, see the Stripe Android example on GitHub.

Introduction​

The Stripe customers API is organized around REST. It has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. It uses built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. It supports cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code).

To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no “switch” for changing between modes, just use the appropriate key to perform a live or test transaction. Requests made with test mode credentials never hit the banking networks and incur no cost.

Customers​

Customer objects allow you to perform recurring charges and track multiple charges that are associated with the same customer. The API allows you to create, delete, and update your customers. You can retrieve individual customers as well as list of all your customers.

The customer object​

The following are the attributes in this feature.

customer-shipping​

The following is the customer-shipping object's child attribute.

customer-shipping-address​

The following are the customer-shipping-address object's attributes.

customer-sources​

The following are the customer-sources object's child attributes.

customer-subscriptions​

The following are the customer-subscriptions object's child attributes.

The following is an example response:

com.stripe.model.Customer JSON: {
  "id": "cus_8JMTaIcum1p34N", 
  "object": "customer", 
  "account_balance": 0, 
  "business_vat_id": null, 
  "created": 1461252581, 
  "currency": "usd", 
  "default_source": "card_182jjK2eZvKYlo2CHJmfmQ93", "delinquent": false, 
  "description": "Mia Anderson", 
  "discount": null, 
  "email": "mia.anderson.34@example.com", "livemode": false, 
  "metadata": { 
  }, 
  "shipping": null, 
  "sources": { 
    "object": "list", 
    "data": [ 
      { 
        "id": "card_182jjK2eZvKYlo2CHJmfmQ93", "object": "card", 
        "address_city": null, 
        "address_country": null, 
        "address_line1": null, 
        "address_line1_check": null, 
        "address_line2": null, 
        "address_state": null, 
        "address_zip": null,
        "address_zip_check": null, 
        "brand": "Visa", 
        "country": "US", 
        "customer": "cus_8JMTaIcum1p34N", 
        "cvc_check": "pass", 
        "dynamic_last4": null, 
        "exp_month": 12, 
        "exp_year": 2017, 
        "funding": "credit", 
        "last4": "4242", 
        "metadata": { 
        }, 
        "name": null, 
        "tokenization_method": null 
      } 
    ], 
    "has_more": false, 
    "total_count": 1, 
    "url": "/v1/customers/cus_8JMTaIcum1p34N/sources" }, 
    "subscriptions": { 
      "object": "list", 
      "data": [ 
        { 
          "id": "sub_8JMVP3u5AvUoKd", 
          "object": "subscription", 
          "application_fee_percent": null, 
          "cancel_at_period_end": false,
          "canceled_at": null, 
          "current_period_end": 1463844717, 
          "current_period_start": 1461252717, 
          "customer": "cus_8JMTaIcum1p34N", 
          "discount": null, 
          "ended_at": null, 
          "metadata": { 
          }, 
          "plan": { 
            "id": "titanium-expert-948", "object": "plan", 
            "amount": 999, 
            "created": 1461252658, 
            "currency": "usd", 
            "interval": "month", 
            "interval_count": 1, 
            "livemode": false, 
            "metadata": { 
            }, 
            "name": "Titanium Expert", 
            "statement_descriptor": null, 
            "trial_period_days": null 
          }, 
          "quantity": 1, 
          "start": 1461252717, 
          "status": "active", 
          "tax_percent": null, 
          "trial_end": null,
          "trial_start": null 
        } 
      ], 
      "has_more": false, 
      "total_count": 1, 
      "url": "/v1/customers/cus_8JMTaIcum1p34N/subscriptions"
    } 
  }

Create a customer​

Creates a new customer object. To do so, add Customer.create(); to your program.

The following are the optional arguments in this feature.

create-shipping​

The following are the shipping object's child arguments.

create-shipping-address​

The following are the create-shipping-address object's child arguments.

create-source​

The following are the create-source object's child arguments.

The following is an example request:

Stripe.apiKey = "test_BQokikJOvBiI2HlWgH4olfQ2"; 

Map<String, Object> customerParams = new HashMap<String, Object>(); 
customerParams.put("description", "Customer for test@example.com");
customerParams.put("source", "tok_182ied2eZvKYlo2CDbFVWcMM"); // obtained with Stripe.js 

Customer.create(customerParams); 

Returns​

Returns a customer object if the call succeeded. The returned object will have information about subscriptions, discount, and payment sources, if that information has been provided. If an invoice payment is due and a source is not provided, the call will raise an error. If a non-existent plan or a non-existent or expired coupon is provided, the call will raise an error.

If a source has been attached to the customer, the returned customer object will have a default_source attribute, which is an ID that can be expanded into the full source details when retrieving the customer.

The following is an example response:

com.stripe.model.Customer JSON: { 
  "id": "cus_8JNNkDAKVZ23vZ", 
  "object": "customer", 
  "account_balance": 0, 
  "business_vat_id": null, 
  "created": 1461255958, 
  "currency": "usd", 
  "default_source": null,
  "delinquent": false, 
  "description": "test papirus (test@n206papirus.net)", "discount": null, 
  "email": "test@n206papirus.net", 
  "livemode": false, 
  "metadata": { 
  }, 
  "shipping": null, 
  "sources": { 
    "object": "list", 
    "data": [ 
    ], 
    "has_more": false, 
    "total_count": 0, 
    "url": "/v1/customers/cus_8JNNkDAKVZ23vZ/sources"
  }, 
  "subscriptions": { 
    "object": "list", 
    "data": [ 
    ], 
    "has_more": false, 
    "total_count": 0, 
    "url": "/v1/customers/cus_8JNNkDAKVZ23vZ/subscriptions" } 
  }

Retrieve a customer​

Retrieves the details of an existing customer. You need only supply the unique customer identifier that was returned upon customer creation.

The following is an example request:

Stripe.apiKey = "test_BQokikJOvBiI2HlWgH4olfQ2"; 

Customer.retrieve("cus_8JNO6XkCpsjc7s"); 

Returns​

Returns a customer object if a valid identifier was provided. When requesting the ID of a customer that has been deleted, a subset of the customer’s information will be returned, including a deleted property, which will be true.

The following is an example response:

com.stripe.model.Customer JSON: { 
  "id": "cus_8JNO6XkCpsjc7s", 
  "object": "customer", 
  "account_balance": 0, 
  "business_vat_id": null, 
  "created": 1461256039,
  "currency": "usd", 
  "default_source": "card_182keA2eZvKYlo2CGbcuGkIT", 
  "delinquent": false, 
  "description": null, 
  "discount": null, 
  "email": "sbvmqa+gwenna@gmail.com", 
  "livemode": false, 
  "metadata": { 
  }, 
  "shipping": null, 
  "sources": { 
    "object": "list", 
    "data": [ 
      { 
        "id": "card_182keA2eZvKYlo2CGbcuGkIT", "object": "card", 
        "address_city": null, 
        "address_country": null, 
        "address_line1": null, 
        "address_line1_check": null, 
        "address_line2": null, 
        "address_state": null, 
        "address_zip": null, 
        "address_zip_check": null, 
        "brand": "Visa", 
        "country": "US", 
        "customer": "cus_8JNO6XkCpsjc7s", 
        "cvc_check": "pass",
        "dynamic_last4": null, 
        "exp_month": 12, 
        "exp_year": 2019, 
        "funding": "credit", 
        "last4": "4242", 
        "metadata": { 
        }, 
        "name": null, 
        "tokenization_method": null 
      } 
    ], 
    "has_more": false, 
    "total_count": 1, 
    "url": "/v1/customers/cus_8JNO6XkCpsjc7s/sources" }, 
    "subscriptions": { 
      "object": "list", 
      "data": [ 
      ], 
      "has_more": false, 
      "total_count": 0, 
      "url": "/v1/customers/cus_8JNO6XkCpsjc7s/subscriptions"
    } 
  }

Update a customer​

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the source parameter, that becomes the customer’s active source (e.g., a card) to be used for all charges in the future.

When you update a customer to a new valid source: for each of the customer’s current subscriptions, if the subscription is in the past_due state, then the latest unpaid, unclosed invoice for the subscription will be retried (note that this retry will not count as an automatic retry, and will not affect the next regularly scheduled payment for the invoice. Note also that no invoices pertaining to subscriptions in the unpaid state, or invoices pertaining to canceled subscriptions, will be retried as a result of updating the customer’s source.)

This request accepts mostly the same arguments as the customer creation call.

To do so, add the following code to your program:

Customer cu = Customer.retrieve({CUSTOMER_ID}); 
Map<String, Object> updateParams = new HashMap<String, Object>(); 
updateParams.put("description", {NEW_DESCRIPTION}); 
... 
cu.update(updateParams); 

The following are the optional arguments in this feature.

update-shipping​

The following are the update-shipping child arguments.

update-shipping-address​

The following are the update-shipping-address object's child arguments.

update-source​

The following are the update-source object's child arguments.

The following is an example request:

Stripe.apiKey = "test_BQokikJOvBiI2HlWgH4olfQ2"; 
Customer cu = Customer.retrieve("cus_8JNceg1cXYpZwJ"); 
Map<String, Object> updateParams = new HashMap<String, Object>(); 
updateParams.put("description", "Customer for test@example.com");

cu.update(updateParams);

Returns​

Returns the customer object if the update succeeded. Throws an error if update parameters are invalid (e.g. specifying an invalid coupon or an invalid source).

The following is an example response:

com.stripe.model.Customer JSON: { 
  "id": "cus_8JNceg1cXYpZwJ", 
  "object": "customer", 
  "account_balance": 0, 
  "business_vat_id": null, 
  "created": 1461256854, 
  "currency": "usd",
  "default_source": "card_182krH2eZvKYlo2CyXuVSi02", "delinquent": false, 
  "description": "Customer for test@example.com", "discount": null, 
  "email": "aheaven87@gmail.com", 
  "livemode": false, 
  "metadata": { 
  }, 
  "shipping": null, 
  "sources": { 
  "object": "list", 
  "data": [ 
    { 
      "id": "card_182krH2eZvKYlo2CyXuVSi02", "object": "card", 
      "address_city": null, 
      "address_country": null, 
      "address_line1": null, 
      "address_line1_check": null, 
      "address_line2": null, 
      "address_state": null, 
      "address_zip": null, 
      "address_zip_check": null, 
      "brand": "Visa", 
      "country": "US", 
      "customer": "cus_8JNceg1cXYpZwJ", 
      "cvc_check": "pass", 
      "dynamic_last4": null,
      "exp_month": 1, 
      "exp_year": 2017, 
      "funding": "credit", 
      "last4": "4242", 
      "metadata": { 
      }, 
      "name": null, 
      "tokenization_method": null 
    } 
  ], 
  "has_more": false, 
  "total_count": 1, 
  "url": "/v1/customers/cus_8JNceg1cXYpZwJ/sources"
}, 
"subscriptions": { 
"object": "list", 
"data": [ 
{ 
  "id": "sub_8JNeptwCu8Zddh", 
  "object": "subscription", 
  "application_fee_percent": null, 
  "cancel_at_period_end": false, 
  "canceled_at": null, 
  "current_period_end": 1463848953, 
  "current_period_start": 1461256953, 
  "customer": "cus_8JNceg1cXYpZwJ", 
  "discount": null, 
  "ended_at": null,
  "metadata": { 
  }, 
  "plan": { 
    "id": "ern-monthly", 
    "object": "plan", 
    "amount": 2499, 
    "created": 1461244184, 
    "currency": "usd", 
    "interval": "month", 
    "interval_count": 1, 
    "livemode": false, 
    "metadata": { 
      "plan_id": "2" 
    }, 
    "name": "Monthly Subscription", 
    "statement_descriptor": null, 
    "trial_period_days": null 
  },
  "quantity": 1, 
  "start": 1461256953, 
  "status": "active", 
  "tax_percent": null, 
  "trial_end": null, 
  "trial_start": null 
}, 
{ 
  "id": "sub_8JNdYGbwDkccbh", 
  "object": "subscription",
  "application_fee_percent": null, 
  "cancel_at_period_end": false, 
  "canceled_at": null, 
  "current_period_end": 1463848903, 
  "current_period_start": 1461256903, 
  "customer": "cus_8JNceg1cXYpZwJ", 
  "discount": null, 
  "ended_at": null, 
  "metadata": { 
  }, 
  "plan": { 
    "id": "ern-monthly", 
    "object": "plan", 
    "amount": 2499, 
    "created": 1461244184, 
    "currency": "usd", 
    "interval": "month", 
    "interval_count": 1, 
    "livemode": false, 
    "metadata": { 
      "plan_id": "2" 
    }, 
    "name": "Monthly Subscription", 
    "statement_descriptor": null, 
    "trial_period_days": null 
  }, 
  "quantity": 1, 
  "start": 1461256903,
  "status": "active", 
  "tax_percent": null, 
  "trial_end": null, 
  "trial_start": null 
}, 
{ 
  "id": "sub_8JNcIPeX5FZHLi", 
  "object": "subscription", 
  "application_fee_percent": null, 
  "cancel_at_period_end": false, 
  "canceled_at": null, 
  "current_period_end": 1463848878, 
  "current_period_start": 1461256878, 
  "customer": "cus_8JNceg1cXYpZwJ", 
  "discount": null, 
  "ended_at": null, 
  "metadata": { 
  }, 
  "plan": { 
    "id": "ern-monthly", 
    "object": "plan", 
    "amount": 2499, 
    "created": 1461244184, 
    "currency": "usd", 
    "interval": "month", 
    "interval_count": 1, 
    "livemode": false, 
    "metadata": {
      "plan_id": "2" 
    }, 
    "name": "Monthly Subscription", 
    "statement_descriptor": null, 
    "trial_period_days": null 
  }, 
  "quantity": 1, 
  "start": 1461256878, 
  "status": "active", 
  "tax_percent": null, 
  "trial_end": null, 
  "trial_start": null 
} 
], 
"has_more": false, 
"total_count": 3, 
"url": "/v1/customers/cus_8JNceg1cXYpZwJ/subscriptions" } 
} 

Delete a customer​

Permanently deletes a customer. It cannot be undone. Also immediately cancels any active subscriptions on the customer.

To do so, add the following code to your program:

Customer cu = Customer.retrieve({CUSTOMER_ID}); 
cu.delete(); 

The following is an example request:

Stripe.apiKey = "test_BQokikJOvBiI2HlWgH4olfQ2"; 

Customer cu = Customer.retrieve("cus_8JNmQG7nBfcoHK"); cu.delete(); 

Returns​

Returns an object with a deleted parameter on success. If the customer ID does not exist, this call raises an error.

Unlike other objects, deleted customers can still be retrieved through the API, in order to be able to track the history of customers while still removing their credit card details and preventing any further operations to be performed (such as adding a new subscription).

The following is an example response:

com.stripe.model.Object JSON: { 
  "deleted": true, 
  "id": "cus_8JNshRXjBWnJdM" 
}

List all customers​

Returns a list of your customers. The customers are returned sorted by creation date, with the most recent customers appearing first.

To do so, add Customer.all(Map<String, Object> options); to your program.

The following are the optional arguments in this feature.

list-created​

The following are the list-created object's optional timestamp child arguments.

The following is an example request:

Stripe.apiKey = "test_BQokikJOvBiI2HlWgH4olfQ2"; 

Map<String, Object> customerParams = new HashMap<String, Object>(); 
customerParams.put("limit", 3); 

Customer.all(customerParams); 

Returns​

A dictionary with a data property that contains an array of up to limit customers, starting after customer starting_after. Each entry in the array is a separate customer object. If no more customers are available, the resulting array will be empty. This request should never raise an error.

You can optionally request that the response include the total count of all customers that match your filters. To do so, specify include[]=total_count in your request.

The following is an example response:

#<com.stripe.model.CustomerCollection id=#> JSON: { 
  "data": [ 
    com.stripe.model.Customer JSON: { 
      "id": "cus_8JO0w4XG8QrzSx", 
      "object": "customer", 
      "account_balance": 0, 
      "business_vat_id": null, 
      "created": 1461258315, 
      "currency": "usd", 
      "default_source": "card_182lEt2eZvKYlo2CpBNb7MFy", "delinquent": false, 
      "description": null, 
      "discount": null, 
      "email": null, 
      "livemode": false, 
      "metadata": { 
      }, 
      "shipping": null, 
      "sources": { 
        "object": "list", 
        "data": [ 
          { 
            "id": "card_182lEt2eZvKYlo2CpBNb7MFy",
            "object": "card", 
            "address_city": null, 
            "address_country": null, 
            "address_line1": null, 
            "address_line1_check": null, 
            "address_line2": null, 
            "address_state": null, 
            "address_zip": null, 
            "address_zip_check": null, 
            "brand": "Visa", 
            "country": "US", 
            "customer": "cus_8JO0w4XG8QrzSx", 
            "cvc_check": "pass", 
            "dynamic_last4": null, 
            "exp_month": 7, 
            "exp_year": 2017, 
            "funding": "unknown", 
            "last4": "1111", 
            "metadata": { 
            }, 
            "name": null, 
            "tokenization_method": null 
          } 
        ], 
        "has_more": false, 
        "total_count": 1, 
        "url": "/v1/customers/cus_8JO0w4XG8QrzSx/sources" },
        "subscriptions": { 
        "object": "list", 
        "data": [ 
        ], 
        "has_more": false, 
        "total_count": 0, 
        "url": "/v1/customers/cus_8JO0w4XG8QrzSx/subscriptions" 
      } 
    }, 
    #<com.stripe.model.Customer[...] ...>, 
    #<com.stripe.model.Customer[...] ...> 
  ], 
  "has_more": false 
}