PayPal Express Checkout - 2012 Integration Guide
PayPal Express
Checkout Integration
Guide
Last updated: August 7, 2012
PayPal Express Checkout Integration Guide
Document Number: 100010.en_US-20120807
© 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 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
Chapter Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Chapter 1 Getting Started With Express Checkout. . . . . . . . . . . 9
Key Features of Express Checkout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
The Express Checkout Experience . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Supported Countries and Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Relationship Between Express Checkout and Shopping Carts . . . . . . . . . . . . . . . 12
Express Checkout Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Implementing the Simplest Express Checkout Integration. . . . . . . . . . . . . . . . . . 13
Obtaining an Express Checkout Button and PayPal Mark. . . . . . . . . . . . . . . . 14
Before You Start Coding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Setting Up the Express Checkout Transaction . . . . . . . . . . . . . . . . . . . . . 16
Obtaining Express Checkout Transaction Details . . . . . . . . . . . . . . . . . . . . 18
Completing the Express Checkout Transaction . . . . . . . . . . . . . . . . . . . . . 19
Testing an Express Checkout Integration . . . . . . . . . . . . . . . . . . . . . . . . 20
Security Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Troubleshooting Your Express Checkout Integration . . . . . . . . . . . . . . . . . . . . 25
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Timeouts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Logging API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Encoding and Decoding Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Express Checkout Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Customizing the Express Checkout User Interface . . . . . . . . . . . . . . . . . . . 27
Settlements and Captured Payments . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Refunds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Recurring Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Mobile Express Checkout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Parallel Payments With Express Checkout . . . . . . . . . . . . . . . . . . . . . . . 29
Fraud Management Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Express Checkout Integration Guide August 7, 2012 3
Contents
Event Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Dynamic Images Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Express Checkout Instant Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Express Checkout Building Blocks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Express Checkout Buttons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Express Checkout API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Express Checkout Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Express Checkout Token Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Chapter 2 Express Checkout User Interface Requirements . . . . . . 35
Express Checkout Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Checkout Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Payment Option Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
PayPal Button and Logo Images. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Express Checkout Image Flavors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Express Checkout Images. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Payment Mark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Chapter 3 Related API Operations . . . . . . . . . . . . . . . . . . . 39
Sale Payment Action for Express Checkout . . . . . . . . . . . . . . . . . . . . . . . . . 39
Authorization Payment Action for Express Checkout . . . . . . . . . . . . . . . . . . . . 39
Order Payment Action for Express Checkout . . . . . . . . . . . . . . . . . . . . . . . . 40
Issuing Refunds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Tracking Failed or Pending Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Chapter 4 Integrating Express Checkout With PayPal SDKs. . . . . . 45
Chapter 5 Going Live With Your Express Checkout Integration . . . .47
Chapter A Obtaining API Credentials. . . . . . . . . . . . . . . . . .49
Creating an API Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Creating an API Certificate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Encrypting Your Certificate Into PKCS12 Format . . . . . . . . . . . . . . . . . . . . 51
Importing Your Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Chapter B PayPal Name-Value Pair API Basics . . . . . . . . . . . . .55
PayPal API Client-Server Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4 August 7, 2012 Express Checkout Integration Guide
Contents
PayPal Name-Value Pair API Requests and Responses . . . . . . . . . . . . . . . . 56
UTF-8 Character Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Multiple API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
NVP Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Creating an NVP Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Specifying the PayPal API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Specifying an API Credential Using Signatures . . . . . . . . . . . . . . . . . . . . . 59
URL Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
List Syntax for Name-Value Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Executing NVP API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Specifying a PayPal Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Logging API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Responding to an NVP Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Common Response Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Error Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
URL Decoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Chapter C PayPal SOAP API Basics . . . . . . . . . . . . . . . . . .65
PayPal WSDL/XSD Schema Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
PayPal SOAP API Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
SOAP RequesterCredentials: Username, Password, Signature, and Subject. . . . . . . . 67
SOAP Service Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
SOAP Request Envelope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Request Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
SOAP Message Style: doc-literal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Response Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Error Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
CorrelationID for Reporting Problems to PayPal. . . . . . . . . . . . . . . . . . . . . . . 75
UTF-8 Character Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Date/Time Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Core Currency Amount Data Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Revision History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Express Checkout Integration Guide August 7, 2012 5
Contents
6 August 7, 2012 Express Checkout Integration Guide
Preface
About This Guide
This document describes basic Express Checkout integration.
Intended Audience
This document is for merchants and developers who want to get started implementing Express
Checkout.
Where to Go for More Information
Express Checkout Advanced Features 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 Integration Guide August 7, 2012 7
Preface
Documentation Feedback
8 August 7, 2012 Express Checkout Integration Guide
Getting Started With Express
1
Checkout
The Express Checkout button gives buyers another way to pay, and it complements your
existing payment solution. Online shoppers appreciate the convenience and security of PayPal,
where they can pay with their PayPal balance, bank account, or credit card.
Key Features of Express Checkout
Express Checkout is a fast, easy way for buyers to pay with PayPal. Express Checkout
eliminates one of the major causes of checkout abandonment by giving buyers all the
transaction details at once, including order details, shipping options, insurance choices, and
tax totals.
Studies show that adding the Express Checkout button to your website can increase your sales
up to 18 percent. The following web page shows the Express Checkout button side-by-side
with an existing checkout button:
Express Checkout Integration Guide August 7, 2012 9
Getting Started With Express Checkout
Key Features of Express Checkout
Use Express Checkout to:
Accept payments from any PayPal account.
Eliminate the need for customers to enter personal information, including shipping, billing,
or payment information.
Keep customers on your site after completing the transaction.
Sign up customers to make payments at regular intervals.
10 August 7, 2012 Express Checkout Integration Guide
See more at: https://merchant.paypal.com/cgi-
bin/marketingweb?cmd=_rendercontent&content_ID=merchant/express_checkout&nav=2.1.5
The Express Checkout Experience
Express Checkout makes it easier for 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:
Getting Started With Express Checkout
Key Features of Express Checkout
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.
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
Express Checkout Integration Guide August 7, 2012 11
Getting Started With Express Checkout
Relationship Between Express Checkout and Shopping Carts
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
Supported Countries and Currencies
Express Checkout enables you to accept payments from many countries and regions. The
checkout flow is also localized for a subset of countries.
For information about the countries and currencies that Express Checkout supports, see
Offerings W orldwide. For information about localized flows and additional country information,
Send and Receive Payments Securely Worldwide.
see
PayPal
Relationship Between Express Checkout and Shopping Carts
If you do not have your own shopping cart and have not integrated Express Checkout with
your website, you might consider using a third-party shopping cart. A shop ping cart is
software that lets buyers put items in a basket and calculates totals during checkout.
PayPal partners with a wide variety of shopping carts, all of which are PayPal compatible and
provide secure purchases for your buyers. The shopping cart vendor provides instructions for
integrating their shopping cart on your website. See the PayPal Partner Directory
(https://www.paypal-
marketing.com/emarketing/partner/directory/directory.page?type=Shopp
ing+Cart#mode=dir&dir%5Bops%5D=either&dir%5Bkey%5D=Keyword+term&dir%
5Btyp%5D%5B%5D=1&dir%5Bind%5D%5B%5D=0&dir%5Brod%5D%5B%5D=1&dir%5Brod
%5D%5B%5D=2) for available shopping carts.
IMPORTANT: If you choose a shopping cart, do not contact PayPal. PayPal has no authority
over a shopping cart vendor and cannot help you resolve issues that might
arise from the integration with or use of a third-party shopping cart.
Express Checkout Prerequisites
Prerequisites to Express Checkout include the kind of PayPal accounts you need as well as the
required programming skills and experience. If you want to use Express Checkout but do not
have the required skills or experience, you should consider using PayPal Payments Standard
(previously known as Website Payments Standard) or a shopping cart provided by PayPal or a
third party.
12 August 7, 2012 Express Checkout Integration Guide
Getting Started With Express Checkout
Implementing the Simplest Express Checkout Inte gr at ion
To use Express Checkout, you must have:
A Business or Premier account. A Business or Premier account enables you to become a
merchant for whom PayPal collects money from buyers for goods or services. PayPal
manages these transactions and charges you a small fee and a percentage of the amount
collected from the buyer for each transaction.
A Sandbox account with two test accounts. The PayPal Sandbox provides an environment
that simulates PayPal, in which you execute your Express Checkout integration without
actually exchanging money. One of your test accounts represents you as the merchant, or
seller using Sandbox terminology, and the other test account represents a buyer. Your
testing is not restricted to just two accounts; however , you must have a Sandbox account to
create test accounts and perform actual testing.
HTML experience. Probably, you already have an existing website and may have already
implemented a checkout experience for the goods or services you sell on your site. You
will need to add the Pay with Express Checkout button, as well as another button, called
the Express Checkout mark, to your web pages. The Pay with Express Checkout button
initiates the PayPal checkout flow. The mark enables the buyer to choose Express
Checkout from the page that specifies the payment method, called the payment page, in
case the buyer did not start with Pay with Express Checkout.
Programming experience. When the buyer clicks a button, you must provide code that
requests a PayPal server to set up or process the transaction and code to handle the
response. PalPal provides an easy-to-user interface built on the HTTP request-response
model, as well as a more complicated SOAP web services interface. PayPal also provides
Software Development Kits (SDKs) that provide an interface in various programming
languages, such as PHP, Ruby, Java, and .NET languages like C#. Although you need not
know a specific language, you will need to understand programming logic, especially the
request-response model, error handling, and the nuances of writing application-level code.
NOTE: If the description of the programming experience prerequisite seems confusing
(like “what’s an interface?”), you can still use Express Checkout provided by a
shopping cart vendor, including PayPal, or use another PayPal product, such as
PayPal Payments Standard. You should not attempt to integrate Express Checkout
on your own unless you have sufficient programming experience. A programmer
or developer will find Express Checkout easy; a complete novice could lose sales
or goods and not even know it.
Implementing the Simplest Express Checkout Integration
The simplest Express Checkout integration requires you to set up a PayPal button and call the
following PayPal API operations when your buyer clicks the button: SetExpressCheckout,
DoExpressCheckoutPayment, and typically, GetExpressCheckoutDetails.
You must also enable the buyer to select PayPal as the payment method after the buyer starts
to check out. Thus, you must call these API operations from two places. You must perform
these API operations on your checkout page and on your payment method page.
Express Checkout Integration Guide August 7, 2012 13
Getting Started With Express Checkout
Implementing the Simplest Express Checkout Inte gr at ion
Related information:
"Express Checkout Flow" on page 35
Obtaining an Express Checkout Button and PayPal Mark
PayPal requires that you use the Check out with PayPal button and the PayPal mark image
hosted on secure PayPal servers. When the images are updated, the changes appear
automatically in your application.
You must put the Express Checkout button on your checkout page. To obtain an Express
Checkout Button:
1. Go to the PayPal
Button Code page (https://www.paypal.com/express-checkout-buttons).
A page similar to the following one appears:
2. Select and copy the image source text from the window below the button.
3. Paste the image source text into your checkout page’s HTML source where you want the
button to appear on your page.
Result:
When you display your checkout page in the browser, the Check out with PayPal button
should appear:
14 August 7, 2012 Express Checkout Integration Guide
Getting Started With Express Checkout
Implementing the Simplest Express Checkout Inte gr at ion
After Completing This Task:
You will need to place the PayPal mark image on your payment page. The instructions for
obtaining this image are similar to the instructions for obtaining the button. The mark is found
on the same
Checkout button:
Button Code page (https://www.paypal.com/express-checkout-buttons) as the Express
Before You Start Coding
If you are not familiar with how PayPal APIs work, read this topic. It provides the minimum
information you need to be successful using the PayPal Name-Value Pair API.
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
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.
Express Checkout Integration Guide August 7, 2012 15
Getting Started With Express Checkout
Implementing the Simplest Express Checkout Inte gr at ion
For example, you might want to obtain the buyer’s shipping address from PayPal. You can
initiate a request specifying an API operation to obtain 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 response
contains the buyer’s shipping address. If the operation fails, the response contains one or more
error messages.
Related information:
"Creating an NVP Request" on page 58
"Responding to an NVP Response" on page 62
Obtaining API Credentials
To use the PayPal API, you must have API credentials that identify you as a PayPal Business
or Premier 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.
Setting Up the Express Checkout Transaction
T o set up an Express Checkout transaction, you must invoke the SetExpressCheckout API
operation to provide sufficient information to initiate the payment flow and redirect to PayPal
if the operation was successful.
This example assumes that you have set up the mechanism you will use to communicate with
the PayPal server and have a PayPal Business account with API credentials. It also assumes
that the payment action is a final sale.
When you set up an Express Checkout transaction, you specify values in the
SetExpressCheckout request and then call the API. The values you specify control the
PayPal page flow and the options available to you and your buyers. You should start by setting
up a standard Express Checkout transaction, which can be modified to include additional
options.
To set up the simplest standard Express Checkout transaction:
16 August 7, 2012 Express Checkout Integration Guide
Getting Started With Express Checkout
Implementing the Simplest Express Checkout Inte gr at ion
1. Specify that you want to execute the SetExpressCheckout API operation and the
version you want to use.
METHOD=SetExpressCheckout
VERSION=XX.0
2. Specify your API credentials.
Use the following parameters for a signature:
USER=API_username
PWD=API_password
SIGNATURE=API_signature
In the Sandbox, you can always use the following signature:
USER=sdk-three_api1.sdk.com
PWD=QFZCWN5HZM8VBG7Q
SIGNATURE=A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU
3. Specify the amount of the transaction; include the currency if it is not in US dollars.
Specify the total amount of the transaction if it is known; otherwise, specify the subtotal.
Regardless of the specified currency, the format must have a decimal point with exactly
two digits to the right and an optional thousands separator to the left, which must be a
comma.
For example, EUR 2.000,00 must be specified as 2000.00 or 2,000.00. The specified amount
cannot exceed USD $10,000.00, regardless of the currency used.
PAYMENTREQUEST_0_AMT=amount
PAYMENTREQUEST_0_CURRENCYCODE=currencyID
4. Specify the return URL.
The return URL is the page to which PayPal redirects your buyer’s browser after the buyer
logs into PayPal and approves the payment. Typically, this is a secure page
(https://...) on your site.
NOTE: You can use the return URL to piggyback parameters between pages on your site.
For example, you can set your Return URL to specify additional parameters using
the https://www.
yourcompany.com/page.html?param=value... syntax. The
parameters become available as request parameters on the page specified by the
Return URL.
RETURNURL=return_url
Express Checkout Integration Guide August 7, 2012 17
Getting Started With Express Checkout
Implementing the Simplest Express Checkout Inte gr at ion
5. Specify the cancel URL.
The cancel URL is the page to which PayPal redirects your buyer’s browser if the buyer
does not approve the payment. Typically, this is the secure page (https://...) on your
site from which you redirected the buyer to PayPal.
NOTE: You can pass SetExpressCheckout request values as parameters in your URL
to have the values available, if necessary, after PayPal redirects to your URL.
CANCELURL=cancel_url
6. Specify the payment action.
Although the default payment action is a Sale, it is a best practice to explicitly specify the
payment action as one of the following values:
PAYMENTREQUEST_0_PAYMENTACTION=Sale
After Completing This Task:
If calling the SetExpressCheckout API was successful, redirect the buyer’s browser to
PayPal and execute the _express-checkout command using the token returned in the
SetExpressCheckout response.
NOTE: The following example uses the PayPal Sandbox server:
https://www.sandbox.paypal.com/webscr
?cmd=_express-checkout&token=tokenV alue
Obtaining Express Checkout Transaction Details
To obtain details about an Express Checkout transaction, you can invoke the
GetExpressCheckoutDetails API operation.
This example assumes that PayPal redirects to your buyer’s browser with a valid token after
the buyer reviews the transaction on PayPal.
Although you are not required to invoke the GetExpressCheckoutDetails API operation,
most Express Checkout implementations take this action to obtain information about the
buyer. You invoke the GetExpressCheckoutDetails API operation from the page
specified by return URL, which you set in your call to the SetExpressCheckout API.
Typically, you invoke this operation as soon as the redirect occurs and use the information in
the response to populate your review page.
To obtain a buyer’s shipping address and Payer ID:
1. Specify that you want to execute the GetExpressCheckoutDetails API operation and
the version you want to use.
18 August 7, 2012 Express Checkout Integration Guide
Getting Started With Express Checkout
Implementing the Simplest Express Checkout Inte gr at ion
METHOD=GetExpressCheckoutDetails
VERSION=XX.0
2. Specify your API credentials.
Use the following parameters for a signature:
USER=API_username
PWD=API_password
SIGNATURE=API_signature
3. Specify the token returned by PayPal when it redirects the buyer’s browser to your site.
PayPal returns the token to use in the token HTTP request parameter when redirecting to
the URL you specified in your call to the SetExpressCheckout API.
TOKEN=tokenValue
4. Execute the GetExpressCheckoutDetails AP I to obtain information about the buyer.
5. Access the fields in the GetExpressCheckoutDetails API response.
NOTE: Only populated fields are returned in the response.
Completing the Express Checkout Transaction
To complete an Express Checkout transaction, you must invoke the
DoExpressCheckoutPayment API operation.
This example assumes that PayPal redirects your buyer’s browser to your website with a valid
token after you call the SetExpressCheckout API. Optionally, you may call the
GetExpressCheckoutDetails API before calling the DoExpressCheckoutPayment
API.
In the simplest case, you set the total amount of the order when you call the
SetExpressCheckout API. However, you can change the amount before calling the
DoExpressCheckoutPayment API if you did not know the total amount when you called
the SetExpressCheckout API.
This example assumes the simplest case, in which the total amount was specified in the return
URL when calling the SetExpressCheckout API. Although you can specify additional
options, this example does not use any additional options.
To execute an Express Checkout transaction:
1. Specify that you want to execute the DoExpressCheckoutPayment API operation and
the version you want to use.
Express Checkout Integration Guide August 7, 2012 19
Getting Started With Express Checkout
Implementing the Simplest Express Checkout Inte gr at ion
METHOD=DoExpressCheckoutPayment
VERSION=XX.0
2. Specify your API credentials.
Use the following parameters for a signature:
USER=API_username
PWD=API_password
SIGNATURE=API_signature
3. Specify the token returned by PayPal when it redirects the buyer’s browser to your site.
PayPal returns the token to use in the token HTTP request parameter when redirecting to
the URL you specified in your call to the SetExpressCheckout API.
TOKEN=tokenValue
4. Specify the Payer ID returned by PayPal when it redirects the buyer’s browser to your site.
PayPal returns the Payer ID to use in the token HTTP request parameter when redirecting
to the URL you specified in your call to the SetExpressCheckout API. Optionally, you
can obtain the Payer ID by calling the GetExpressCheckoutDetails API.
PAYERID=id
5. Specify the amount of the order including shipping, handling, and tax; include the currency
if it is not in US dollars.
Most of the time, this will be the same amount as you specified in your
SetExpressCheckout call, adjusted for shipping and taxes.
PAYMENTREQUEST_0_AMT=amount
PAYMENTREQUEST_0_CURRENCYCODE=currencyID
6. Specify the same payment action that you specified in SetExpressCheckout.
PAYMENTREQUEST_0_PAYMENTACTION=Sale
Testing an Express Checkout Integration
You can test your Express Checkout integration in the Sandbox.
This example shows how to simulate your web pages using HTTP forms and supplying the
values for API operations from these forms. You can use this strategy for your initial testing;
however, for more complete testing, you need to replace these forms with your web pages
containing your actual code.
20 August 7, 2012 Express Checkout Integration Guide
Getting Started With Express Checkout
Implementing the Simplest Express Checkout Inte gr at ion
The following diagram shows the Express Checkout execution flow, which uses the Sandbox
as the API server. The pages on the left represent your site.
The following steps match the circled numbers in the diagram. Perform the actions in each
step to test Express Checkout.
1. Invoke a form on your site that calls the SetExpressCheckout API on the Sandbox.
To invoke the API, set form fields whose names match the NVP names of the fields you want
to set, specify their corresponding values, and then post the form to a PayPal Sandbox server,
such as https://api-3t.sandbox.paypal.com/nvp, as shown in the following
example:
Express Checkout Integration Guide August 7, 2012 21
Getting Started With Express Checkout
Implementing the Simplest Express Checkout Inte gr at ion
<form method=post action=https://api-3t.sandbox.paypal.com/nvp>
<input type=hidden name=USER value=API_username>
<input type=hidden name=PWD value=API_p assword>
<input type=hidden name=SIGNATURE value=API_signature>
<input type=hidden name=VERSION value=XX.0>
<input type=hidden name=PAYMENTREQUEST_0_PAYMENTACTION
value=Sale>
<input name=PAYMENTREQUEST_0_AMT value=19.95>
<input type=hidden name=RETURNURL
value=https://www.YourReturnURL.com>
<input type=hidden name=CANCELURL
value=https://www.YourCancelURL.com>
<input type=submit name=METHOD value=SetExpressCheckout>
</form>
NOTE: Use an API username from a Sandbox business test account for which a signature
exists. See the T est Certificates tab of the Sandbox to obtain a signature. If you are not
using a signature, you must use a different Sandbox server.
IMPORTANT: This example does not establish a secure connection and should not be used
live on paypal.com.You must protect the values for USER, PWD, and
SIGNATURE in your implementation. Consider storing these values in a secure
location other than your web server document root and setting the file
permissions so that only the system user that executes your ecommerce
application can access it.
2. Review the response string from the SetExpressCheckout API operation.
PayPal responds with a message, such as the one shown below. Note the status, which
should include ACK set to Success, and a token that is used in subsequent steps.
TIMESTAMP=2007%2d04%2d05T23%3a23%3a07Z
&CORRELATIONID=63cdac0b67b50
&ACK=Success
&VERSION=XX%2e000000
&BUILD=1%2e0006
&TOKEN=EC%2d1NK66318YB717835M
3. If the operation was successful, use the token and redirect your browser to the Sandbox to
log in, as follows:
22 August 7, 2012 Express Checkout Integration Guide
Getting Started With Express Checkout
Implementing the Simplest Express Checkout Inte gr at ion
https://www.sandbox.paypal.com/cgi-bin/webscr?
cmd=_express-checkout
&token=EC-1NK66318YB717835M
You may need to decode the URL, which is the opposite of URL encoding, by replacing
hexadecimal codes with ASCII codes; for example, you may need to replace %2d in the
token with a hyphen ( - ).
You must log in to https://developer.paypal.com before you log in to a Sandbox
test account. You then log in to the test account that represents the buyer, not the seller’s
business test account that represents you as the merchant.
4. After logging into the buyer test account, confirm the details.
When you confirm, the Sandbox redirects your browser to the return URL you specified
when invoking the SetExpressCheckout API operation, as in the following example:
http://www.YourReturnURL.com/
?token=EC-1NK66318YB717835M&PayerID=7AKUSARZ7SAT8
5. Invoke a form on your site that calls the GetExpressCheckoutDetails API operation
on the Sandbox:
<form method=post action=https://api-3t.sandbox.paypal.com/nvp
<input type=hidden name=USER value=API_username>
<input type=hidden name=PWD value=API_p assword>
<input type=hidden name=SIGNATURE value=API_signature>
<input type=hidden name=VERSION value=XX.0>
<input name=TOKEN value=EC-1NK66318YB717835M>
<input type=submit name=METHOD value=GetExpressCheckoutDetails>
</form>
If the operation was successful, the GetExpressCheckoutDetails API returns
information about the payer, such as the following information:
Express Checkout Integration Guide August 7, 2012 23
Getting Started With Express Checkout
Implementing the Simplest Express Checkout Inte gr at ion
TIMESTAMP=2007%2d04%2d05T23%3a44%3a11Z
&CORRELATIONID=6b174e9bac3b3
&ACK=Success
&VERSION=XX%2e000000
&BUILD=1%2e0006
&TOKEN=EC%2d1NK66318YB717835M
&EMAIL=Y ourSandboxBuyerAccountEmail
&PAYERID=7AKUSARZ7SAT8
&PAYERSTATUS=verified
&FIRSTNAME=...
&LASTNAME=...
&COUNTRYCODE=US
&BUSINESS=...
&PAYMENTREQUEST_0_SHIPTONAME=...
&PAYMENTREQUEST_0_SHIPTOSTREET=...
&PAYMENTREQUEST_0_SHIPTOCITY=...
&PAYMENTREQUEST_0_SHIPTOSTATE=CA
&PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE=US
&PAYMENTREQUEST_0_SHIPTOCOUNTRYNAME=United%20States
&PAYMENTREQUEST_0_SHIPTOZIP=94666
&PAYMENTREQUEST_0_ADDRESSID=...
&PAYMENTREQUEST_0_ADDRESSSTATUS=Confirmed
6. Invoke a form on your site that invokes the DoExpressCheckoutPayment API operation
on the Sandbox:
<form method=post action=https://api-3t.sandbox.paypal.com/nvp>
<input type=hidden name=USER value=API_username>
<input type=hidden name=PWD value=API_p assword>
<input type=hidden name=SIGNATURE value=API_signature>
<input type=hidden name=VERSION value=XX.0>
<input type=hidden name=PAYMENTREQUEST_0_PAYMENTACTION
value=Authorization>
<input type=hidden name=PAYERID value=7AKUSARZ7SAT8>
<input type=hidden name=TOKEN value= EC%2d1NK66318YB717835M>
<input type=hidden name=PAYMENTREQUEST_0_AMT value= 19.95>
<input type=submit name=METHOD value=DoExpressCheckoutPayment>
</form>
24 August 7, 2012 Express Checkout Integration Guide
Loading...