Mobile Express Checkout Library Developer Guide and Reference – iOS Edition Last updated: January 2011
PayPal Mobile Payments Developer Guide and Reference – iOS Edition Document Number 10123.en_US-201011 © 2011 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other trademarks and brands are the property of their respective owners. The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc. Copyright © PayPal. All rights reserved. PayPal S.
Contents Preface ............................................................................................................... 5 Purpose ........................................................................................................................ 5 Scope ............................................................................................................................ 5 Revision History ....................................................................................................
Using Updated Provisioning Profiles for New Devices ........................................ 24 Creating the App ID .................................................................................................... 24 Creating a Distribution Provisioning Profile ................................................................ 26 Creating the Build in XCode ....................................................................................... 27 Notes ......................................................
Preface The PayPal Mobile Express Checkout Library lets you embed your mobile implementation of Express Checkout in mobile applications for the iPhone® and iPod touch®. Purpose The PayPal Mobile Express Checkout Library lets you embed Express Checkout in iPhone and iPod touch applications. Download the library from x.com/mobile and include it in your application. You need only a few lines of code to integrate the library and your Express Checkout implementation in your mobile application.
January 2011 PayPal Mobile Express Checkout Library Developer Guide and Reference
1. PayPal Mobile Express Checkout Library This section provides details about the Mobile Express Checkout Library. It provides instructions and examples for using the library to embed your mobile implementation of Express Checkout in your iPhone or iPod touch application. Mobile Express Checkout Library API Reference The library supports 2 programming flows. They differ in where you place the PayPal button that buyers click to begin checking out with PayPal.
devices exposes you and PayPal to unacceptable security risks. Send Express Checkout requests only from secure servers. Programming Flow with the PayPal Button on Your Mobile Website Place the PayPal button on your mobile website if your checkout process begins and ends with pages on your mobile website. In this programming flow, you embed your entire mobile Express Checkout implementation in a web view. 1.
- (void)fetchDeviceReferenceTokenWithAppID:(NSString const *)inAppID forEnvironment:(PayPalEnvironment)env withDelegate:(id)del; Parameter Description inAppId: (Required) PayPal Application ID from X.com. For the Sandbox environment, use APP-80W284485P519543T. env: (Optional) Which PayPal servers the library uses Allowable values are: ENV_LIVE ENV_SANDBOX ENV_NONE NOTE: The ENV_LIVE environment does not support simulators.
+ (PayPal*)getInstance; The following table lists the properties of the PayPal object that you are most likely to use in your mobile application. For a complete list of properties, see the PayPal.h file. Property Description lang Locale code for the label of the PayPal button. By default, the library uses the locale of the device. errorMessage If the library fails to acquire a valid device token, the error message provides more details about the failure.
PAYPAL_BUTTON_TYPE PayPal displays the following images for buyers on the mobile device. BUTTON_152x33: BUTTON_194x37: BUTTON_278x43: BUTTON_294x43: Localization Support in the Mobile Express Checkout Library The Mobile Express Checkout Library supports many locales. Set the locale after you initialize the library. The default is the locale of the device. If the library does not support the device locale, the library uses en_US, instead.
Locales Supported by the Mobile Express Checkout Library The lang property of the PayPal object allows these values.
Adding the Mobile Express Checkout Library to Your Xcode Project PayPal provides a package that contains the header file PayPal.h and the static library file libPayPalEC.a. 1. Open your Xcode project. 2. CONTROL+CLICK your project, and then select Add > Existing Files…. 3. Select the .h and .a files, and then click Add.
Method Sequence with the PayPal Button in Your Mobile App The following diagram illustrates the sequence of methods that embed only the mobile PayPal payment pages in a web view within your mobile application. IMPORTANT: Never send Express Checkout requests from your mobile application directly to PayPal. The requests require your PayPal API credentials. Placing your credentials on mobile devices exposes you and PayPal to unacceptable security risks. Send Express Checkout requests only from secure servers.
Method Sequence with the PayPal Button on Your Mobile Webpage The following diagram illustrates the sequence of methods that embed your entire mobile Express Checkout implementation in a web view within your mobile application.
Sample Code The sample code in this section comes from sample application code included with the download of Mobile Express Checkout Library. Get the download of the library from x.com/mobile. Library Header File The library header file, PayPal.h, includes the following definitions. #import ... Use the following protocol to implement your own delegate class. Your class receives device tokens from the library when your code attempts to fetch a device token.
- (UIButton *)getPayButtonWithTarget:(NSObject const *)target andAction:(SEL)action andButtonType:(PayPalButtonType)inButtonType; @end Fetching the Device Token Regardless where you place the PayPal button, you must fetch a device token from the library by calling fetchDeviceReferenceTokenWithAppID(). If you place the PayPal button in your mobile application, fetch a device token just before you get the PayPal button.
The sample application implements the payWithPayPal() callback method in the class that gets the button, ReviewOrderViewController. UIButton *button = [[PayPal getInstance] getPayButtonWithTarget:self andAction:@selector(payWithPayPal) andButtonType:BUTTON_278x43]; The getPayButtonWithTarget method follows standard memory management conventions and is autoreleased.
2. The Checkout Experience with the Mobile Express Checkout Library The screen shots that follow illustrate the checkout experience when you embed your mobile implementation of Express Checkout in your mobile application. The embedded checkout experience is the same whether you place the Checkout with PayPal button in your mobile application or on your mobile website.
PayPal displays the mobile PayPal Review page after buyers log in successfully. The mobile Review page fully supports Express Checkout when you include a device token with your redirect to PayPal. When satisfied with the payment information the Review page, buyers click Continue to complete the payment in your mobile application or on your mobile website. If buyers pay on PayPal in your implementation of Express Checkout, the button label on the review page reads, “Pay Now” instead of “Continue.
3. Submitting Your Application to PayPal Log in or sign up on PayPal‟s developer website www.x.com. From there, click the MyApps tab to submit your mobile application. For PayPal to test your application, upload your build signed with the Ad Hoc Distribution profile. PayPal reviews applications within 24 hours and responds by sending you your PayPal Application ID.
A. Creating an Ad Hoc Build The Ad Hoc distribution method for iPhone apps allows for distribution of the build to internal or external sources. PayPal provides the Device ID values for PayPal‟s devices. In the process below, you add PayPal‟s devices to your Ad Hoc Provisioning Profile. You then compile the build, sign it with your Ad Hoc Provisioning Profile, and deliver the zipped build and the Ad Hoc Provisioning Profile to PayPal.
4. In the User Email Address field, enter your email address. Make sure that the email address entered matches the information that you submitted when you registered as an iPhone Developer. 5. In the Common Name field, enter your name. Make sure that the name you enter matches the information that you submitted to register as an iPhone Developer. A CA (Certificate Authority) Email Address is not required. The „Required‟ message disappears after completing the following step. 6.
You need to add your devices, as well as PayPal‟s devices. You receive UDID values for PayPal‟s devices from PayPal. Locating your Device ID 1. Connect your device to your Mac and open Xcode. 2. In Xcode, navigate to the Window drop-down menu and select Organizer. The 40-hex character string in the Identifier field is your device‟s UDID. Adding Devices to the iPhone Developer Program Portal 1. Navigate to the Devices section of the Program Portal and click Add Device. 2.
3. Enter a common name for your App ID. This is a name for easy reference and identification within the Program Portal. 4. Enter a Bundle Identifier in the free-form text field. PayPal recommends a reverse-domain-name-style string, such as com.domainname.applicationname. For applications suites that share the same Keychain access, use a wild-card character in the Bundle Identifier, such as com.domainname.* or *.
Creating a Distribution Provisioning Profile To successfully build your application in Xcode for Ad Hoc distribution, you must create and download an Ad Hoc Distribution Provisioning Profile. 1. Navigate to the Provisioning section of the Program Portal. 2. Click the Distribution tab. 3. 4. 5. 6. 7. 8. 9. Select the Ad Hoc radio button. Enter the name for your Ad Hoc Distribution Provisioning Profile. Make sure that your iPhone Distribution Certificate has been created and is displayed.
Creating the Build in XCode After you create the Distribution Provisioning Profile, you can compile and sign your application. 1. Open the project in Xcode and duplicate the Release configuration in the Configurations pane of the Info panel for the project. 2. Rename this new configuration “Distribution”. 3. In the Target Info window, click the Build tab and set the Configuration to Distribution. 4. In the Target Info window, navigate to the Build pane. 5.
The preceding example shows „iPhone Distribution: Example Corp, Inc.‟ as the Distribution Certificate and „My App Store Distribution Provisioning Profile‟ as its associated .mobileprovision file. 6. In the Properties Pane of the Target Info window, enter the Bundle Identifier portion of your App ID. If you used an explicit App ID, enter the Bundle Identifier portion of the App ID in the Identifier field. For example, enter com.domainname.applicationname if your App ID is A1B2C3D4E5.com.domainname.
9. Name the file “Entitlements.plist” and click the Finish button. This creates a copy of the default entitlements file within the project. 10. Select the new Entitlements.plist file, uncheck the get-task-allow property, and save the Entitlements.plist file. 11. Select the Target and open the Build settings inspector. 12. In the Code Signing Entitlements build setting, type the filename of the new Entitlements.plist file, including the extension. Do not specify a path unless you put the Entitlements.
Verifying a Successful Ad Hoc Distribution Build 1. Open the Build Log detail view and check the presence of the “embedded.mobileprovision” file. This takes you to the line in the build log that shows the provisioning profile was called successfully. Make sure that the embedded.mobileprovision file is located in the proper “Distribution” build directory and not a “Debug” or “Release” build directory. Also, make sure the destination path at the end of the build message is the app that you are building. 2.
