PayPal Pro - 2012 Integration Guide

PayPal Payments Pro

Integration Guide

Last updated: April 2012

PayPal Payments Pro Integration Guide

Document Number: 100001.en_US-201204

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.

2449, Luxembourg, R.C.S. Luxembourg B 118 349

Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval

of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.

Notice of non-liability:

PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,

implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused

by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use

of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.

PayPal Payments Pro Integration Guide April 2012 3

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

Contents

4 April 2012 PayPal Payments Pro Integration Guide

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

PayPal Payments Pro Integration Guide April 2012 5

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

Contents

6 April 2012 PayPal Payments Pro Integration Guide

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

PayPal Payments Pro Integration Guide April 2012 7

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.

Where to Go for More Information

8 April 2012 PayPal Payments Pro Integration Guide

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:

[email protected]

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.

Date Description

PayPal Payments Pro Integration Guide April 2012 9

1

Introducing PayPal Payments Pro

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

Merchant Setup and Administration Guide.

 If you use the Payflow API to process transactions with PayPal as your internet merchant

account, see

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.

Introducing PayPal Payments Pro

Additional Features of PayPal Payments Pro

1

10 April 2012 PayPal Payments Pro Integration Guide

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 operation 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.

PayPal Payments Pro Integration Guide April 2012 11

Introducing PayPal Payments Pro

Additional Features of PayPal Payments Pro

1

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.

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 billing amount. Payments reoccur until the profile expires, there 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 handle

payments for varying amounts of money on a varying 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 stand-

alone credit card-processing terminal. Virtual Terminal is ideal when you receive orders by

Introducing PayPal Payments Pro

Additional Features of PayPal Payments Pro

1

12 April 2012 PayPal Payments Pro Integration Guide

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

Virtual Terminal Users Guide.

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

Website Payments Pro

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.

 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

Fraud Management Filters

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

PayPal Payments Pro Integration Guide April 2012 13

Introducing PayPal Payments Pro

PayPal Payments Pro API Operations

1

 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

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)

Introducing PayPal Payments Pro

PayPal Payments Pro API Operations

1

14 April 2012 PayPal Payments Pro Integration Guide

NOTE: If you use the Payflow API to process transactions with PayPal as your internet

merchant account, see

Gateway Developer Guide and Reference.

DoReauthorization Reauthorize a previously authorized payment.

DoVoid Void an order or an authorization.

Recurring Payment API operations:

CreateRecurringPaymentsProfile Create a recurring payments profile.

GetRecurringPaymentsProfileDetails Obtain information about a recurring payments profile.

ManageRecurringPaymentsProfileStatus 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.

GetBillingAgreementCustomerDetails 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.

PayPal API Operation Description

PayPal Payments Pro Integration Guide April 2012 15

Introducing PayPal Payments Pro

Website Payments Pro Regional Differences

1

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:

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:

NOTE: Contact PayPal if you want to increase transaction limits.

Country Accepted credit cards

Canada

 Visa

 MasterCard

NOTE: Interac debit cards are not accepted.

United Kingdom

 Visa, including Visa Electron and Visa Debit

 MasterCard

 Maestro, including Switch

United States

 Visa

 MasterCard

 Discover

 American Express

Country Default transaction limit in default currency

Canada 12,500 CAD

United Kingdom 5,500 GBP

United States 10,000 USD

Introducing PayPal Payments Pro

Website Payments Pro Regional Differences

1

16 April 2012 PayPal Payments Pro Integration Guide

Credit Card Currencies by Country

The following currencies are supported for Direct Payment:

Currencies and Currency Codes Supported by Express Checkout and Direct Payment

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.

Express

Checkout

Currency

Cur-

rency

Code

Direct Payment

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

AUD Visa, MasterCard Visa, MasterCard Visa, MasterCard

Canadian

Dollar

CAD Visa, MasterCard Visa, MasterCard Visa, MasterCard

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

HKD Visa, MasterCard Visa, MasterCard

Hungarian

Forint

HUF Visa, MasterCard Visa, MasterCard

Japanese Yen JPY Visa, MasterCard Visa, MasterCard Visa, MasterCard

Norwegian

Krone

NOK Visa, MasterCard Visa, MasterCard

New Zealand

Dollar

NZD Visa, MasterCard Visa, MasterCard

Polish Zloty PLN Visa, MasterCard Visa, MasterCard

Pound Sterling GBP Visa, MasterCard Visa, MasterCard, Maestro Visa, MasterCard

Singapore

Dollar

SGD Visa, MasterCard Visa, MasterCard

Swedish Krona SEK Visa, MasterCard Visa, MasterCard

Swiss Franc CHF Visa, MasterCard Visa, MasterCard

U.S. Dollar USD Visa, MasterCard,

Discover, American

Express

Visa, MasterCard Visa, MasterCard

PayPal Payments Pro Integration Guide April 2012 17

Introducing PayPal Payments Pro

Website Payments Pro Regional Differences

1

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

in the State field; for example you can specify the city for both the city and state.

For more information about addresses, see the

PayPal Developer Network.

Introducing PayPal Payments Pro

Website Payments Pro Regional Differences

1

18 April 2012 PayPal Payments Pro Integration Guide

PayPal Payments Pro Integration Guide April 2012 19

2

Introducing Direct Payment

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 DoDirectPayment 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

Introducing Direct Payment

The Direct Payment User Experience

2

20 April 2012 PayPal Payments Pro Integration Guide

– 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

Page is loading ...

PayPal Pro - 2012 Integration Guide

This manual is also suitable for

PayPal Pro - 2012 Integration Guide

Related papers

Other documents