PayPal Express Checkout - 2010 Integration Guide
Express Checkout
Integration Guide
Last updated: May 2010
Express Checkout Integration Guide
Document Number: 100010.en_US-201005
© 2010 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 i n this document t o you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information co ntained 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 f rom 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Chapter 1 Introducing Express Checkout . . . . . . . . . . . . . . .11
The Express Checkout Experience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Express Checkout Integration Steps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Configuring and Customizing the Express Checkout Experience . . . . . . . . . . . . 13
Additional PayPal API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Express Checkout Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Checkout Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Payment Option Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Express Checkout Building Blocks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Express Checkout Buttons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Express Checkout API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Express Checkout Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Express Checkout Token Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Chapter 2 Express Checkout Button and Logo Image Integration . . .19
About PayPal Button and Logo Images . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Express Checkout Images. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Express Checkout Image Flavors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Dynamic Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Configuring the Dynamic Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Set Up the Default Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Set Up Image for Dynamic Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Change the Locale. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Feedback to Buyer Meeting an Incentive . . . . . . . . . . . . . . . . . . . . . . . . 22
Choose the Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Dynamic Image Command Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Dynamic Image Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Locale Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Express Checkout Integration Guide May 2010 3
Contents
Static PayPal Button and Mark Images Source Requirements . . . . . . . . . . . . . . . 25
Chapter 3 PayPal Name-Value Pair API Basics . . . . . . . . . . . . .27
PayPal API Client-Server Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
PayPal Name-Value Pair API Requests and Responses . . . . . . . . . . . . . . . . 28
Multiple API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Obtaining API Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Creating an API Signature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Creating an API Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Creating an NVP Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Specifying the PayPal API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Specifying an API Credential . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
URL Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
List Syntax for Name-Value Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Executing NVP API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Specifying a PayPal Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Logging API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Responding to an NVP Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Common Response Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
URL Decoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Chapter 4 Implementing the Simplest Express Checkout Integration . 37
Setting Up the Express Checkout Transaction. . . . . . . . . . . . . . . . . . . . . . . . 37
Obtaining Express Checkout Transaction Details . . . . . . . . . . . . . . . . . . . . . . 39
Completing the Express Checkout Transaction . . . . . . . . . . . . . . . . . . . . . . . 39
Chapter 5 Testing an Express Checkout Integration . . . . . . . . . .43
Chapter 6 Customizing Express Checkout . . . . . . . . . . . . . . .49
PayPal Review Page Order Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Special Instructions to Merchant. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Integrating Order Details into the Express Checkout Flow . . . . . . . . . . . . . . . 52
eBay-Issued Incentives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Integrating eBay Incentives into the Express Checkout Flow . . . . . . . . . . . . . . 56
Providing Gift Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Getting Buyer Consent to Receive Promotional Email. . . . . . . . . . . . . . . . . . . . 60
Providing Your Customer Service Number. . . . . . . . . . . . . . . . . . . . . . . . . . 60
4 May 2010 Express Checkout Integration Guide
Contents
Adding a Survey Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
PayPal Page Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Custom Page Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Individual Page Style Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Changing the Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Confirmed Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Suppressing the Buyer’s Shipping Address . . . . . . . . . . . . . . . . . . . . . . . 70
Shipping Address Override . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Automatically Filling Out the PayPal Login Page . . . . . . . . . . . . . . . . . . . . . . 73
Buyer Pays on PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Chapter 7 Implementing the Instant Update API . . . . . . . . . . . .77
About the Instant Update API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Integration Steps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Post-Integration Checkout Experience . . . . . . . . . . . . . . . . . . . . . . . . . 78
How the Callback Works in the Express Checkout Flow. . . . . . . . . . . . . . . . . . . 80
Following Instant Update API Best Practices . . . . . . . . . . . . . . . . . . . . . . . . 81
Setting Up the Callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
GetExpressCheckoutDetails and DoExpressCheckoutPayment Changes . . . . . . . 83
Other Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Using the Callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
SetExpressCheckout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Callback Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Callback Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Chapter 8 Immediate Payment . . . . . . . . . . . . . . . . . . . . .91
Overview of Immediate Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
About Immediate Payment For Third Party Checkout . . . . . . . . . . . . . . . . . . . . 91
Integrating Immediate Payment for Third-Party Checkout. . . . . . . . . . . . . . . . . . 93
The Call to SetExpressCheckout . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
The Call to DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . . . . . 94
About Immediate Payment For Express Checkout . . . . . . . . . . . . . . . . . . . . . 94
Integrating Immediate Payment for Express Checkout . . . . . . . . . . . . . . . . . . . 95
Chapter 9 Implementing Parallel Payments . . . . . . . . . . . . . . 97
About Parallel Payments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
What Is and What Is Not Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Express Checkout Integration Guide May 2010 5
Contents
Post-Integration Experience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Name-Value Pair Syntax Supporting Parallel Payments. . . . . . . . . . . . . . . . . . . 99
Integrating Parallel Payments Using the NVP API. . . . . . . . . . . . . . . . . . . . . .100
Integrating Parallel Payments Using the SOAP API . . . . . . . . . . . . . . . . . . . . .103
Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
Chapter 10 Handling Payment Settlements . . . . . . . . . . . . . . 109
Sale Payment Action for Express Checkout . . . . . . . . . . . . . . . . . . . . . . . . .109
Authorization Payment Action for Express Checkout . . . . . . . . . . . . . . . . . . . .109
Order Payment Action for Express Checkout . . . . . . . . . . . . . . . . . . . . . . . .110
Chapter 11 Handling Recurring Payments . . . . . . . . . . . . . . . 113
How Recurring Payments Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
Recurring Payments Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
Options for Creating a Recurring Payments Profile . . . . . . . . . . . . . . . . . . . . .115
Specifying the Regular Payment Period . . . . . . . . . . . . . . . . . . . . . . . . .115
Including an Optional Trial Period . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
Specifying an Initial Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
Maximum Number of Failed Payments . . . . . . . . . . . . . . . . . . . . . . . . .117
Billing the Outstanding Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
Recurring Payments With Express Checkout . . . . . . . . . . . . . . . . . . . . . . . .117
Initiating the Processing Flow With SetExpressCheckout . . . . . . . . . . . . . . .119
Redirecting the Buyer’s Browser to PayPal . . . . . . . . . . . . . . . . . . . . . . .120
Getting Buyer Details Using GetExpressCheckoutDetails. . . . . . . . . . . . . . . .121
Creating the Profiles With CreateRecurringPaymentsProfile . . . . . . . . . . . . . .121
Recurring Payments Profile Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Getting Recurring Payments Profile Information. . . . . . . . . . . . . . . . . . . . . . .122
Modifying a Recurring Payments Profile. . . . . . . . . . . . . . . . . . . . . . . . . . .123
Updating Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
Updating the Billing Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
Billing the Outstanding Amount of a Profile . . . . . . . . . . . . . . . . . . . . . . . . .124
Recurring Payments Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
6 May 2010 Express Checkout Integration Guide
Contents
Chapter 12 Using Other PayPal API Operations . . . . . . . . . . . . 127
Issuing Refunds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
Handling Payment Review. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128
Chapter 13 Integrating giropay with Express Checkout . . . . . . . . 131
giropay Page Flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
giropay Payment Page Flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
Cancelled or Unsuccessful giropay Payment Page Flow . . . . . . . . . . . . . . . .132
giropay Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
Initiate the Flow with SetExpressCheckout . . . . . . . . . . . . . . . . . . . . . . .133
Redirect the Buyer to PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
Complete the Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
Receive Transaction Status Notification . . . . . . . . . . . . . . . . . . . . . . . . .134
Express Checkout Integration Guide May 2010 7
Contents
8 May 2010 Express Checkout Integration Guide
Preface
This document describes Express Checkout integration.
Intended Audience
This document is intended for merchants and developers implementing Express Checkout.
Where to Go for More Information
For information on the administrative tasks you can perform from your PayPal account, see
the Merchant Setup and Administra tion Guide. The guide is located on the Documentation
page linked to the Library tab in Developer Central.
Revision History
Revision history for Express Checkout Integration Guide.
TABLE 1.1 Revision history
Date Description
05/11/10 Added details for integrating parallel payments using the NVP and SOAP
03/10/10 Added support for parallel payments.
01/21/2010 Added new Express Checkout fields to provide the buyer contact
10/05/2009 Added Immediate Payment.
06/30/2009 Added a section on payment review.
API, including use with airlines. Added new Immediate Payment
functionality. Updated billing agreements with functionality to obtain the
latest billing address, skip billing agreement creation, and clarify use of the
BAUpdate API.
information, gift options, promotions, and a survey question on the PayPal
pages. Added a new callback response API field providing no-shipping
details.
Edited for technical accuracy.
Removed PayPal placement guidelines.
Express Checkout Integration Guide May 2010 9
Revision History
T
ABLE 1.1 Revision history
Date Description
06/04/2009 Added a chapter on pre-populating the PayPal review page. Updated PayPal
04/30/2009 Created first edition for Enterprise-level merchants and added chapter on
04/08/2009 Added a chapter describing the Instant Update Callback API.
03/03/2009 Updated to allow useraction=continue for eBay incentives.
11/13/2008 Added information about integrating dynamic images and added
06/30/2008 Complete revision.
Review pages. Moved some customization topics out of this guide. They
are now in the Merchant Setup and Administration Guide.
reference transactions.
information about order details that can be displayed on the PayPal Review
page.
10 May 2010 Express Checkout Integration Guide
Introducing Express Checkout
1
Express Checkout is PayPal’s premier checkout solution, which streamlines the checkout
process for buyers and keeps them on the merchant’s site after making a purchase.
z The Express Checkout Experience
z Express Checkout Integration Steps
z Express Checkout Flow
z Express Checkout Building Blocks
NOTE: For information about administrative tasks you can perform from your PayPal account
such as adding users, setting up custom page styles, and managing multiple currency
balances, see the
The Express Checkout Experience
Merchant Setup and Administration Guide.
Express Checkout makes it easier for a buyers to pay online. It also enables you to accept
PayPal while retaining control of the buyer and the overall checkout flow.
Consider your buyers’ experience before implementing Express Checkout. A generic flow
probably has the following sequence of pages:
A generic checkout flow
In a typical checkout flow, a buyer:
1. Checks out from the shopping cart page
2. Provides shipping information
3. Chooses a payment option and provides billing and payment information
4. Reviews the order and pays
5. Receives an order confirmation
In an Express Checkout flow, a buyer still checks out at the beginning of the flow. However,
the buyer does not enter shipping, billing, or payment information, because PayPal provides
the stored information. This simplifies and expedites the checkout process.
Express Checkout Integration Guide May 2010 11
Introducing Express Checkout
1
Express Checkout Integration Steps
The following diagram shows the Express Checkout flow:
Express Checkout Flow
In the Express Checkout flow, the buyer:
1. Chooses Express Checkout by clicking Check out with PayPal
2. Logs into PayPal to authenticate his or her identity
3. Reviews the transaction on PayPal
NOTE: Optionally, (not shown in the diagram), the buyer can then proceed to review the
order on your site. You can also include other checkout steps, including upselling
on your Review Order page.
4. Confirms the order and pays from your site
5. Receives an order confirmation
Express Checkout Integration Steps
You can implement Express Checkout in 4 steps:
1. Place PayPal checkout buttons and PayPal payment mark images in your checkout flow.
2. For each PayPal button that you place, modify your page to handle the button click.
Use a PayPal Express Checkout API operation to set up the interaction with PayPal and
redirect the browser to PayPal to initiate buyer approval for the payment.
3. On your order confirmation page, obtain the payment authorization from PayPal and use
PayPal Express Checkout API operations to obtain the shipping address and accept the
payment.
4. Test your integration using the PayPal Sandbox before taking your pages live.
Because PayPal offers you the flexibility to control your checkout flow, you should first
understand how your current checkout flow works, then, become familiar with the Express
Checkout flow. Start by reviewing Express Checkout Flow. For additional background
information to help you get started, see Express Checkout Building Blocks.
12 May 2010 Express Checkout Integration Guide
Introducing Express Checkout
Express Checkout Integration Steps
Configuring and Customizing the Express Checkout Experience
After you implement and test your basic Express Checkout integration, you should configure
the additional features of Express Checkout to customize it to meet your needs.
Carefully evaluate each feature because the more you streamline the checkout process and
make Express Checkout seamless to buyers, the more likely your sales will increase.
At a minimum, you should:
z Set your logo on the PayPal site and provide order details in the transaction history.
z Use the PayPal confirmation page as your Order Review page to further streamline the user
experience when you do not need the benefits associated with paying on your site. This
strategy can lead to a better order completion rate, also known as a conversion rate.
Configure the look and feel of PayPal pages to match the look and feel of your site by
specifying the:
z Logo to display
z Colors for the background and border
z Language in which PayPal content is displayed
1
You should include:
z Order details, including shipping and tax, during checkout
IMPORTANT: Not displaying this information is a major cause of shopping cart
abandonment during checkout.
z Shipping information for non-digital goods, which can be your address information for the
buyer or the address on file with PayPal; if you use the address on file with PayPal, you can
specify whether or not it must be a confirmed address
You can also activate additional features, including:
z Associate a payment with an eBay auction item
z Assign an invoice number to a payment
z Accept payments with giropay (Germany only)
Additional PayPal API Operations
You can use PayPal API operations to include advanced processing and back-office processes
with Express Checkout. You can:
z Capture payments associated with authorizations and orders
z Process recurring payments
z Issue refunds, search transactions using various criteria, and provide other back-office
operations
Express Checkout Integration Guide May 2010 13
Introducing Express Checkout
1
Express Checkout Flow
Express Checkout Flow
T o implement Express Checkout, you must offer it both as a checkout option and as a payment
method. Typically, you initiate the Express Checkout flow on your shopping cart page and on
your payment options page.
You add Express Checkout to your existing flow by placing the Checkout with PayPal button
on your Shopping Cart page and by placing the PayPal mark on your Payment Methods
page. The following diagram shows the complete flow:
Complete Express Checkout flow
Make the following changes to implement the complete Express Checkout flow:
z On your Shopping Cart page, place the Checkout with PayPal button and respond to a
click by setting up the Express Checkout request and redirecting your buyer’s browser to
PayPal.
z On your Payment Methods page, associate the PayPal mark with an option. Handle
selection of the PayPal mark by setting up the Express Checkout request and redirecting
your buyer’s browser to PayPal.
z On the page your buyer returns to, obtain shipping information from PayPal and accept the
payment to complete the Express Checkout transaction.
NOTE: You also can allow the buyer to pay on the PayPal Review page; in which case, your
checkout flow can omit the Merchant Review page and proceed directly to your
Confirmation page. For more information see “Buyer Pays on PayPal” on page 75.
Checkout Entry Point
The checkout entry point is one of the places where you must implement Express Checkout.
Buyers initiate the Express Checkout flow on your shopping cart page by clicking the
Checkout with PayPal button.
The following diagram shows how Express Checkout integrates with a typical checkout flow:
14 May 2010 Express Checkout Integration Guide
Integrating Express Checkout from the Shopping Cart page
Payment Option Entry Point
The payment option entry point is one of the places where you must implement Express
Checkout. Buyers initiate the Express Checkout flow on your payment methods page by
selecting PayPal as the default option.
Introducing Express Checkout
Express Checkout Building Blocks
1
The following diagram shows how to integrate Express Checkout from your payment methods
page:
Integrating Express Checkout from the Payment Method page
Express Checkout Building Blocks
You implement Express Checkout flows with Express Checkout buttons, PayPal API
operations, PayPal commands, and tokens.
Express Checkout Integration Guide May 2010 15
Introducing Express Checkout
1
Express Checkout Building Blocks
The following conceptual diagram identifies the building blocks that you use to integrate
Express Checkout on your website:
Express Checkout Integration
A token is a value assigned by PayPal that associates the execution of API operations and
commands with a specific instance of a user experience flow.
NOTE: Tokens are not shown in the diagram.
Express Checkout Buttons
PayPal provides buttons and images for you to place on your website.
To implement the Express Checkout shopping cart experience, place the following button on
your Shopping Cart page:
To implement PayPal as a payment option, which is part of the Express Checkout experience,
associate the PayPal mark image with your payment options. PayPal recommends using radio
buttons for payment options:
16 May 2010 Express Checkout Integration Guide
Introducing Express Checkout
Express Checkout Building Blocks
Express Checkout API Operations
The PayPal API provides three API operations for Express Checkout, which sets up the
transaction, obtains information about the buyer, and handles the payment and completes the
transaction.
API Operation Description
SetExpressCheckout Sets up the Express Checkout transaction. You can specify information
to customize the look and feel of the PayPal site and the information it
displays. You must include the following inform atio n:
z URL to the page on your website that PayPal redirects to after the
buyer logs into PayPal and approves the payment successfully.
z URL to the page on your website that PayPal redirects to if the buyer
cancels.
z T otal amount of the order or your best estimate of the total. It should
be as accurate as possible.
1
GetExpressCheckout Obtains information about the buyer from PayPal, including shipping
information.
DoExpressCheckoutPayment Completes the Express Checkout transaction, including the actual total
amount of the order.
Express Checkout Command
PayPal provides a command that you use when redirecting your buyer’s browser to PayPal.
This command enables your buyer to log into PayPal to approve an Express Checkout
payment.
When you redirect your buyer’s browser to PayPal, you must specify the
_ExpressCheckout command for Express Checkout. You also specify the token that
identifies the transaction, which was returned by the SetExpressCheckout API operation.
NOTE: T o enable PayPal to redirect back to your website, you must have already invoked the
SetExpressCheckout API operation, specifying URLs that PayPal uses to redirect
back to your site. PayPal redirects to the success URL when the buyer pays on PayPal;
otherwise, PayPal redirects to the cancel URL.
If the buyer approves the payment, PayPal redirects to the success URL with the following
information:
Express Checkout Integration Guide May 2010 17
Introducing Express Checkout
1
Express Checkout Building Blocks
z The token that was included in the redirect to PayPal
z The buyer’s unique identifier (Payer ID)
If the buyer cancels, PayPal redirects to the cancel URL with the token that was included in the
redirect to PayPal.
Express Checkout Token Usage
Express Checkout uses a token to control access to PayPal and execute Express Checkout API
operations.
The SetExpressCheckout API operation returns a token, which is used by other Express
Checkout API operations and by the _ExpressCheckout command to identify the
transaction. The life of the token is approximately 3 hours.
18 May 2010 Express Checkout Integration Guide
Express Checkout Button and
2
Logo Image Integration
PayPal hosts the PayPal button and logo images that you use on your website. Using PayPal’s
buttons and logos is convenient and standardizes appearance on websites that use PayPal as a
payment option.
z About PayPal Button and Logo Images
z Dynamic Images
z Configuring the Dynamic Image
z Dynamic Image Command Reference
z Static PayPal Button and Mark Images Source Requirements
About PayPal Button and Logo Images
To inform buyers that PayPal is accepted on your website, you must place PayPal button and
logo images in your checkout flow.
PayPal Express Checkout requires that you integrate two images. The Check out with PayPal
button and the PayPal Acceptance mark.
Express Checkout Images
The Check out with PayPal button is the image you place on your shopping cart page. The US
version of the image looks like this. PayPal also provides buttons for other locales.
The PayPal Acceptance Mark is the image you place on your payment methods page. It looks
like this:
Express Checkout Image Flavors
The Check out with PayPal button and the PayPal Acceptance mark images are available in
two flavors:
z Dynamic image
Express Checkout Integration Guide May 2010 19
Express Checkout Button and Logo Image Integration
2
Dynamic Images
z Static image
The dynamic images enable PayPal to change their appearance dynamically. If, for example,
you have signed up to participate in a PayPal campaign, PayPal can change the appearance of
the image dynamically for the duration of that campaign based on parameter information you
append to the image URL. By default, the Express Checkout images appears as shown above.
The static images cannot be changed dynamically. To participate in a PayPal campaign, you
would have to manually update the image code to change the image displayed and restore the
default image when the campaign is over. The only way you can have image management
taken care of for you is to replace static images in your implementation with dynamic images.
Dynamic Images
To use dynamic images, you mus t pass information to PayPal as parameters appended to the
image URL. Your unique ID tells PayPal whether or not you are participating in events that
require image changes. Other information you pass instructs PayPal on the types of images to
return.
If, for example, you are participating in a PayPal campaign that you have signed up for with
PayPal and you have passed the appropriate parameter information to PayPal, PayPal
automatically updates the image to reflect the campaign information. When the campaign is
over, PayPal restores the default image. You are not responsible for scheduling or making
changes to your website application code before, during, o r af ter the campaign. It is all
handled for you when you set up the dynamic image.
If you require localized campaign images, you can have the localized button image display for
each country in which you participate. Simply assign the correct code for the country to the
locale parameter you append to the dynamic image URL. PayPal will return to the default
button image associated with each locale when the campaign is not available.
Configuring the Dynamic Image
To set up the dynamic image, you provide the name-value pair parameter information in the
image URL. You can pass information in the image URL for any of the following options.
z Set Up the Default Image
z Set Up Image for Dynamic Use
z Change the Locale
z Feedback to Buyer Meeting an Incentive
z Choose the Image
20 May 2010 Express Checkout Integration Guide
Express Checkout Button and Logo Image Integration
Set Up the Default Image
The following URL points to the default Check out with PayPal image:
https://fpdbs.paypal.com/dynamicimageweb?cmd=_dynamic -image
T o make the image dynamic, you need only add parameters to this URL to specify the changes
you want displayed.
To test in the Sandbox environment, send the image to the following Sandbox URL:
https://fpdbs.sandbox.paypal.com/dynamicimageweb?cmd=_dynamic-image
Set Up Image for Dynamic Use
T o set up the image URL for dynamic use, you associate it with your PayPal Secure Merchant
Account ID or pal. You can obtain your pal by getting it from the Profile page, contacting
PayPal, or calling the GetPalDetails API.
This is an example call to GetPalDetails request.
Request Parameters:
Configuring the Dynamic Image
2
[requiredSecurityParameters]
&METHOD=GetPalDetails
Response Parameters
This GetPalDetails response returns the value of PAL and your country code (LOCALE), as
shown below:
[successResponseFields]
&PAL=SFJCXFDLNFR5U
&LOCALE=en_US
1. Append the pal parameter to the image URL, and set the parameter to the value of your
encrypted PayPal merchant account number.
https://fpdbs.paypal.com/dynamicimagewe b?cmd=_dynamicimage&pal=SFJCXFDLNFR5U
2. You can optionally change the value of LOCALE. See Change the Locale for details.
3. Place the URL with parameter informa tion at the appropriate image locations in your web
application.
The pal alerts PayPal to campaigns in which you are participating. PayPal obtains this
information from your account and replaces the default image with the appropriate
campaign image during that campaign.
NOTE: If you pass in a pal value matching a merchant account that is not yours, PayPal
displays the image for that account. Be sure to pass the pal value matching your
account.
Express Checkout Integration Guide May 2010 21
Express Checkout Button and Logo Image Integration
2
Dynamic Image Command Reference
Change the Locale
To specify the locale of the image, append the locale parameter set to the code for the
appropriate country to the image URL. If a country does not have a localized image or if you
do not pass a locale value, the default US image displays. This example displays the image
for the Spanish locale:
https://fpdbs.paypal.com/dynamicimagewe b?cmd=_dynamicimage&pal=SFJCXFDLNFR5U&locale=es_ES
If you are participating in a campaign across multiple countries, you can set the image locale
for each country in which you participate. PayPal returns the default image associated with the
locale when the campaign is over.
Feedback to Buyer Meeting an Incentive
Pass the order total amount in the ordertotal parameter so PayPal can determine if the
buyer is eligible for an incentive. Say, for example, that you are participating in a campaign in
which the buyer is eligible for a 20% discount when thei r order meets a minimum of $50.00.
You can pass that value to PayPal in the ordertotal parameter, as shown here:
https://fpdbs.paypal.com/dynamicimagewe b?cmd=_dynamicimage&pal=SFJCXFDLNFR5U&ordertotal=50.0 0
When a buyer’s order meets or exceeds $50.00, PayPal displays the incentive image informing
the buyer of their eligibility for the discount. When a buyer’s order is less than $50.00, PayPal
displays the default image.
NOTE: If ordertotal is not passed, PayPal does not display the incentive image even if the
buyer is eligible for the incentive.
Choose the Image
To specify the image that you want to display, set the value of buttontype. This example
sets buttontype to the PayPal Acceptance Mark image:
https://fpdbs.paypal.com/dynamicimagewe b?cmd=_dynamicimage&pal=SFJCXFDLNFR5U&buttontype=ecma rk
The default value for buttontype is ecshortcut.
Dynamic Image Command Reference
To set up the information that enables dynamic images, you add name-value pairs to the
dynamic image URL. Parameters and values are described below.
22 May 2010 Express Checkout Integration Guide
Express Checkout Button and Logo Image Integration
Dynamic Image Parameters
The table below describes the dynamic image name-value pair parameters.
Dynamic-Image Command Variable Descriptions
pal Type: encrypted PayPal account number
(Optional) Unique identification number. When merchants sign up for a PayPal
business account, PayPal assigns them an account number. The pal value
represents the pay-to merchant account, not a third party making the API request
on behalf of this merchant.
NOTE: If pal is not passed, PayPal displays the default Check out with PayPal
button.
ordertotal Type: numeric
(Optional) The total cost of the order to the buyer. If shipping and sales tax are
known, include them in this value. If not, this value should be the current subtotal
of the order.
NOTE: If ordertotal is not passed, PayPal does not display the incentive
image even if the buyer is eligible for the incentive.
Character length and limitations: Must not exceed $10,000.00 USD in any
currency. No currency symbol.Must have two decimal places, decimal separator
must be a period (.), and the optional thousands separator must be a comma(,).
Dynamic Image Command Reference
2
locale Ty pe: string
(Optional) The five-character locale code. See Locale Codes.
Any other values default to US.
NOTE: The merchant can participate in one campaign per country.
buttontype Type: string
(Optional) Indicates a dynamic image. The values are:
z (Default) Check out with PayPal button image: ecshortcut
z PayPal Acceptance Mark image: ecmark
Locale Codes
The table below lists the locale values. Country code is the two-letter code for the country.
Language priority is the language associated with the country code where language_0 is the
default.
Express Checkout Integration Guide May 2010 23
Express Checkout Button and Logo Image Integration
2
Dynamic Image Command Reference
Country codes, language priorities, and locale values
Country code Language priority Locale
AT language_0 de_DE
AT language_1 en_US
AU language_0 en_AU
BE language_0 en_US
BE language_1 nl_NL
BE language_2 fr_FR
C2 language_0 en_US
C2 language_1 zh_XC
C2 language_2 fr_XC
C2 language_3 es_XC
CH language _0 de_DE
CH language_1 fr_FR
CH language_2 en_US
CN language_0 zh_CN
default language_0 en_US
default language_1 fr_XC
default language_2 es_XC
default language_3 zh_XC
DE language_0 de_DE
DE language_1 en_US
ES language_0 es_ES
ES language_1 en_US
FR language_0 fr_FR
FR language_1 en_US
GB language _0 en_GB
GF language_0 fr_FR
GF language_1 en_US
GI language_0 en_US
GP language_0 fr_FR
GP language_1 en_US
24 May 2010 Express Checkout Integration Guide
Express Checkout Button and Logo Image Integration
Static PayPal Button and Mark Images Sour ce Requirements
Country code Language priority Locale
IE language_0 en_US
IT language_0 it_IT
IT language_1 en_US
JP language_0 ja_JP
JP language_1 en_US
MQ language_0 fr_FR
MQ language_1 en_US
NL language_0 nl_NL
NL language_1 en_US
PL language_0 pl_PL
PL language_1 en_US
RE language_0 fr_FR
2
RE language_1 en_US
US language_0 en_US
US language_1 fr_XC
US language_2 es_XC
US language_3 zh_XC
Static PayPal Button and Mark Images Source Requirements
Using the static image code on the PayPal servers eliminates the need for you to maintain them
yourself.
PayPal requires that you use the Check out with PayPal and the PayPal acceptance mark
images hosted on secure PayPal servers. When the images are updated, the changes appear
automatically in your application.
Do not host copies of the PayPal images locally on your servers. Outdated PayPal images
reduces buyer confidence in your site.
Follow the links in the table below to obtain HTML code that displays the PayPal-hosted
images.
HTML Code for Displaying PayPal-Hosted Button and Mark Images
Country Links to HTML Code for Displaying PayPal-Hosted Images
Australia https://www.paypal.com/au/cgi-
bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
Express Checkout Integration Guide May 2010 25
Express Checkout Button and Logo Image Integration
2
Static PayPal Button and Mark Images Source Requirements
Country Links to HTML Code for Displaying PayPal-Hosted Images
Austria https://www.paypal.com/at/cgi-
bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
Belgium https://www.paypal.com/be/cgi-
bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
Canada https://www.paypal.com/ca/cgi-
bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
China https://www.paypal.com/cn/cgi-
bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
France https://www.paypal.com/fr/cgi-
bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
Germany https://www.paypal.com/de/cgi-
bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
Italy https://www.paypal.com/it/cgi-
bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
Japan https://www.paypal.com/j1/cgi-
bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
Netherlands https://www.paypal.com/nl/cgi-
bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
Poland https://www.paypal.com/pl/cgi-
bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
Spain https://www.paypal.com/es/cgi-
bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
Switzerland https://www.paypal.com/ch/cgi-
bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
United Kingdom https://www.paypal.com/uk/cgi-
bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
United States https://www.paypal.com/us/cgi-
bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside
26 May 2010 Express Checkout Integration Guide
3
PayPal Name-Value Pair API Basics
The Name-Value Pair (NVP) API provides parameter-based association between request and
response fields of a message and their values. The request message is sent via the API from
your website and a response message is returned by PayPal using a client-server model in
which your site is a client of the PayPal server.
NOTE: The PayFlow API also uses name-value pairs to provide parameter-based association
between request and response fields of a message and their values; however, the
PayFlow API is not the same as the NVP API; for more information about the
PayFlow API, see
z PayPal API Client-Server Architecture
z Obtaining API Credentials
z Creating an NVP Request
z Executing NVP API Operations
z Responding to an NVP Response
Websit e Payments Pro Pay flo w Edition Developer Guide.
PayPal API Client-Server Architecture
The PayPal API uses a client-server model in which your website is a client of the PayPal
server.
A page on your website initiates an action on a PayPal API server by sending a request to the
server. The PayPal server responds with a confirmation that the requested action was taken or
or indicates that an error occurred. The response might also contain additional information
related to the request. The following diagram shows the basic request-response mechanism.
For example, you might want to obtain the buyer’s shipping address from PayPal. You can
initiate a request specifying an API operation that gets buyer details. The response from the
PayPal API server contains information about whether the request was successful. If the
operation succeeds, the response contains the requested information; in this case, the buyer’s
shipping address. If the operation fails, the response contains one or more error messages.
Express Checkout Integration Guide May 2010 27
PayPal Name-Value Pair API Basics
3
PayPal API Client-Server Architecture
PayPal Name-Value Pair API Requests and Responses
To perform a PayPal NVP API operation, you send an NVP-formatted request to a PayPal
NVP server and interpret the response.
In the following diagram, your website generates a request. The request is executed on a
PayPal server and the response is returned to your site.
The request identifies
z The name of the API operation to be performed and its version; for example,
SetExpressCheckout for version 62.0
z Credentials that identify the PayPal account making the request
z Request-specific information that controls the API operation to be performed
A PayPal API server performs the operation and returns a response. The response contains
z An acknowledgement status that indicates whether the operation was a success or failure
and whether any warning messages were returned
z Information that can be used by PayPal to track execution of the API operation
z Response-specific information required to fulfill the request
Multiple API Operations
Some of the features, such as Express Checkout, require you to call multiple API operations.
Typically, these features require you to
1. Invoke an API operation, suc h as SetExpressCheckout, that sets up the return URL to
which PayPal redirects your buyer’s browser after the buyer finishes on PayPal. Other
setup also can be performed by this API operation.
2. Invoke additional API operations after receiving the buyer’s permission on PayPal, for
example, GetExpressCheckoutDetails or DoExpressC heckoutPayment.
The following diagram shows the execution flow between your site and PayPal:
28 May 2010 Express Checkout Integration Guide
PayPal Name-Value Pair API Basics
PayPal API Client-Server Architecture
3
Token Usage
Typically, the API operation that sets up a redirection to PayPal returns a token. This token is
passed as a parameter in the redirect to PayPal. The token also might be required in related
API operations.
Express Checkout Integration Guide May 2010 29
PayPal Name-Value Pair API Basics
3
Obtaining API Credentials
Obtaining API Credentials
To use the PayPal API, you must have API credentials that identify you as a PayPal Business
account holder who is authorized to perform various API operations. Although you can use
either an API signature or a certificate for credentials, PayPal recommends you use a
signature.
IMPORTANT: Although you can have both a signature and certificate, you cannot use both at
the same time.
Creating an API Signature
An API signature consists of an API username along with an associated API passwo rd and
signature, all of which are assigned by PayPal. You need to include this information whenever
you execute a PayPal API operation.
You must have a PayPal Business account to create a signature.
To create an API signature :
1. Log into PayPal, then click Profile under My Account.
2. Click API Access.
3. Click Request API Credentials.
4. Check R equest API signature and click Agree and Submit.
30 May 2010 Express Checkout Integration Guide
Loading...