Technical Note TN2259

Adding In-App Purchase to your iOS and OS X Applications

In-App Purchase allows you to sell additional features and functionality from within your iOS apps and OS X apps. If you wish to offer In-App Purchase in your applications, you must complete several steps before you can do it. This document provides step-by-step instructions for setting up and testing In-App Purchase. It also answers common questions about In-App Purchase. The "Agreements, Tax, and Banking Information" section describes all the financial documents that must be completed. The "Certificates, Identifiers & Profiles" and "iTunes Connect" sections indicate the steps to be respectively done in the Certificates, Identifiers & Profiles section of Member Center and iTunes Connect. The "What's Next" section shows how to test In-App Purchase. The "Update Your App for Ask to Buy" section describes how to support the Ask to Buy feature.

This document does not cover how to implement In-App Purchase in your applications. Read the In-App Purchase Programming Guide for detailed information about implementing In-App Purchase in your applications.

Agreements, Tax, and Banking Information
Certificates, Identifiers & Profiles
iTunes Connect
What's Next?
Update Your App for Ask to Buy
Document Revision History

Agreements, Tax, and Banking Information

You must complete the following steps before you can support In-App Purchase in your applications:

  1. Agree to the latest Developer Program License Agreement.

    Your team agent must agree to the latest Apple Developer Program License Agreement in the Member Center before you are allowed to create In-App Purchase products.

  2. Complete your contract, tax, and banking Information.

    You must have a Paid Applications contract in effect with Apple and have provided your tax and banking information in iTunes Connect as seen in Figure 1. Read Managing Agreements, Tax, and Banking for more information.

Figure 1  Paid Applications contract in iTunes Connect

Certificates, Identifiers & Profiles

The Certificates, Identifiers & Profiles section of Member Center is used to configure your App ID and Provisioning Profiles for In-App Purchase. You must complete the following step in that section:

  1. Register an explicit App ID for your application.

    Explicit App IDs are App IDs whose Bundle Identifier portion is a string without the wildcard ("*") character. Furthermore, they are automatically registered for In-App Purchase and Game Center as shown in Figure 2. Using an explicit App ID ensures that your In-App Purchase products are only associated with your application. For example, use com.example.MyGreatApplication rather than com.example.*.

    Your team agent or admin should navigate to the App IDs section of the Member Center to create App IDs for your applications. Read Registering App IDs in the App Distribution Guide to find out how to create App IDs.

Figure 2  Explicit App ID

iTunes Connect

To test In-App Purchase, you need to create products to purchase and test accounts to make the purchases. iTunes Connect allows you to create and manage In-App Purchase products and Test User accounts. You must complete the following steps in iTunes Connect:

  1. Create test user accounts.

    Apple provides a testing environment, called the sandbox, which allows you to test your In-App Purchase products without incurring any financial charges. The sandbox environment uses special test user accounts rather than your regular iTunes Connect accounts to test In-App Purchase. See Test Users in the iTunes Connect Developer Guide for more information about creating test user accounts.

  2. Create In-App Purchase products.

    Creating In-App Purchase products is available via the In-App Purchases feature for your app in iTunes Connect. This feature is only visible to users with admin or technical role in iTunes Connect. See Creating In-App Purchase Products in the In-App Purchase Configuration Guide for iTunes Connect for more information.

    • Fill out the In-App Purchases form.

      The In-App Purchase form contains the Product ID field, which specifies a unique identifier for each of your In-App Purchase products. See Technical Q&A QA1329, 'In-App Purchase Product Identifiers' for more information about product identifiers and how to access the form.

    • Leave the state of your product as Waiting for Screenshot as shown in Figure 3.

    • Clear your product for sale.

      The In-App Purchases form contains a Cleared for Sale checkbox, which determines whether your In-App Purchase product will be available for purchase from within your application. Check that box to make sure your product is available for sale.

Figure 3  Status of Product IDs

What's Next?

You have successfully set up In-App Purchase for your application, let's implement and test it:

  1. Launch or create your project in Xcode.

  2. Enter the Bundle Identifier portion of your App ID in the Bundle Identifier field of your Target's Info pane in Xcode.

  3. Enter a version number (CFBundleVersion) and a build number (CFBuildNumber) in the Version and Build fields of your Target's Summary Pane in Xcode, respectively as seen in Figure 4.

Figure 4  Setting the version and build in the Summary pane
  1. Set up your project to use automatic provisioning. Read Technical Q&A, QA1814, Setting up Xcode to automatically manage your provisioning profiles for more information.

  2. Add the In-App Purchase capability to your app as seen in Figure 5.

    Xcode will automatically create a development provisioning profile enabled for In-App Purchase. Read Enabling In-App Purchase for more information.

Figure 5  Enable In-App Purchase for your app
  1. Write code for your application.

    • Read the In-App Purchase Programming Guide and Receipt Validation Programming Guide for detailed information about implementing In-App Purchase in your applications and receipt validation, respectively.

    • OS X applications should perform receipt validation immediately after launch. The apps should call exit with a status of 173 if validation fails as shown in Listing 1.

      Listing 1  Receipt validation

      -(void)applicationWillFinishLaunching:(NSNotification *)notification
         // Locate the receipt
         NSURL *receiptURL = [[NSBundle mainBundle] appStoreReceiptURL];
         // Test whether the receipt is present at the above path
         if(![[NSFileManager defaultManager] fileExistsAtPath:[receiptURL path]])
              // Validation fails
         // Proceed with further receipt validation steps
  2. Test your application in the sandbox environment.

    • iOS developers must complete the following steps:

      • Sign out of the Store in the Settings application on your testing device.

      • Set the run destination of your application to an iOS Device in Xcode.

      • Build and run your application from Xcode.

    • OS X developers must complete the following steps:

      • Build your application in Xcode.

      • Run your application.

        You must launch your application from the Finder rather than from Xcode the first time in order to obtain a receipt. Click on your application in the Finder to launch it. OS X displays a "Sign in to download from the App Store." dialog. Enter your test user account and password as requested. The sandbox provides you with a new receipt upon successful authentication.

    StoreKit connects to the sandbox environment when you launch your application from Xcode, from your test device (iOS), or from the Finder (OS X). It connects to a production environment for applications that were downloaded from the App Store. You must not use your test user account to sign into the production environment. This will result in your test user account becoming invalid. Invalid test accounts cannot be used to test In-App Purchase again.

  3. Submit your In-App Purchase products for review.

    Log in to iTunes Connect to submit your In-App Purchase products for review by Apple, after you are done thoroughly testing them in the sandbox environment.

Update Your App for Ask to Buy

iOS 8 introduces Ask to Buy, which lets parents approve any purchases initiated by children, including apps or In-App Purchases on the App Store. When a child requests to make a purchase, Ask to Buy will indicate that the app is awaiting the parent’s approval for this purchase by sending the SKPaymentTransactionStateDeferred state to the paymentQueue:updatedTransactions: method on your transaction queue observer as shown in Listing 2. You should update your UI to reflect this deferred state, and expect paymentQueue:updatedTransactions: to be called again with a new transaction state reflecting the parent’s decision or after the transaction times out. Avoid blocking your UI or gameplay while waiting for the transaction to be updated.

Listing 2  Responding to transaction statuses

- (void)paymentQueue:(SKPaymentQueue *)queue updatedTransactions:(NSArray *)transactions
      for(SKPaymentTransaction * transaction in transactions)
          switch (transaction.transactionState)
              // Call the appropriate custom method
              case SKPaymentTransactionStatePurchasing:
              case SKPaymentTransactionStateDeferred:
                  // Do not block your UI. Allow the user to continue using your app.
                  [self transactionDeferred:transaction];
              case SKPaymentTransactionStatePurchased:
                   [self completeTransaction:transaction];
              case SKPaymentTransactionStateRestored:
                   [self restoreTransaction:transaction];
              case SKPaymentTransactionStateFailed:
                   [self failedTransaction:transaction];
              default: break;


Document Revision History


Editorial update. Moved the FAQ section to TN2413, In-App Purchase FAQ.


Added the Update Your App for Ask to Buy section. Updated FAQ 9.


Editorial update.


Updated for iOS 7.


Fixed typos and updated the FAQ section.


Updated the FAQ section and fixed typos.


Added screenshots. Updated the "What's Next?" and FAQ sections.


Added information about In App Purchase in Mac OS X 10.7. Updated the FAQ section.


Updated the "What's Next?" section.


Updated the FAQ section.


Removed the Enable your App ID for In App Purchase section. Updated the FAQ section.


New document that describes how to set up and test In-App Purchase in your iOS and OS X applications.