PayPal Mobile Checkout - 2009 Developer's Guide
Mobile Checkout
Developer Guide
Last updated: October 2009
Mobile Checkout Developer Guide
Document Number: 10044.en_US-200910
© 2009 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 (Europe) 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
This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Chapter 1 PayPal Mobile Checkout Overview . . . . . . . . . . . . . 7
Security on the Mobile Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
How Mobile Checkout Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Customer Activation for Mobile Checkout . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Mobile Checkout Processing Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Merchant Integration Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Initiating the Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Redirecting to PayPal Mobile Checkout . . . . . . . . . . . . . . . . . . . . . . . . . 12
Completing the Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Chapter 2 Mobile Checkout API Reference . . . . . . . . . . . . . . .15
SetMobileCheckout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
SetMobileCheckout Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
SetMobileCheckout Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
DoMobileCheckoutPayment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
DoMobileCheckoutPayment Request . . . . . . . . . . . . . . . . . . . . . . . . . . 20
DoMobileCheckoutPayment Response . . . . . . . . . . . . . . . . . . . . . . . . . 20
Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Appendix A PayPal Supported Currencies . . . . . . . . . . . . . . . .31
Appendix B Country Codes . . . . . . . . . . . . . . . . . . . . . . . 33
Mobile Checkout Developer Guide October 2009 3
4 October 2009 Mobile Checkout Developer Guide
Preface
This Guide
The Mobile Checkout Developer Guide describes the PayPal Mobile Checkout service. It
describes the interfaces, information flows, and functionality of this service.
Intended Audience
This guide is written for developers of mobile applications that use PayPal. You should be
familiar with mobile website programming and with either the PayPal Web Services API or
the PayPal Name-Value Pair API Interface.
Revision History
Revision history for Mobile Checkout Developer Guide.
TABLE P.1 Revision History
Date Description
October 2009 Updated the list of supported currencies and currency codes.
May 2008 Added general API error codes.
September 2007
May 2007 Initial version of document.
z Added information about secure Return and Cancel URLs
z Noted that PIN is recommended but not required.
Where to Go for More Information
This guide relies on information in the following guides and references:
z Express Checkout Integration Guide
z Name-Value Pair API Developer Guide
z SOAP API Developer Reference
z Sandbox User Guide
Mobile Checkout Developer Guide October 2009 5
6 October 2009 Mobile Checkout Developer Guide
1
PayPal Mobile Checkout Overview
PayPal Mobile Checkout provides merchants with the essential components necessary for
mobile commerce:
z A hosted quick buyer flow
z A straightforward merchant interface
z Transaction completion data
z PayPal merchant support
PayPal defines mobile commerce as any and all transactions completed using a mobile phone.
Buyers use a simple two step process (login and review) to make payments. The merchant
interface can be plugged into any mobile medium that can initiate a mobile browser session,
and uses either the PayPal Web Services SOAP or Name/Value Pair (NVP) API interface.
After a transaction is completed, the necessary buyer and transaction data is delivered to the
merchant via the interface.
The processing flow and APIs for Mobile Checkout are similar to those for Express Checkout.
For more information about Express Checkout, see the Name-Value Pair (NVP) Developer
Guide and Reference and the SOAP API Reference.
Security on the Mobile Web
PayPal Mobile Checkout is designed to support the vast majority of mobile devices sold by
major carriers that can make secure connections. To access mobile checkout, a device, mobile
carrier, and browser must support the following:
z WAP 2.0 phones (not WAP 1.0)
z xHTML or HTML markup language
z SSL connections
z Cookies enabled
z No carrier "WAP gap"
If a device or connection fails any of the these checks, the customer will not be able to connect
to the PayPal servers.
N OTE: Mobile web generally refers to the collection of accepted web standards used on
mobile devices. Most modern mobile devices use mini-browsers, much like a web
browser on a computer. A growing portion of phone subscribers pay for data plans to
access information, services, and commerce on their mobile devices though these
mobile browers. Most mobile browsers use the xHTML markup language, while
others also use cHTML, HTML, and WML. Most devices support cookies with default
Mobile Checkout Developer Guide October 2009 7
PayPal Mobile Checkout Overview
1
How Mobile Checkout Works
on and support SSL connections. However, not all devices meet these standards or
have implemented these standards to the associated specification.
How Mobile Checkout Works
1. After selecting products to purchase, your customers click a Checkout with PayPal link or
button on your mobile site or in a Short Message Service (SMS) text message.
2. They are transferred to PayPal, where they log in, review and select their payment method
and the correct shipping address.
3. The customer is returned to your mobile site to complete the transaction. PayPal returns to
you the shipping address, email, and other customer information needed to fulfill the order.
Availability
Only authorized business and premier merchants have access to the Mobile Checkout API. For
more information, contact your PayPal Account Manager.
Customer Activation for Mobile Checkout
Because numeric characters are easier to enter on a phone than an alphanumeric password, the
PayPal Mobile Checkout flow encourages customers to create a numeric PIN to use for future
transactions. The process of creating a numeric PIN is known as activation. In the checkout
flow, customers can activate their phones on the PayPal website or as part of the checkout
process when using Mobile Checkout.
If the customer has previously activated their phone, they log into PayPal Mobile Checkout
using their phone number and PIN. If the customer is not activated, they must enter their
PayPal user name (email) and password. They can then optionally create a new PIN.
Depending on the information PayPal gets about the phone number from cookies or the API
call, PayPal presents either the user name and password login option or the phone number and
PIN option.
Figure 1.1 illustrates the login flow for activated customers. Figure 1.2 illustrates the login
flow for non-activated customers.
8 October 2009 Mobile Checkout Developer Guide
FIGURE 1.1 Activated Mobile Checkout Flow
F
IGURE 1.2 Non-Activated Mobile Checkout Flow
PayPal Mobile Checkout Overview
Customer Activation for Mobile Checkout
1
Mobile Checkout Developer Guide October 2009 9
PayPal Mobile Checkout Overview
1
Mobile Checkout Processing Flow
Mobile Checkout Processing Flow
Table 1.1 shows the generic processing flow of a Mobile Checkout transaction. The Merchant
column entries in bold represent integration points, which are described in more detail in
subsequent sections.
TABLE 1.1 Mobile Checkout Processing Flow
Customer Merchant PayPal
Selects product from
merchant mobile site,
website, client, or SMS
keyword list
Displays product details and gives customer
the option to pay with PayPal.
Selects PayPal by
clicking link to open
PayPal Mobile Checkout
Logs in to PayPal flow
and selects funding.
Confirms transaction on
merchant site, if
necessary
Calls SetMobileCheckout API to
initiate transaction
Receives API call and returns response
containing transaction token.
Redirects customer to PayPal URL with
token appended
Starts PayPal flow.
Redirects customer to merchantsupplied, secure Return URL.
Calls DoMobileCheckoutPayment API
to complete transaction
Displays order confirmation page
10 October 2009 Mobile Checkout Developer Guide
PayPal Mobile Checkout Overview
Mobile Checkout Processing Flow
Figure 1.3, “Mobile Checkout Processing Flow,” illustrates the processing flow for a Mobile
Checkout Transaction.
FIGURE 1.3 Mobile Checkout Processing Flow
1
Mobile Checkout Developer Guide October 2009 11
PayPal Mobile Checkout Overview
1
Merchant Integration Points
Merchant Integration Points
This section describes the merchant integration points shown in bold in Table 1.1.
Initiating the Transaction
When the customer clicks the Checkout with PayPal link or button, initiate the PayPal
transaction with a call to the SetMobileCheckout API. You can call SetMobileCheckout
using either PayPal SOAP Web Services or the PayPal Name-Value Pair (NVP) API. The
SetMobileCheckoutRequest contains the following information:
z Shopping cart information, including billing, tax, and shipping amounts and currencies
z PayPal flow information, including Return URL and Cancel URL
IMPORTANT: Always use a secure site for the return URL. Mobile browsers may not
smoothly handle the transition from secure sites (https) to unsecure sites
(http) and may display warning messages or experience delays.
z Customer information (optional), including name, phone number, shipping address, and e-
mail)
If you include the customer’s phone number, e-mail address, or shipping address in the
SetMobileCheckout request, these values are used as defaults within the PayPal flow. See
“SetMobileCheckout Request” on page 15 for more information about specific request fields.
The SetMobileCheckout response contains a Tok en , which identifies the transaction at
subsequent integration points. The token times out after 24 hours.
Redirecting to PayPal Mobile Checkout
After the response from SetMobileCheckout, you must redirect the customer’s browser to
PayPal. The SetMobileCheckout response contains a session token field, t. Add the value
of the token to the following URL and direct the customer’s browser to it in the following
form:
https://mobile.paypal.com/wc?t=<Token>
For example:
https://mobile.paypal.com/wc?t=Q234AD23AF92821
N OTE: Redirecting the customer to https://mobile.paypal.com/wc?t=<Token>
ensures best performance. However, you can also redirect to
https://www.paypal.com/wc?t=<Token>.
PayPal gets details about the customer (such as shipping address and payment method) and
then returns control back to the ReturnURL field from the SetMobileCheckout request.
This URL should be the final review page, if provided, where the customer confirms the order
and payment, or the confirmation page.
12 October 2009 Mobile Checkout Developer Guide
Completing the Transaction
After the customer has confirmed the transaction on your mobile site, complete the transaction
by calling the DoMobileCheckoutPayment API. The DoMobileCheckoutPayment
request contains the token from the SetMobileCheckout response.
N OTE: If you do not call DoMobileCheckoutPayment, the transaction is not completed.
The token returned by SetMobileCheckout times out after 24 hours. If you call
DoMobileCheckoutPayment with a expired token, an error is returned.
PayPal returns a DoMobileCheckoutPayment response, which contains the following
information:
z Customer information (including name, shipping address, and e-mail)
z Payment information (PayerInfo type, including billing, tax, and shipping amounts, and
other transaction information)
PayPal Mobile Checkout Overview
Merchant Integration Points
1
Mobile Checkout Developer Guide October 2009 13
PayPal Mobile Checkout Overview
1
Merchant Integration Points
14 October 2009 Mobile Checkout Developer Guide
Loading...