Chapter 5. PayPal Mobile Express Checkout

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.

Table 5-1. Standard PayPal APIs and mobile equivalents
PayPal APIs you use todayUse this for native mobile developmentUse this for mobile web development
Express CheckoutMEC library for iOSMEC
Adaptive PaymentsMPLN/A
Website Payments StandardMPLN/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.

Mobile Express Checkout Flow

The MEC flow, shown in Figure 5-1, has the following steps:

  1. The customer clicks the “Checkout with PayPal” button on your site.

  2. The customer logs into PayPal.

  3. The customer reviews the transaction on PayPal and submits payment.

  4. The customer receives an order confirmation.

Mobile Express Checkout flow
Figure 5-1. Mobile Express Checkout flow

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.

Mobile Express Checkout Best Practices

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.

Mobile Express Checkout Library for iOS

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 Mobile Application Integration

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:

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

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

  3. When your customer clicks the PayPal button, it will initialize your delegated method to do the following:

    1. Call a routine on your mobile web server for passing the payment information.

    2. Your mobile web server will then send a SetExpressCheckout request with the payment information to PayPal.

    3. Pass the checkout token returned from SetExpressCheckout back to your mobile application.

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

    5. Watch the web view for a redirect call from PayPal to either your return or cancel URLs.

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

MEC Mobile Website Integration

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:

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

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

  3. 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 Library Methods

MEC contains three methods: fetchDeviceReferenceTokenWithAppID, getPayButtonWithTarget, and getInstance. Let’s look at each in depth.

fetchDeviceReferenceTokenWithAppID method

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

Table 5-2. fetchDeviceReferenceTokenWithAppID method
ParameterDescription
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:
  • ENV_LIVE

  • ENV_SANDBOX

  • ENV_NONE

del:Your delegate function that receives device tokens (required).

getPayButtonWithTarget method

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.

Table 5-3. getPayButtonWithTarget method
ParameterDescription
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:
  • BUTTON_152x33

  • BUTTON_194x37

  • BUTTON_278x43

  • BUTTON_294x43

getInstance method

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.

Table 5-4. getInstance method
ParameterDescription
langThe locale code for the label of the PayPal button. By default, the library uses the locale of the device.
errorMessageIf the library fails to acquire a valid device token, the error message provides more details about the failure.
paymentsEnabledIf your attempt to fetch a device token succeeded, the value of this property is TRUE.

MEC Localization Support

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.

Table 5-5. Supported localizations
Country or regionSupported locale codes
Argentinaes_AR
Brazilpt_BR
Australiaen_AU
Belgiumen_BE, nl_BR, fr_BE
Canadaen_CA, fr_CA
Francefr_FR, en_FR
Germanyde_DE, en_DE
Hong Kongzh_HK, en_HK
Indiaen_IN
Italyit_IT
Japanja_JP, en_JP
Mexicoes_MX, en_MX
Netherlandsnl_NL, en_NL
Polandpl_PL, en_PL
Singaporeen_SG
Spaines_ES, en_ES
Switzerlandde_CH, en_CH, fr_CH
Taiwanzh_TW, en_TW
United Statesen_US

Sample MEC Code

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.

Example 5-1. PayPal.h

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

Summary

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.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.222.119.177