PayPal Website Payments Pro - 2007 Developer's Guide
Website Payments Pro Developer’s Guide
© 2006 PayPal Inc. All rights reserved. PayPal, the PayPal logo, Payflow, and Payflow Pro are registered
trademarks 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.
PayPal (Europe) Ltd. is authorised and regulated by the Financial Services Authority in the United
Kingdom as an electronic money institution. PayPal FSA Register Number: 226056.
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 Inc. does not guarantee that the features described in this document will be announced or made
available to anyone in the future.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Organisation of This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
How to Contact Customer Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Chapter 1 Website Payments Pro Overview . . . . . . . . . . . . . . 9
How Website Payments Pro Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Supported Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Supported Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Direct Payment Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
PayPal Express Checkout Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Additional Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Business Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
About the PayPal SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Chapter 2 Installing and Configuring the Payflow SDK . . . . . . . . 13
Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Preparing the Payflow Client Application . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Chapter 3 Creating a Simple Transaction Request . . . . . . . . . . .15
Transaction Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Request Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Data Modes for Sending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Values Required by All Transaction Types. . . . . . . . . . . . . . . . . . . . . . . . 17
Sale Transaction Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Typical Sale Transaction PARMLIST . . . . . . . . . . . . . . . . . . . . . . . . . . 18
How to Format a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Website Payments Pro Developer’s Guide 3
Contents
Chapter 4 Performing Direct Payment Credit Card Transactions . . .21
How Direct Payment Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
About Direct Payment Credit Card Processing . . . . . . . . . . . . . . . . . . . . . . . 22
Considerations Regarding Your Website Integration . . . . . . . . . . . . . . . . . . 23
Parameters Used in Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Additional Parameters by Transaction Type . . . . . . . . . . . . . . . . . . . . . . . . . 29
Submitting Sale Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
When to Use a Sale Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Additional Parameters for Sale Transactions . . . . . . . . . . . . . . . . . . . . . . 30
Typical Sale Transaction Parameter String . . . . . . . . . . . . . . . . . . . . . . . 30
Submitting Authorisation/Delayed Capture Transactions . . . . . . . . . . . . . . . . . . 31
Required Authorisation Transaction Parameters . . . . . . . . . . . . . . . . . . . . 31
Typical Authorisation Transaction Parameter String . . . . . . . . . . . . . . . . . . . 31
Required Delayed Capture Transaction Parameters . . . . . . . . . . . . . . . . . . 32
Delayed Capture Transaction: Capturing Transactions for Lower Amounts . . . . . . . 33
Delayed Capture Transaction: Capturing Transactions for Higher Amounts . . . . . . 34
Delayed Capture Transaction: Error Handling and Retransmittal . . . . . . . . . . . . 35
Submitting Credit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Required Credit Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . 35
Credit Transaction Parameter Strings . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Submitting Void Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
When to Use a Void Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Required Void Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 36
Example Void Transaction Parameter String . . . . . . . . . . . . . . . . . . . . . . 37
Recharging to the Same Credit Card (Reference Transactions). . . . . . . . . . . . . . . 37
When to Use a Reference Transaction . . . . . . . . . . . . . . . . . . . . . . . . . 37
Transaction Types that Can Be Used as the Original Transaction . . . . . . . . . . . 38
Fields Copied from Reference Transactions. . . . . . . . . . . . . . . . . . . . . . . 38
Example Reference Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Using Address Verification Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Example AVS Request Parameter String . . . . . . . . . . . . . . . . . . . . . . . . 40
Example AVS Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Card Security Code Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
American Express Card Security Code Enhancements . . . . . . . . . . . . . . . . . 41
Example CVV2 Request Parameter String . . . . . . . . . . . . . . . . . . . . . . . 42
Example CVV2 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4 Website Payments Pro Developer’s Guide
Contents
Chapter 5 Testing Credit Card Transactions . . . . . . . . . . . . . . 43
Testing Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Credit Card Numbers Used for Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Testing Result Code Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Chapter 6 PayPal Express Checkout Transaction Processing . . . . . 47
What Is PayPal Express Checkout? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
How PayPal Express Checkout Works . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Sale and Authorisation Transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Void, Delayed Capture and Credit Transactions. . . . . . . . . . . . . . . . . . . . . 50
PayPal Express Checkout Sale Transaction Example. . . . . . . . . . . . . . . . . . . . 50
Set Express Checkout (ACTION=S) . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Redirecting the Customer to PayPal Example. . . . . . . . . . . . . . . . . . . . . . 51
Get Express Checkout Details (ACTION=G) . . . . . . . . . . . . . . . . . . . . . . 52
Redirecting the Customer to Your Website Example . . . . . . . . . . . . . . . . . . 52
Do Express Checkout Payment (ACTION=D) . . . . . . . . . . . . . . . . . . . . . . 53
PayPal Express Checkout Transaction Parameter Descriptions . . . . . . . . . . . . . . 53
Sale and Authorisation Transaction Parameters . . . . . . . . . . . . . . . . . . . . 53
Void Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Delayed Capture Transaction Parameters. . . . . . . . . . . . . . . . . . . . . . . . 62
Credit Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Chapter 7 PayPal Button Placement and Page Designs . . . . . . . .65
HTML for PayPal Button Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Examples of Button Placement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Payment Method Page Layout Recommendations . . . . . . . . . . . . . . . . . . . . . 67
Chapter 8 Responses to Transaction Requests . . . . . . . . . . . .69
Contents of a Transaction Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Address Verification Responses from PayPal . . . . . . . . . . . . . . . . . . . . . . . . 71
Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Normalised Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
PayPal Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
PNREF Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
PNREF Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Website Payments Pro Developer’s Guide 5
Contents
RESULT Codes and RESPMSG Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
RESULT Values for Transaction Declines or Errors . . . . . . . . . . . . . . . . . . . 74
RESULT Values for Communications Errors . . . . . . . . . . . . . . . . . . . . . . 80
Appendix A Verbosity: Viewing Processor-Specific
Transaction Results . . . . . . . . . . . . . . . . . . . . .83
Supported Verbosity Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Changing the Verbosity Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Setting the Default Verbosity Level for All Transactions . . . . . . . . . . . . . . . . . 85
Setting the Verbosity Level on a Per-Transaction Basis. . . . . . . . . . . . . . . . . 85
Appendix B ISO Country Codes . . . . . . . . . . . . . . . . . . . . .87
6 Website Payments Pro Developer’s Guide
Preface
Website Payments Pro Developer’s Guide describes Website Payments Pro and how
to integrate it into your website using the Payflow SDK. The product offers two website
payment solutions: PayPal Direct Payment and PayPal Express Checkout.
Intended Audience
This guide is written for merchants who have signed up through PayPal Manager to
use PayPal as their processor and Website Payments Pro as their solution for handling
payment transactions on their website.
This guide assumes that its readers:
z Are experienced web or application developers
z Have a background in payments services
Scope
This guide describes the Payflow SDK programming interfaces needed to integrate Website
Payments Pro into your website, along with guidelines and best practices for presenting
these payment offerings.
Organisation of This Document
The guide is organised into the following chapters and appendices:
z Chapter 1, “Website Payments Pro Overview”, provides a brief overview of the product.
z Chapter 2, “Installing and Configuring the Payflow SDK”, describes where to get the
Payflow SDK and how to install it.
z Chapter 3, “Creating a Simple Transaction Request”, identifies a common set of
transaction data required in all transactions and provides syntax guidelines on how to
format it so that it can be understood by the Payflow server.
z Chapter 4, “Performing Direct Payment Credit Card Transactions”, describes how you can
implement Direct Payment credit card processing. The chapter provides a basic set of data
parameters typically used in transaction requests.
z Chapter 5, “Testing Credit Card Transactions”,
Website Payments Pro Developer’s Guide 7
Preface
Where to Go for More Information
z Chapter 6, “PayPal Express Checkout Transaction Processing”, explains how PayPal
Express Checkout works and describes additional (optional) parameters you can send
in PayPal Express Checkout transaction requests.
z Chapter 7, “PayPal Button Placement and Page Designs”,
z Chapter 8, “Responses to Transaction Requests”, describes parameters returned in
transaction responses.
z Appendix A, “Verbosity: Viewing Processor-Specific Transaction Results”, describes how
you can use the VERBOSITY parameter to control the kind and level of information you
want returned in a transaction response
z Appendix B, “ISO Country Codes”, lists the country codes you provide as transaction data
in certain transactions.
Where to Go for More Information
PayPal Manager Online Help describes the use of PayPal Manager — the web-based
administration tool that you can use to process transactions manually, issue credits
and generate reports. PayPal Manager provides links to the PayPal website, where you can
perform additional tasks such as resolving disputes. See the Manager Online Help for details.
Getting Started with PayPal Manager contains instructions on how to use PayPal Manager,
including testing credit card numbers and Direct Payments.
For answers to specific questions about Payflow products, search PayPal’s Knowledge Base
at the following URL:
http://knowledge.paypal.com/.
How to Contact Customer Service
For problems with transaction processing or your connection to the server, contact Customer
Service at business-support@paypal.co.uk.
8 Website Payments Pro Developer’s Guide
Website Payments Pro Overview
1
With Website Payments Pro, you get the payment processing capabilities of a merchant
account and gateway – plus much more. It is an all-in-one payment solution that includes:
z Direct Payment. Direct Payment enables you to accept credit card payments directly
on your website. PayPal remains invisible, so you control the customer experience.
z PayPal Express Checkout. PayPal Express Checkout allows PayPal account holders
to check out fast with saved information, and enables you to gain incremental sales
from PayPal’s growing base of users.
How Website Payments Pro Works
Figure 1.1, “ High-Level View”, is an example of a standard checkout process.
Website Payments Pro has the flexibility to work with your unique checkout process,
whether it is one page or has multiple steps.
FIGURE 1.1 High-Level View
Website Payments Pro Developer’s Guide 9
Website Payments Pro Overview
1
Supported Transactions
After selecting products to purchase, your customer chooses whether they want to pay using
PayPal or pay using credit cards directly on your website.
If your customer pays using credit cards on your website, PayPal processes them in the
background.
If your customer chooses to use PayPal, your customer is transferred to PayPal to log in and
select a postal address and payment method, and is returned to your website to complete their
purchase.
Once the buyer completes their order, you receive your payment.
Supported Transactions
Website Payments Pro supports the following transaction types:
Sale
Authorisation
Vo i d
Delayed Capture
Credit
Chapter 4, “Performing Direct Payment Credit Card Transactions”, describes the transaction
types in detail and identifies the minimum parameters that you must send for each.
Supported Currencies
Website Payments Pro supports the following currencies:
z USD (US dollar)
z EUR (Euro)
z GBP (UK pound)
z CAD (Canadian dollar)
z JPY (Japanese Yen)
z AUD (Australian dollar)
Unlike other processors that require you to set up a separate account for each currency,
PayPal allows you to run transactions using any of the six currencies with a single account.
10 Website Payments Pro Developer’s Guide
Direct Payment Overview
Direct Payment offers you direct credit card payment processing capability through PayPal.
For credit card transactions, customers can stay on your website as PayPal processes the
payment in the background.
For each payment, Direct Payment takes the billing address, transaction amount, credit card
information and item information as inputs. Within seconds, PayPal returns a confirmation
that the transaction has been processed. If you have signed up for Fraud Protection Services,
Direct Payment lets you flag potentially fraudulent transactions, and provides you with
industry-standard Address Verification Service and card security code (CVV2) responses
for each transaction.
By integrating Direct Payment with PayPal Express Checkout as part of the Website Payments
Pro solution, you can accept all major payment types, including PayPal, while working with a
single provider that processes and manages all your online payments for you.
IMPORTANT:Direct Payment is not a standalone product. You are required to use Direct
Payment and PayPal Express Checkout together as part of the Website
Payments Pro solution. See “Business Rules” on page 12.
Direct Payment is not covered by the PayPal Seller Protection Policy (SPP).
Website Payments Pro Overview
Direct Payment Overview
1
PayPal Express Checkout Overview
With PayPal Express Checkout, a customer selects their products and completes their
orders on your website. Payment method along with postage and billing details are managed
on PayPal’s website. PayPal automatically gives you the postal address and other customer
information to fulfil the order.
The more convenient it is for your customers to buy from you, the more they'll buy.
PayPal Express Checkout allows customers the option to pay quickly through PayPal
and gives your business more benefits.
PayPal Express Checkout provides these advantages to your customers:
z Gives buyers more convenience, and gets more sales. Since your customers simply log
in to use information they've already entered with PayPal, they save time by completing
transactions in fewer steps.
z Helps buyers feel safer, so they buy more. Buyers prefer to pay with PayPal because
their customer information is kept safe. When they’re confident about the security
of their information, they purchase more.
With this design, you have these advantages:
z Real-time notification of successful payments.
z Automation of your internal business processes.
z More advertising opportunities as buyers finish their orders on your website.
z Notification that the buyer's address is confirmed.
z Eligibility for coverage under PayPal’s Seller Protection Policy.
Website Payments Pro Developer’s Guide 11
Website Payments Pro Overview
1
Additional Services
Additional Services
If you have signed up for the Recurring Billing Service, see the Payflow Pro Recurring Billing
Service User’s Guide. It is downloadable from the PayPal Manager Documentation page.
Business Rules
Website Payments Pro must be integrated on your website in the following ways. You must:
z Present the PayPal Express Checkout button and associated messaging before requesting
postal address, billing address and financial information. PayPal account holders should
not be required to enter any of this information on your website, because the information
is available from their PayPal accounts.
z Display PayPal as an option together with other payment methods, wherever other payment
methods are offered.
z Present the PayPal mark graphic wherever other payment marks are displayed.
For details on displaying PayPal graphics on your website, see Chapter 7, “Integrating PayPal
Button Graphics”.
Testing For details on testing, see the documentation at the following URL:
https://test-expresscheckout.paypal.com/documentation/
About the PayPal SDK
The SDK is available from the PayPal Manager Downloads page.
12 Website Payments Pro Developer’s Guide
Installing and Configuring the
2
Payflow SDK
The Payflow SDK is available either as a standalone client that you can integrate with your
web shop using CGI scripts or as a set of APIs for direct integration with your application.
This chapter provides instructions for downloading the SDK appropriate to your platform.
IMPORTANT:Full API documentation is included with each SDK.
Supported Platforms
The PayPal SDK is available on all major web server platforms in a variety of formats
to support your integration requirements. It is available as a C library (.dll/.so), binary
executable, Java library, COM object, Java Native Interface and Perl Module Interface.
TABLE 2.1 Supported platforms
Windows NT 4.0, 2000, 2003 Linux - libc6 / glibc2 / ELF kernels 2.0.36 and above
Solaris 2.6 - Intel Linux (Redhat 9.x)
Solaris 2.7/2.8 - Sparc Pure Java Any JDK 1.2, 1.4
BSDI 4.0 SGI IRIX 6.2
HP UX 11.0 AIX 4.3
FreeBSD 5.x
Website Payments Pro Developer’s Guide 13
Installing and Configuring the Payflow SDK
2
Preparing the Payflow Client Application
Preparing the Payflow Client Application
Follow these steps to download and install:
Step 1 Download the Payflow SDK
From the Download page in PayPal Manager (
Payflow SDK appropriate for your platform.
Step 2 Extract the files to a local directory
Step 3 Configure your firewall
If you have a stateful firewall, enable outbound traffic for SSL (port 443). The firewall
keeps state on the connection, and automatically permits the inbound response from PayPal.
If you do not have a stateful firewall, enable inbound and outbound traffic for SSL (port 443).
Outbound traffic permits the initial request by Website Payments Pro, while inbound permits
the response from PayPal.
Step 4 Set the certificate path
To enable the client to authenticate the Payflow server, you must set the path to include
the certs directory (included with the SDK that you downloaded).
For specific information on setting the certificate path, see the readme.txt file and example
applications in the SDK.
Step 5 Read the readme.txt file
The readme.txt file includes integration information and samples that illustrate how to use
the client in your development environment.
https://manager.paypal.com), download the
14 Website Payments Pro Developer’s Guide
Creating a Simple Transaction
3
Request
This chapter describes how to create a simple Sale transaction request.
The chapter focuses on the common set of parameters required in all transactions and how
you set up these parameters using name-value pair strings. Additional parameters are required,
depending on the transaction type. You can also provide many optional parameters, depending
on the results you want returned. For example, you can set the VERBOSITY parameter to
return PayPal processor-specific details rather than normalised information if you are looking
for this kind of information.
In This Chapter
z “Transaction Request” on page 15
z “Sale Transaction Example” on page 18
z “How to Format a Transaction” on page 19
Transaction Request
Request Contents
A transaction request includes the following:
z Connection parameters.
z Parameters required by all transactions. This list includes 'user information' parameters.
z Additional parameters required by the type of transaction.
Data Modes for Sending
You can send parameter data in the transaction request to the Payflow server in either
of two modes:
z Name-value pair
z XMLPay
The examples in this guide are presented in name-value pair format. Name-value pair syntax
guidelines are described in “PARMLIST Syntax Guidelines” on page 16.
XMLPay is an XML syntax for payment requests and associated responses in a
payment-processing network. Instead of using name-value pairs, you can send to the Payflow
server XML documents based on the XMLPay 2.0 schema. For details on XMLPay, see the
Website Payments Pro — XMLPay Developer’s Guide. It is available from the Documentation
page in PayPal Manager.
Website Payments Pro Developer’s Guide 15
Creating a Simple Transaction Request
3
Transaction Request
Connection Parameters
Table 3.1 describes the connection parameters. Pass them in the format and syntax required
by the Payflow SDK and programming language that you are using. See your integration
documentation for details.
TABLE 3.1 Connection parameters
Argument Required Description
16
HOSTADDRESS
HOSTPORT
PARMLIST
TIMEOUT
PROXYADDRESS
PROXYPORT
PROXYLOGON
Yes
Yes
Yes
Yes
No
No
No
Payflow host name.
For live transactions, use payflowpro.verisign.com
For testing purposes use pilot-payflowpro.verisign.com
Use port 443.
The PARMLIST is the list of parameters that specify the payment
information for the transaction. The quotation marks “ ” at the beginning
and end are required. The following is an example:
"TRXTYPE=S&TENDER=C&PARTNER=PayPalUK&VENDOR=SuperMercha
nt&USER=SuperMerchant&PWD=SuperUserPassword&AMT=123.00"
The content of the PARMLIST varies by the type of transaction being
processed. For example, a Void transaction requi res a dif ferent set of
parameters than a Sale.
Time-out period for the transaction. The minimum recommended time-out
value is 30 seconds. The client begins tracking from the time that it sends
the transaction request to the server.
Proxy server address. Use the PROXY parameters for servers behind
a firewall. Your network admi nistrator can provide the values.
Proxy server port.
Proxy server logon ID.
PROXYPASSWORD No Proxy server logon password.
PARMLIST Syntax Guidelines
Follow these guidelines when creating the PARMLIST:
Spaces are allowed in values.
Enclose the PARMLIST in quotation marks (“”).
Do not place quotation marks (“”) within the body of the PARMLIST.
Separate all name-value pairs in the PARMLIST using an ampersand (&).
Payflow SDKSet the VERBOSITY transaction parameter to MEDIUM (default is LOW)
if you want the response to return more detailed information. For details, see Appendix A,
“Verbosity: Viewing Processor-Specific Transaction Results”.
Website Payments Pro Developer’s Guide
Using Special Characters in Values
Because the ampersand (&) and equal sign (=) characters have special meanings
in the PARMLIST, name-value pairs like the following examples are not valid:
NAME=Ruff & Johnson
COMMENT1=Level=5
To use special characters in the value of a name-value pair, use a length tag. The length tag
specifies the exact number of characters and spaces that appear in the value. The following
name-value pairs are valid:
NAME[14]=Ruff & Johnson
COMMENT1[7]=Level=5
NOTE: Quotation marks (“ ”) are not allowed even if you use a length tag.
Values Required by All Transaction Types
All Payflow SDK transactions require the parameters described in Table 3.2.
Creating a Simple Transaction Request
Transaction Request
3
TABLE 3.2 Required transaction parameters
Parameter Description Required Type
USER If you set up one or more additional users on the account,
this value is the ID of the user authorised to process
transactions. If, however, you have not set up additional
users on the account, USER has the same value as
VENDOR.
The examples in this document use
USER=SuperMerchant.
Limitations: This value is case-sensitive.
VENDOR Your merchant login ID that you created when you
registered for the Website Payments Pro account.
The examples in this document use
VENDOR=SuperMerchant.
Limitations: This value is case-sensitive.
PARTNER The ID provided to you by the authorised PayPal Reseller
who registered you for the Payflow SDK. If you
purchased your account directly from PayPal, use
PayPalUK.
The examples in this document use
PA RTN E R= Pa y Pa lU K
Limitations: This value is case-sensitive.
Yes Alphanumeric 64
Yes Alphanumeric 64
Yes Alphanumeric 12
Max.
Length
Website Payments Pro Developer’s Guide 17
Creating a Simple Transaction Request
3
Sale Transaction Example
ABLE 3.2 Required transaction parameters(Continued)
T
Parameter Description Required Type
Max.
Length
PWD The 6 to 32-character password that you defined while
registering for the account.
The examples in this document use
PWD=SuperUserPassword.
This value is case-sensitive.
TENDER The tender type (method of payment). Values are:
z C = Credit card for Direct Payment transactions
z P = PayPal for PayPal Express Checkout transactions
TRXTYPE A single character indicating the type of transaction to
perform. Website Payments Pro supports the following
values:
S = Sale transaction
A = Authorisation
C = Credit
D = Delayed Capture
V = Void
Sale Transaction Example
In addition to the connection parameters and the required parameters in Table 3 .2, each
transaction type (TRXTYPE) has additional parameter requirements and can use a number
of optional ones as well.
For example, to perform a Direct Payment credit card Sale transaction, you are required
to pass the following parameters:
z ACCT - The payer’s credit card number
z AMT - The amount of the sale
z EXPDATE - The expiry date of the credit card
Yes Alphanumeric 32
Yes Alpha 1
Yes Alpha 1
Typical Sale Transaction PARMLIST
The following is a typical PARMLIST string passed in a Sale transaction.
"TRXTYPE=S&TENDER=C&USER=SuperMerchant&PWD=SuperUserPassword&PARTNER=PayPal
UK&ACCT=5105105105105100&EXPDATE=1209&AMT=99.06&COMMENT1=Reservation&FIRSTN
AME=John&LASTNAME=Jones&STREET=123 Main St.&CITY=San
Jose&STATE=CA&ZIP=123451234&COUNTRY=US&CVV2=123&CLIENTIP=0.0.0.0"
Note that, besides the required Sale transaction parameters, this string includes other typical
Website Payments Pro Payflow Edition parameters. These parameters are described in
Chapter 4, “Performing Direct Payment Credit Card Transactions”. and in Chapter 6, “PayPal
Express Checkout Transaction Processing”.
18 Website Payments Pro Developer’s Guide
How to Format a Transaction
For details on how to format a transaction based on the above information, refer
to the examples and the supporting documentation provided with your SDK.
Creating a Simple Transaction Request
How to Format a Transaction
3
Website Payments Pro Developer’s Guide 19
Creating a Simple Transaction Request
3
How to Format a Transaction
20 Website Payments Pro Developer’s Guide
Performing Direct Payment Credit
4
Card Transactions
This chapter provides guidelines on how to implement PayPal Direct Payment transactions.
Direct Payment offers you credit card payment processing capability through PayPal directly
from the buyer’s credit card.
NOTE: Direct Payment is not a standalone feature. You must use Direct Payment together
with PayPal Express Checkout. See Chapter 7, “PayPal Button Placement and
Page Designs,” for guidelines on how to display the PayPal mark logo with credit
card logos.
With the exception of a few optional PayPal Express Checkout transaction parameters not
covered here, this chapter describes all required Website Payments Pro Payflow Edition
request parameters. Differences exist in PayPal Express Checkout transactions, however, and
these are explained in Chapter 6, “PayPal Express Checkout Transaction Processing.”
In This Chapter
z “How Direct Payment Works” on page 22
z “About Direct Payment Credit Card Processing” on page 22
z “Parameters Used in Transactions” on page 23
z “Additional Parameters by Transaction Type” on page 29
z “Submitting Sale Transactions” on page 29
z “Submitting Authorisation/Delayed Capture Transactions” on page 31
z “Submitting Credit Transactions” on page 35
z “Submitting Void Transactions” on page 36
z “Recharging to the Same Credit Card (Reference Transactions)” on page 37
z “Using Address Verification Service” on page 39
z “Card Security Code Validation” on page 40
Website Payments Pro Developer’s Guide 21
Performing Direct Payment Credit Card Transactions
4
How Direct Payment Works
How Direct Payment Works
Figure 3-1 shows the general flow of customer checkout with Direct Payment.
The numbered steps in the figure are described below:
1. On your website, the customer chooses to pay with a credit card and enters the credit card number
and other details.
2. The customer reviews the order.
3. When your customer clicks “Pay” to place the order, you perform a transaction to request payment,
and the payment transaction is initiated.
4. You transfer your customer to your order confirmation page.
The “Pay” button on your website sends the payment request to the server, including required
information you collected from the customer, such as the amount of the transaction, the
buyer’s credit card number, expiry date, browser IP address, and an element that specifies
whether this transaction is a final sale (complete transaction amount including postage,
packing and tax) or an authorisation for a final amount that you must capture later with a
Delayed Capture transaction.
About Direct Payment Credit Card Processing
Direct Payment credit card processing occurs in two steps — a real-time authorisation and a
capture (settlement) of the funds that were authorised. You perform these two steps either as a
single Sale transaction or as two types of transactions, an Authorisation and Delayed Capture,
depending on your business model.
22 Website Payments Pro Developer’s Guide
Performing Direct Payment Credit Card Transactions
Parameters Used in Transactions
For an Authorisation, PayPal sends the transaction information to the cardholder’s issuing
bank. The issuing bank checks whether the card is valid, evaluates whether sufficient credit
exists, checks values such as Address Verification Service and card security codes, and returns
a response: Approval, Decline, Referral, or others. For details on Address Verification Service
and card security codes, see:
z “Using Address Verification Service” on page 39
z “Card Security Code Validation” on page 40
You receive the response shortly after you submit the transaction to PayPal. If the
Authorisation is approved, the bank temporarily reserves credit for the amount of the
transaction to prepare to capture (fulfil) the transaction. The hold on funds typically lasts for
about a week.
Capturing a transaction (also known as settling a transaction) actually transfers the funds to
PayPal. At least once a day, the Payflow server gathers all transactions that are flagged to be
settled and sends them in a batch file to PayPal. PayPal charges the issuing bank and transfers
the funds to your PayPal account. It typically takes a few days before the money is actually
available in your PayPal account.
4
Considerations Regarding Your Website Integration
In the design of your website integration, you should consider whether you want to store
information in your local database or use PayPal Manager reports to manage the data. You
may want to store postal information in your system, or you may prefer to send the
information to PayPal with the transaction and report on it later.
NOTE: PayPal recommends that you do not store credit card numbers. If you must store
numbers, encrypt and store them behind properly configured firewalls. You should also
consider whether and how to use the merchant-defined fields COMMENT1 and
COMMENT2 to help tie PayPal reports to your orders/customers or to report on other
information about the transaction.
If you want to integrate with other systems, such as order fulfilment, customer service, and so
on, you may want to connect these systems directly to
Website Payments Pro for capturing
funds, issuing refunds/credits, and so on. Alternatively, you may prefer to perform these steps
manually using PayPal Manager. Either way, PayPal recommends that you monitor transaction
activity using PayPal Manager.
Parameters Used in Transactions
PayPal accepts the parameters listed in Tab le 4.1. The table indicates whether the parameters
are required or optional.
Website Payments Pro Developer’s Guide 23
Performing Direct Payment Credit Card Transactions
4
Parameters Used in Transactions
NOTE: Unless otherwise noted, the parameters in Table 4.1 can be used in Direct Payment and
PayPal Express Checkout transactions. See Chapter 6, “PayPal Express Checkout
Transaction Processing,” for additional (optional) PayPal Express Checkout
parameters.
TABLE 4.1 Transaction parameters
Parameter Description Required Type
ACCT Payer’s credit card or account number. It may
not contain spaces, non-numeric characters, or
dashes.
For example, ACCT=5555555555554444
Ye s
a
Max.
Length
Numeric 19
ACCTTYPE Credit card type. The following card types are
supported:
0 = Visa
1 = MasterCard
8 = Other
9 = Switch
S = Solo
AMT Total of this order.
NOTE: You must set CURRENCY to one of
the three-character currency codes for
any of the supported PayPal currencies.
See CURRENCY in this table for
details.
Limitations: Must not exceed $10,000 USD in
any currency. No currency symbol. Decimal
separator must be a period (.). Do not use
comma separators. Use 1199.95, not 1,199.95.
BILL-TO Address (Next five table entries)
STREET Cardholder’s bill-to postal address (number and
street name).
The STREET value is verified by Address
Verification System (described on
page 39).
No Alpha 10
Yes Decimal 10
No Alpha-
numeric
100
CITY Name of bill-to city. No String 40
STATE Name of bill-to county or province. No String 40
COUNTRY Bill-to country code. See
Country Codes
.”
Appendix B, “ISO
No Alpha 2
24 Website Payments Pro Developer’s Guide
Performing Direct Payment Credit Card Transactions
Parameters Used in Transactions
ABLE 4.1 Transaction parameters (Continued)
T
Parameter Description Required Type
4
Max.
Length
ZIP Account holder’s five to nine-digit bill-to ZIP
code or other country-specific bill-to postcode.
Do not use spaces, dashes or non-numeric
characters.
ZIP is verified by Address Verification System
and the International Address Verification
System (described on
page 39).
BUTTONSOURCE Identification code for use by third-party
applications to identify transactions.
CARDISSUE Issue number of Switch or Solo card.
NOTE: For a Switch or Solo transaction to be
approved, either CARDISSUE or
CARDSTART must be present.
CARDSTART Date that Switch or Solo card was issued in
mmyy format.
For example, 0308 represents March 2008.
NOTE: For a Switch or Solo transaction to be
approved, either CARDISSUE or
CARDSTART must be present.
CLIENTIP IP address of payer’s browser as recorded in its
HTTP request to your website.
NOTE: PayPal records this IP address as a
means to detect possible fraud.
Limitations: This value is in dotted quad format:
xxx.xxx.xxx.xxx
No String 20
No Alpha-
32
numeric
No Numeric 2
No Numeric 4
No, but is
String 15
recommended
COMMENT1 Merchant-defined value for reporting and
auditing purposes. See
Verification Service” on page 39
“Using Address
.”
COMMENT2 Merchant-defined value for reporting and
auditing purposes.
CAPTURECOMPLETE Indicates if this Delayed Capture transaction is
the last capture you intend to make. The values
No Alpha-
numeric
No Alpha-
numeric
No Alpha-
numeric
128
128
12
are:
z Y (default)
z N
NOTE: If CAPTURECOMPLETE is Y, any
remaining amount of the original
reauthorised transaction is
automatically voided.
Website Payments Pro Developer’s Guide 25
Performing Direct Payment Credit Card Transactions
4
Parameters Used in Transactions
ABLE 4.1 Transaction parameters (Continued)
T
Parameter Description Required Type
Max.
Length
CURRENCY One of the following three-character currency
No Alpha 3
codes:
z USD (US dollar)
z EUR (Euro)
z GBP (UK pound)
z CAD (Canadian dollar)
z JPY (Japanese Yen)
z AUD (Australian dollar)
CUSTOM A free-form field for your own use. No Alpha-
numeric
CUSTREF Merchant-defined identifier for reporting and
auditing purposes. For example, you can set
No Alpha-
numeric
CUSTREF to INVNUM.
CVV2 A three of four-digit code that is printed (not
imprinted) on the back of a credit card. Used as
No Alpha-
numeric
partial assurance that the card is in the buyer’s
possession. For details, see
Code Validation” on page 40
NOTE: CVV2 values are normalised to Y, N
“Card Security
.
and X values. The PayPal processor
values are returned when you set
VERBOSITY parameter to MEDIUM.
For details on VERBOSITY, see
Appendix A, “Verbosity: Viewing
Processor-Specific Transaction
Results
.”
256
12
4
EMAIL Email address of payer. No Alpha-
127
numeric
EXPDATE Expiry date of the credit card in mmyy format.
Ye s
a
Numeric 4
For example, 0308 represents March 2008.
FREIGHTAMT Total postage costs for this order.
NOTE: You must set CURRENCY to one of
No Decimal 10
the three-character currency codes for
any of the supported PayPal currencies.
See the CURRENCY entry in this table
for details.
Limitations: Must not exceed $10,000 USD in
any currency. No currency symbol. Decimal
separator must be a period (.). Do not use
comma separators. Use 1199.95, not 1,199.95.
26 Website Payments Pro Developer’s Guide
Performing Direct Payment Credit Card Transactions
Parameters Used in Transactions
ABLE 4.1 Transaction parameters (Continued)
T
Parameter Description Required Type
4
Max.
Length
HANDLINGAMT Total packing costs for this order.
NOTE: You must set CURRENCY to one of
the three-character currency codes for
any of the supported PayPal currencies.
See the CURRENCY entry in this table
for details.
Limitations: Must not exceed $10,000 USD in
any currency. No currency symbol. Decimal
separator must be a period (.). Do not use
comma separators. Use 1199.95, not 1,199.95.
INVNUM Your own unique invoice or tracking number. No Alpha-
ITEMAMT Sum of cost of all items in this order.
Limitations: Must not exceed $10,000 USD in
any currency. No currency symbol. Decimal
separator must be a period (.). Do not use
comma separators. Use 1199.95, not 1,199.95.
L_DESCn Line item name.
NOTE: You can view line item information in
the Transaction Details report in your
PayPal merchant account.
No Decimal 10
numeric
No Decimal 127
No String 127
127
L_AMTn Cost of line item.
NOTE: You must set CURRENCY to one of
the three-character currency codes for
any of the supported PayPal currencies.
See the CURRENCY entry in this table
for details.
Limitations: Must not exceed $10,000 USD in
any currency. No currency symbol. Decimal
separator must be a period (.). Do not use
comma separators. Use 1199.95, not 1,199.95.
L_QTYn Line item quantity. No String Any
L_TAXAMTn Line item tax amount.
Limitations: Any valid currency amount;
CURRENCY value must be set the same as
for AMT.
Website Payments Pro Developer’s Guide 27
No Decimal See
description
positive
integer
No Decimal See
description
Performing Direct Payment Credit Card Transactions
4
Parameters Used in Transactions
T
ABLE 4.1 Transaction parameters (Continued)
Parameter Description Required Type
Max.
Length
MERCHANTSESSIONID Your customer Direct Payment session
No String 64
identification token.
PayPal records this session token as an
additional means to detect possible fraud.
NAME Information (Next two table entries)
FIRSTNAME Account holder's first name. No, but
recommended
LASTNAME Account holder’s last name. No, but
recommended
NOTIFYURL Your URL for receiving Instant Payment
No Alpha-
Notification (IPN) about this transaction.
If you do not specify NOTIFYURL in the
request, the notification URL from your
Merchant Profile is used, if one exists.
ORDERDESC Description of items the
customer is
No Alpha-
purchasing.
ORIGID ID of the original Direct Payment transaction
Ye s
a
that is being referenced. This ID is returned by
the PNREF parameter and appears as the
Transaction ID in PayPal Manager reports.
Limitations: This value is case-sensitive.
Alpha 25
Alpha 25
2048
numeric
127
numeric
Alpha-
12
numeric
RECURRINGTYPE Type of transaction occurrence. The values are:
No Alpha 1
F = First occurrence
S = Subsequent occurrence (default)
SHIP-TO Address Information (Next five table entries)
b
SHIPTOSTREET Post-to postal address. No
SHIPTOCITY Name of post-to city. No
SHIPTOSTATE Name of post-to county or province. No
SHIPTOCOUNTRY Post-to country code. See
Country Codes
.”
Appendix B, “ISO
SHIPTOZIP US post-to ZIP code or other country-specific
String 30
b
String 40
b
String 10
b
No
Alpha 2
b
String 20
No
postcode.
28 Website Payments Pro Developer’s Guide
Performing Direct Payment Credit Card Transactions
Additional Parameters by Transaction Type
ABLE 4.1 Transaction parameters (Continued)
T
Parameter Description Required Type
4
Max.
Length
TAXAMT Sum of tax for all items in this order.
NOTE: You must set CURRENCY to one of
the three-character currency codes for
any of the supported PayPal currencies.
See the CURRENCY entry in this table
for details.
Limitations: Must not exceed $10,000 USD in
any currency. No currency symbol. Decimal
separator must be a period (.). Do not use
comma separators. Use 1199.95, not 1,199.95.
VERBOSITY Either of two values: LOW or MEDIUM.
LOW is the default setting — normalised
values.
MEDIUM returns the PayPal processor’s raw
response values.
Appendix A, “Verbosity: Viewing
See
No Decimal 10
No Alpha
Processor-Specific Transaction Results.”
a. Some transaction types do not require this parameter. See
b. If you pass in any of the post-to address parameters such as SHIPTOCITY or SHIPTOSTATE, you must pass in the
complete set (that is, SHIPTOSTREET, SHIPTOCITY, SHIPTOSTATE, SHIPTOCOUNTRY and SHIPTOZIP).
“Values Required by All Transaction Types” on page 17.
Additional Parameters by Transaction Type
Each Direct Payment credit card transaction type has its own request parameter requirements.
These are in addition to the parameters required by all transactions described in the following
tables in Chapter 3, “Creating a Simple Transaction Request.”
z Table 3.1, “Connection parameters”
z Table 3.2, “Required transaction parameters”
Transaction responses are described in Chapter 8, “Responses to Transaction Requests.”
Submitting Sale Transactions
The Sale transaction (TRXTYPE=S) charges the specified amount against the account, and
marks the transaction for immediate fund transfer during the next settlement period. PayPal
submits each merchant’s transactions for settlement on a daily basis.
Website Payments Pro Developer’s Guide 29
Performing Direct Payment Credit Card Transactions
4
Submitting Sale Transactions
When to Use a Sale Transaction
A Sale transaction is best suited to businesses that provide immediate fulfilment for their
products or services. Electronic goods merchants, for example, who fulfil orders immediately
can use Sale transactions. If your business does not provide immediate fulfilment, then credit
card association rules recommend that you use the Authorisation and Delayed Capture model.
For details, see “Submitting Authorisation/Delayed Capture Transactions” on page 31. If you
need to recharge a credit card and you are not storing the credit card information in your local
database, you can perform a new reference transaction based on a Sale transaction. For details,
see “Recharging to the Same Credit Card (Reference Transactions)” on page 37.
Additional Parameters for Sale Transactions
To perform a Sale transaction, you are required to pass the following parameters:
ACCT
AMT
EXPDATE
Typical Sale Transaction Parameter String
The following is a typical PARMLIST string passed in a Sale transaction.
EXAMPLE 4.1 Typical Sale transaction parameter string
"TRXTYPE=S&TENDER=C&USER=SuperMerchant&PWD=SuperUserPassword&PARTNER=PayPal
UK&ACCT=5105105105105100&EXPDATE=1209&AMT=99.06&COMMENT1=Reservation&FIRSTN
AME=John&LASTNAME=Jones&STREET=123 Main St.&CITY=San
Jose&STATE=CA&ZIP=123451234&COUNTRY=US&CVV2=123&CLIENTIP=0.0.0.0"
Note that, besides the required parameters that you pass in a Sale transaction, this string
includes other typical parameters. PayPal recommends that you include the account holder’s
FIRSTNAME and LASTNAME. PayPal also recommends including CLIENTIP to help detect
possible fraud. The COMMENT1 field helps to track transaction information. The customer’s
postal address (STREET) and ZIP (postcode) should be passed to use the Address Verification
Service (AVS). CVV2 is needed for card security code validation. For details on AVS and card
security code, see the following sections:
z “Using Address Verification Service” on page 39
z “Card Security Code Validation” on page 40
The following is a typical set of Response parameters. See Chapter 8, “Responses to
Transaction Requests,” for details on response parameters.
EXAMPLE 4.2 Typical response parameters
RESULT=0&PNREF=EFIP0D391C30&RESPMSG=Approved&AVSADDR=N&AVSZIP=Y&CVV2MATCH=X
&PPREF=7XX11903GL026951F&CORRELATIONID=3a5df0066697a
30 Website Payments Pro Developer’s Guide
Loading...