iOS Integration

Accept payments in iPhone and iPad apps, with built-in support for Apple Pay.

If you want to build a mobile app like Lyft or Fancy 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, which we'll cover in this guide:

  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

Step 1: 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 haven't set up Cocoapods before, their site has installation instructions. Then, add pod 'Stripe' to your Podfile, and run pod install.

(Don't forget to use the .xcworkspace file to open your project in Xcode, instead of the .xcodeproj file, from here on out.)

Using Carthage

We also support installing our SDK using Carthage. You can simply add github "stripe/stripe-ios" to your Cartfile, and follow the Carthage installation instructions.

Manual installation

We also publish our SDK as a static framework that you can copy directly into your app without any additional tools:

  1. Head to our releases page and download the framework that's right for you.
  2. Unzip the file you downloaded.
  3. In Xcode, with your project open, click on 'File' then 'Add files to "Project"...'.
  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 make sure -ObjC is present under "Other Linker Flags".

Step 2: Configure API keys

First, you'll want to configure Stripe with your publishable API key. We recommend doing this in your AppDelegate's application:didFinishLaunchingWithOptions: method so that it'll be set for the entire lifecycle of your app.

We've placed your test publishable API key as the StripePublishableKey constant in the above snippet. You'll 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

At some point in the flow of your app, you'll want to obtain payment details from the user. There are three ways to do this. You can (in increasing order of complexity):

  1. Use 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

Apple Pay only supports certain US 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'll be able to access payment information stored on your customers' iOS devices.

Important note before starting

In order to use Apple Pay, you'll need to add the "Apple Pay" capability to your app in Xcode. This requires creating a merchant ID with Apple first, as explained in this tutorial.

After you're set up, you'll need to generate a PKPaymentRequest to submit to Apple. We've provided a convenience method to generate one with reasonable defaults. You'll need to 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 a more in-depth reference, see the PKPaymentRequest documentation.

After you create the request, query the device to see if Apple Pay is available (i.e. 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, as explained in this tutorial. If Apple Pay is available, you should create and display the payment request view controller.

You may have noticed that ViewController is a PKPaymentAuthorizationViewControllerDelegate. You'll handle the PKPayment that the payment authorization controller returns by implementing this protocol.

You can also choose to implement some optional PKPaymentAuthorizationViewControllerDelegate methods for custom events (for example, to recalculate shipping costs based on user selection). See the PKPaymentAuthorizationViewController documentation for more information about these callbacks.

After the controller has returned with a PKPayment, we can move ahead to the next step.

Using STPPaymentCardTextField

To use our pre-built form component, we'll create a view controller called PaymentViewController and add a STPPaymentCardTextField property to the view controller.

Next, let's instantiate the STPPaymentCardTextField, set the PaymentViewController as its STPPaymentCardTextFieldDelegate, and add it to our view.

This will add an STPPaymentCardTextField to the controller to accept card numbers, expiration dates, and CVCs. It'll format the input, and validate it on the fly.

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

Building your own form

If you build your own payment form, you'll need to collect at least your customers' card numbers and expiration dates. You should likely also collect the CVC to prevent fraud. You can also optionally collect the user's name and billing address for addititional 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 data directly to our servers, where we can convert them to tokens. You can charge these tokens later in your server-side code.

Using a PKPayment (Apple Pay)

After you've received a PKPayment, you can turn it into a single-use Stripe token with a simple method call:

Using STPCardParams

If you're using STPPaymentCardTextField or your own form, you can assemble the data into an STPCardParams object. Once you've collected the card number, expiration, and CVC, package them up in an STPCardParams object and invoke the createTokenWithCard: method on the STPAPIClient class, instructing the library to send off the credit card data to Stripe and return a token.

In the example above, we're calling createTokenWithCard: when a save button is tapped. The important thing to ensure is the createToken isn't called before the user has finished entering their card details.

Handling error messages and showing activity indicators while we're creating the token is up to you.

Sending the token to your server

The block you gave to createToken will be called whenever Stripe returns with a token (or error). You'll need to send the token off to your server so you can, for example, charge the card.

Here's how it looks for a token created with Apple Pay:

If you're not using Apple Pay, the above code would be mostly the same, though you'll want a slightly different signature—the completion callback shown above is Apple Pay-specific. You would instead want to implement custom error and success handling.

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

Once you have a Stripe token representing a card on our server we can go ahead and charge it, save it for charging later, or sign the user up for a subscription. For more information, proceed to our creating charges tutorial.

Take a look at the full example application to see everything put together.

Next up

Once you've retrieved a token from Stripe, you're going to want to do something with the payment details you just collected. This is usually one of two things: