<< Customizing

Express Checkout on Mobile Devices

Express Checkout on mobile devices runs in mobile browsers with pages optimized for smaller mobile screens and mobile keyboards. If you have an Express Checkout implementation, you can take advantage of the mobile checkout experience with only minimal programming changes.


About the Express Checkout Experience on Mobile Devices

On mobile devices, Express Checkout provides payment pages tailored for faster checkout and for smaller mobile screens and keyboards. You can either set up the experience so that the buyer pays on your site or on PayPal.


Buyer Pays on Your Site

The Express Checkout experience on mobile devices begins on your mobile website when a buyer is ready to pay you.

With Express Checkout on mobile devices, the buyer:

  1. Clicks Checkout with PayPal on your mobile website or from your app.
  2. Enters login credentials on the mobile PayPal login page, and then clicks Log in.
  3. Reviews payment details on the mobile PayPal review page, and then clicks Continue.
  4. Confirms the order and pays on your mobile website or app.
  5. Views order confirmation on your mobile site or app.

Note To pay with debit or credit cards, buyers click "pay by card" at the bottom of the login page to enter their billing information; this flow is called PayPal account optional checkout.

Buyer Pays on PayPal

You can shorten the Express Checkout experience on mobile devices by letting buyers pay on PayPal.

When buyers pay on PayPal, the buyer:

  1. Clicks Checkout with PayPal on your mobile website or from your app.
  2. Enters login credentials on the mobile PayPal login page, and then clicks Log in.
  3. Reviews payment details on the mobile PayPal review page, and then presses Pay Now.
  4. Views order confirmation on your mobile site or app.

Mobile Platforms Supported by Express Checkout

Express Checkout supports most mobile devices in use today. In case we are not able to support an (older) device, we will fall back on the standard PayPal experience.

About Mobile Express Checkout Integration

PayPal supports several implementations of Mobile Express Checkout. You can provide a complete mobile website, or you can create a mobile phone app in which the checkout button is integrated into the app itself or is on your mobile website.

Your preferred integration determines what you must do to convert an existing Express Checkout integration to provide a mobile experience. Typically, your decision depends on whether you create a native app for the devices you want to support:

  • If you are not providing an app, you must modify your pages to the recommended size for your device. When a buyer uses Express Checkout to check out, PayPal attempts to determine whether the buyer is using a mobile device, and the kind of device, and redirects the mobile browser to PayPal's mobile Express Checkout webpages. The call to SetExpressCheckout occurs as a result of the buyer clicking Checkout with PayPal.

    Important: You cannot call SetExpressCheckout or any PayPal API directly from your app. If the page that hosts the Pay with PayPal button is on your app and not on a secure webpage on your server, you must make the call from your secure server and pass the response to your app; otherwise, the credentials used to make the call are not protected.

Integrating Express Checkout With Your Mobile Website

To integrate Express Checkout on you mobile website, specify return and cancel URLs on your mobile website in your call to SetExpressCheckout and specify the command in the redirect as cmd=_expresscheckout-mobile. Not all features of Express Checkout are supported on mobile websites.

Your mobile website should conform to the standards of the browser in which it runs; for example, Safari on an iPad or Chrome on an Android phone. It must contain a page or pages to which PayPal redirects the buyer's browser when the payment flow completes or is canceled. You specify these pages in the RETURNURL and CANCELURL fields, respectively, of your call to SetExpressCheckout.

The following steps assume you already have a working Express Checkout integration that you want to "port" to your mobile website.

To support Mobile Express Checkout integration:

  1. Change the command in your redirect to the Express Checkout flow to _expresscheckout-mobile. If the buyer checks out on PayPal, your redirect will include:
    https://www.paypal.com/cgi-bin/webscr?
    cmd=_express-checkout-mobile
    &token=valueFromSetExpressCheckoutResponse
    
    If the buyer checks out on your website, also set useraction=commit:
    https://www.paypal.com/cgi-bin/webscr?
    cmd=_express-checkout-mobile
    &useraction=commit
    &token=valueFromSetExpressCheckoutResponse
    

    Note While it is not strictly required that you change the cmd value, PayPal recommends that you make this change to improve performance.

  2. Change the RETURNURL field in your call to SetExpressCheckout to the page you want your buyer to return to on your mobile website.
    RETURNURL=https://mobileWebsitePage.html
    
  3. Change the CANCELURL field in your call to SetExpressCheckout to the page you want your buyer to return to if they cancel out of the Express Checkout payment flow.
    CANCELURL=https://mobileWebsitePage.html
    
  4. Remove any non-supported fields from your SetExpressCheckout and DoExpressCheckoutPayment calls. Include only fields for supported features.

When you redirect to PayPal and the buyer pays on PayPal, the following Login page appears on an iOS device:

When the buyer logs in to PayPal, the following Review page appears on an iOS device:

Enabling PayPal Account Optional Checkout on Mobile Devices

PayPal account optional checkout enables buyers to pay using debit and credit cards on your mobile website without logging in to PayPal, whether or not the buyer has a PayPal account. You cannot use this kind of checkout with recurring payments or reference transactions because these features require buyers to log in to PayPal to complete the initial payment.

To enable account optional checkout using Express Checkout, you must set the PayPal Account Optional preference to On in Profile > Website Payment Preferences after you log in to PayPal.

To enable account optional checkout, modify your SetExpressCheckout request to include the following information:

  1. Specify that the buyer is not required to have a PayPal account:
    SOLUTIONTYPE=Sole
  2. Specify whether the buyer lands on the checkout billing page or the PayPal mobile login page to complete the payment.
    • LANDINGPAGE=Billing places the buyer on the billing page:
       

    • LANDINGPAGE=Login places the buyer on the PayPal login page:
       

      From the PayPal mobile login page, the buyer can choose to log in to PayPal, pay with a debit or credit card, or log in to PayPal using the non-mobile payment flow. The buyer enters debit or credit card information on the billing page after clicking Pay with a card.

  3. Fill in all required fields and optional fields in the SetExpressCheckout request and call the SetExpressCheckout API operation.
  4. Redirect your buyer's browser to PayPal's mobile endpoint.

Request Fields Supported by Express Checkout on Mobile Devices

Express Checkout on mobile devices supports a subset of the API request fields that Express Checkout supports when it runs on personal computers. PayPal ignores API request fields for features that Express Checkout does not support when it runs on mobile devices.

NVP Request Fields Supported by Express Checkout on Mobile Devices

Express Checkout on mobile devices supports only these NVP fields:

Table 1. NVP SetExpressCheckout Request Fields Supported on Mobile Devices

PAYMENTREQUEST_n_AMT RETURNURL CANCELURL TOKEN
MAXAMT PAYMENTREQUEST_n_DESC PAYMENTREQUEST_n_CUSTOM PAYMENTREQUEST_n_INVNUM
REQCONFIRMSHIPPING NOSHIPPING ADDROVERRIDE LOCALECODE The following values are not supported:
  • AD – Andorra
  • AL – Albania
  • AM – Armenia
  • GE – Georgia
  • VA – Holy See
  • IN – India
  • MC – Monaco
  • MD – Moldova
  • UA – Ukraine
PAYMENTREQUEST_n_PAYMENTACTION EMAIL SOLUTIONTYPE value must be mark CHANNELTYPE value must be merchant
BRANDNAME

Table 2. NVP Address Type Fields Supported by Express Checkout on Mobile Devices

PAYMENTREQUEST_n_SHIPTOSTREET PAYMENTREQUEST_n_SHIPTOSTREET2 PAYMENTREQUEST_n_SHIPTOCITY
PAYMENTREQUEST_n_SHIPTOSTATE PAYMENTREQUEST_n_SHIPTOCOUNTRYCODE PAYMENTREQUEST_n_SHIPTOZIP
PAYMENTREQUEST_n_SHIPTOPHONENUM

Table 3. NVP Payment Details Type Fields Supported by Express Checkout on Mobile Devices

PAYMENTREQUEST_n_AMT PAYMENTREQUEST_n_CURRENCYCODE PAYMENTREQUEST_n_ITEMAMT
PAYMENTREQUEST_n_SHIPPINGAMT PAYMENTREQUEST_n_INSURANCEAMT PAYMENTREQUEST_n_SHIPDISCAMT
PAYMENTREQUEST_n_HANDLINGAMT PAYMENTREQUEST_n_TAXAMT PAYMENTREQUEST_n_DESC
PAYMENTREQUEST_n_CUSTOM PAYMENTREQUEST_n_INVNUM BUTTONSOURCE
PAYMENTREQUEST_n_NOTIFYURL PAYMENTREQUEST_n_NOTETEXT PAYMENTREQUEST_n_TRANSACTIONID
PAYMENTREQUEST_n_ALLOWEDPAYMENTMETHOD PAYMENTREQUEST_n_PAYMENTACTION PAYMENTREQUEST_n_PAYMENTREQUESTID

Table 4. NVP Payment Details Item Type Fields Supported by Express Checkout on Mobile Devices

L_PAYMENTREQUEST_n_NAMEm L_PAYMENTREQUEST_n_DESCm L_PAYMENTREQUEST_n_AMTm
L_PAYMENTREQUEST_n_NUMBERm L_PAYMENTREQUEST_n_QTYm L_PAYMENTREQUEST_n_TAXAMTm
L_PAYMENTREQUEST_n_ITEMWEIGHTVALUEm L_PAYMENTREQUEST_n_ITEMWEIGHTUNITm L_PAYMENTREQUEST_n_ITEMURLm

SOAP Request Fields Supported by Express Checkout on Mobile Devices

Express Checkout on mobile devices supports only these SOAP fields:

Table 5. SOAP SetExpressCheckout Request Fields Supported on Mobile Devices

OrderTotal ReturnURL CancelURL Token
MaxAmount OrderDescription Custom InvoiceID
Address ReqConfirmShipping NoShipping AddressOverride
LocaleCode The following values are not supported:
  • AD – Andorra
  • AL – Albania
  • AM – Armenia
  • BR – Brazil
  • GE – Georgia
  • VA – Holy See
  • IN – India
  • MC – Monaco
  • MD – Moldova
  • UA – Ukraine
PaymentAction BuyerEmail SolutionType value must be mark
ChannelType value must be merchant BrandName

Table 6. SOAP AddressType Fields Supported by Express Checkout on Mobile Devices

Street1 Street2 CityName
StateOrProvince Country PostalCode
Phone

Table 7. SOAP PaymentDetailsType Fields Supported by Express Checkout on Mobile Devices

OrderTotal ItemTotal ShippingTotal
InsuranceTotal ShippingDiscount HandlingTotal
TaxTotal OrderDescription Custom
InvoiceID ButtonSource NotifyURL
ShipToAddress PaymentDetailsItem NoteText
TransactionId AllowedPaymentMethodType PaymentAction
PaymentRequestID

Table 8. SOAP PaymentDetailsItemType Fields Supported by Express Checkout on Mobile Devices

Name Description Amount
Number Quantity Tax
ItemWeight ItemURL

Locales Supported by Express Checkout on Mobile Devices

You can set the locale for Express Checkout pages on mobile devices to any of the countries generally supported by PayPal, with a few exceptions. PayPal displays the Login page in the default language for the country that you specify. The default locale is United States.

Locale Codes Not Supported by Express Checkout on Mobile Devices

The following locale codes are not supported by Express Checkout on mobile devices:

Country or Region Code
Albania AL
Andorra AD
Armenia AM
Brazil BR
Georgia GE
Holy See (Vatican City State) VA
India IN
Moldova, Republic of MD
Monaco MC
Ukraine UA

Handling Locales Not Supported by Express Checkout on Mobile Devices

If you attempt use an unsupported locale, the following actions occur:

  • Merchants – If you set the locale code to an unsupported country, PayPal switches buyers to the full website checkout experience.
  • Buyers – If a buyer logs in with a PayPal account for an unsupported country, PayPal stops the mobile checkout experience and the buyer cannot pay.

Features Not Supported by Express Checkout on Mobile Devices

Before implementing Express Checkout on mobile devices, examine the list of features that are not supported.

Express Checkout does not support the following features when it runs on mobile devices:

  • SMS security keys for mobile PayPal login, in which buyers can sign up for an extra layer of security with a secure token. Buyers add a one-time secure code to their password or mobile PIN when they log in to PayPal. Buyers can use secure codes from hardware tokens but not from software tokens sent by SMS to the buyer's mobile phone.
  • Forgotten email or password, in which buyers can request their email address or password during checkout, before logging in to PayPal.
  • Parallel payments, which lets buyers pay multiple merchants in a single checkout session.
  • Dynamic images, which lets PayPal update the images on your website for the Checkout With Express Checkout button and PayPal acceptance mark automatically to coincide with PayPal campaigns.
  • Buyer experience enhancements, which lets you offer gift wrap, ask a survey question, or display your customer service number during checkout.
  • Custom payment page styles, which lets you change the overall appearance of the Review your information page with a custom page style or with individual page style characteristics.
  • Instant Update API, which is a callback that sends you the buyer's shipping address during checkout on PayPal and lets you respond with your actual shipping charges and handling charges.
  • International addresses, which lets buyers add international addresses during checkout after logging in to PayPal.
  • Promotional offers, which lets buyers pay with coupons, incentives, and buyer credit.
  • Dynamic currency conversion, which lets you list an item in one currency and then accept payment in a different currency.
  • Keep me logged in, in which buyers remain logged in to PayPal between transactions.

Recurring Payments >>