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 and OS X applications. 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 "Contracts, Tax, and Banking Information" section describes all the financial documents that must be completed. The "Member Center" and "iTunes Connect" sections indicate the steps to be respectively done in the Member Center and iTunes Connect. The "What's Next" section shows how to test In-App Purchase.

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.

Contracts, Tax, and Banking Information
Member Center
iTunes Connect
What's Next?
Frequently Asked Questions
References
Document Revision History

Contracts, 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 iOS Developer Program License Agreement (iOS) or to the latest Mac Developer Program License Agreement (OS X) 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 an iOS Paid Applications contract (iOS) or a Mac OS X Paid Applications contract (OS X) in effect with Apple and have provided your tax and banking information in iTunes Connect as seen in Figure 1.

Figure 1  Contract section in iTunes Connect

Member Center

The Member Center is used to configure your App ID and Provisioning Profiles for In-App Purchase. OS X and iOS developers must complete the following steps in the Member Center:

  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 Team 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
  1. Certificates and Provisioning Profiles.

    • iOS developers must create, download, and install a new Development Provisioning Profile that uses their App ID enabled for In-App Purchase as seen in Figure 3. Read Creating Provisioning Profiles Using Member Center and Refreshing Provisioning Profiles in Xcode in the App Distribution Guide to learn how to create and install Provisioning Profiles.

    • OS X developers must create, download, and install a Mac Development Certificate that uses their App ID enabled for In-App Purchase. Read Requesting Signing Identities in the App Distribution Guide to learn how to create a Mac Development certificate.

Figure 3  Provisioning Profile

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. Both iOS developers and OS X developers 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 Manage In-App Purchases feature in iTunes Connect.

    Your Admin or Technical users should navigate to the Manage Your Applications in iTunes Connect, select the application for which they want to create In-App Purchase products, then click on the Manage In-App Purchases button in the ensuing page for this application. See Creating In-App Purchase Products in the In-App Purchase Configuration Guide for iTunes Connect for more information about creating In-App Purchase products.

    • 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 4.

    • 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 4  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 5.

Figure 5  Setting the version and build in the Summary pane
  1. Sign your application.

    Navigate to the Build Settings pane of your Target and select the iOS Development Certificate/Provisioning Profile pair (iOS) or Mac signing certificate (OS X) associated with your App ID in the code signing identity section.

  2. Write code for your application.

    • Both iOS developers and OS X developers should 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
              exit(173);
         }
       
         // Proceed with further receipt validation steps
      }
  3. 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.

    Store Kit 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.

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

Frequently Asked Questions

  1. How many In-App Purchase product IDs can we create per application in iTunes Connect?

    Read Configuring a Product in the In-App Purchase Configuration Guide for iTunes Connect to find out how many In-App Purchase product IDs you can create per application.

  2. My iOS application is currently signed with a Provisioning Profile that uses a wildcard App ID. How do I enable my App ID to support In-App Purchase?

    Read Editing App IDs in the App Distribution Guide to learn how you can enable your App ID to support In-App Purchase.

  3. I cannot find the Manage In-App Purchases button in iTunes Connect?

    The Manage In-App Purchases button may not be available to you for one or more of the following reasons:

    • You are not an Admin or Technical user for your iTunes Connect account.

    • Your Team Agent has not agreed to the latest iOS or Mac Developer Program License Agreement.

    • You do not have the latest Paid Applications contract in effect.

  4. Must I upload a binary to test In-App Purchase?

    No. Testing In-App Purchase does not require uploading a binary.

  5. How do I resolve the 'Your account info has changed' error?

    You are getting the 'Your account info has changed' error because you are signed in with your test user account on your device while testing In-App Purchase. To resolve this error, sign out of the Store in the Settings application on your device, create a new test user account in iTunes Connect, and use it when testing In-App Purchase.

  6. Why are my product identifiers being returned in the invalidProductIdentifiers array?

    Your product identifiers may be returned in the invalidProductIdentifiers array for one or more of the following reasons:

    • You did not complete all the financial requirements (see the "Contracts, Tax, and Banking Information" section of this document).

    • You did not use an explicit App ID.

    • You did not use the Provisioning Profile associated with your explicit App ID.

    • You did not use the correct product identifier in your code. See Technical Q&A, QA1329, 'In-App Purchase Product Identifiers' for more information about product identifiers.

    • You did not clear your In-App Purchase products for sale in iTunes Connect.

    • You might have modified your products, but these changes are not yet available to all the App Store servers.

    • If you or App Review rejected your most recent binary in iTunes Connect.

  7. How do I resolve the "You've already purchased this In-App Purchase but it hasn't been downloaded." error message?

    You are getting the "You've already purchased this In-App Purchase but it hasn't been downloaded." error message because you did not call SKPaymentQueue 's finishTransaction:method in your application. Calling finishTransaction: allows you to remove a transaction from the payment queue.

  8. How do I resolve the "You've already purchased this. Tap OK to download it again for free." error message?

    The "You've already purchased this. Tap OK to download it again for free." message is a notification rather than an error. It indicates that you are attempting to purchase a nonconsumable product that you have already bought. You are not charged when purchasing an already bought nonconsumable product.

  9. Calling the payment queue’s restoreCompletedTransactions method does not restore any products in my application.

    Calling the payment queue’s restoreCompletedTransactions method may not restore any products in your application for one or more of the following reasons:

    • You did not have any previously bought non-consumable, auto-renewable subscriptions, or free subscriptions.

    • You were trying to restore non-renewing subscription or consumable products, which are not restorable. The restoreCompletedTransactions method only restores non-consumable, auto-renewable subscriptions, and free subscriptions.

  10. When should I restore my In-App Purchase products?

    You should only restore your auto-renewal subscription or nonconsumable products in both of these cases:

    • To install them on additional devices owned by your customers.

    • To reinstall them on devices where their associated application was deleted.

  11. How do I resolve the "This is not a test user account. Please create a new account in the Sandbox environment." error message?

    You are getting the "This is not a test user account. Please create a new account in the Sandbox environment." error message because you signed in with your iTunes user account when prompted by Store Kit to confirm a purchase. To resolve this error, sign out of the Store in the Settings application on your device and use your In-App Purchase test user account when prompted by Store Kit to confirm a purchase.

  12. How do I retrieve the receipt data?

    Use NSBundle's appStoreReceiptURL method to first locate your application receipt, then read the entire receipt to retrieve your receipt data as shown in Listing 2 (iOS 7, OS X 10.7 and later).



    Listing 2  Retrieving the receipt data

     NSURL *receiptURL = [[NSBundle mainBundle] appStoreReceiptURL];
      // Test whether the receipt is present at the above URL
       if(![[NSFileManager defaultManager] fileExistsAtPath:[receiptURL path]])
       {
          NSData *receiptData = [NSData dataWithContentsOfURL:receiptURL];
       }


    Listing 3  Retrieving the receipt data in iOS 6 and earlier

    -(void)completeTransaction:(SKPaymentTransaction *)transaction
    {
       NSData *receiptData = [transaction transactionReceipt];
    }
  13. Verifying my receipt fails with a status of <string of numbers> (iOS)

    Verifying your receipt may fail with a status of <string of numbers> for one or more of the following reasons:

    • You did not encode your receipt data using base64 encoding in your iOS application.

    • The object being posted to the App Store is not formatted as JSON. See Listing 4 for a proper JSON object for an auto-renewable subscription.



      Listing 4  valid sample receipt for verifying an auto-renewable subscription

      {
          "receipt-data" : "...",
              "password" : "..."
      }
  14. I updated my iOS application with In-App Purchase. How do I test it (iOS)?

    Follow these steps if you are trying to test whether your updated app correctly implements In-App Purchase:

    • Install your original application via the Ad Hoc Distribution method.

    • Install your updated application also via the Ad Hoc Distribution method to verify that it overwrites the original application.

    • Attempt to use the updated application and try purchasing In-App Purchase products from it.

  15. What url should I use to verify my receipt ?

    • Use the sandbox URL https://sandbox.itunes.apple.com/verifyReceipt while testing your application in the sandbox and while your application is in review.

    • Use the production URL https://buy.itunes.apple.com/verifyReceipt once your application is live in the App Store.

  16. How do I verify my auto-renewable subscriptions receipt (iOS)?

    Always verify your receipt for auto-renewable subscriptions first with the production URL; proceed to verify with the sandbox URL if you receive a 21007 status code. Following this approach ensures that you do not have to switch between URLs while your application is being tested or reviewed in the sandbox or is live in the App Store.

  17. How do I resolve the "Current receipt invalid or mismatched ds person id" error message (OS X)?

    You are getting this message because your application does not contain an OS X App Store receipt. See the "Write code for your application" step of this technote's "What's Next?" for more infomation on how to obtain a receipt for your application.

  18. My In-App Purchase has localized information for various languages on iTunes Connect. However, the localizedDescription and localizedTitle properties always return information in English even though my test device language is not set to English.

    localizedDescription and localizedTitle return localized information whose language is based on the current iTunes Store rather than the current device language setting. For instance, if your In-App Purchase is localized for German in iTunes Connect and you are logged with an English test user account, then localizedDescription and localizedTitle will return information localized in English. To have localizedDescription and localizedTitle return information localized in German, login with a German test user account on your test device.

References



Document Revision History


DateNotes
2014-01-30

Updated for iOS 7.

2013-02-21

Fixed typos and updated the FAQ section.

2012-08-29

Updated the FAQ section and fixed typos.

2012-02-22

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

2011-08-03

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

2011-05-23

Updated the "What's Next?" section.

2011-05-05

Updated the FAQ section.

2010-10-20

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

2010-03-03

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