PayPal Pro - 2012, Website Payments Pro - 2012 Integration Guide
PayPal Payments Pro
Integration Guide
Last updated: April 2012
PayPal Payments Pro Integration Guide
Document Number: 100001.en_US-201204
© 2010-2011 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Chapter 1 Introducing PayPal Payments Pro. . . . . . . . . . . . . . 9
Getting Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
PayPal Payments Pro Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Additional Features of PayPal Payments Pro . . . . . . . . . . . . . . . . . . . . . . . . 10
Settlements and Captured Payments . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Recurring Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Virtual Terminal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Hosted Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Fraud Management Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Event Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
PayPal Payments Pro API Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Website Payments Pro Regional Differences . . . . . . . . . . . . . . . . . . . . . . . . 15
Credit Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Default Currency and Transaction Limits . . . . . . . . . . . . . . . . . . . . . . . . 15
Credit Card Currencies by Country . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Chapter 2 Introducing Direct Payment . . . . . . . . . . . . . . . . .19
The Direct Payment User Experience . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
User Interface Recommendations for Direct Payment Checkout . . . . . . . . . . . . . . 21
Chapter 3 Introducing Express Checkout . . . . . . . . . . . . . . .23
The Express Checkout Experience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Express Checkout Integration Steps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Configuring and Customizing the Express Checkout Experience . . . . . . . . . . . . 25
Additional PayPal API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
PayPal Payments Pro Integration Guide April 2012 3
Contents
Express Checkout Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Checkout Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Payment Option Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Express Checkout Building Blocks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
PayPal Button and Logo Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Express Checkout API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Express Checkout Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Express Checkout Token Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Chapter 4 Getting Started With Direct Payment . . . . . . . . . . . .33
Implementing the Simplest Direct Payment Integration . . . . . . . . . . . . . . . . . . . 33
Testing Direct Payment Using NVP and cURL. . . . . . . . . . . . . . . . . . . . . . . . 34
Direct Payment Authorization and Captures . . . . . . . . . . . . . . . . . . . . . . . . . 38
Sale Payment Action for Direct Payment . . . . . . . . . . . . . . . . . . . . . . . . 38
Authorization and Capture for Direct Payment . . . . . . . . . . . . . . . . . . . . . 38
DoDirectPayment Authorization and Capture Example . . . . . . . . . . . . . . . . . 39
DoDirectPayment Reauthorization and Capture Example. . . . . . . . . . . . . . . . 41
Chapter 5 Getting Started With Express Checkout. . . . . . . . . . . 45
Implementing the Simplest Express Checkout Integration. . . . . . . . . . . . . . . . . . 45
Setting Up the Express Checkout Transaction . . . . . . . . . . . . . . . . . . . . . 45
Obtaining Express Checkout Transaction Details . . . . . . . . . . . . . . . . . . . . 47
Completing the Express Checkout Transaction . . . . . . . . . . . . . . . . . . . . . 48
Testing an Express Checkout Integration . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Handling Payment Settlements With Express Checkout. . . . . . . . . . . . . . . . . . . 53
Sale Payment Action for Express Checkout. . . . . . . . . . . . . . . . . . . . . . . 54
Authorization Payment Action for Express Checkout . . . . . . . . . . . . . . . . . . 54
Order Payment Action for Express Checkout . . . . . . . . . . . . . . . . . . . . . . 55
Issuing Refunds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Chapter 6 Integrating Recurring Payments. . . . . . . . . . . . . . .59
How Recurring Payments Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Recurring Payments Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Recurring Payments With Direct Payment. . . . . . . . . . . . . . . . . . . . . . . . . . 61
Recurring Payments With the Express Checkout API . . . . . . . . . . . . . . . . . . . . 62
Initiating the Processing Flow With SetExpressCheckout . . . . . . . . . . . . . . . 63
4 April 2012 PayPal Payments Pro Integration Guide
Contents
Redirecting the Buyer to PayPal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Getting Buyer Details Using GetExpressCheckoutDetails. . . . . . . . . . . . . . . . 65
Creating the Profiles With CreateRecurringPaymentsProfile . . . . . . . . . . . . . . 65
Options for Creating a Recurring Payments Profile . . . . . . . . . . . . . . . . . . . . . 66
Specifying the Regular Payment Period . . . . . . . . . . . . . . . . . . . . . . . . . 66
Including an Optional Trial Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Specifying an Initial Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Maximum Number of Failed Payments . . . . . . . . . . . . . . . . . . . . . . . . . 68
Billing the Outstanding Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Identifying Items as Digital or Physical Goods. . . . . . . . . . . . . . . . . . . . . . 69
Recurring Payments Profile Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Getting Recurring Payments Profile Information. . . . . . . . . . . . . . . . . . . . . . . 70
Modifying a Recurring Payments Profile. . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Updating Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Updating the Billing Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Billing the Outstanding Amount of a Profile . . . . . . . . . . . . . . . . . . . . . . . . . 72
Recurring Payments Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Appendix A Getting Started With the PayPal Name-Value Pair API . . .75
PayPal API Client-Server Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
PayPal Name-Value Pair API Requests and Responses . . . . . . . . . . . . . . . . 76
UTF-8 Character Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Multiple API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Obtaining API Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Creating an API Signature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Creating an API Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
NVP Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Creating an NVP Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Specifying the PayPal API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Specifying an API Credential . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
URL Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
List Syntax for Name-Value Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Executing NVP API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Specifying a PayPal Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Logging API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Responding to an NVP Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Common Response Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Error Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
PayPal Payments Pro Integration Guide April 2012 5
Contents
URL Decoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Appendix B Implementing 3-D Secure Transactions (UK Only) . . . . .87
Introduction to 3-D Secure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Integration Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Cardinal Commerce Registration and Installation . . . . . . . . . . . . . . . . . . . . . . 88
Transaction Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
URL to Handle Issuer’s Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Transaction Flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
3-D Secure Fields for Direct Payment Transaction Requests . . . . . . . . . . . . . . 92
Website Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Example 1: Successful 3-D Secure Authentication . . . . . . . . . . . . . . . . . . . 94
Example 2: 3-D Secure with Unsuccessful Authentication . . . . . . . . . . . . . . . 94
Example 3: Card Issuer Not Using 3-D Secure . . . . . . . . . . . . . . . . . . . . . 95
Example 4: Merchant Not Using 3-D Secure . . . . . . . . . . . . . . . . . . . . . . 95
Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
cmpi_lookup API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
cmpi_lookup Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
cmpi_lookup Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Issuer Authentication Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Issuer Authentication Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Issuer Authentication Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
cmpi_authenticate API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
cmpi_authenticate Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
cmpi_authenticate Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
6 April 2012 PayPal Payments Pro Integration Guide
Preface
This document describes PayPal Payments Pro (known as Website Payments Pro outside the
U.S.) integration.
Intended Audience
This document is intended for merchants and developers implementing PayPal Payments Pro.
Revision History
Revision history for PayPal Payments Pro Integration Guide.
Date Description
04/03/12 Updated references to Website Payments Standard and Website Payments
Pro to PayPal Payments Standard and PayPal Payments Pro, respectively.
02/13/12 Updated user experience graphics.
12/20/10 Replaced deprecated field names in examples.
10/26/10 Added a reference to information on Mobile Express Checkout, which is
located in the Epxress Checkout Integration Guide.
08/11/10 Divided the Website Payments Pro Integration Guide into 2 guides: the
Website Payments Pro Integration Guide and the Express Checkout
Advanced Features Guide
05/11/10 Added details for integrating parallel payments using the NVP and SOAP
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.
03/10/10 Consolidated all regions (US, UK, and Canada) into one manual.
Added additional information about Direct Payment.
10/05/09 Added Immediate Payment.
Edited for technical accuracy.
Removed PayPal placement guidelines.
.
06/30/09 Added a section on payment review.
PayPal Payments Pro Integration Guide April 2012 7
Where to Go for More Information
Date Description
06/04/09 Added a chapter on pre-populating the PayPal review page. Updated PayPal
Review pages. Moved some customization topics out of this guide. They
are now in the Merchant Setup and Administration Guide.
04/08/09 Added a chapter describing the Instant Update Callback API.
Added Express Checkout feature of passing AMT=0 to create one or more
billing agreements.
12/11/08 Revised the Website Payments Pro introduction and overview chapters.
11/13/08 Added information about integrating dynamic images and added
information about order details that can be displayed on the PayPal Review
page.
06/30/08 Complete revision.
Where to Go for More Information
Express Checkout Advanced Features Guide
Merchant Setup and Administration Guide
Documentation Feedback
Help us improve this guide by sending feedback to:
documentationfeedback@paypal.com
8 April 2012 PayPal Payments Pro Integration Guide
Introducing PayPal Payments Pro
1
You can accept credit and debit cards and PayPal payments directly on your website using 2
API-based solutions: Direct Payment and Express Checkout. You must integrate with both
Direct Payment and Express Checkout to use PayPal Payments Pro, known as Website
Payments Pro outside the U.S.
PayPal Payments Pro Overview
Additional Features of PayPal Payments Pro
PayPal Payments Pro API Operations
Website Payments Pro Regional Differences
Getting Related Information
All PayPal documentation is available on x.com, including video demos, forums and developer
resources.
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
If you use the Payflow API to process transactions with PayPal as your internet merchant
account, see
Merchant Setup and Administration Guide.
Gateway Developer Guide and Reference.
PayPal Payments Pro Overview
PayPal Payments Pro includes Direct Payment, Express Checkout, and additional PayPal
solutions and tools, such as Virtual Terminal, Fraud Management Filters, and reference
transactions.
Direct Payment enables you to accept both debit and credit cards directly from your site.
Express Checkout enables you to accept payments from PayPal accounts in addition to
debit and credit cards.
The following diagram shows the relationship between Direct Payment and Express Checkout
to a buyer.
PayPal Payments Pro Integration Guide April 2012 9
Introducing PayPal Payments Pro
1
Additional Features of PayPal Payments Pro
From your shopping cart, a buyer can either checkout with Express Checkout, starting from
the Checkout with PayPal button on your Shopping Cart page, or pay directly by credit or
debit card using Direct Payment.
If a buyer pays using Express Checkout, PayPal provides a checkout experience that
streamlines checkout. Even if buyers do not pay using Express Checkout, they can still pay by
credit or debit card using Direct Payment. In this case, buyers might need to enter payment,
billing, and shipping information. In both cases, buyers stay on your website or are sent to the
page of your choice.
You must implement both an Express Checkout flow and a Direct Payment flow to use PayPal
Payments Pro. You implement the Express Checkout flow by calling PayPal’s Express
Checkout API operations, which guides a buyer through the checkout process. You implement
the Direct Payment flow using your own code, for which PayPal provides an API operatio n to
process the credit or debit card payment.
NOTE: Purchases through Direct Payment are not covered by the PayPal Seller Protection
Policy.
Additional Features of PayPal Payments Pro
PayPal Payments Pro consists of APIs for accepting credit card, debit card, and PayPal
payments; these payments can be immediate, authorized for later capture, and they can be
recurring payments. PayPal Payments Pro also includes standalone applications for accepting
payments.
In addition, PayPal Payments Pro includes Fraud Management Filters for automatic review
and management of risk.
10 April 2012 PayPal Payments Pro Integration Guide
Settlements and Captured Payments
Often, you accept a payment and ship goods immediately, which is refered to as sale. In
addition to immediate payments, Direct Payment and Express Checkout both allow you to
authorize payments to be captured later, which is referred to as an authorization. An
authorization is useful, for example, when you want to reserve a buyer’s funds pending the
shipment of goods; the actual payment is captured when the goods are shipped. An
authorization can be reauthorized one time if necessary; for example, when you are unable to
ship within 3 days of the authorization.
Express Checkout provides an additional option, called an order, which you use when a single
authorization is insufficient. You can create multiple authorizations and capture them as part
of the same order. This would be useful, for example, when an order is split into multiple
shipments and you need to capture a payment each time part of the order is shipped.
Recurring Payments
You can support recurring payments to manage subscriptions and other payments on a fixed
schedule. Direct Payment and Express Checkout both process recurring payments.
Introducing PayPal Payments Pro
Additional Features of PayPal Payments Pro
1
When you support recurring payments for a buyer, you create a recurring payments profile.
The profile contains information about the recurring payments, including details for an
optional trial period and a regular payment period. Both periods contain information about the
payment frequency and payment amounts, including shipping and tax, if applicable.
After creating a profile, PayPal automatically queues payments based on the billing start date,
billing frequency, and billin g amount. Payments reoccur until th e profile expires, t here are too
many failed payments to continue, or you cancel the profile.
Permission to allow recurring payments is established by the buyer setting up a billing
agreement with the merchant on PayPal. For Express Checkout, the billing agreement can be
established either in advance or when the buyer first makes a purchase; in either case, it occurs
when you call Express Checkout API operations. For direct payment, it occurs when you make
an explicit call to set up the billing agreement.
Recurring payments using reference transactions is an alternative, which enables you to ha ndle
payments for varying amounts of money on a va rying schedule. A reference transaction is a
financial transaction from which subsequent transactions can be derived; for example, a buyer
can make a purchase on your site and the PayPal transaction ID, called a reference transaction
ID, can later be used to initiate another transaction.
NOTE: The use of recurring payments with direct payment may incur additional fees.
Virtual Terminal
PayPal’s Virtual Terminal is a web-based application that allows you to accept credit card
payments. It is available to merchants in the United States, Canada, France, and the United
Kingdom. Virtual Terminal provides your business with the functionality similar to a standalone credit card-processing terminal. Virtual Terminal is ideal when you receive orders by
PayPal Payments Pro Integration Guide April 2012 11
Introducing PayPal Payments Pro
1
Additional Features of PayPal Payments Pro
phone, fax, or by mail and want to accept credit cards. An optional card reader is available to
process face-to-face purchases; however, some restrictions apply. You can use Virtual
Terminal on any computer with an internet connection and a web browser.
For more information about Virtual Terminal, see
Hosted Solution
Hosted Solution, which is available to merchants in the United Kingdom as part of PayPal
Payments Pro, is a fast and easy way to add transaction processing to your website. It is a
secure, PayPal-hosted, web-based payment solution that allows you to securely send your
buyers to PayPal’s payment page to authorize and process transactions. Buyers pay with a
debit or credit card, or their PayPal account. You do not have to capture or store credit card
information on your website, thereby helping towards achieving PCI compliance. Hosted
Solution is the choice for merchants who prefer a solution where all financial details are
handled by PayPal.
For more information about Hosted Solution for UK merchants, see
Hosted Solution Integration Guide.
Fraud Management Filters
Fraud Management Filters (FMF) provide you filters that identify potentially fraudulent
transactions. There are 2 categories of filters:
Basic filters screen against data such as the country of origin and the value of transactions.
PayPal provides basic filters for Business accounts and Website Payments Pro accounts.
Virtual Terminal Users Guide.
Website Payments Pro
Advanced filters screen data such as credit card and addresses information, lists of high-
risk indicators, and additional transaction characteristics. Website Payments Pro merchants
can upgrade to use these filters.
NOTE: Using advanced filters might incur additional charges.
For more information about Fraud Management Filters, see
Event Notification
In most cases you can use the GetTransactionDetails API operation to determine the
information you need about a transaction. However, there may be some cases in which you
must set up IPN; for example, when you need automatic notification about actions, such as
disputes and their resolution.
IPN is a message service that PayPal uses to notify you about events, such as:
Instant payments, including Express Checkout, Adaptive Payments, and direct credit card
payments, and authorizations, which indicate a sale whose payment has not yet been
collected
Fraud Management Filters
12 April 2012 PayPal Payments Pro Integration Guide
Introducing PayPal Payments Pro
PayPal Payments Pro API Operations
eCheck payments and associated status, such as pending, completed, or denied, and
payments pending for other reasons, such as those being reviewed for potential fraud
Recurring payment and subscription actions
Chargebacks, disputes, reversals, and refunds associated with a transaction
1
For more information about IPN, see
Instant Payment Notification Guide
PayPal Payments Pro API Operations
The PayPal API supports a range of functions related to payment processing. Though most
API operations support both Direct Payment and Express Checkout, some are specific to
Direct Payment and others are specific to Express Checkout.
PayPal API Operation Description
Direct Payment core API operations: (Direct Payment only)
DoDirectPayment Process a credit card payment, such as a sale or
authorization.
DoNonReferencedCredit Issue a credit to a card not referenced by the original
transaction.
NOTE: Contact PayPal to use this API operation; in most
cases, you should use the RefundTransaction
API operation instead.
Express Checkout core API operations: (Express Checkout only)
SetExpressCheckout Initiates an Express Checkout transaction.
GetExpressCheckoutDetails Obtain information about an Express Checkout transaction.
DoExpressCheckoutPayment Completes an Express Checkout transaction.
Common API operations:
GetTransactionDetails Obtain information about a specific transaction.
ManagePendingTransactionStatus Accept or deny a pending transaction held by Fraud
Management Filters.
RefundTransaction Issue a refund to the PayPal account holder associated with a
transaction.
TransactionSearch Search transaction history for transactions that meet the
specified criteria.
Authorization and Capture API operations:
DoCapture Capture an authorized payment.
DoAuthorization Authorize a payment. (Express Checkout only)
PayPal Payments Pro Integration Guide April 2012 13
Introducing PayPal Payments Pro
1
PayPal Payments Pro API Operations
PayPal API Operation Description
DoReauthorization Reauthorize a previously authorized payment.
DoVoid Void an order or an authorization.
Recurring Payment API operations:
CreateRecurringPaymentsProfile Create a recurring payments profile.
GetRecurringPaymentsProfileDeta ils Obtain information about a recurring payments profile.
ManageRecurringPaymentsProfileS tatus Cancel, suspend, or reactivate a recurring payments profile.
BillOutstandingAmount Bill the buyer for the outstanding balance associated with a
recurring payments profile.
UpdateRecurringPaymentsProfile Update a recurring payments profile.
DoReferenceTransaction Process a payment from a buyer’s account, which is
identified by a previous transaction.
Recurring Payment Billing Agreement API operations: (Express Checkout only)
BAUpdate Update or delete a billing agreement.
GetBillingAgreementCustomerDeta ils Obtain information about a billing agreement’s PayPal
account holder.
SetCustomerBillingAgreement Initiates the creation of a billing agreement.
Other Express Checkout API operations: (Express Checkout only)
AddressVerify Confirms whether a postal address and postal code match
those of the specified PayPal account holder. (Express
Checkout only)
Callback Define the shipping and handling parameters associated with
Express Checkout.
GetBalance Obtain the available balance for a PayPal account. (Express
Checkout only)
GetPalDetails Obtain your Pal ID, which is the PayPal-assigned merchant
account number, and other information about your account.
MassPay Make a payment to one or more PayPal account holders.
NOTE: If you use the Payflow API to process transactions with PayPal as your internet
merchant account, see
Gateway Developer Guide and Reference.
14 April 2012 PayPal Payments Pro Integration Guide
Introducing PayPal Payments Pro
Website Payments Pro Regional Differences
Website Payments Pro Regional Differences
Website Payments Pro is available in the United States, Canada, and the United Kingdom.
Minor regional differences include transaction limits, the kinds of credit cards accepted, and
address information.
The following sections identify regional differences:
Credit Cards
The following table lists the credit cards that are accepted:
Country Accepted credit cards
1
Canada
United Kingdom
United States
Visa
MasterCard
NOTE: Interac debit cards are not accepted.
Visa, including Visa Electron and Visa Debit
MasterCard
Maestro, including Switch
Visa
MasterCard
Discover
American Express
MasterCard is a registered trademark.
NOTE: For direct payment only, American Express restricts direct card acceptance merchants
in certain business categories. Merchants are required to accept the American Express
Card Acceptance agreement in order to process American Express cards directly.
Default Currency and Transaction Limits
The following table lists the default transaction limit in the default currency for each country:
Country Default transaction limit in default currency
Canada 12,500 CAD
United Kingdom 5,500 GBP
United States 10,000 USD
NOTE: Contact PayPal if you want to increase transaction limits.
PayPal Payments Pro Integration Guide April 2012 15
Introducing PayPal Payments Pro
1
Website Payments Pro Regional Differences
Credit Card Currencies by Country
The following currencies are supported for Direct Payment:
Currencies and Currency Codes Supported by Express Checkout and Direct Pa yment
Direct Payment
Express
Checkout
Currency
Currency
Code
Currency for
Specified Card in
United States
Direct Payment
Currency for Specified
Card in United Kingdom
Direct Payment
Currency for Specified
Card in Canada
Australian
Dollar
Canadian
Dollar
Czech Koruna CZK Visa, MasterCard Visa, MasterCard
Danish Krone DKK Visa, MasterCard Visa, MasterCard
Euro EUR Visa, MasterCard Visa, MasterCard Visa, MasterCard
Hong Kong
Dollar
Hungarian
Forint
Japanese Yen JPY Visa, MasterCard Visa, MasterCard Visa, MasterCard
Norwegian
Krone
New Zealand
Dollar
Polish Zloty PLN Visa, MasterCard Visa, MasterCard
Pound Sterling GBP Visa, MasterCard Visa, MasterCard, Maestro Visa, MasterCard
AUD Visa, MasterCard Visa, MasterCard Visa, MasterCard
CAD Visa, MasterCard Visa, MasterCard Visa, MasterCard
HKD Visa, MasterCard Visa, MasterCard
HUF Visa, MasterCard Visa, MasterCard
NOK Visa, MasterCard Visa, MasterCard
NZD Visa, MasterCard Visa, MasterCard
Singapore
Dollar
Swedish Krona SEK Visa, MasterCard Visa, MasterCard
Swiss Franc CHF Visa, MasterCard Visa, MasterCard
U.S. Dollar USD Visa, MasterCard,
SGD Visa, MasterCard Visa, MasterCard
Visa, MasterCard Visa, MasterCard
Discover, American
Express
NOTE: Virtual Terminal for France supports the same currencies as Visa or MasterCard for
the UK. Express Checkout supports all of the countries identified in the table.
16 April 2012 PayPal Payments Pro Integration Guide
Addresses
For Canada, specify the province abbreviation in the State field.
For Great Britain, the State field is ignored; however, you still may need to specify a value
Introducing PayPal Payments Pro
Website Payments Pro Regional Differences
in the State field; for example you can specify the city for both the city and state.
1
For more information about addresses, see the
PayPal Developer Network.
PayPal Payments Pro Integration Guide April 2012 17
Introducing PayPal Payments Pro
1
Website Payments Pro Regional Differences
18 April 2012 PayPal Payments Pro Integration Guide
Introducing Direct Payment
2
Direct Payment lets buyers who do not have a PayPal account use their credit cards without
leaving your website. PayPal processes the payment in the background.
The Direct Payment User Experience
User Interface Recommendations for Direct Payment Checkout
The Direct Payment User Experience
Direct Payment enables buyers to pay by credit or debit card during your checkout flow. You
have complete control over the experience; however, you must consider PCI compliance.
When buyers choose to pay with a credit or debit card, they enter their card number and other
information on your website. After they confirm their order and click Pay, you complete the
order in the background by invoking the DoDirectPa yment API operation. Buyers never
leave your site. Although PayPal processes the order , buyers aren’t aware of PayPal’s
involvement; PayPal will not even appear on the buyer’s credit card statement for the
transaction.
The following diagram shows a typical Direct Payment flow:
The numbers in the diagram correspond to the following implementation steps:
1. On your checkout pages, you need to collect the following information from a buyer to be
used in the DoDirectPayment request:
– Amount of the transaction
– Credit card type
– Credit card number
– Credit card expiration date
PayPal Payments Pro Integration Guide April 2012 19
Introducing Direct Payment
2
The Direct Payment User Experience
– Credit card CSC value
– Cardholder first and last name
– Cardholder billing address
The following example shows the collection of credit card information from a US buyer
after the transaction amount has been determined:
NOTE: In some cases, the billing address and CSC value may be optional. You must also
identify debit on your PCI compliant checkout page when you reference a direct
card checkout image.
2. You must also retrieve the IP address of the buyer's browser and include this with the
request.
3. When a buyer clicks the Pay button, invoke the DoDirectPayment API operation.
4. The PayPal API server executes the request and returns a response.
– Ack code (Success, SuccessWithWarning, or Failure)
– Amount of the transaction
20 April 2012 PayPal Payments Pro Integration Guide
Introducing Direct Payment
User Interface Recommendations fo r D ire ct Pay me n t Che cko u t
– AVS response code
– CSC response code
– PayPal transaction ID
– Error codes and messages (if any)
– Correlation ID (unique identifier for the API call)
5. If the ope r ation is successful, you send the buyer to an order confirmation page.
The Ack code determines whether the operation is a success.
– If successful, you should display a message on the order confirmation page.
– Otherwise, you should show the buyer information related to the error. You should also
provide an opportunity to pay using a different payment method.
User Interface Recommendations for Direct Payment Checkout
Your checkout pages must collect all the information you need to create the
DoDirectPayment request. The request information can be collected by your site’ s checkout
pages.
2
The following recommendations help process requests correctly and make it easier for buyers
to provide necessary information:
IMPORTANT: You are responsible for processing card industry (PCI) compliance for
protecting cardholder data. For example, storing the Card Security Code
(CSC) violates PCI compliance. For more information about PCI compliance,
see
PCI Security Standards Council.
Provide a drop-down menu for the state or province fields for addresses in countries that
use them. For U.S. addresses, the state must be a valid 2-letter abbreviation for the state,
military location, or U.S. territory. For Canada, the province must be a valid 2-letter
province abbreviation. For the UK, do not use a drop-down menu; however, you may need
to provide a value for the state in your DoDirectPayment request.
Ensure buyers can enter the correct number of digits for the Card Security Code (CSC).
The value is 3 digits for Visa, MasterCard, and Discover. The value is 4 digits for
American Express.
Show information on the checkout page that shows where to find the CSC code on the card
and provide a brief explanation of its purpose.
Configure timeout settings to allow for the fact that the DoDirectPayment API operation
might take as long as 60 seconds to complete, even though completion in less than 3
seconds is typical. Consider displaying a “processing transaction” message to the buyer
and disabling the Pay button until the transaction finishes.
Use the optional Invoice ID field to prevent duplicate charges. PayPal ensures that an
Invoice ID is used only once per account. Duplicate requests with the same Invoice ID
result in an error and a failed transaction.
PayPal Payments Pro Integration Guide April 2012 21
Introducing Direct Payment
2
User Interface Recommendations for Direct Payment Checkout
22 April 2012 PayPal Payments Pro Integration Guide
Introducing Express Checkout
3
Express Checkout is PayPal’s premier checkout solution that streamlines the checkout process
for buyers and keeps them on a merchant’s website after making a purchase.
The Express Checkout Experience
Express Checkout Integration Steps
Express Checkout Flow
Express Checkout Building Blocks
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:
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:
PayPal Payments Pro Integration Guide April 2012 23
Introducing Express Checkout
3
Express Checkout Integration Steps
Express Checkout flow
In the Express Checkout flow, the buyer:
1. Chooses Expres s Checkout by clicking Check out with PayPal
2. Logs into PayPal to authenticate his or her identity
3. Reviews the transaction on PayPa l
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 Confirm 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 Confirm order page, 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.
24 April 2012 PayPal Payments Pro 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:
Set your logo on the PayPal site and provide order details in the transaction history.
Use the PayPal Review your information page as your Confirm order 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:
Logo to display
Gradient fill color of the border around the cart review area
3
Language in which PayPal content is displayed
You should include:
Order details, including shipping and tax, during checkout
IMPORTANT: Not displaying this information is a major cause of shopping cart
abandonment during checkout.
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:
Associate a payment with an eBay auction item
Assign an invoice number to a payment
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:
Capture payments associated with authorizations and orders
Process recurring payments
Issue refunds, search transactions using various criteria, and provide other back-office
operations
PayPal Payments Pro Integration Guide April 2012 25
Introducing Express Checkout
3
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:
Make the following changes to implement the complete Express Checkout flow:
On your Shopping cart page, place the Checkout with PayPal button. Handle clicks by
sending the Express Checkout setup request. After receiving the response, redirect your
buyer’s browser to PayPal.
On your Payment methods page, associate the PayPal mark with an option. Handle clicks
by sending the Express Checkout setup request. After receiving the response, redirect your
buyer’s browser to PayPal.
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 your information page. In
this case, your checkout flow can omit your Confirm order page and proceed directly
to your Order confirmation page.
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:
26 April 2012 PayPal Payments Pro Integration Guide
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
3
The following diagram shows how to integrate Express Checkout from your payment methods
page:
Express Checkout Building Blocks
You implement Express Checkout flows with Express Checkout buttons, PayPal API
operations, PayPal commands, and tokens.
The following conceptual diagram identifies the building blocks that you use to integrate
Express Checkout on your website:
PayPal Payments Pro Integration Guide April 2012 27
Introducing Express Checkout
3
Express Checkout Building Blocks
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.
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 recommends that you use dynamic images.
PayPal requires that you use Check out with PayPal buttons and PayPal 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 buttons and images reduce buyer confidence in your site.
Express Checkout Image Flavors
The Check out with PayPal button and the PayPal mark image are available in two flavors:
Dynamic image
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.
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.
28 April 2012 PayPal Payments Pro Integration Guide
Introducing Express Checkout
Express Checkout Building Blocks
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.
3
To create an Express Checkout button, see
bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside. PayPal also
https://www.paypal.com/us/cgi-
provides buttons for other countries. To locate a page for another country, replace the country
abbreviation in the link with another country abbreviation. For example, replace us with uk
for United Kingdom, as follows:
bin/webscr?cmd=xpt/Merchant/merchant/ExpressCheckoutButtonCode-outside. PayPal hosts images
https://www.paypal.com/uk/cgi-
for the countries:
Country-specific buttons and images
URL
Country
Australia au
China cn France fr Germany de Italy it
Japan j1 Netherlands nl Poland pl Spain es
Switzerland ch United
Change Country
Austria at Belgium be Canada ca
Kingdom
NOTE: URL changes are case sensitive. The abbreviation in the URL may not be a country
URL
Change Country
uk United
States
URL
Change Country
us
code.
Payment Mark
URL
Change
The PayPal mark is the image you place on your payment methods page. It looks like this:
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:
PayPal Payments Pro Integration Guide April 2012 29
Introducing Express Checkout
3
Express Checkout Building Blocks
To create a PayPal mark, see https://www.paypal.com/cgi-
bin/webscr?cmd=xpt/Marketing/general/OnlineLogoCenter-outside.
Express Checkout API Operations
The PayPal API provides three API operations for Express Checkout. These API operations
set up the transaction, obtain information about the buyer, and handle 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 information:
URL to the page on your website that PayPal redirects to after the
buyer logs into PayPal and approves the payment successfully.
URL to the page on your website that PayPal redirects to if the buyer
cancels.
T otal amount of the order or your best estimate of the total. It should
be as accurate as possible.
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 in to 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:
The token that was included in the redirect to PayPal
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.
30 April 2012 PayPal Payments Pro Integration Guide
Loading...