PayPal Express Checkout - 2012 Advanced Features Guide
Express Checkout
Advanced Features
Guide
Last updated: April 2012
PayPal Express Checkout Advanced Features Guide
Document Number: 10121.en_US-201204
© 2010-2012 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, L2449, 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Chapter 1 Customizing Express Checkout . . . . . . . . . . . . . . . 9
PayPal Review Page Order Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Special Instructions to Merchant. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Integrating Order Details into the Express Checkout Flow . . . . . . . . . . . . . . . 11
Providing Gift Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Obtaining Buyer Consent to Receive Promotional Email . . . . . . . . . . . . . . . . . . 15
Overriding Your Customer Service Number . . . . . . . . . . . . . . . . . . . . . . . . . 16
Adding a Survey Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
PayPal Page Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Custom Page Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Individual Page Style Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Changing the Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Handling Shipping Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Confirmed Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Suppressing the Buyer’s Shipping Address . . . . . . . . . . . . . . . . . . . . . . . 23
Shipping Address Override . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Automatically Filling Out Shipping and Contact Information . . . . . . . . . . . . . . . . . 25
Buyer Pays on PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Express Checkout Redirect to Let Buyers Pay on PayPal. . . . . . . . . . . . . . . . 28
Chapter 2 Express Checkout on Mobile Devices . . . . . . . . . . . .29
About the Express Checkout Experience on Mobile Devices . . . . . . . . . . . . . . . . 29
Buyer Pays on Your Site. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Buyer Pays on PayPal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Mobile Platforms Supported by Express Checkout . . . . . . . . . . . . . . . . . . . . . 30
About Mobile Express Checkout Integration. . . . . . . . . . . . . . . . . . . . . . . . . 31
Express Checkout Advanced Features Guide April 2012 3
Contents
Integrating Express Checkout With Your Mobile Website . . . . . . . . . . . . . . . . . . 31
Enabling PayPal Account Optional Checkout on Mobile Devices . . . . . . . . . . . . . . 34
Request Fields Supported by Express Checkout on Mobile Devices . . . . . . . . . . . . 36
NVP Request Fields Supported by Express Checkout on Mobile Devices . . . . . . . 37
SOAP Request Fields Supported by Express Checkout on Mobile Devices . . . . . . 39
Locales Supported by Express Checkout on Mobile Devices . . . . . . . . . . . . . . . . 40
Locale Codes Not Supported by Express Checkout on Mobile Devices . . . . . . . . 40
Handling Locales Not Supported by Express Checkout on Mobile Devices. . . . . . . 40
Features Not Supported by Express Checkout on Mobile Devices . . . . . . . . . . . . . 41
Chapter 3 Handling Recurring Payments . . . . . . . . . . . . . . . .43
How Recurring Payments Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Recurring Payments Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Options for Creating a Recurring Payments Profile . . . . . . . . . . . . . . . . . . . . . 45
Specifying the Regular Payment Period . . . . . . . . . . . . . . . . . . . . . . . . . 45
Including an Optional Trial Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Specifying an Initial Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Maximum Number of Failed Payments . . . . . . . . . . . . . . . . . . . . . . . . . 46
Billing the Outstanding Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Identifying Items as Digital or Physical Goods. . . . . . . . . . . . . . . . . . . . . . 47
Recurring Payments With the Express Checkout API . . . . . . . . . . . . . . . . . . . . 47
Initiating the Processing Flow With SetExpressCheckout . . . . . . . . . . . . . . . 49
Redirecting the Buyer to PayPal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Getting Buyer Details Using GetExpressCheckoutDetails. . . . . . . . . . . . . . . . 51
Creating the Profiles With CreateRecurringPaymentsProfile . . . . . . . . . . . . . . 51
Recurring Payments Profile Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Getting Recurring Payments Profile Information. . . . . . . . . . . . . . . . . . . . . . . 53
Modifying a Recurring Payments Profile. . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Updating Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Updating the Billing Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Billing the Outstanding Amount of a Profile . . . . . . . . . . . . . . . . . . . . . . . . . 55
Recurring Payments Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Chapter 4 Reference Transactions . . . . . . . . . . . . . . . . . . . 57
Introduction to Reference Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Reference Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Billing Agreements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
4 April 2012Express Checkout Advanced Features Guide
Contents
API Operations for Reference Transactions. . . . . . . . . . . . . . . . . . . . . . . 58
Setting Up a Billing Agreement Using the Express Checkout API . . . . . . . . . . . . . . 59
Initiating a Payment Using a Reference Transaction . . . . . . . . . . . . . . . . . . . . 60
About Cancelling Agreements and Getting the Billing Address . . . . . . . . . . . . . . . 61
Canceling a Billing Agreement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Obtaining the Most Recent Billing Address . . . . . . . . . . . . . . . . . . . . . . . 62
Chapter 5 Implementing Parallel Payments . . . . . . . . . . . . . .63
About Parallel Payments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
What Is and What Is Not Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Post-Integration Experience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Name-Value Pair Syntax Supporting Parallel Payments. . . . . . . . . . . . . . . . . . . 65
Integrating Parallel Payments by Using the NVP API . . . . . . . . . . . . . . . . . . . . 66
Integrating Parallel Payments by Using the SOAP API . . . . . . . . . . . . . . . . . . . 68
Best Practices for Online Travel Agencies Implementing Parallel Payments . . . . . . . . 72
Styles of Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Payment Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Chapter 6 Integrating giropay with Express Checkout . . . . . . . . .75
giropay Page Flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
giropay Payment Page Flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Canceled or Unsuccessful giropay Payment Page Flow . . . . . . . . . . . . . . . . 76
giropay Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Initiate the Flow with SetExpressCheckout . . . . . . . . . . . . . . . . . . . . . . . 76
Redirect the Buyer to PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Complete the Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Receive Transaction Status Notification . . . . . . . . . . . . . . . . . . . . . . . . . 77
Chapter 7 Implementing the Instant Update API . . . . . . . . . . . . 79
About the Instant Update API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Integration Steps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Post-Integration Checkout Experience . . . . . . . . . . . . . . . . . . . . . . . . . 80
How the Callback Works in the Express Checkout Flow. . . . . . . . . . . . . . . . . . . 82
Following Instant Update API Best Practices . . . . . . . . . . . . . . . . . . . . . . . . 83
Setting Up the Callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
GetExpressCheckoutDetails and DoExpressCheckoutPayment Changes . . . . . . . 85
Express Checkout Advanced Features Guide April 2012 5
Contents
Other Callback Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Using the Callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
SetExpressCheckout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Callback Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Callback Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Chapter 8 Payment Review . . . . . . . . . . . . . . . . . . . . . . . 91
Handling Payment Review. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Chapter 9 Express Checkout Dynamic Image Integration . . . . . . . 95
Dynamic Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Configuring the Dynamic Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Set Up the Default Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Set Up Image for Dynamic Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Change the Locale. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Provide Incentive Eligibility Feedback to Buyer . . . . . . . . . . . . . . . . . . . . . 97
Choose the Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Dynamic Image Command Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Dynamic Image Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Locale Codes and Priorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Chapter 10 Immediate Payment . . . . . . . . . . . . . . . . . . . . 101
Overview of Immediate Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
About Immediate Payment For Third-Party Checkout . . . . . . . . . . . . . . . . . . . .101
Integrating Immediate Payment for Third-Party Checkout. . . . . . . . . . . . . . . . . .103
The Call to SetExpressCheckout . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
The Call to DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . . . . .104
About Immediate Payment For Express Checkout . . . . . . . . . . . . . . . . . . . . .104
Revision History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
6 April 2012Express Checkout Advanced Features Guide
Preface
About This Guide
This document describes advanced features of Express Checkout integration.
Intended Audience
This document is for merchants and developers implementin g Exp ress Checko ut wh o wan t to
learn about its extra features, which can enhance their integrations with PayPal.
Where to Go for More Information
Express Checkout Integration Guide
Name-Value Pair API Developer Guide
SOAP API Developer Reference
Merchant Setup and Administration Guide
Documentation Feedback
Help us improve this guide by sending feedback to:
documentationfeedback@paypal.com
Express Checkout Advanced Features Guide April 2012 7
Documentation Feedback
8 April 2012 Express Checkout Advanced Features Guide
Customizing Express Checkout
1
You can specify options in Express Checkout API requests that change the appearance,
behavior, and flow of the checkout process.
PayPal Review Page Order Details
When a buyer logs in to PayPal to check out, you can present the buyer with detailed
information about each item being purchased. PayPal order details are available with API
version 53.0 or later.
NOTE: The DoExpressCheckoutPayment request includes the same order details as
SetExpressCheckout. PayPal recommends that you submit the same parameters in
both API calls.
The following diagram shows all of the details that you can include:
Express Checkout Advanced Features Guide April 2012 9
Customizing Express Checkout
1
PayPal Review Page Order Details
(1) – Item name. The item name can identify this item to distinguish it from other line items in
the order.
(2) – Item number. Each item can be further identified by an item number. If the item is an
eBay auction item, it is recommended that you provide the eBay item number in this field.
(3) – Item description. This field identifies which of several items the buyer is purchasing. For
example, you may be offering an item in different sizes. Knowing the size helps the buyer
decide whether the one they selected was appropriate. If the item is an eBay auction item, it is
recommended that you provide the phrase “eBay item” in this field.
(4) – Item unit price. This field specifies exactly how much one unit of the item costs. It can be
a positive or negative value but not zero.
(5) – Item unit quantity. This field identifies the number of units the buyer is ordering.
PayPal calculates the value in the Amount (6) column as the product of line-item unit price
and line-item unit quantity.
You can also show other detailed information about the order:
(7) – Item total and tax, which are the total of all items in the order and the tax, respectively.
(8) – Shipping and handling, which is the sum of the shipping and handling amounts.
NOTE: You must determine actual shipping and handling amounts.
10 April 2012 Express Checkout Advanced Features Guide
(9) – Shipping discount. If the buyer is receiving a discount on shipping, the value appears as a
credit in this field.
(10) – Insurance. This field shows the insurance fee when there is insurance on shipping.
(11) – Total. This is the total of the order, including shipping, handling, tax, and other price
adjustment-related items.
NOTE: The Enter gift certificate, reward, or discount link enables the buyer to redeem
certificates, rewards, or discounts that PayPal issues. The link does not enable the
buyer to redeem incentives that you issue.
Special Instructions to Merchant
You can allow the buyer to send you special instructions about an order. This feature is
especially helpful to buyers who want to customize merchandise. A buyer also might want to
tell you to ship their order at a later date because they are out of the country.
NOTE: Users of this feature should be sure to read the instructions the buyer sends.
This feature appears as the link on the Review your information page. When the buyer clicks
Add, a Note to seller text box opens in which the buyer can enter special instructions to the
merchant and click Save. The instructions are returned in the responses to
GetExpressCheckoutDetails and DoExpressC heckoutPayment.
Customizing Express Checkout
PayPal Review Page Order Details
1
Integrating Order Details into the Express Checkout Flow
To integrate order details into the checkout flow, pass any of the following Express Checkout
parameters to SetExpressCheckout.
NVP Field SOAP Field Description and Comments
L_PAYMENTREQUEST_
L_PAYMENTREQUEST_
L_PAYMENTREQUEST_
n_NAMEm Name Item name.
n_NUMBERm Number Item number.
n_DESCm Description Item description.
The DESC (NVP) and OrderDescription
(SOAP) fields still exist for backwards
compatibility. However, L_DESCn and
Description enable you to provide a more
precise description for each different item
purchased, such as hiking boots or
cooking utensils rather than one general
purpose description such as camping
supplies.
Express Checkout Advanced Features Guide April 2012 11
Customizing Express Checkout
1
PayPal Review Page Order Details
NVP Field SOAP Field Description and Comments
L_PAYMENTREQUEST_n_AMTm Amount Item unit price. PayPal calculates the product
of the item unit price and item unit quantity
(below) in the Amount column of the cart
review area. The item unit price can be a
positive or a negative value, but not 0. You
may provide a negative value to reflect a
discount on an order, for example.
L_PAYMENTREQUEST_
ITEMAMT ItemTotal Sum of costs of all items in this order.
TAXAMT TaxTotal Sum of tax for all items in this order.
SHIPPINGAMT ShippingTotal T otal shipping cost for this order (8). PayPal
PAYMENTREQUEST_
PAYMENTREQUEST_
PAYMENTREQUEST_
PAYMENTREQUEST_
n_QTYm Quantity Item unit quantity.
calculates the sum of the shipping cost and the
handling cost.
Although you may change the value later, try
to pass in a shipping amount that is
reasonably accurate.
n_HANDLINGAMT HandlingTotal Total handling cost for this order.
n_SHIPDISCAMT ShippingDiscount Shipping discount for this order. You specify
this value as a negative number.
n_INSURANCEAM T InsuranceTotal Total shipping insurance cost for this order.
n_AMT OrderTotal T otal of order, including shipping, handling,
tax, and any other billing adjustments such as
a credit due.
If you pass the generic order description parameter (PAYMENTREQUEST_n_DESC) along with
any two of the following line-item parameters, the order description value does not display.
L_PAYMENTREQUEST_n_NAMEm
L_PAYMENTREQUEST_n_NUMBERm
L_PAYMENTREQUEST_n_DESCm
If you pass in unit price information (L_PAYMENTREQUEST_n_ AMTm) without passing in the
unit quantity (L_PAYMENTREQUEST_
n_QTYm), the unit price does not display. To show both
values, you must pass in values for both parameters. You can pass in a value of 1 even if the
item purchase is uncountable.
The following example shows how to set line-item parameters in the call to
SetExpressCheckout.
12 April 2012 Express Checkout Advanced Features Guide
Customizing Express Checkout
Request Parameters
[requiredSecurityParameters]
&METHOD=SetExpressCheckout
&RETURNURL=http://...
&CANCELURL=http://...
&PAYMENTREQUEST_0_PAYMENTACTIO N=Sale
&L_PAYMEN TREQUEST_0_NAME0=10% Decaf Kona Blend Coffee
&L_PAYMEN TREQUEST_0_NUMBER0=62 3083
&L_PAYMEN TREQUEST_0_DESC0=Size : 8.8-oz
&L_PAYMEN TREQUEST_0_AMT0=9.95
&L_PAYMEN TREQUEST_0_QTY0=2
&L_PAYMEN TREQUEST_0_NAME1=Coffee Fi lter bags
&L_PAYMEN TREQUEST_0_NUMBER1=62 3084
&L_PAYMEN TREQUEST_0_DESC1=Size : Two 24-piece box es
&L_PAYMEN TREQUEST_0_AMT1=39.70
&L_PAYMEN TREQUEST_0_QTY1=2
&PAYMENTR EQUEST_0_ITEMAMT=99.3 0
&PAYMENTR EQUEST_0_TAXAMT=2.58
&PAYMENTR EQUEST_0_SHIPPINGAMT= 3.00
&PAYMENTR EQUEST_0_HANDLINGAMT= 2.99
&PAYMENTR EQUEST_0_SHIPDISCAMT= -3.00
&PAYMENTR EQUEST_0_INSURANCEAMT =1.00
&PAYMENTR EQUEST_0_AMT=105.87
&PAYMENTR EQUEST_0_CURRENCYCODE =USD
&ALLOWNOT E=1
Providing Gift Options
1
Response Parameters
[successResponseFields]
&TOKEN=EC-17C76533PL706494P
Related information:
"Providing Gift Options" on page 13
"Following Instant Update API Best Practices" on page 83
"Setting Up the Callback" on page 84
Providing Gift Options
You can provide the buyer with gift options on PayPal. To use this feature, you must
implement line-item details.
NOTE: Gift options are available with API Version 61.0 or later.
You can enable any of the following gift options:
Gift message – This feature displays a text box in which the buyer can enter a gift message.
Gift receipt – This feature provides a checkbox for the buyer to check if they would like a
gift receipt included.
Express Checkout Advanced Features Guide April 2012 13
Customizing Express Checkout
1
Providing Gift Options
Gift wrap – This feature provides a checkbox for the buyer to check if they would like to
have the gift wrapped. The gift wrap feature can include a label describing the gift
wrapping, for example, “Decorator box and bow.” Optionally, you can provide the amount
to be charged to the buyer for gift wrapping.
The following SetExpressCheckout request example sets these options:
Request Parameters
[requiredSecurityParameters]
&METHOD=S etExpressCheckout
&RETURNURL=https://...
&CANCELURL=https://...
&PAYMENTREQUEST_0_AMT=10.00
&PAYMENTREQUEST_0_CURRENCYCODE =USD
&PAYMENTREQUEST_0_PAYMENTACTIO N=Sale
&GIFTMESS AGEENABLE=1
&GIFTRECE IPTENABLE=1
&GIFTWRAP ENABLE=1
&GIFTWRAP NAME="Bow and Ribbon"
&GIFTWRAP AMOUNT=6.00
Response Parameters
[successResponseFields]
&TOKEN=EC-17C76533PL706495P
The following figure shows how the gift options appear to the buyer.
NOTE: You can also configure this option from your profile. For details, see the Merchant
Setup and Administration Guide.
14 April 2012 Express Checkout Advanced Features Guide
Customizing Express Checkout
Obtaining Buyer Consent to Receive Promotional Email
Related information:
"PayPal Review Page Order Details" on page 9
Obtaining Buyer Consent to Receive Promotional Email
You can obtain the buyer ’s consent to receive email promotions on PayPal pages. PayPal
returns the email address in the response to GetExpressCheckoutDetails and
DoExpressCheckoutPayment.
NOTE: Obtaining buyer consent to receive promotional email is available with API Version
61.0 or later.
To obtain the buyer’s email address, set the BUYEREMAILOPTINENABLE field to 1 in the call
to SetExpressCheckout.
The following request example sets this field:
Request Parameters
[requiredSecurityParameters]
&METHOD=S etExpressCheckout
&RETURNURL=https://...
&CANCELURL=https://...
&PAYMENTREQUEST_0_AMT=10.00
&PAYMENTREQUEST_0_CURRENCYCODE =USD
&PAYMENTREQUEST_0_PAYMENTACTIO N=Sale
&BUYEREMA ILOPTINENABLE=1
1
Response Parameters
[successResponseFields]
&TOKEN=EC-17C76533PL706495P
The following figure shows how this appears to the buyer in the cart review area.
Express Checkout Advanced Features Guide April 2012 15
Customizing Express Checkout
1
Overriding Your Customer Service Number
NOTE: You can also configure this feature in your profile. For details, see the Merchant Setup
and Administration Guide.
Overriding Your Customer Service Number
You can display your Customer Service number to the buyer on Express Checkout pages by
configuring it in your profile. You can override this number by specifying another number in
the SetExpressCheckout request.
NOTE: This feature is available with API Version 61.0 or later.
Displaying your Customer Service number to the buyer enables you to quickly answer the
buyer’s questions through a telephone call. To override the Customer Service number
configured in your profile with a different number on Express Checkout pages, set the
CUSTOMERSERVICENUMBER field in the call to SetExpres sCheckout.
The following request example sets this field:
16 April 2012 Express Checkout Advanced Features Guide
Request Parameters
[requiredSecurityParameters]
&METHOD=S etExpressCheckout
&RETURNURL=https://...
&CANCELURL=https://...
&PAYMENTREQUEST_0_AMT=10.00
&PAYMENTREQUEST_0_CURRENCYCODE =USD
&PAYMENTREQUEST_0_PAYMENTACTIO N=Sale
&CUSTOMER SERVICENUMBER=1-800-F LOWERS
Response Parameters
[successResponseFields]
&TOKEN=EC-17C76533PL706494P
NOTE: For details on configuring the Customer Service number on the PayPal Profile page,
see the
Merchant Setup and Administration Guide.
Adding a Survey Question
Customizing Express Checkout
Adding a Survey Question
1
You can add one survey question to the PayPal pages. PayPal returns the choice that the buyer
selected in the response to GetExpressCheckoutDetails and
DoExpressCheckoutPayment.
NOTE: This feature is available with API Version 61.0 or later.
The survey question displays in the format of a text string on the PayPal Review your
information page. The buyer responds by selecting from choices in a drop-down menu.
To enable the display of the survey question and choices, set the SURVEYENABLE field to 1 in
the call to SetExpressCheckout.
Set the SURVEYENABLE field to 1 in the call to SetExpressCheckout.
Set SURVEYQUESTION to the string containing your question.
Provide at least two L_SURVEYCHOICEn options from which the buyer can select one.
The following request example sets these fields:
Request Parameters
[requiredSecurityParameters]
&METHOD=S etExpressCheckout
&RETURNURL=https://...
&CANCELURL=https://...
&PAYMENTREQUEST_0_AMT=10.00
&PAYMENTREQUEST_0_CURRENCYCODE =USD
&PAYMENTREQUEST_0_PAYMENTACTIO N=Sale
&SURVEYEN ABLE=1
&SURVEYQU ESTION="How did you h ear about us?"
&L_SURVEY CHOICE0="friend"
&L_SURVEY CHOICE1="newspaper ad"
Express Checkout Advanced Features Guide April 2012 17
Customizing Express Checkout
1
PayPal Page Style
Response Parameters
[successResponseFields]
&TOKEN=EC-17C76533PL706495P
The survey question appears to the buyer in the cart review area.
NOTE: You can also configure this feature in your profile. For details, see the Merchant Setup
and Administration Guide.
PayPal Page Style
You can change the overall appearance of the PayPal pages by defining a custom page style or
by customizing individual page style characteristics.
You define a custom page style in your profile and pass the resulting page style name when
you call SetExpressCheckout. Typically you customize individual page style
characteristics in your profile as well. However, you can also call SetExpressCheckout and
pass in individual page characteristics dynamically.
Custom Page Style
When your buyer logs in to PayPal to check out, you can make the PayPal pages the buyer sees
appear to have a similar look and feel to those on your website. You can customize any of
these page characteristics and save the results as a Page Style Name. You can define up to
three unique Page Style Names, in which you can specify the following characteristics:
Header image
Header border color
Header background color
Page background color
For instructions on how to customize page styles and create Page Style Names, see the
Merchant Setup and Administration Guide.
To set a custom page style in a call to SetExpressCheckout:
1. Include the optional PAGESTYLE parameter in the call to SetExpressCheckout.
2. Set PAGESTYLE to the Page Style Name you defined in your account.
The following example sets PAGESTYLE to the Page Style Name:
18 April 2012 Express Checkout Advanced Features Guide
Request Parameters
[requiredSecurityParameters]
&METHOD=S etExpressCheckout
&RETURNURL=https://...
&CANCELURL=https://...
&PAYMENTREQUEST_0_AMT=10.00
&PAYMENTREQUEST_0_CURRENCYCODE =USD
&PAYMENTREQUEST_0_PAYMENTACTIO N=Sale
&PAGESTYL E=TestMerchant
Response Parameters
[successResponseFields]
&TOKEN=EC-17C76533PL706494P
Individual Page Style Characteristics
Typically, you create a custom page style for the PayPal pages using the custom payment
pages in your Account Profile. In cases where you do not want to use the Account Profile
option, you can specify these individual page style characteristics using variables in your
program code:
Customizing Express Checkout
PayPal Page Style
1
Logo image — a URL to an image of your logo.
Cart review area border color — your principal identifying color. PayPal blends your color
to white in a gradient fill that borders the cart review area.
To define your logo image:
1. Create a logo image up to 90 pixels wide by 60 pixels high and save it in a valid graphics
format, such as .gif, .jpg, or .png.
2. Store the URL to the image on a secure (https) server so your buyer’s web browser does not
display a message that the payment contains insecure items.
3. Assign the URL to the LOGOIMG parameter in the call to SetExpressCheckout.
To di splay the border in your principal identifying color, set the CARTBORDERCOLOR
parameter to the 6-digit hexadecimal value of that color in the call to SetExpressCheckout .
The following example sets a custom header image and adds a border color.
Request Parameters
[requiredSecurityParameters]
&METHOD=S etExpressCheckout
&RETURNURL=https://...
&CANCELURL=https://...
&PAYMENTREQUEST_0_AMT=10.00
&PAYMENTREQUEST_0_MAXAMT=...
&PAYMENTREQUEST_0_PAYMENTACTIO N=Sale
&LOGOIMG= https://www.../YourLo go.gif
&CARTBORD ERCOLOR=0000CD
Express Checkout Advanced Features Guide April 2012 19
Customizing Express Checkout
1
Changing the Locale
Response Parameters
[successResponseFields]
&TOKEN=EC-17C76533PL706494P
The figure below shows the cart review area with a custom logo and border color around it that
were set in the call to SetExpressCheckout.
Changing the Locale
You can change the locale of PayPal pages to match the language on your website.
T o change the language displayed on the PayPal pages, set the LOCALECODE parameter to one
of the following allowable values in the SetExpressCheckout call:
AU – Australia
AT – Austria
BE – Belgium
20 April 2012 Express Checkout Advanced Features Guide
BR – Brazil
CA – Canada
CH – Switzerland
CN – China
DE – Germany
ES – Spain
GB – United Kingdom
FR – France
IT – Italy
NL – Netherlands
PL – Poland
PT – Portugal
RU – Russia
US – United States
Customizing Express Checkout
Changing the Locale
1
The following 5-character codes are also supported for languages in specific countries:
– da_DK – Danish (for Denmark only)
– he_IL – Hebrew (all)
– id_ID – Indonesian (for Indonesia only)
– jp_JP – Japanese (for Japan only)
– no_NO – Norwegian (for Norway only)
– pt_BR – Brazilian Portuguese (for Portugal and Brazil only)
– ru_RU – Russian (for Lithuania, Latvia, and Ukraine only)
– sv_SE – Swedish (for Sweden only)
– th_TH – Thai (for Thailand only)
– tr_TR – Turkish (for Turkey only)
– zh_CN – Simplified Chinese (for China only)
– zh_HK – Traditional Chinese (for Hong Kong only)
– zh_TW – Traditional Chinese (for Taiwan only)
The following example sets LOCALCODE to ES (Spain).
Request Parameters
[requiredSecurityParameters]
&METHOD=S etExpressCheckout
&RETURNURL=https://...
&CANCELURL=https://...
&PAYMENTREQUEST_0_AMT=10.00
&PAYMENTREQUEST_0_CURRENCYCODE =EUR
&PAYMENTREQUEST_0_PAYMENTACTIO N=Sale
&LOCALECO DE=ES
Express Checkout Advanced Features Guide April 2012 21
Customizing Express Checkout
1
Handling Shipping Addresses
Response Parameters
[successResponseFields]
&TOKEN=EC-17C76533PL706494P
The following figure shows the Log in to PayPal page when the is set to ES:
The following figure shows the PayPal Choose a way to pay page when the LOCALECODE is
set to ES:
Handling Shipping Addresses
You can specify several shipping address options that affect the PayPal pages.
In your SetExpressCheckout request, you can specify the following options:
Require a confirmed address.
Do not display the shipping address on the review page.
Display an alternative address on the review page.
22 April 2012 Express Checkout Advanced Features Guide
Confirmed Address
A confirmed address is a shipping address that PayPal has established as belonging to the
PayPal account holder. To be protected by PayPal’s Seller Protection Policy, you must require
the shipping address to be a confirmed address.
NOTE: Because many buyers prefer to ship to a non-confirmed address (they may, for
example, be shipping a gift to someone), PayPal does not recommend requiring a
confirmed address unless you are selling high-risk merchandise. If you prefer that
confirmed addresses be used, then do not set ADDROVERRIDE.
To require a confirmed address for the shipping address, ensure that the shipping address
matches the address on record with PayPal. You can do this through your account profile, as
described in the
call to SetExpressCheckout, as follows:
1. Include the optional REQCONFIRMSHIPPING parameter in the call to
SetExpressCheckout.
2. Set REQCONFIRMSHIPPING to 1.
Customizing Express Checkout
Handling Shipping Addresses
Merchant Setup and Administration Guide. Alternately, you can set a flag in the
1
The following example shows how to require the shipping address to be a confirmed address.
NOTE: The value of REQCONFIRMSHIPPING overrides the setting in your Merchant Account
Profile.
Request Parameters
[requiredSecurityParameters]
&METHOD=S etExpressCheckout
&RETURNURL=https://...
&CANCELURL=https://...
&PAYMENTREQUEST_0_AMT=10.00
&PAYMENTREQUEST_0_PAYMENTACTIO N=Sale
&REQCONFI RMSHIPPING=1
&PAYMENTREQUEST_0_SHIPTOSTREET =1 Main St
&PAYMENTREQUEST_0_SHIPTOCITY=S an Jose
&PAYMENTREQUEST_0_SHIPTOSTATE= CA
&PAYMENTREQUEST_0_SHIPTOCOUNTR YCODE=US
&PAYMENTREQUEST_0_SHIPTOZIP=95 131
&PAYMENTREQUEST_0_SHIPTOPHONEN UM=408-967-4444
Response Parameters
[successResponseFields]
&TOKEN=EC-6UA07551EA393551U
Suppressing the Buyer’s Shipping Address
You can suppress the display of the buyer’s shipping address on the PayPal pages. You might
want to do this in these cases:
You are selling a product or service that does not require shipping.
Express Checkout Advanced Features Guide April 2012 23
Customizing Express Checkout
1
Handling Shipping Addresses
You prefer to handle addresses completely on your own and do not want to let buyers
choose from their PayPal address book.
T o suppress the display of the buyer’s shipping address, set the NOSHIPPING parameter to 1 in
the call to SetExpressCheckout. No shipping address displays on Express Checkout pages.
The following example suppresses the shipping address.
Request Parameters
[requiredSecurityParameters]
&METHOD=S etExpressCheckout
&RETURNURL=https://...
&CANCELURL=https://...
&PAYMENTREQUEST_0_AMT=10.00
&PAYMENTREQUEST_0_CURRENCYCODE =USD
&PAYMENTREQUEST_0_PAYMENTACTIO N=Sale
&NOSHIPPI NG=1
&PAYMENTREQUEST_0_SHIPTONAME=J Smith
&PAYMENTREQUEST_0_SHIPTOSTREET =1 Main St
&PAYMENTREQUEST_0_SHIPTOCITY=S an Jose
&PAYMENTREQUEST_0_SHIPTOSTATE= CA
&PAYMENTREQUEST_0_SHIPTOCOUNTR YCODE=US
&PAYMENTREQUEST_0_SHIPTOZIP=95 131
&PAYMENTREQUEST_0_SHIPTOPHONEN UM=408-967-4444
Response Parameters
[successResponseFields]
&TOKEN=EC-17C76533PL706494P
The PayPal Review your information page does not display a shipping address when
NOSHIPPING is set to 1.
Shipping Address Override
You can override the buyer’s shipping address stored on PayPal. You would want to do this i f,
for example, your website registration already requested the buyer’s shipping address.
Overriding the shipping address stored on PayPal replaces it with one you specify in the call to
SetExpressCheckout. The buyer cannot edit the overridden address.
NOTE: If you prefer to override addresses, PayPal recommends that you do not require
confirmed addresses, as described in Confirmed Address.
To override the shipping address:
1. Set the ADDROVERRIDE parameter to 1 in the call to SetExpressCheckout.
2. Set the following shipping address parameters in the call to SetExpressCheckout to the
address values you want to use for the new address.
– PAYMENTREQUEST_0_SHIPT ONAME
– PAYMENTREQUEST_0_SHIPT OSTREET
24 April 2012 Express Checkout Advanced Features Guide
Customizing Express Checkout
Automatically Filling Out Shipping and Contact Information
– PAYMENTREQUEST_0_SHIPT OCITY
– PAYMENTREQUEST_0_SHIPT OSTATE (Optional)
– PAYMENTREQUEST_0_SHIPT OCOUNTRYCODE
– PAYMENTREQUEST_0_SHIPT OZIP
– PAYMENTREQUEST_0_SHIPT OSTREET2 (Optional)
The following example overrides the shipping address with the address values shown.
Request Parameters
[requiredSecurityParameters]
&METHOD=S etExpressCheckout
&RETURNURL=https://...
&CANCELURL=https://...
&PAYMENTREQUEST_0_AMT=10.00
&PAYMENTREQUEST_0_CURRENCYCODE =USD
&PAYMENTREQUEST_0_PAYMENTACTIO N=Sale
&ADDROVERRIDE=1
&PAYMENTR EQUEST_0_SHIPTOSTREET=1 Se cond St
&PAYMENTR EQUEST_0_SHIPTOSTREET 2=Ste 210
&PAYMENTR EQUEST_0_SHIPTOCITY=San Jo se
&PAYMENTR EQUEST_0_SHIPTOSTATE= CA
&PAYMENTR EQUEST_0_SHIPTOCOUNTR YCODE=US
&PAYMENTR EQUEST_0_SHIPTOZIP=95 131
&PAYMENTREQUEST_0_SHIPTOPHONEN UM=408-967-4444
1
Response Parameters
[successResponseFields]
&TOKEN=EC-57K68322WE343022B
The PayPal Review your information page shows the shipping address parameter values you
specified in the SetExpressCheckout request.
Automatically Filling Out Shipping and Contact Information
PayPal can automatically fill out form fields for the buyer based on the buyer’s shipping
contact information passed in the call to SetExpressCheckout.
When you pass the buyer’s shipping address, telephone number and email address in the call
to SetExpressCheckout, PayPal automatically fills out this information in the debit or
credit card form fields on the PayPal Choose a way to pay page.
After the call to SetExpressCheckout, the buyer is redirected to the PayPal. On the Choose
a way to pay page, buyers having a PayPal account can log in with their email address and
password. Buyers who do not have an account can use their debit or credit card to pay and will
have their shipping and contact information filled out.
See the following SetExpressCheckout example:
Express Checkout Advanced Features Guide April 2012 25
Customizing Express Checkout
1
Automatically Filling Out Shipping and Contact Information
Request Parameters
[requiredSecurityParameters]
&METHOD=S etExpressCheckout
&RETURNURL=https://...
&CANCELURL=https://...
&PAYMENTREQUEST_0_AMT=10.00
&PAYMENTREQUEST_0_PAYMENTACTIO N=Sale
&PAYMENTR EQUEST_0_SHIPTOSTREET=1 Ma in Street
&PAYMENTR EQUEST_0_SHIPTOCITY=San Jo se
&PAYMENTR EQUEST_0_SHIPTOSTATE= CA
&PAYMENTR EQUEST_0_SHIPTOCOUNTR YCODE=US
&PAYMENTR EQUEST_0_SHIPTOZIP=95 131
&PAYMENTR EQUEST_0_EMAIL=jsmith 01@example.com
&PAYMENTR EQUEST_0_SHIPTOPHONEN UM=408-559-5948
Response Parameters
[successResponseFields]
&TOKEN=EC-6UA07551EA393551U
The figure below shows the Pay with debit or credit card section expanded with the buyer
shipping and contact fields filled out.
26 April 2012 Express Checkout Advanced Features Guide
Customizing Express Checkout
Automatically Filling Out Shipping and Contact Information
1
Express Checkout Advanced Features Guide April 2012 27
Customizing Express Checkout
1
Buyer Pays on PayPal
Buyer Pays on PayPal
With Express Checkout, you can shorten your checkout flow to let buyers complete their
purchases on PayPal. Then, you can skip your order confirmation page.
Generally, buyers select payment methods as the last step before they complete their
purchases. If you collect no additional information after buyers return from PayPal, you can
skip the confirm-order page on your website. If you collect additional information that does
not affect the payment, PayPal recommends that you collect it after buyers complete their
purchases.
The useraction URL parameter in your redirect to PayPal determines whether buyers
complete their purchases on PayPal or on your website. If you set useraction to commit,
PayPal sets the button text to Pay Now on the PayPal Review your informaton page. This
text lets buyers know that they complete their purchases if they click the button.
After PayPal redirects buyers to your site, call GetExpressCheckoutDetails and
DoExpressCheckoutPayment to have PayPal complete the payment successfully. Call
DoExpressCheckoutPayment without waiting for buyer interaction. Use information in the
GetExpressCheckoutDetails response to fill out your order confirmation page.
Express Checkout Redirect to Let Buyers Pay on PayPal
The following sample code shows the redirect to let buyers pay on PayPal:
https://www.paypal.com/cgi-bin /webscr?cmd=_expre sscheckout&useraction=commit&tok en=valueFromSetExpressCheckoutResponse
28 April 2012 Express Checkout Advanced Features Guide
Express Checkout on Mobile
2
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
Buyer Pays 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 de tails on the mobile PayPal review page, and then clicks Continue.
Express Checkout Advanced Features Guide April 2012 29
Express Checkout on Mobile Devices
2
Mobile Platforms Supported by Express Checkout
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 wi th debit or credit cards, buyers click the “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.
Related information:
"Enabling PayPal Account Optional Checkout on Mobile Devices" on page 34
Mobile Platforms Supported by Express Checkout
Express Checkout supports the mobile checkout experience on specific mobile devices and
their embedded mobile browsers only.
30 April 2012 Express Checkout Advanced Features Guide
Loading...