PayPal Website Payments Pro - 2009 User Manual

Website Payments Pro Payflow Edition Developer’s Guide

Last updated: November 2009

PayPal Website Payments Pro Pa yf low Editiion Developer’s Guide

Document Number: 200016.en_US-200911

© 2009 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 (Europe) S.à r.l. et Cie., S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L-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 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 co ntained in this d ocument or resultin g 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.

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

How to Contact Customer Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 9

About Website Payments Pro Payflow Edition. . . . . . . . . . . . . . . . . . . . . . . . . 9

Payflow SDK Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Host Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

How Direct Payment Processing Works . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Chapter 2 Downloading, Installing, and Activating . . . . . . . . . .11

Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Preparing the Payflow Client Application . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Activating Your Payflow Pro Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Chapter 3 Simple Payflow Transaction. . . . . . . . . . . . . . . . . 13

Transaction Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Request Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Data Modes for Sending. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

User Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Sale Transaction Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Typical Sale Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Formatting Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Chapter 4 Performing Direct Payment Credit Card Transactions . . .17

About Direct Payment Credit Card Processing . . . . . . . . . . . . . . . . . . . . . . . 17

Considerations Regarding Your Website Integration . . . . . . . . . . . . . . . . . . 17

Website Payments Pro Payflow Edition Developer’s Guide 3

Contents

Parameters Used in Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Submitting Sale Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

When To Use a Sale Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Additional Parameters For Sale Transactions . . . . . . . . . . . . . . . . . . . . . . 24

Typical Sale Transaction Parameter String . . . . . . . . . . . . . . . . . . . . . . . 24

Submitting Authorization/Delayed Capture Transactions . . . . . . . . . . . . . . . . . . 24

When To Use Authorization/Delayed Capture Transactions. . . . . . . . . . . . . . . 25

Required Authorization Transaction Parameters . . . . . . . . . . . . . . . . . . . . 25

Typical Authorization Transaction Parameter String. . . . . . . . . . . . . . . . . . . 25

Required Delayed Capture Tr ansaction Parameters . . . . . . . . . . . . . . . . . . 25

Delayed Capture Transaction: Capturing Transactions for Lower Amounts. . . . . . . 27

Delayed Capture Transaction: Capturing Transactions for Higher Amounts . . . . . . 28

Delayed Capture Transaction: Error Handling and Retransmittal . . . . . . . . . . . . 28

Submitting Credit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Required Credit Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . 28

Credit Transaction Parameter Strings . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Submitting Void Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

When To Use a Void Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Required Void Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 31

Example Void Transaction Parameter String . . . . . . . . . . . . . . . . . . . . . . 31

Recharging to the Same Credit Card (Reference Transactions). . . . . . . . . . . . . . . 32

When To Use a Reference Transaction . . . . . . . . . . . . . . . . . . . . . . . . . 32

Transaction Types that Can Be Used as the Original Transaction . . . . . . . . . . . 32

Fields Copied From Reference Transactions . . . . . . . . . . . . . . . . . . . . . . 33

Example Reference Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Using Address Verification Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Example Address Verification Service Request . . . . . . . . . . . . . . . . . . . . . 34

Example Address Verification Service Response . . . . . . . . . . . . . . . . . . . . 34

Card Security Code Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Example CVV2 Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Example CVV2 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Chapter 5 Responses to Transaction Requests . . . . . . . . . . . .37

Contents of a Response to a Credit Card Transaction Request . . . . . . . . . . . . . . . 37

Address Verification Service Responses From PayPal . . . . . . . . . . . . . . . . . . . 39

Card Security Code Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Normalized Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

PayPal Card Security Code Results. . . . . . . . . . . . . . . . . . . . . . . . . . . 41

PNREF Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

4 Website Payments Pro Payflow Edition Developer’s Guide

Contents

PNREF Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

RESULT Values and RESPMSG Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

RESULT Values for Transaction Declines or Errors . . . . . . . . . . . . . . . . . . . 42

RESULT Values for Communications Errors . . . . . . . . . . . . . . . . . . . . . . 48

Chapter 6 Testing Credit Card Transactions . . . . . . . . . . . . . . 51

Testing Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Credit Card Numbers Used for Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Testing Result Code Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Appendix A Verbosity: Viewing Processor-Specific Transaction

Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Supported Verbosity Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Changing the Verbosity Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Appendix B Currency Codes . . . . . . . . . . . . . . . . . . . . . . .59

Appendix C Country Codes . . . . . . . . . . . . . . . . . . . . . . . 61

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67

Website Payments Pro Payflow Edition Developer’s Guide 5

Contents

6 Website Payments Pro Payflow Edition Developer’s Guide

Preface

About This Guide

Website Payments Pro Payflow Edition uses the Payflow gateway and Payflow Pro SDK to send transactions to PayPal for processing. This product offers two payment solutions: PayPal Direct Payment, to process credit card transactions, and PayPal Express Checkout, to process PayPal transactions.

Website Payments Pro Payflow Edition Developer’s Guide introduces transaction processing through the Payflow gateway and describes how to integrate Direct Payment credit card processing.

NOTE:Direct Payment credit card processing is not a standalone feature. You must use Direct

Payment together with Express Checkout. Use this guide along with the companion guide, Express Checkout for Payflow Pro, for details on integrating Express Checkout.

Intended Audience

This guide is written for merchants who have signed up through PayPal Manager to use PayPal as their processor 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

How to Contact Customer Support

For problems with transaction processing or your connection to the server, contact Customer Support by opening a ticket on the under Contact Support tab at

http://www.paypal.com/mts.

Revision History

Revision history for PayPal Website Payments Pro Payflow Editiion Developer’s Guide.

TABLE 1.1 Revision history

Date Description

November 2009 Updated currency codes table. October 2009 Updated currency codes.

Edits for technical accuracy.

March 2009 Added credit card line-item details parameters to Chapter 4, “Performing Direct Payment

Credit Card Transactions.”

November 2008

June 2008 Updated Preface.

March 2008 Added coverage of PayPal success with warning message, which can be returned by

February 2008 Added support for non-referenced credits.

November 2007 Explains how merchant can determine what SDK version they are using.

z Moved coverage of Express Checkout, originally in this guide, to a separate document,

Express Checkout for Payflow Pro.

z Removed Enroute and Jal from credit card ACCTTYPE description z Added PPREF to transaction responses z Updated table of RESULT values and RESPMSG text z Added Currency Codes appendix

Made

CURRENCY a required parameter.

PayPal when

Updated test and live host URLs.

Explains more about Explains how to eliminate Updates Index to include an alphabetical listing of all Payflow parameters cited in the

guide. Updated Figures 1.1 and 4.1 to show new PayPal logo. Adds new transaction type N. Includes other minor edits for technical accuracy.

RESULT=0.

VERBOSITY parameter.

TRANSSTATE 106 results.

8 Website Payments Pro Payflow Edition Developer’s Guide

Introduction

This chapter introduces the Website Payments Pro Payflow Edition product and provides an overview of its Direct Payment credit card processing payment solution.

About Website Payments Pro Payflow Edition

Website Payments Pro Payflow Edition uses the Payflow gateway and Payflow Pro SDK to send transactions to PayPal for processing. It is available from the PayPal Manager Downloads page as a .NET or Java library, or you can build your own API by posting directly to the servers via HTTPS.

With Website Payments Pro Payflow Edition, y ou 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 Express Checkout, which 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.

z Direct Payment credit card processing, which enables you to accept credit card payments

directly on your website. PayPal remains invisible, so you control the customer experience.

By integrating Direct Payment credit card processing with Express Checkout as part of the Website Payments Pro Payflow Edition solution, you can accept all major payment types, including PayPal, while working with a single provider that processes and manages all of your online payments.

Payflow SDK Version

To determine the version of the Payflow SDK you are using, view a transaction in PayPal Manager. In Transaction Details, check the value of Client Version. A value of 3x means you are using a version 3 (V3) SDK; a value of 4x means you are using a versio n 4 (V4) SDK.

Host Addresses

Use the following host addresses for the Payflow V4 SDK:

z For live transactions, use payflowpro.paypal.com z For testing purposes, use pilot-payflowpro.paypal.com

Website Payments Pro Payflow Edition Developer’s Guide 9

Introduction

How Direct Payment Processing Works

Figure 1.1 illustrates the Direct Payment credit card processing flow. For credit card

transactions, customers can stay on your website as PayPal processes the payment in the background.

FIGURE 1.1 Direct Pay ment c redit card p roces sing

The numbers in the flow identify these events:

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 send the Direct Payment request.

Within seconds, you receive the response confirming that the transaction has been processed.

4. You transfer your customer to your order confirmation page. The “Pay” button on your website sends the Direct Payment request over the Payflow gateway

to the server. The request includes the required information you collected from the customer such as the amount of the transaction, the buyer’s credit card number, expiration date, browser IP address, and an element that specifies whether the transaction is a final sale or an authorization for a final amount that you capture in a subsequent transaction.

PayPal is completely invisible to your customer before, du ring, an d after the purchase. PayP al does not send an email receipt to the customer, nor does the customer’s credit card statement indicate that PayPal processed the payment.

NOTE:Direct Payment credit card processing is not covered by the PayPal Seller Protection

Policy (SPP).

10 Website Payments Pro Payflow Edition Developer’s Guide

Downloading, Installing, and

Activating

The Payflow Software Development Kit (SDK) is a set of APIs to allow you to integrate Website Payments Pro Payflow Edition (Payflow Pro) with your application or website.

IMPORTANT: Full API documentation is included with each SDK.

Supported Platforms

Payflow Pro is available on all major web server platforms in a variety of formats to support your integration requirements. Payflow Pro is available as a .NET or Java library, or you can build your own API by posting directly to the Payflow servers via HTTPS.

Preparing the Payflow Client Application

Unless you are building your own API and using HTTPS to post to the servers, you will need to obtain the Payflow SDK. Follow these steps.

1. Download the Payflow SDK.

From the SDKs and Downloads page linked to the Library tab on PayPal Developer Central, download the Payflow SDK appropriate for your platform.

2. Extract the files to a local directory.

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 Payflow Pro, while inbound permits the response from PayPal.

4. Read the Readme.txt file.

The Readme.txt file includes integration information and samples that illustrate how to use the Payflow client application in your development environment.

Website Payments Pro Payflow Edition Developer’s Guide 11

Downloading, Installing, and Activating

Activating Your Payflow Pro Account

When you are ready to activate your Payflow Pro account to begin submitting live transactions, follow these steps:

1. Log in to PayPal Manager at

2. Click ActivateYour Account and follow the on-screen instructions.

3. Change the URL within your web or desktop application to point to the live Payflow

servers. For details on Payflow server URLs, see “Host Addresses” on page 9.

https://manager.paypal.com.

12 Website Payments Pro Payflow Edition Developer’s Guide

Simple Payflow Transaction

All Payflow transactions include a common set of required parameters. 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 normalized information if you are looking for this kind of information. VERBOSITY is described in detail in Appendix A, “Verbosity: Viewing Processor-Specific Transaction Results.”

Transaction Requests

Request Contents

A transaction request includes:

z Connection parameters z User parameters z Parameters specific to the type of the transaction, such as a sale or an authorization

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

XMLPay is an XML syntax for payment requests and associated responses in a paymentprocessing network. Instead of using name-value pairs, you can send XML documents to the Payflow server based on the XMLPay 2.0 schema. For details on XMLPay, see XMLPay Developer’s Guide in the Payflo w Pro documentation on Developer Central.

Website Payments Pro Payflow Edition Developer’s Guide 13

Simple Payflow Transaction

Transaction Requests

Connection Parameters

The connection parameters are described below. 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 Connectio n pa rame ters

Parameter Description

HOSTADDRESS (Required) Payflow host name. See “Host Addresses” on page 9 for details on host

addresses.

HOSTPORT (Required) Use port 443. PARMLIST (Required) 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=PayP al&VENDOR=SuperMer chant&USER=Sup erMerchant&PWD=SuperUserPasswor d&ACCT=55555555555 54444&EXPDATE= 0308&AMT=123.00

The content of the PARMLIST varies by the type of transaction being processed. For example, a Void transaction requires a different set of parameters than a Sale.

TIMEOUT (Required) 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.

PROXYADDRESS (Optional) Proxy server address. Use the PROXY parameters for servers behind a

firewall. Your network administrator can provide the values.

PROXYPORT (Optional) Proxy server port. PROXYLOGON (Optional) Proxy server logon ID. PROXYPASSWORD (Optional) Proxy server logon password.

PARMLIST Syntax Guidelines

Follow these guidelines when creating the PARMLIST:

z Spaces are allowed in values. z Enclose the PARMLIST in quotation marks (“”). z Do not place quotation marks (“”) within the body of the PARMLIS T. z Separate all name-value pairs in the PARMLIST using an ampersand (&). z Set 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.”

Using Special Characters in Values

Because the ampersand (&) and equa l sign (=) characters have special meanings in the PARMLIST, name-value pairs like the following examples are not valid:

14 Website Payments Pro Payflow Edition Developer’s Guide

Simple Payflow Transaction

Sale Transaction Example

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.

User Parameters

All Payflow Pro transactions require the user parameters described below.

TABLE 3.2 User para me ters

Parameter Description

USER (Required) If you set up one or more additional users on the account, this value is the ID

of the user authorized to process transactions. If, however, you have not set up additional users on the account, USER has the same value as VENDOR.

Limitations: Sixty-four alphanumeric, case-sensitive characters.

VENDOR (Required) Your merchant login ID that you created when you registered for the account.

Limitations: Sixty-four alphanumeric, case-sensitive characters.

PARTNER (Required) The ID provided to you by the authorized PayPal Reseller who registered you

for the Payflow SDK. If you purchased your account directly from PayPal, use PayPal. Limitations: Sixty-four alphanumeric, case-sensitive characters.

PWD (Required) The password that you defined while registering for the account.

Limitations: Six- to thirty-two alphanumeric, case-sensitive characters.

Sale Transaction Example

In addition to the connection and user parameters, each transaction type has additional parameter requirements and can include a number of optional parameters as well. The transaction parameters common to all processors are described in detail in Table 4.1 on

page 26.

To perform a credit card Sale transaction, you are required to pass the following parameters:

z TRXTYPE - The type of the transaction, such as S for Sale z TENDER - The method of payment, such as C for credit card z ACCT - The buyer’s credit card number z AMT - The amount of the sale

Website Payments Pro Payflow Edition Developer’s Guide 15

Simple Payflow Transaction

Formatting Transactions

z EXPDATE - The expiration date of the credit card

Typical Sale Transaction

The following is a typical request transaction string for a Sale transaction.

TRXTYPE=S&TENDER=C&USER=SuperM erchant&PWD=SuperU serPassword&PARTNER=P ayPal& ACCT=5105105105105100&EXPDATE= 1209&AMT=99.06&COM MENT1=Reservation&FIR STNAME =John&LASTNAME=Jones&STREET=12 3 Main St.&CITY=Sa n Jose&STATE=CA&ZIP=123451234&BI LLTOCOUNTRY=US&CVV 2=123&CUSTIP=0.0.0.0

Note that, besides the required Sale transaction parameters, the above string includes other Payflow Pro parameters typically included in a credit card Sale transaction request.

When the transaction completes, the Payflow server returns a response string made up of name-value pair response parameters. If the transaction is successful, a RESULT value of 0 is returned. The value of PNREF identifies the transaction in future requests, and RESPMSG is a string indicating whether the transaction was approved. This is an example response to a credit card Sale transaction request:

RESULT=0&PNREF=VXYZ01234567&RE SPMSG=APPROVED&AVS ADDR=Y&AVSZIP=N&IAVS= Y&CVV2 MATCH=Y&PPREF=68W3371331353001 F&CORRELATIONID=2d c60e253495e

Formatting Transactions

For details on how to format a transaction based on the above information, see the examples and the supporting documentation provided with your SDK.

16 Website Payments Pro Payflow Edition Developer’s Guide

Performing Direct Payment Credit

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 credit card processing is not a standalone feature. You must use Direct

Payment together with Express Checkout. Use this guide along with the companion guide, Express Checkout for Payflow Pro, for details on integrating Express Checkout.

About Direct Payment Credit Card Processing

Direct Payment credit card processing occurs in two steps — a real-time authorization and a capture (settlement) of the funds that were authorized. You perform these two steps either as a single Sale transaction or as two types of transactions, an Authorization and Delayed Capture, depending on your business model.

For an Authorization, 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 34 z “Card Security Code Validation” on page 35

You receive the response shortly after you submit the transaction to PayPal. If the Authorization is approved, the bank temporarily reserves credit for the amount of the transaction to prepare to capture (fulfill) 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. Once the capture is approved, you will see the funds in your PayPal account.

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 shipping 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. Y ou should also consider whether and how to use the merchant-defined fields COMMENT1 and

Website Payments Pro Payflow Edition Developer’s Guide 17

Performing Direct Payment Credit Card Transactions

Parameters Used in Transactions

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 fulfillment and customer service, you may want to connect these systems directly to your Payflow integration for capturing funds, issuing refunds or 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 table below . The table indicates whether the parameters are required or optional.

T o enable line-item support, which includes the parameters bel ow, you must contact Merchant Technical Support at

z L_NAMEn z L_DESCn

http://www.paypal.com/mts.

z L_COSTn z L_TAXAMTn z L_QTYn z L_SKUn

TABLE 4.1 Credit card transactio n request parameters

Parameter Description

TENDER (Required) The method of payment. Values are:

z C = Credit card z P = PayPal

Limitations: One alpha character.

TRXTYPE (Required) Indicates the type of transaction to perform. Values are:

z S = Sale transaction z C = Credit z A = Authorization z D = Delayed Capture z V = Void z N = Duplicate transaction

NOTE:A type N transaction represents a duplicate transaction (version 4 SDK or

HTTPS interface only) with a PNREF the same as the original. It appears only in the PayPal Manager user interface and will never settle.

18 Website Payments Pro Payflow Edition Developer’s Guide

Performing Direct Payment Credit Card Transactions

Parameters Used in Transactions

ABLE 4.1 Credit card transactio n request p arameters

Parameter Description

ACCT (Required) Credit card or purchase card number.

Limitations: A maximum of 19 numeric characters. This value may not contain spaces, non-numeric characters, or dashes. For example, ACCT=5555555555554444

EXPDATE (Required) Expiration date of the credit card.

Limitations: Four numeric characters in mmyy format. For example, 1008 represents

November 2008.

ACCTTYPE (Optional) Credit card type. The following card types are supported:

z 0 = Visa z 1 = MasterCard z 2 = Discover z 3 = AMEX z 8= Other

T (Required) Amount (US Dollars) U.S. based currency.

AMT=ITEMAMT + TAXAMT + FREIGHTAMT + HAND LINGAMT + INSURANCEAMT

- DISCOUNT

NOTE:You must set CURRE NCY 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. Nine numeric characers plus decimal (.) character. No currency symbol. Specify the exact amount to the cent using a decimal point—use 34.00, not 34. Do not include comma separators— use

1199.95 not 1,199.95. Nine numeric characters plus decimal.

CURRENCY (Required) The currency code. See Appendix B, “Currency Codes.”

NOTE:CURRENCY is applicable only to processors that support transaction-level

currency.

Limitations: Three characters.

BUTTONSOURCE (Optional) Identification code for use by third-party applications to identify

transactions. Limitations: 32 alphanumeric characters.

CUSTIP (Optional) IP address of payer’s browser as recorded in its HTTP request to your

website. This value is optional but recommended.

NOTE:PayPal records this IP address as a means to detect possible fraud.

Limitations: 15-character string in dotted quad format: xxx.xxx.xxx.xxx

COMMENT1 (Optional) Merchant-defined value for reporting and auditing purposes.

Limitations: 128 alphanumeric characters.

Website Payments Pro Payflow Edition Developer’s Guide 19

Performing Direct Payment Credit Card Transactions

Parameters Used in Transactions

ABLE 4.1 Credit card transactio n request p arameters

Parameter Description

COMMENT2 (Optional) Merchant-defined value for reporting and auditing purposes.

Limitations: 128 alphanumeric characters.

CAPTURECOMPLETE (Optional) Indicates if this Delayed Capture transaction is the last capture you intend

to make. The values are:

z Y (default) z N

NOTE:If CAPTURECOMPLETE is Y, any remaining amount of the original

reauthorized transaction is automatically voided.

Limitations: 12-character alphanumeric string.

CUSTOM (Optional) A free-form field for your own use.

Limitations: 256-character alphanumeric string.

CUSTREF (Optional) Merchant-defined identifier for reporting and auditing purposes. For

example, you can set CUSTREF to INVNUM. Limitations: 12 alphanumeric characters.

CVV2 (Optional) A code that is printed (not imprinted) on the back of a credit card and used

as partial assurance that the card is in the buyer’s possession.

NOTE:CVV2 values are normalized to Y, N, and X values. The PayPal processor

values are returned when you set VERBOSITY parameter to MEDIUM.

Limitations: Four digits .

EMAIL (Optional) Email address of payer.

Limitations: 127 alphanumeric characters.

INVNUM (Optional) Your own unique invoice or tracking number.

Limitations: 127 alphanumeric characters.

ITEMAMT (Required if L_COSTn is specified) Sum of cost of all items in this order.

ITEMAMT = L_QTY0*LCOST0 + L_QTY1*LCOST1... L_QTYn*L_COSTn

Limitations: Nine numeric characers plus decimal (.) character. No currency symbol. Specify the exact amount to the cent using a decimal point—use 34.00, not 34. Do not include comma separators—use 1199.95 not 1,199.95.

Limitations: Nine numeric characters plus decimal.

TAXAMT (Required if L_TAXAMTn is specified) Sum of tax for all items in this order.

TAXAMT=L_QTY0*L_TAXAMT0 + L_QTY 1*L_TAXAMT1 +...L_ QTYn *L_TAXAMTn

NOTE:You must set CU RRENCY to one of the three-character currency codes for any

of the supported PayPal currencies. See CURRENCY in this table for details.

Nine numeric characters plus decimal.

20 Website Payments Pro Payflow Edition Developer’s Guide

Performing Direct Payment Credit Card Transactions

ABLE 4.1 Credit card transactio n request p arameters

Parameter Description

FREIGHTAMT (Optional) Total shipping costs for this order.

NOTE:You must set CU RRENCY to one of the three-character currency codes for any

of the supported PayPal currencies. See CURRENCY in this table for details.

Nine numeric characters plus decimal.

HANDLINGAMT (Optional) Total handling costs for this order.

NOTE:You must set CU RRENCY to one of the three-character currency codes for any

of the supported PayPal currencies. See CURRENCY in this table for details.

Nine numeric characters plus decimal.

Parameters Used in Transactions

DISCOUNT (Optional) Shipping discount for this order. Specify the discount as a positive

amount. Limitations: Nine numeric characers plus decimal (.) character. No currency symbol.

Specify the exact amount to the cent using a decimal point—use 34.00, not 34. Do not include comma separators—use 1199.95 not 1,199.95.

INSURANCEAMT (Optional) Total shipping insurance cost for this order.

L_NAMEn (Optional) Line-item name.

Character length and limitations: 36 alphanumeric characters.

L_DESCn (Optional) Line-item description of the item purchased such as hiking boots or

cooking utensils.

Limitations: 127 alphanumeric characters.

L_COSTn(Required if L_QTYn is supplied) Cost of the line item. The line-item unit price can be

a positive or a negative value but not 0.

NOTE:You must set CU RRENCY to one of the three-character currency codes for any

of the supported PayPal currencies. See CURRENCY in this table for details.

Nine numeric characters plus decimal.

L_QTYn(Required if L_COSTn is supplied) Line-item quantity.

Limitations: 10-character inte ger.

Website Payments Pro Payflow Edition Developer’s Guide 21

+ 49 hidden pages

PayPal Website Payments Pro - 2009 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

Preface

About This Guide

Intended Audience

Related Documentation

How to Contact Customer Support

Revision History

Introduction

About Website Payments Pro Payflow Edition

Payflow SDK Version

Host Addresses

How Direct Payment Processing Works

Supported Platforms

Preparing the Payflow Client Application

Activating Your Payflow Pro Account

Simple Payflow Transaction

Transaction Requests

Request Contents

Data Modes for Sending

Connection Parameters

Sale Transaction Example

User Parameters

Formatting Transactions

Typical Sale Transaction

About Direct Payment Credit Card Processing

Considerations Regarding Your Website Integration

Parameters Used in Transactions