The latest wave of development focuses on creating applications and commerce interfaces for the mobile market. At the Innovate 2010 Developer Conference, PayPal announced the release of Mobile Express Checkout (MEC), which is built on the existing Express Checkout API. Mobile Express Checkout allows for fast development, especially if you already have an Express Checkout-based solution. In addition to Mobile Express Checkout, PayPal provides development libraries, or Mobile Payment Libraries (MPL), for both the iPhone and Android platforms. Table 5-1, also provided by Bill Day at https://www.x.com/docs/DOC-3035, outlines the standard PayPal APIs and their mobile equivalents.
PayPal APIs you use today | Use this for native mobile development | Use this for mobile web development |
Express Checkout | MEC library for iOS | MEC |
Adaptive Payments | MPL | N/A |
Website Payments Standard | MPL | N/A |
MPL is a native application development option, and it is especially useful if you are targeting apps on iOS- or Android-based devices that have no backend commerce infrastructure to interface with. MPL also supports some PayPal technologies currently not addressed by MEC, such as Adaptive Payments.
To fully utilize the capabilities of Mobile Express Checkout and the development libraries, you should be familiar with mobile website programming, the Name-Value Pair API, and additionally the platform you are developing on if integrating with a mobile application. It should also be noted that iOS uses Objective-C, and so knowledge of this language is a plus. Let’s look at the MEC flow first.
The MEC flow, shown in Figure 5-1, has the following steps:
The customer clicks the “Checkout with PayPal” button on your site.
The customer logs into PayPal.
The customer reviews the transaction on PayPal and submits payment.
The customer receives an order confirmation.
As you can see, Mobile Express Checkout functions identically to Express Checkout, but MEC has several design and implementation best practices to consider, which are outlined next.
Just as with Express Checkout, shortcut placement for MEC is key. Customers can enter into MEC from either the Shopping Cart (where users see the items they are purchasing) or the Payments page (where they are asked to provide all their billing and payment information). The recommendations and requirements when entering from the Shopping Cart are as follows:
“Checkout with PayPal” buttons should be used.
You must use approved, hosted PayPal buttons.
You cannot resize any PayPal-supplied images.
The checkout button should take the customer directly to PayPal.
It should take no more then two pages after the PayPal pages to complete the payment.
The recommended flows are Shopping Cart→Login→Review→Confirmation, or Shopping Cart→Login→Review→Additional Review with Submit→Confirmation.
If you are entering into MEC from the Payments page, the recommendations and requirements are as follows:
The PayPal Payment Mark should be used.
You must use approved, hosted PayPal marks.
You cannot resize any PayPal-supplied images.
Radio buttons should have at least a 44 pixel spacing to enable easy selection on touch-enabled devices.
If your customer has already set up a billing agreement through Express Checkout online, the “Checkout with PayPal” button should contain her email address. Doing so helps to personalize the transaction. If there is no billing agreement set up, the basic “Checkout with PayPal” button should be used.
PayPal provides a MEC library for iOS, available for download from https://www.x.com/community/ppx/xspaces/mobile/mobile_ec. This MEC library supports two different programming flows: it can be called either directly from your mobile application or via a PayPal button on your mobile website.
MEC can be integrated into your mobile application, allowing you to start and end the payment process with screens inside your application. The MEC checkout pages themselves are contained inside a web view. The steps for doing so are as follows:
Acquire a device token from the MEC library before rendering the payment screen with the PayPal Button. Include a pointer to the method you delegate for handling the device token.
Acquire a PayPal payment button from the Library and render it on your mobile application screen. Include a pointer to the method you delegate for handling the button-click event.
When your customer clicks the PayPal button, it will initialize your delegated method to do the following:
Call a routine on your mobile web server for passing the payment information.
Your mobile web server will then send a SetExpressCheckout
request
with the payment information to PayPal.
Pass the checkout token returned from
SetExpressCheckout
back to your mobile application.
Open a web view redirecting the customer’s browser to
PayPal with the Mobile
command, using the
device token and the checkout token as URL parameters. For example:
https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout-mobile
&drt=valueFromMobileExpressCheckoutLibrary&token=valueFromSetExpressCheckoutResponse
Watch the web view for a redirect call from PayPal to either your return or cancel URLs.
If PayPal redirects the web view to your return URL, call
surrogate routines on your mobile
web server that send GetExpressCheckoutDetails
and DoExpress
CheckoutPayment
requests to
PayPal to complete the payment.
MEC can be integrated directly with your mobile website, allowing you to start and end the payment process with pages on your site. The steps for doing so are as follows:
Acquire a device token from the MEC library before rendering the web view of your MEC implementation. Include a pointer to the method you delegate for handling the device token.
Launch a web view of the web page or routine on your mobile server that initiates your checkout process. Include the device token as a URL parameter, as well as the item details in the shopping cart.
Watch the web view for a redirect from your mobile web server that contains a call to a known URL, signaling the checkout process is complete.
MEC contains three methods:
fetchDeviceReferenceTokenWithAppID
,
getPayButtonWithTarget
, and
getInstance
. Let’s look at each in depth.
The fetchDeviceReferenceTokenWithAppID
method returns a device token for use with the transaction. Use the
del
parameter to specify your delegate function
that receives device tokens. Device tokens have a 45-minute expiration
time limit, and are passed as the &drt
parameter on the URL when you redirect the mobile browser to PayPal.
The MEC library uses the PayPal production servers by default to
get device tokens. During your development process, use the
env
parameter to fetch device tokens from the
sandbox. Be sure to fetch the device token just before you get the
PayPal button. When you fetch the device token, the library determines
whether the buyer stays logged in on the device. If the buyer is
already logged into PayPal, the library will display the buyer’s name
above the button when it renders. Table 5-2 outlines the parameters
for fetch
DeviceReferenceTokenWithAppID.
Parameter | Description |
inAppId: | The PayPal Application ID from X.com (required). For
the sandbox environment, use
APP-80W284485P519543T . |
env: | Indicates which PayPal servers the library uses
(optional). Allowable values are:
|
del: | Your delegate function that receives device tokens (required). |
If your payment implementation is in a mobile application,
you can get a button from the MEC library. The
getPayButtonWithTarget
method returns a
UIButton
for use on your mobile application screen,
and it provides a target:
parameter that allows you
to specify which UIViewController
receives the
callbacks. Table 5-3
outlines the parameters for
getPayButtonWithTarget.
Parameter | Description |
target: | The UIViewController that is the
delegate for callbacks (required). |
action: | Your method that responds to the PayPal button click (required). |
buttonType: | The size and appearance of the PayPal button
(required). Allowable values are:
|
You can use the getInstance
method to
specify and access the library’s runtime properties. This can be used
for debugging purposes as well as to verify that your payment is
working properly. Table 5-4
outlines the parameters for getInstance.
Parameter | Description |
lang | The 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. |
paymentsEnabled | If your attempt to fetch a device token succeeded, the
value of this property is TRUE . |
MEC supports numerous locales, which can be specified after
you initialize the library. By default it will determine the local of
the user’s device, and if it does not support the device’s locale, it
will fall back on en_US
. You specify the locale with
the lang
property of the PayPal object. This should
be set after initializing the library and before you make the call to
getPayButtonWithTarget()
to get a localized button.
Table 5-5 lists the supported
localizations.
Country or region | Supported locale codes |
Argentina | es_AR |
Brazil | pt_BR |
Australia | en_AU |
Belgium | en_BE , nl_BR ,
fr_BE |
Canada | en_CA ,
fr_CA |
France | fr_FR ,
en_FR |
Germany | de_DE ,
en_DE |
Hong Kong | zh_HK ,
en_HK |
India | en_IN |
Italy | it_IT |
Japan | ja_JP ,
en_JP |
Mexico | es_MX ,
en_MX |
Netherlands | nl_NL ,
en_NL |
Poland | pl_PL ,
en_PL |
Singapore | en_SG |
Spain | es_ES ,
en_ES |
Switzerland | de_CH , en_CH ,
fr_CH |
Taiwan | zh_TW ,
en_TW |
United States | en_US |
The MEC library includes a library header file,
PayPal.h, for your mobile application or mobile web
code. The contents of PayPal.h are shown in Example 5-1. You can access features of the MEC library using the
"PayPal : NSObject
<UIWebViewDelegate>"
interface.
#import <UIKit/UIKit.h> typedef enum PayPalEnvironment { ENV_LIVE, ENV_SANDBOX, ENV_NONE, } PayPalEnvironment; typedef enum PayPalButtonType { BUTTON_118x24, BUTTON_152x33, BUTTON_194x37, BUTTON_278x43, BUTTON_294x43, BUTTON_TYPE_COUNT, }PayPalButtonType; @protocol DeviceReferenceTokenDelegate <NSObject> @required - (void)receivedDeviceReferenceToken:(NSString *)token; - (void)couldNotFetchDeviceReferenceToken; //Check the errorMessage property to see what //the problem was. @end @interface PayPal : NSObject <UIWebViewDelegate> { @private BOOL initialized;//Determines if the initialization call has finished and the PayPal //object is initialized. BOOL paymentsEnabled; NSString *appID; NSString *lang; PayPalEnvironment environment; NSString *errorMessage; NSMutableArray *payButtons; id<DeviceReferenceTokenDelegate> delegate; } @property (nonatomic, retain) NSString *lang; @property (nonatomic, retain) NSString *errorMessage; @property (nonatomic, retain) NSMutableArray *payButtons; @property (nonatomic, readonly) NSString *appID; @property (nonatomic, readonly) BOOL initialized; @property (nonatomic, readonly) BOOL paymentsEnabled; @property (nonatomic, readonly) PayPalEnvironment environment; + (PayPal*)getInstance; - (void)fetchDeviceReferenceTokenWithAppID:(NSString const *) inAppID forEnvironment:(PayPalEnvironment)env withDelegate:(id<DeviceReferenceTokenDelegate>)del; - (void)fetchDeviceReferenceTokenWithAppID:(NSString const *) inAppID withDelegate:(id<DeviceReferenceTokenDelegate>)del; - (UIButton *)getPayButtonWithTarget:(NSObject const *)target andAction:(SEL)action andButtonType:(PayPalButtonType)inButtonType; @end
A full example of using the MEC library for an online pizza delivery service application can be found in the library download at https://www.x.com/community/ppx/xspaces/mobile/mobile_ec.
MEC is a new PayPal offering, but it builds on the tried and true PayPal Express Checkout. PayPal continues to bring new technologies into the realm of payment solutions. In this book, I’ve tried to provide the fundamental knowledge you need to choose which PayPal solution is right for you and understand how to implement that solution into your unique situation. I hope that I have succeeded in both of these avenues.
18.222.119.177