PayPal Mobile Express Checkout Library User Manual
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.à r.l. et Cie, S.C.A., Société en Commandite par Actions. Registered
office: 22-24 Boulevard Royal, L-2449, Luxembourg, R.C.S. Luxembourg B 118 349
Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it
does not require the approval of the Monetary Authority of Singapore. You are advised to read the terms and conditions
carefully.
Notice of non-liability:
PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of
any kind (whether express, implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no
liability for damages (whether direct or indirect), caused by errors or omissions, or resulting from the use of this document or
the information contained in this document or resulting from the application or use of the product or service described herein.
PayPal, Inc. reserves the right to make changes to any information herein without further notice.
Contents
Preface ............................................................................................................... 5
Purpose ........................................................................................................................ 5
Scope ............................................................................................................................ 5
Revision History ............................................................................................................ 5
Where to Go for More Information ................................................................................ 5
1. PayPal Mobile Express Checkout Library ................................................. 7
Mobile Express Checkout Library API Reference ........................................................ 7
Programming Flow with the PayPal Button in Your Mobile Application ................. 7
Programming Flow with the PayPal Button on Your Mobile Website .................... 8
Methods in the Mobile Express Checkout Library ................................................. 8
Enumerated Values in the Mobile Express Checkout Library.............................. 10
Localization Support in the Mobile Express Checkout Library ................................... 11
How to Set the Language and the Region ........................................................... 11
Locales Supported by the Mobile Express Checkout Library .............................. 12
Library Support for Devices and iOS versions ........................................................... 12
Adding the Mobile Express Checkout Library to Your Xcode Project ........................ 13
Method Sequence with the PayPal Button in Your Mobile App ................................. 14
Method Sequence with the PayPal Button on Your Mobile Webpage ....................... 15
Sample Code .............................................................................................................. 16
Library Header File............................................................................................... 16
Fetching the Device Token .................................................................................. 17
Placing the PayPal Button in Your Mobile Application ......................................... 17
Redirecting Buyers to PayPal .............................................................................. 18
Completing the Payment ............................................................................................ 18
2. The Checkout Experience with the Mobile Express Checkout Library . 19
Express Checkout Experience ................................................................................... 19
3. Submitting Your Application to PayPal ................................................... 21
A. Creating an Ad Hoc Build ......................................................................... 22
Creating a Distribution Certificate ............................................................................... 22
Creating and Approving a Certificate Signing Request ....................................... 22
Creating a Distribution Certificate ........................................................................ 23
Adding Device IDs ...................................................................................................... 23
Locating your Device ID ....................................................................................... 24
Adding Devices to the iPhone Developer Program Portal ................................... 24
PayPal Mobile Express Checkout Library Developer Guide and Reference January 2011 3
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 .......................................................................................................................... 29
Saving the Private Key and Transferring It to Other Systems ............................. 29
Verifying a Successful Ad Hoc Distribution Build ................................................. 30
Correcting an Unsuccessful Ad Hoc Distribution Build ........................................ 30
4 January 2011 PayPal Mobile Express Checkout Library Developer Guide and Reference
Preface
Date Published
Description
January 2011
Updated to reflect the disabling of „Keep Me Logged In‟ functionality for version
1.0.1
November 2010
Created for version 1.0 of the Mobile Express Checkout Library
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.
Scope
This document describes how to use the PayPal Mobile Express Checkout Library to embed your
mobile implementation of Express Checkout in your mobile application. It also describes how to
provide your build to PayPal. We review your application so we can approve it to accept
payments through the library.
Revision History
The following table lists revisions made to the Mobile Express Checkout Library Developer
Guide and Reference.
Where to Go for More Information
Express Checkout Integration Guide
Mobile Payments Library Developer Guide and Reference – iOS Edition
Sandbox User Guide
Merchant Setup and Administration Guide
PayPal X Developer Network (x.com)
PayPal Mobile Express Checkout Library Developer Guide and Reference January 2011 5
6 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.
Programming Flow with the PayPal Button in Your Mobile Application
Place the PayPal button in your mobile application if your checkout process begins and ends with
screens in your mobile application. In this programming flow, you embed only the mobile
Express Checkout payment pages in a web view.
1. Fetch a device token from the library, just before you display the mobile application screen
where you show a PayPal button.
Include a pointer to your delegate method that receives the device token.
2. Get a PayPal button from the library, and place it on your mobile application screen.
Include a pointer to your delegate method that handles the button-click event.
3. When buyers select the PayPal button, your delegate method is called:
a. Call a routine on your mobile web server, passing the payment information.
b. On your mobile web server, send a SetExpressCheckout request with the payment
information to PayPal.
c. Pass the checkout token returned in the SetExpressCheckout response from your
mobile web server to your mobile application.
d. Open a web view, and redirect the browser to PayPal with the mobile command, the
device token, and the checkout token as URL parameters.
https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkoutmobile
&drt=valueFromMobileExpressCheckoutLibrary&token=valueFromSetExpr
essCheckoutResponse
4. Monitor the web view for a redirect from PayPal to your return or cancel URL.
5. If PayPal redirects the web view to your return URL, call surrogate routines on your mobile
web server that send GetExpressCheckoutDetails and DoExpressCheckoutPayment
requests to PayPal to complete the payment.
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
PayPal Mobile Express Checkout Library Developer Guide and Reference January 2011 7
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. Fetch a device token from the library, just before you open a web view of your mobile
Express Checkout implementation.
Include a pointer to your delegate method that receives device tokens.
2. Open a web view of a page or routine on your mobile web server that begins your checkout
process.
Include the device token as a URL parameter when you open the web view, along with the
item details in the shopping cart.
3. Monitor the web view for a redirect from your web server to a well-known URL that signals
the checkout process on your mobile website is complete.
Methods in the Mobile Express Checkout Library
fetchDeviceReferenceTokenWithAppID Method
The fetchDeviceReferenceTokenWithAppID method returns a device token. Use the del
parameter to specify your own delegate function of that receives device tokens. Include the
device token as the &drt parameter in the URL when your redirect the buyer‟s mobile browser to
PayPal. Device tokens expire after 45 minutes.
By default, the library uses PayPal‟s production servers for fetching device tokens. To test your
application, use the optional env parameter so the library fetches device tokens from PayPal‟s
Sandbox servers, instead.
In your programming flow, fetch the device token just before you get the PayPal button.
8 January 2011 PayPal Mobile Express Checkout Library Developer Guide and Reference
- (void)fetchDeviceReferenceTokenWithAppID:(NSString const *)inAppID
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.
del:
(Required) Your delegate function that receives device tokens
Parameter
Description
target:
(Required) The UIViewController that is the delegate for callbacks
action:
(Required) Your method that responds to the PayPal button click
buttonType:
(Required) Size and appearance of the PayPal button
Allowable values are:
BUTTON_152x33
BUTTON_194x37
BUTTON_278x43
BUTTON_294x43
forEnvironment:(PayPalEnvironment)env
withDelegate:(id<DeviceReferenceTokenDelegate>)del;
getPayButtonWithTarget Method
If you place the PayPal button in your mobile application, get an instance from the Mobile
Express Checkout Library. This method returns a UIButton that you place on your mobile
application screen. If you need to move the button, because your application supports rotation for
example, change the button frame. The target parameter sets which UIViewController
receives delegate callbacks. If data is invalid, you receive an alert from the UIAlertViews.
- (UIButton *)getPayButtonWithTarget:(NSObject const *)target
andAction:(SEL)action andButtonType:(PayPalButtonType)inButtonType;
getInstance Method
The library provides a singleton instance of the PayPal object. Use the getInstance method to
set and access runtime properties of the library. For example, use the value of the
paymentsEnabled property to determine whether your attempt to fetch a device token was
successful.
PayPal Mobile Express Checkout Library Developer Guide and Reference January 2011 9
Loading...