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

Performing Direct Payment Credit Card Transactions

Parameters Used in Transactions

ABLE 4.1 Credit card transactio n request p arameters

Parameter Description

L_SKUn (Optional) Pro duct number.

Limitations: 18-characters.

L_TAXAMTn (Optional) Line-item tax amount.

MERCHANTSESSIONID (Optional) Your customer Direct Payment session identification token.

PayPal records this session token as an additional means to detect possible fraud. Limitations: 64 characters.

NOTIFYURL (Optional) Your URL for receiving Instant Payment 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.

Limitations: 2048 alphanumeric characters.

ORDERDESC (Optional) Description of items the

Limitations: 127 alphanumeric characters.

RECURRINGTYPE (Optional) Type of transaction occurrence. The values are:

z F = First occurrence z S = Subsequent occurrence (default)

Limitations: One alpha character.

FIRSTNAME (Optional) Account holder's first name.

Limitations: 25 alpha characters.

LASTNAME (Optional) Account holder's first name.

Limitations: 25 alpha characters.

STREET (Optional) The cardholder’s bill-to street address (number and street name).

The STREET address is verified by the address verification service. Limitations: 100 alphanumeric characters.

CITY (Optional) Bill-to city address.

Limitations: 40 alphanumeric characters.

STATE (Optional) Bill-to state or province address.

Limitations: 40 alphanumeric characters.

COUNTRY (Optional) Bill-to country address.

Limitations: 2 alphanumeric characters.

customer is purchasing.

ZIP (Optional) Bill-to postal code.

Limitations: Nine characters maximum. Do not use spaces, dashes, or non-numeric characters.

22 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

SHIPTOSTREET (Optional) Ship-to street address.

NOTE:If you pass in any of the ship-to address parameters such as SHIPTOCITY or

SHIPTOSTATE, you must pass in the complete set (that is, SHIPTOSTREET, SHIPTOCITY, SHIPTOSTATE, SHIPTO COUNTRY, and SHIPTOZIP).

Limitations: 30-character stri ng .

SHIPTOCITY (Optional) Ship-to city address.

NOTE:If you pass in any of the ship-to address parameters such as SHIPTOCITY or

SHIPTOSTATE, you must pass in the complete set (that is, SHIPTOSTREET, SHIPTOCITY, SHIPTOSTATE, SHIPTO COUNTRY, and SHIPTOZIP).

Limitations: 40-character stri ng .

SHIPTOSTATE (Optional) Ship-to state or province address.

NOTE:If you pass in any of the ship-to address parameters such as SHIPTOCITY or

SHIPTOSTATE, you must pass in the complete set (that is, SHIPTOSTREET, SHIPTOCITY, SHIPTOSTATE, SHIPTO COUNTRY, and SHIPTOZIP).

Limitations: 10-character stri ng .

Submitting Sale Transactions

SHIPTOCOUNTRY (Optional) Ship-to country code. See Appendix C, “Country Codes.

NOTE:If you pass in any of the ship-to address parameters such as SHIPTOCITY or

SHIPTOSTATE, you must pass in the complete set (that is, SHIPTOSTREET, SHIPTOCITY, SHIPTOSTATE, SHIPTO COUNTRY, and SHIPTOZIP).

Limitations: Two alpha characters.

SHIPTOZIP (Optional) U.S. ship-to zip code or other country-specific postal code.

NOTE:If you pass in any of the ship-to address parameters such as SHIPTOCITY or

SHIPTOSTATE, you must pass in the complete set (that is, SHIPTOSTREET, SHIPTOCITY, SHIPTOSTATE, SHIPTO COUNTRY, and SHIPTOZIP).

Limitations: 20-character stri ng .

Submitting Sale Transactions

The Sale transaction (TRXTYPE=S) charges the specified amount (including shipping, handling, and tax) 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.

When To Use a Sale Transaction

A Sale transaction is best suited to businesses that provide immediate fulfillment for their products or services. If your business does not provide immediate fulfillment, then credit card

Website Payments Pro Payflow Edition Developer’s Guide 23

Performing Direct Payment Credit Card Transactions

Submitting Authorization/Delayed Capture Transactions

association rules recommend that you use an Authorization and a Delayed Capture transaction. For details, see “Submitting Authorization/Delayed Capture Transactions” on page 24. 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 32.

Additional Parameters For Sale Transactions

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

z ACCT z AMT z EXPDATE

Typical Sale Transaction Parameter String

The following is a typical PARMLIST string passed in a Sale transaction.

TRXTYPE=S&TENDER=C&USER=user&P WD=password&PARTNE R=partner&ACCT=510510 510510 5100&EXPDATE=1209&AMT=99.06&CO MMENT1=Reservation &FIRSTNAME=John&LASTN AME=Jo nes&STREET=123 Main St.&CITY=S an Jose&STATE=CA&ZIP=123451234&CO UNTRY=US&CVV2=123& CUSTIP=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 CUSTIP to help detect possible fraud. The COMMENT1 field helps to track transaction information. The customer’s street address (STREET) and ZIP should be passed to use the Address Verification Service. CVV2 is needed for card security code validation. For details on Address Verification Service and card security code, see the following sections:

z “Using Address Verification Service” on page 34 z “Card Security Code Validation” on page 35

Submitting Authorization/Delayed Capture Transactions

An Authorization (TRXTYPE=A) transaction places a hold on the cardholder’s open-to-buy limit, lowering the cardholder’s limit by the amount of the transaction. It does not transfer funds.

One or more Delayed Capture (TRXTYPE=D) transactions are performed after an Authorization to capture the original Authorization amount. You can perform up to 10 partial captures for a single authorization provided the buyer is in good standing. A partial capture keeps the funds in a Pending status. A Delayed Capture is scheduled for settlement during the next settlement period.

24 Website Payments Pro Payflow Edition Developer’s Guide

Performing Direct Payment Credit Card Transactions

Submitting Authorization/Delayed Capture Transactions

Because Visa and MasterCard regul ations prohibit capturing credit card transaction funds until a product or service has shipped to the buyer, most processing networks implement an Authorization transaction followed by a Delayed Capture transaction.

When To Use Authorization/Delayed Capture Transactions

If your business does not provide immediate fulfillment of products or services, you should use this two-stage transaction solution, also known as Delayed Capture processing, because it enables you to capture credit card transaction funds when your are ready to collect them.

If your business provides immediate fulfillment, you can use a simple Sale transaction instead. For details, see “Submitting Sale Transactions” on page 23. 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. For details, see “Recharging to the Same

Credit Card (Reference Transactions)” on page 32.

Required Authorization Transaction Parameters

To perform an Authorization transaction, you are required to pass the following parameters:

z ACCT z AMT z EXPDATE

Typical Auth orization Transaction Parameter String

A typical parameter string passed in an Authorization transaction is the same as a Sale transaction string. The only difference is that the TRXTYPE value is A in an Authorization.

TRXTYPE=A&TENDER=C&USER=user&P WD=password&PARTNE R=partner&ACCT=510510 510510 5100&EXPDATE=1209&AMT=99.06&CO MMENT1=Reservation &FIRSTNAME=John&LASTN AME=Jo nes&STREET=123 Main St.&CITY=S an Jose&STATE=CA&ZIP=123451234&CO UNTRY=US&CVV2=123& CLIENTIP=0.0.0.0

Required Delayed Capture Transaction Parameters

To perform a Delayed Capture (TRXTYPE=D) transaction, you are required to pass the following parameter:

Website Payments Pro Payflow Edition Developer’s Guide 25

Performing Direct Payment Credit Card Transactions

Submitting Authorization/Delayed Capture Transactions

ORIGID

ABLE 4.2 Delayed Capture required parameter

Parameter Description

ORIGID (Required by some transaction types) ID of the original transaction that is being

referenced. This ID is returned by the PNREF parameter and appears as the Transaction ID in PayPal Manager reports.

Limitations: Case sensitive.

Set ORIGID to the PNREF (T ransaction ID in PayPal Manager reports) value returned from the original transaction. In addition, if the amount of the capture differs from the amount of the Authorization, you also must pass a value for AMT.

Fields Copied From the Authorization Transaction into the Delayed Capture Transaction

The following fields are copied from the Authorization transaction into the Delayed Capture transaction (if they exist in the original transaction). If you provide a new value for any of these parameters when submitting the Delayed Capture transaction, then the new value is used. (Exceptions are ACCT and EXPDATE. These parameters retain their original values.)

ABLE 4.3 Fields cop ied fro m Authorizat ion to Delayed Ca pture t ransac tion

ACCT AMT CITY COMMENT1 COMMENT2 COUNTRY CUSTCODE CUSTIP EMAIL EXPDAT E FIRSTNAME FREIGHTAMT INVNUM LASTNA ME NOTE PHONEUM SHIPTOCITY SHIPTOCOUNTRY SHIPTOFIRSTNAME SHIPTOLASTNAME SHIPTOSTATE SHIPTOSTREET SHIPTOZIP STATE STREET TAXAMT ZIP

To perform the Delayed Capture:

1. Perform the Authorization transaction.

The Authorization transaction uses the same parameters as Sale transactions, except that the transaction type is A.

The return data for an Authorization transaction is the same as for a Sale transaction. To capture the authorized funds, perform a Delayed Capture transaction that includes the value returned for PNREF, as described in Step 2 below.

Example: Authorization-only Transaction

TRXTYPE=A&TENDER=C&USER=user&V ENDOR=vendor&PARTN ER=partner&PWD=passwo rd& ACCT=5105105105105100&EXPDATE= 1209&AMT=9.06COMME NT1=Reservation&FIRST NAM

26 Website Payments Pro Payflow Edition Developer’s Guide

Performing Direct Payment Credit Card Transactions

Submitting Authorization/Delayed Capture Transactions

E=John&LASTNAME=Jones&STREET=1 23 Main St.&CITY=San Jose&STATE=CA&ZIP=123451234&CO UNTRY=US&CVV2=123& CLIENTIP=0.0.0.0

Example:Authorization Response

RESULT=0&PNREF=EFHP0D426838&RE SPMSG=Approved&AVSADD R=N&AVSZIP=Y&CVV2M ATC H=X&PPREF=68W3371331353001F&CO RRELATIONID=2e52df 7ddf292

2. Perform the Delayed Capture transaction.

Set ORIGID to the PNREF value returned in the original Authorization transaction response string. (There is no need to retransmit the credit card or billing address information—it is stored at PayPal.)

If the capture succeeds, the amount of the Capture is transferred to the merchant’s account during the daily settlement process. If the capture does not succeed, the hold on the cardholder’s open-to-buy is still in effect.

Example:Delayed Capture Transaction

TRXTYPE=D&TENDER=C&USER=SuperMerc hant&VENDOR=SuperM erchantPARTNER=Pay Pal &PWD=SuperUserPassword&TENDER= C&COMMENT1=Reserva tion&ORIGID=EFHP0D426838

Example:Delayed Capture Response

RESULT=0&PNREF=EFHP0D42687C&RE SPMSG=Approved&COR RELATIONID=b5689409e2 79f &PPREF=68W3371331353001F&FEEAM T=0.56&PAYMENTTYPE =instant&PENDINGREASO N=c ompleted

Delayed Capture Transaction: Capturing Transactions for Lower Amounts

You can perform a Delayed Capture transaction for an amount lower than the original Authorization amount (useful, for example, when you make a partial shipment). To perform a partial capture programmatically using the Payflow SDK, set CAPTURECOMPLETE to N in the Delayed Capture transaction request. Setting CAPTURECOMPLETE to Y voids any remaining amount of the original authorized transaction

You can also perform Authorizations and Delayed Captures through through PayPal Manager. For details, see PayPal Manager online help.

Example:Partial Capture Transaction

In this example, you authorize an amount of $100 for a shipment and charge $66 for the first partial shipment using a Delayed Capture transaction. You charge the $34 for the final part of the shipment using a second Delayed Capture transaction to draw credit card and shipping address information from the initial Authorization transaction.

1. Submit the initial transaction (Authorization in this example).

This example uses an Authorization transaction for the full amount of a purchase of $100.

TRXTYPE=A&TENDER=C&PWD=SuperUserP assword&PARTNER= PayPal&VENDOR=SuperM erc hant&USER=SuperMerchant&ACCT=5 555555555554444&EX PDATE=0308&AMT=100.00 &IN VNUM=123456789&FIRSTNAME=John& LASTNAME=Jones&STR EET=5199 MAPLE&ZIP=94 588

Note the value of the PNREF in the response.

RESULT=0&PNREF=EFHP0D426A51&RE SPMSG=Approved&AVSADD R=N&AVSZIP=Y&CVV2M ATC H=X&PPREF=6FS950632E172331R&CO RRELATIONID=3c1a7c 1c411a

Website Payments Pro Payflow Edition Developer’s Guide 27

Performing Direct Payment Credit Card Transactions

Submitting Credit Transactions

2. Capture the authorized funds for a partial shipment of $66.

When you deliver the first $66 worth of product, you use a Delayed Capture transaction to collect the $66. Set ORIGID to the value of PNREF in the original Authorization and set

CAPTURECOMPLETE to N.

TRXTYPE=D&TENDER=C&PWD=SuperUserP assword&PARTNER= PayPal&VENDOR=SuperM erc hant&USER=SuperMerchant&CAPTUR ECOMPLETE=N&ORIGID=EFHP0D426A51&AMT=66.00

This is the response.

RESULT=0&PNREF=VXYZ01234568&AU THCODE=25TEST&AVSA DDR=Y&AVSZIP=N&CORREL ATI ONID=2dc60e253492e&PPREF=68W33 71331353001F

3. Capture the $34 balance for the rest of the shipment.

Once you have shipped the remainder of the product, you can collect the remaining $34 in a second Delayed Capture transaction, setting CAPTURECOMPLETE to Y.

TRXTYPE=D&TENDER=C&PWD=SuperUserP assword&PARTNER= PayPal&VENDOR=SuperM erc hant&USER=SuperMerchant&CAPTUR ECOMPLETE=Y&ORIGID=EFHP0D426A51&AMT=34.00

This is the response.

RESULT=0&PNREF=VXYZ01234569&AU THCODE=25TEST&AVSA DDR=Y&AVSZIP=N&CORREL ATI ONID=2dc60e253493e&PPREF=68W33 71331353001F

Delayed Capture Transaction: Capturing Transactions for Higher Amounts

You can perform a Delayed Capture transaction for an amount higher than the original Authorization amount. The cardholder’s open-to-buy could be reduced by the sum of the original Authorization-only amount and the final Delayed Cap ture amount.

Delayed Capture Transaction: Error Handling and Retransmittal

If an error occurs while processing a Delayed Capture transaction, it is safe to retry the capture with values that allow the Payflow server to successfully process it. Conversely, if a capture for a previous Authorization succeeds, subsequent attempts to capture it again will return an error.

Submitting Credit Transactions

The Credit transaction (TRXTYP E=C) refunds the specified amount to the cardholder.

Required Credit Transaction Parameters

The required parameter data for a Credit transaction depends on the Allow non-referenced credits security setting for your Payflow Pro account. A non-referenced credit is a Credit

transaction that does not use the credit card information from an existing transaction. Credit card information must be supplied. As an example, Sally Smith calls you on the telephone to

28 Website Payments Pro Payflow Edition Developer’s Guide

Performing Direct Payment Credit Card Transactions

Submitting Credit Transactions

cancel an order from your business. To refund her money, you credit her credit card by submitting a non-referenced Credit transaction.

Guidelines and parameter requirements for Credit transactions differ depending on whether or not non-referenced credits are allowed.

Non-Referenced Credits Not Allowed

When non-referenced credits are not allowed (the setting recommended by PayPal), then Credit transactions are permitted only against existing Sale, Delayed Capture, and Voice Authorization transactions. T o submit a Credit transa ction when non-re ferenced credits are not allowed, you must pass the following parameter:

ORIGID

TABLE 4.4 Credit required parameter

Parameter Description

ORIGID (Required by some transaction types) ID of the original transaction that is being

referenced. This ID is returned by the PNREF parameter and appears as the Transaction ID in PayPal Manager reports.

Limitations: Case sensitive.

Set the value of ORIGID to the PNREF value returned for the original transaction. (PNREF is displayed as the Transaction ID in PayPal Manager reports. If you do not specify an amount, then the amount of the original transaction is credited to the cardholder.

Non-Referenced Credits Allowed

When non-referenced credits are allowed, then Credit transactions are permitted in any amount up to the transaction limit for the credit card account that you specify. To submit a Credit transaction when non-referenced credits are not allowed, you must pass values for the following parameters:

z ACCT z EXPDATE z AMT

IMPORTANT: The default security setting for Payflow Pro accounts is Allow

non-referenced credits = No, so sending the ORIGID is the preferred method for performing Credit transactions. Using the ACCT, EXPDATE, or AMT parameters for such accounts leads to RESULT value 117 (failed the security check). For information on setting the security settings, see PayPal Manager online help.

Fields Copied From the Original Transaction into the Credit Transaction

The following fields are copied from the original transaction into the Credit transaction (if they exist in the original transaction). If you provide a new value for any of these parameters when submitting the Credit transaction, then the new value is used. (Exceptions are ACCT, EXPDATE, and SWIPE. These parameters retain their original values).

Website Payments Pro Payflow Edition Developer’s Guide 29

Performing Direct Payment Credit Card Transactions

Submitting Void Transactions

NOTE: TAXAMT and FREIGHTAMT are not copied for referenced credits.

TABLE 4.5 Fields cop ied from o riginal transact ion into t he Credit tran saction

ACCT AMT CITY COMMENT1 COMMENT2 COUNTRY CUSTCODE CUSTIP EMAIL EXPDAT E FIRSTNAME INVNUM LASTNAME PHONEUM SHIPTOCITY SHIPTOCOUNTRY SHIPTOFIRSTNAME SHIPTOLASTNAME SHIPTOSTATE SHIPTOSTREET SHIPTOZIP STATE STREET ZIP

Credit Transaction Parameter Strings

This is an example Credit transaction string (non-referenced credits not allowed):

TRXTYPE=C&TENDER=C&PARTNER=par tner&VENDOR=vendor &USER=user&PWD=passwo rd&ORI GID=EFHP0D426A62

This is an example Credit transaction string (non-referenced credits allowed):

TRXTYPE=C&TENDER=C&PARTNER=par tner&VENDOR=vendor &USER=user&PWD=passwo rd&ACC T=5555555555554444&EXPDATE=030 8&AMT=123.00

Submitting Void Transactions

The Void transaction (TRXTYPE=V) prevents a transaction from being settled. As part of its internal process, PayPal makes reasonable effort to process authorization

reversals for void transactions for debit and credit cards.

NOTE:For more information on authorization reversals, see

http://en.wikipedia.org/wiki/Authorization_hold.

When To Use a Void Transaction

Follow these guidelines:

z You void Delayed Capture and Authorization transactions. You cannot void a Void

transaction.

z You can only use a Void transaction on a transaction that has not yet settled. To refund a

customer’s money for a settled transaction, you must submit a Credit transaction.

30 Website Payments Pro Payflow Edition Developer’s Guide

Performing Direct Payment Credit Card Transactions

Submitting Void Transactions

Required Void Transaction Parameters

To submit a Void transaction, you must pass the following parameter:

ORIGID

ABLE 4.6 Void required parameter

Parameter Description

ORIGID (Required by some transaction types) ID of the original transaction that is being

referenced. This ID is returned by the PNREF parameter and appears as the Transaction ID in PayPal Manager reports.

Limitations: Case sensitive.

Set ORIGID to the PNREF (Transaction ID in PayPal Manager reports) value returned for the original transaction.

Fields Copied From the Original Transaction into the Void Transaction

The following fields are copied from the original transaction into the Void transaction (if they exist in the original transaction). If you provide a new value for any of these parameters when submitting the Void transaction, then the new value is used. (Exceptions are ACCT , EXPDATE, and SWIPE. These parameters retain their original values).

ABLE 4.7 Fields cop ied fro m original tran saction in to the Void transaction

Example Void Transaction Parameter String

This is an example Void transaction parameter string:

“TRXTYPE=V&TENDER=C&PARTNER=Pa yPal&VENDOR=SuperM erchant&USER=SuperMer chant& PWD=SuperUserPassword&ORIGID=E FHP0D426A68”

Website Payments Pro Payflow Edition Developer’s Guide 31

Performing Direct Payment Credit Card Transactions

Recharging to the Same Credit Card (Reference Transactions)

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 reference transaction. A reference transaction takes the existing credit card information that is on file and reuses it.

When To Use a Reference Transaction

Say that Joe Smith purchases a holiday gift from your web site store and requests that it be sent by UPS ground service. That evening, Joe becomes concerned that the item might not arrive in time for the holiday. So he calls you to upgrade shipping to second-day air. You obtain his approval for charging an e xtra $10 for the upgr ade. In this situation, you can create a reference transaction based on the original Sale and charge an additional $10 to Joe’s credit card without having to ask him again for his credit card information.

IMPORTANT: As a security measure, reference transactions are disallowed by default. Only

your account administrator can enable reference transactions for your account. If you attempt to perform a reference transaction in an account for which reference transactions are disallowed, RESULT value 117 is returned. See PayPal Manager online help for instructions on setting reference transactions and other security features.

Sale and Authorization transactions can make use of a reference transaction as a source of transaction data. PayPal looks up the reference transaction and copies its transaction data into the new Sale or Authorization transaction. With the exception of dollar amount data, which triggers a filter if out of range, reference transactions are not screened by fraud filters.

IMPORTANT: When PayPal looks up the reference transaction, neither the transaction being

referenced nor any other transaction in the database is changed in any way. That is, a reference transaction is a read-only operation—only the new transaction is populated with data and acted upon. No linkage is maintained between the reference transaction and the new transaction.

You can also initiate reference transactions from PayPal Manager. See PayPal Manager online help for details.

Transaction Types that Can Be Used as the Original Transaction

You can reference the following transaction types to supply data for a new Sale or Authorization transaction:

z Sale z Authorization (To capture the funds for an approved Authorization transaction, be sure to

perform a Delayed Capture transaction—not a Reference transaction.)

z Void z Delayed Capture

32 Website Payments Pro Payflow Edition Developer’s Guide

Performing Direct Payment Credit Card Transactions

Recharging to the Same Credit Card (Referen ce Transactions)

z Credit

Fields Copied From Reference Transactions

The following fields are copied from the reference transaction into the new Sale or Authorization transaction (if they exist in the original transaction). If you provide a value for any of these parameters when submitting the new transaction, then the new value is used.

ABLE 4.8 Fields copied to new trans action

ACCTTYPE STREET ACCT CITY EXPDATE STATE FIRSTNAME ZI P LASTNAME COUNTRY

Example Reference Transaction

In this example, you authorize an amount of $100 for a shipment and charge $66 for the first partial shipment using a normal Delayed Capture transaction. You charge the $34 for the final part of the shipment using a reference transaction to draw credit card and shipping address information from the initial Authorization transaction.

This example procedure creates a reference transaction:

1. Submit the initial transaction, such as an Authorization.

You use an Authorization transaction for the full amount of the purchase of $100:

TRXTYPE=A&TENDER=C&PWD=passwor d&PARTNER=partner& VENDOR=vendor&USER=us er& ACCT=5555555555554444&EXPDATE= 0308&AMT=100.00&IN VNUM=123456789&STREET =51 99 MAPLE&ZIP=94588

Note the value of the PNREF in the response:

RESULT=0&PNREF=EFHP0D426A51&RE SPMSG=Approved&AVSADD R=N&AVSZIP=Y&CVV2M ATC H=X&PPREF=6FS950632E172331R&CO RRELATIONID=3c1a7c 1c411a

2. Capture the authorized funds for a partial shipment of $66.

When you deliver the first $66 worth of product, you use a normal Delayed Capture transaction to collect the $66. Set ORIGID to the value of PNREF in the original Authorization (See “Required Delayed Capture Transaction Parameters” on page 25):

TRXTYPE=D&TENDER=C&PWD=passwor d&PARTNER=partner& VENDOR=vendor&USER=us er& ORIGID=VXYZ01234567&AMT=66.00

This is the response:

RESULT=0&PNREF=VXYZ01234568&AU THCODE=25TEST&AVSA DDR=Y&AVSZIP=N&CORREL ATI ONID=2dc60e253495e&PPREF=68W33 71331353001F

Website Payments Pro Payflow Edition Developer’s Guide 33

Performing Direct Payment Credit Card Transactions

Using Address Verification Service

3. Submit a new Sale or Authorization/Delayed Capture transaction of $34 for the rest of the

shipment. Once you have shipped the remainder of the product, you can collect the remaining $34 in

a Sale transaction that uses the initial Authorization as a reference transaction:

TRXTYPE=S&TENDER=C&PWD=passwor d&PARTNER=partner& VENDOR=vendor&USER=us er& ORIGID=VXYZ01234567&AMT=34.00

This is the response:

RESULT=0&PNREF=EFHP0D426A53&AU THCODE=25TEST&AVSA DDR=Y&AVSZIP=N&CORREL ATI ONID=2dc60e253495e&PPREF=68W33 71331353001F

Using Address Verification Service

To qualify for the lowest bank rate, you must pass address verification service information— street address and ZIP (postal) code.

Address Verification Service compares the submitted billing street address and ZIP code with the values on file at the cardholder’s bank. The response includes values for AVSADDR and

AVSZIP: Y, N, or X for the match status of the customer’s street address and ZIP code. Y = match, N = no match, X=cardholder’s bank does not support Address Verification

Service. The Address Verification Service result is for advice only. Banks do not decline transactions based on the Address Verification Service result—the merchant makes the decision to approve or decline a transaction. Address V erification Service is supported by most U.S. banks and some international banks.

NOTE:Address Verification Service checks only for a street number match, not a street name

match, so 123 Main Street returns the same response as 123 Elm Street.

The International Address V erification Service (IAVS) response indicates whether the Address Verification Service response is international (Y), USA (N), or cannot be determined (X). SDK version 3.06 or later is required.

Example Address Verification Service Request

This example request include the address verification service request parameters STREET and ZIP:

TRXTYPE=A&TENDER=C&PWD=passwor d&PARTNER=partner& VENDOR=vendor&USER=us er&ACC T=5555555555554444&EXPDATE=030 8&AMT=123.00

&STREET=5199 Maple&ZIP=98765

Example Address Verification Service Response

In this example, the address value matches the value in the bank’s records, but the ZIP code does not. The IAVS response is X..

RESULT=0&PNREF=EFHP0D426A56&RE SPMSG=APPROVED&AVSADD R=Y&AVSZIP=N&IAVS=X&C ORR ELATIONID=2dc60e253496a&PPREF= 68W3371331353001F

34 Website Payments Pro Payflow Edition Developer’s Guide

Performing Direct Payment Credit Card Transactions

Card Security Code Validation

The card security code is a 3- or 4-digit number (not part of the credit card number) that is printed on the credit card. Because the card security code appears only on the card and not on receipts or statements, the card security code provides some assurance that the physical card is in the possession of the buyer.

This fraud prevention tool has various names, depending on the payment network. Visa calls it CVV2 and MasterCard calls it CVC2. To ensure that your customers see a consistent name, PayPal recommends use of the term card security code on all end-user materials.

You must provide a CVV2 value as a transaction parameter for those credit cards that use card security code validation. The value is required for Visa and MasterCard cards.

IMPORTANT: To comply with credit card association regulations, do not store the CVV2

value.

On most cards, the card security code is printed on the back of the card (usually in the signature field). All or part of the card number appears before the card security code (567 in the example). For American Express, the 4-digit number (1122 in the example) is printed on the front of the card, above and to the right of the embossed account number. Be sure to explain this to your customers.

Card Security Code Validation

For details on PayPal processor card security code responses, see “Responses to Transaction

Requests” on page 37.

FIGURE 4.1 Ca rd secu rity cod e

Example CVV2 Request

This example request parameter string includes the CVV2 parameter.

TRXTYPE=A&TENDER=C&PWD=SuperUs erPassword&PARTNER= PayPal&VENDOR=SuperM erchan t&USER=SuperMerchant&ACCT=5555 555555554444&EXPDA TE=0308&AMT=123.00

&CVV2=56

Example CVV2 Response

In this example result, the card security code value matches the value in the bank’s records.

Website Payments Pro Payflow Edition Developer’s Guide 35

Performing Direct Payment Credit Card Transactions

Card Security Code Validation

RESULT=0&PNREF=VXW412345678&RE SPMSG=APPROVED&CVV2MATC H=Y&PPREF=68W33713313 53001F&CORRELATIONID=2dc60e253 4971&PPREF=68W3371 331353001F

36 Website Payments Pro Payflow Edition Developer’s Guide

Responses to Transaction

Requests

When a transaction finishes, the Payflow server returns a response string made up of namevalue pairs. This is an example response string.

RESULT=0&PNREF=EFHP0D426A53&RESPMSG=APP ROVED&AUTHCODE=25TEST&AVSADDR =Y&AVSZIP=N&CVV2MATCH=Y

Contents of a Response to a Credit Card Transaction Request

The table below describes values that can be returned in response strings

TABLE 5.9 Transaction response values

Field Description

PNREF Payflow Transaction ID, a unique number that identifies the transaction.

Character length and limitations: 12 alphanumeric characters

PPREF Unique transaction ID of the payment.

Character length and limitations: 17-character string

RESULT The outcome of the attempted transaction. RESULT=0 means the

transaction was approved. Any other value for RESULT indicates a decline or error.

NOTE:The PayPal processor may also return a warning message in the

RESPMSG string when RESULT=0. For more information on corrective actions, see the PayPal developer documentation on Developer Central.

Character length and limitations: variable length, numeric

CVV2MATCH Result of the card security code (CVV2) check. The issuing bank may

decline the transaction if there is a mismatch. In other cases, the transaction may be approved despite a mismatch.

Character length and limitations: 1 alpha character (Y, N, X, or no response)

Website Payments Pro Payflow Edition Developer’s Guide 37

Responses to Transaction Requests

Contents of a Response to a Credit Card Transaction Request

ABLE 5.9 Transaction response values

Field Description

RESPMSG The response message returned with the transaction result. Exact wording

varies. Sometimes a colon appears after the initial RESPMSG followed by more detailed information.

NOTE:The PayPal processor may also return a warning message in the

RESPMSG string when RESULT=0. For more information on corrective actions, see the PayPal developer documentation on Developer Central.

Character length and limitations: variable, alphanumeric characters

AUTHCODE Returned for Sale, Authorization, and Voice Authorization credit card

transactions. AUTHCODE is the approval code obtained over the telephone from the processing network.

AUTHCODE is required when submitting a Force (F) transaction. Character length and limitations: 6 alphanumeric characters

AVSADDR Address Verification Service address response returned if you are using

Address Verification Service. Address Verification Service address responses are for advice only. This process does not affect the outcome of the authorization.

Character length and limitations: 1 alpha character (Y, N, X, or no response)

AVSZIP Address Verification Service address response returned if you are using

Address Verification Service. Address Verification Service address responses are for advice only. This process does not affect the outcome of the authorization.

Character length and limitations: 1 alpha character (Y, N, X, or no response)

IAVS International Address Veri fication Service address responses may be

returned if you are using Address Verification Service. IAVS responses are for advice only. This value does not affect the outcome of the transaction.

Indicates whether Address Verification Service response is internatio nal (Y), US (N), or cannot be determined (X). Client version 3.06 or later is required.

Character length and limitations: 1 alpha character (Y, N, X, or no response)

PROCAVS Address Verification Service response from the processor when you use

Address Verification Service and send a VERBOSITY request parameter value of MEDIUM.

Character length and limitations: 1 character

PROCCVV2 CVV2 response from the processor when you send a VERBOSITY request

parameter value of MEDIUM. Character length and limitations: 1 character

38 Website Payments Pro Payflow Edition Developer’s Guide

Responses to Transaction Requests

Address Verification Service Responses From PayPal

ABLE 5.9 Transaction response values

Field Description

PAYMENTTYPE Returns instant if the payment is instant or echeck if the payment is

delayed. (DP) Character length and limitations: 7-character string

CORRELATIONID Value used for tracking this Direct Payment transaction.

Character length and limitations: 13 alphanumeric characters

Address Verification Service Responses From PayPal

The table below compares the detailed response returned by the PayPal processor for addre ss verification to the normalized response value (Y, N, or X) returned in the AVSADDR and AVSZIP response parameters. If you want to obtain the PayPal processor value, set the VERBOSITY parameter to MEDIUM. With this setting, the processor value is returned in the PROCAVS response parameter. For details on V ERBOSITY, see Appendix A, “Verbosity: Viewing

Processor-Specific Transaction Results.”

ABLE 5.10 Address Verification Service response value mappin g

PayPal Processor Address Verification Service Code Meaning AVSADDR AVSZIP

AAddress YN B International “A” Y N C International “N” N N D International “X” Y Y E Not allowed for MOTO (Internet/Phone)

transactions F UK-specific “X” Y Y G Global Unavailable X X I International Unavailable X X NNo NN P Postal (International “Z”) N Y

RRetry XX S Service not Supported X X

Website Payments Pro Payflow Edition Developer’s Guide 39

Responses to Transaction Requests

Card Security Code Results

ABLE 5.10 Address Verification Service response value mappin g

PayPal Processor Address Verification Service Code Meaning AVSADDR AVSZIP

U Unavailable X X W Whole Zip N Y X Exact Match Y Y YYes YY ZZip NY All other X X

Card Security Code Results

The CVV2MATCH parameter returns Y, N, or X. The

CVV2MATCH parameter returns Y, N, or X or a processor-specific response.

Normalized Results

The table below shows the detailed results returned by the PayPal processor for card security codes. If you want to obtain the PayPal processor value, set the VERBOSITY parameter to MEDIUM. The processor value is returned in the PROCCVV2 response parameter.

ABLE 5.11 CVV2MATCH response values

CVV2MATCH Value Description

Y The submitted value matches the data on file for the card. N The submitted value does not match the data on file for the card. X The cardholder’s bank does not support this service.

40 Website Payments Pro Payflow Edition Developer’s Guide

PayPal Card Security Code Results

TABLE 5.12 Card security co de response c ode ma pping

Responses to Transaction Requests

PNREF Value

PayPal Processor CVV2 Code

M Match Y NNo MatchN P Not Processed X S Service Not Supported X U Unavailable X X No Response X All other X

PNREF Value

The PNREF is a unique transaction identification number issued by PayPal that identifies the transaction for billing, reporting, and transaction data purposes. The PNREF value appears in the Transaction ID column in PayPal Manager reports.

z The PNREF value is used as the ORIGID value (original transaction ID) in Delayed

Capture transactions (TRXTYPE=D), Credits (TRXTYPE=C), Inquiries (TRXTYPE=I), and Voids (TRXTYPE=V).

PayPal Processor Code Description PROCVV2MATCH

z The PNREF value is used as the ORIGID value (original transaction ID) value in reference

transactions for Authorization (TRXTYPE=A) and Sale (TRXTYPE=S).

NOTE:The PNREF is also referred to as the Transaction ID in PayPal Manager.

PNREF Format

The PNREF is a 12-character string of printable characters, for example:

z VADE0B248932 z ACRAF23DB3C4

NOTE:Printable characters also include symbol s other than letters and numbers such as the

question mark (?). A PNREF typically contains letters and numbers only.

The PNREF in a transaction response tells you that your transaction is connecting to PayPal.

Website Payments Pro Payflow Edition Developer’s Guide 41

Responses to Transaction Requests

RESULT Values and RESPMSG Text

The RESULT parameter and value is the first name-value pair returned in the response string. The value of RESULT indicates the overall status of the transaction attempt:

z A value of 0 (zero) indicates that no errors occurred and the transaction was approved. z A value less than 0 indicates that a communication error occurred. In this case, no

transaction is attempted.

z A value greater than 0 indicates a decline or error (except in the case of RESULT 104. See

the table below).

The response message (RESPMSG) provides a brief description for decline or error results.

RESULT Values for Transaction Declines or Errors

For non-zero RESULT values, the response string includes a RESPMSG name-value pair. The exact wording of the RESPMSG (shown in bold) may vary. Sometimes a colon appears after the initial RESPMSG followed by more detailed information.

When interpreting RESULT values for the PayPal processor, note the following:

z When RESULT=0, warning information may be returned that is useful to the request

applicaton. See the PayPal API documentation on Developer Central for detailed information on corrective actions.

z When RESULT=104, you must log in to the PayPal website to determine if the transaction

actually went through. If the transaction does not appear in the History section, you should retry it.

TABLE 5.13 Payflow Transaction RESULT Values and RESPMSG Text

RESULT RESPMSG and Explanation

0 Approved

NOTE:PayPal processor: Warning information may be returned that may be useful

to the request applicaton. See the PayPal API documentation on the PayPal website for information on corrective actions.

42 Website Payments Pro Payflow Edition Developer’s Guide

Responses to Transaction Requests

RESULT Values and RESPMSG Text

ABLE 5.13 Payflow Transaction RESULT Values and RESPMSG Text

RESULT RESPMSG and Explanation

1 User authentication failed. Error is caused by one or more of the following:

z Login information is incorrect. Verify that USER, VEN DOR, PARTNER, and

PASSWORD have been entered correctly. VENDOR is your merchant ID and USER

is the same as VENDOR unless you created a Payflow Pro user. All fields are case sensitive.

z Invalid Processor information entered. Contact merchant bank to verify. z "Allowed IP Address" security feature implemented. The transaction is coming

from an unknown IP address. See PayPal Manager online help for details on how to use Manager to update the allowed IP addresses.

z You are using a test (not active) account to submit a transaction to the live

PayPal servers. Change the host address from the test server URL to the live server URL

2 Invalid tender type. Your merchant bank account does not support the following

credit card type that was submitted.

3 Invalid transaction type. Transaction type is not appropriate for this transaction.

For example, you cannot credit an authorization-only transaction

4 Invalid amount format. Use the format: “#####.##” Do not include currency

symbols or commas.

5 Invalid merchant information. Processor does not recognize your merchant

account information. Contact your bank account acquirer to resolve this problem.

6 Invalid or unsupported currency code 7 Field format error. Invalid information entered. See RESPMSG 8 Not a transaction server 9 Too many parameters or invalid stream 10 Too many line items 11 Client time-out waiting for response 12 Declined. Check the credit card number, expiration date, and transaction

information to make sure they were entered correctly. If this does not resolve the problem, have the customer call their card issuing bank to resolve.

13 Referral. Transaction cannot be approved electronically but can be approved with a

verbal authorization. Contact your merchant bank to obtain an authorization and submit a manual Voice Authorization transaction.

19 Original transaction ID not found. The transaction ID you entered for this

transaction is not valid. See RESPMSG

20 Cannot find the customer reference number 22 Invalid ABA number

Website Payments Pro Payflow Edition Developer’s Guide 43

Responses to Transaction Requests

RESULT Values and RESPMSG Text

ABLE 5.13 Payflow Transaction RESULT Values and RESPMSG Text

RESULT RESPMSG and Explanation

23 Invalid account number. Check credit card number and re-submit. 24 Invalid expiration date. Check and re-submit. 25 Invalid Host Mapping. You are trying to process a tender type such as Discover

Card, but you are not set up with your merchant bank to accept this card type.

z You are trying to process a tender type such as Discover Card, but you are not

z Y o u are trying to proce ss an Express Checkout transaction when your account is

26 Invalid vendor account. Login information is incorrect. Verify that USER,

VENDOR, P ARTNER, and PASSWORD have been entered correctly. VENDOR is your merchant ID and USER is the same as VENDOR unless you created a Payflow Pro user. All fields are case sensitive.

27 Insufficient partner permissions

set up with your merchant bank to accept this card type.

not set up to do so. Contact your account holder to have Express Checkout added to your account.

28 Insufficient user permissions 29 Invalid XML document. This could be caused by an unrecognized XML tag or a

bad XML format that cannot be parsed by the system.

30 Duplicate transaction 31 Error in adding the recurring profile 32 Error in modifying the recurring profile 33 Error in canceling the recurring profile 34 Error in forcing the recurring profile 35 Error in reactivating the recurring profile 36 OLTP Transaction failed 37 Invalid recurring profile ID 50 Insufficient funds available in account 51 Exceeds per transaction limit 99 General error. See RESPMSG. 100 Transaction type not supported by host 101 Time-out value too small 102 Processor not available 103 Error reading response from host

44 Website Payments Pro Payflow Edition Developer’s Guide

Responses to Transaction Requests

RESULT Values and RESPMSG Text

ABLE 5.13 Payflow Transaction RESULT Values and RESPMSG Text

RESULT RESPMSG and Explanation

104 Timeout waiting for processor response. Try your transaction again. 105 C redit error. Make sure you have not already credited this transaction, or that this

transaction ID is for a creditable transaction. (For example, you cannot credit an authorization.)

106 Host not available 107 Duplicate suppression time-out 108 Void error. See RESPMSG. Make sure the transaction ID entered has not already

been voided. If not, then look at the Transaction Detail screen for this transaction to see if it has settled. (The Batch field is set to a number greater than zero if the transaction has been settled). If the transaction has already settled, your only recourse is a reversal (credit a payment or submit a payment for a credit)

109 Time-out waiting for host response 110 Referenced auth (against order) Error

111 Capture error. Either an attempt to capture a transaction that is not an

authorization transaction type, or an attempt to capture an authorization transaction that has already been captured.

112 Failed AVS check. Address and ZIP code do not match. An authorization may still

exist on the cardholder’s account.

113 Merchant sale total will exceed the sales cap with current transaction. ACH

transactions only.

114 Card Security Code (CSC) Mismatch. An authorization may still exist on the

cardholder’s account.

115 System busy, try again later 116 VPS Internal error. Failed to lock terminal number 117 Failed merchant rule check. One or more of the following three failures occurred:

An attempt was made to submit a transaction that failed to meet the security settings specified on the PayPal Manager Security Settings page. If the transaction exceeded the Maximum Amount security setting, then no values are returned for AVS or CSC.

AVS validation failed. The AVS return value should appear in the RESPMSG. CSC validation failed. The CSC return value should appear in the RESPMSG

118 Invalid keywords found in string fields 120 Attempt to reference a failed transaction 121 Not enabled for feature

Website Payments Pro Payflow Edition Developer’s Guide 45

Responses to Transaction Requests

RESULT Values and RESPMSG Text

ABLE 5.13 Payflow Transaction RESULT Values and RESPMSG Text

RESULT RESPMSG and Explanation

122 Merchant sale total will exceed the credit cap with current transaction. ACH

transactions only.

125 Fraud Protection Services Filter — Declined by filters 126 Fraud Protection Services Filter — Flagged for review by filters

IMPORTANT: RESULT value 126 indicates that a transaction triggered a fraud

RESULT value 126 is intended to give you an idea of the kind of transaction that is considered suspicious to enable you to evaluate whether you can benefit from using the Fraud Protection Services.

T o eliminate RESULT 126, tu rn the filters off. For more information, see the fraud documentation for your payments solution.

filter. This is not an error, but a notice that the transaction is in a review status. The transaction has been authorized but requires you to review and to manually accept the transaction before it will be allowed to settle.

127 Fraud Protection Services Filter — Not processed by filters 128 Fraud Protection Services Filter — Declined by merchant after being flagged

for review by filters 132 Card has not been submitted for update 133 Data mismatch in HTTP retry request 150 Issuing bank timed out 151 Issuing bank unavailable 200 Reauth error 201 Order error 600 Cybercash Batch Error 601 Cybercash Query Error 1000 Generic host error. This is a generic message returned by your credit card

processor. The RES PMSG will contain more information describing the error.

1001 Buyer Authentication Service unavailable 1002 Buyer Authentication Service — Transaction timeout 1003 Buyer Authentication Service — Invalid client version 1004 Buyer Authentication Service — Invalid timeout value 1011 Buyer Authentication Service unavailable 1012 Buyer Authentication Service unavailable

46 Website Payments Pro Payflow Edition Developer’s Guide

Responses to Transaction Requests

RESULT Values and RESPMSG Text

ABLE 5.13 Payflow Transaction RESULT Values and RESPMSG Text

RESULT RESPMSG and Explanation

1013 Buyer Authentication Service unavailable 1014 Buyer Authentication Service — Merchant is not enrolled for Buyer

Authentication Service (3-D Secure) 1016 Buyer Authentication Service — 3-D Secure error response r eceived. Instead of

receiving a PARes response to a Validate Authentication transaction, an error

response was received. 1017 Buyer Authentication Service — 3-D Secure error response is invalid. An error

response is received and the response is not well formed for a Validate

Authentication transaction.

1021 Buyer Authentication Service — Invalid card type 1022 Buyer Authentication Service — Invalid or missing currency code 1023 Buyer Authentication Service — merchant status for 3D secure is invalid

1041 Buyer Authentication Service — Validate Authentication failed: missing or

invalid PARES 1042 Buyer Authentication Service — Validate Authentication failed: PARES

format is invalid 1043 Buyer Authentication Service — Validate Authentication failed: Cannot find

successful Verify Enrollment 1044 Buyer Authentication Service — Validate Authentication failed: Signature

validation failed for PARES 1045 Buyer Authentication Service — Validate Authentication failed: Mismatched

or invalid amount in PARES 1046 Buyer Authentication Service — Validate Authentication failed: Mismatched

or invalid acquirer in PARES 1047 Buyer Authentication Service — Validate Authentication failed: Mismatched

or invalid Merchant ID in PARES 1048 Buyer Authentication Service — Validate Authentication failed: Mismatched

or invalid card number in PARES 1049 Buyer Authentication Service — Validate Authentication failed: Mismatched

or invalid currency code in PARES 1050 Buyer Authentication Service — Validate Authentication failed: Mismatched

or invalid XID in PARES 1051 Buyer Authentication Service — Validate Authentication failed: Mismatched

or invalid order date in PARES

Website Payments Pro Payflow Edition Developer’s Guide 47

Responses to Transaction Requests

RESULT Values and RESPMSG Text

ABLE 5.13 Payflow Transaction RESULT Values and RESPMSG Text

RESULT RESPMSG and Explanation

1052 Buyer Authentication Service — Validate Authentication failed: This PARES

was already validated for a previous Validate Authenticatio n tra nsaction

RESULT Values for Communications Errors

A RESUL T value less than zero indicates that a communication error occurred. In this case, no transaction is attempted.

A value of -1 or -2 usually indicates a configuration error caused by an incorrect URL or by configuration issues with your firewall. A value of -1 or -2 can also be possible if the PayPal servers are unavailable, or an incorrect server/socket pair has been specified. A value of -1 can also result when there are internet connectivity errors. Contact customer support regarding any other errors.

Details of the response message may vary slightly from that shown in the table, depending on your SDK integration.

ABLE 5.14 Communications RESULT values

RESULT Description

-1 Failed to connect to host

-2 Failed to resolve hostname

-5 Failed to initialize SSL context

-6 Parameter list format error: & in name

-7 Parameter list format error: invalid [ ] name length clause

-8 SSL failed to connect to host

-9 SSL read failed

-10 SSL write failed

-11 Proxy authorization failed

-12 Timeout waiting for response

-13 Select failure

-14 Too many connections

-15 Failed to set socket options

-20 Proxy read failed

-21 Proxy write failed

-22 Failed to initia lize SSL certificate

48 Website Payments Pro Payflow Edition Developer’s Guide

Responses to Transaction Requests

RESULT Values and RESPMSG Text

ABLE 5.14 Communications RESULT values

RESULT Description

-23 Host address not specified

-24 Invalid transaction type

-25 Failed to create a socket

-26 Failed to initialize socket layer

-27 Parameter list format error: invalid [ ] name length clause

-28 Parameter list format error: name

-29 Failed to initialize SSL connection

-30 Invali d timeout value

-31 The certificate chain did not validate, no local certificate found

-32 The certificate chain did not validate, common name did not match URL

-40 Unexpected Request ID found in request

-41 Required Request ID not found in request

-99 Out of memory

-100 Parameter list cannot be empty

-103 Context initialization failed

-104 Unexpected transaction state

-105 Invalid name value pair request

-106 Invalid response format

-107 This XMLPay version is not supported

-108 The server certificate chain did not validate

-109 Unable to do logging

-111 The following error occurred while initializing from message file: <Details of

the error message>

-113 Unable to round and truncate the currency value simultaneously

Website Payments Pro Payflow Edition Developer’s Guide 49

Responses to Transaction Requests

RESULT Values and RESPMSG Text

50 Website Payments Pro Payflow Edition Developer’s Guide

Testing Credit Card Transactions

To test your application, direct all transactions to the host address for testing. For details, see

“Host Addresses” on page 9. Transactions directed to the testing URL are processed through

PayPal’s simulated payment network, enabling you to test the configuration and operation of your application or storefront — no money changes hands. (You must activate your account and configure your application for live transactions before accepting real orders.)

Testing Guidelines

z While testing, use only the credit card numbers listed in this chapter. Other numbers

produce an error.

z Expiration Date must be a valid date in the future (use the mmyy format). z To view the credit card processor that you have selected for testing, see Account Info >

Processor Info in PayPal Manager.

Credit Card Numbers Used for Testing

Use the following credit card numbers for testing. Any other card number produces a general failure.

TABLE 6.1 Testing credit card numbers

Credit Card Number

American Express 378282246310005 American Express 371449635398431 Amex Corporate 378734493671000 Australian BankCard 5610591081018250 Diners Club 30569309025904 Diners Club 38520000023237 Discover 6011111111111117 Discover 6011000990139424 JCB 3530111333300000 JCB 3566002020360505

Website Payments Pro Payflow Edition Developer’s Guide 51

Testing Credit Card Transactions

Testing Result Code Responses

ABLE 6.1 Testing credit card numbers

Credit Card Number

MasterCard 555555 5555554444 MasterCard 510510 5105105100 Visa 4111111111111111 Visa 4012888888881881 Visa 4222222222222

NOTE:Even though this number has a different character count than the other test

numbers, it is the correct and functional number.

Testing Result Code Responses

You can use the amount of the transaction to generate a particular result code. The table below lists the general guidelines for specifying amounts.

ABLE 6.2 Obtaining PayPal result code

Result Definition How to test

0 Approved Use an AMOUNT of 10000 or less 3 Invalid transaction type Use the AMOUNT 10402 4 Invalid amo unt Use any of these as AMOUNT:

z 10400 z 10401 z 10403 z 10404

5 Invalid merchant information Use any of these as AMOUNT:

z 10548 z 10549

52 Website Payments Pro Payflow Edition Developer’s Guide

Testing Credit Card Transactions

Testing Result Code Responses

ABLE 6.2 Obtaining PayPal result code

Result Definition How to test

7 Field format error Use any of these as AMOUNT:

z 10405 z 10406 z 10407 z 10408 z 10409 z 10410 z 10412 z 10413 z 10416 z 10419 z 10420 z 10421 z 10509 z 10512 z 10513 z 10514 z 10515 z 10516 z 10517 z 10518 z 10540 z 10542

12 Declined Use any of these as AMOUNT:

z 10417 z 15002 z 15005 z 15006 z 15028 z 15039 z 10544 z 10545 z 10546

13 Referral Use the AMOUNT 10422 23 Invalid account number Use any of these as AMOUNT:

z 10519 z 10521 z 10522 z 10527 z 10535 z 10541 z 10543

Website Payments Pro Payflow Edition Developer’s Guide 53

Testing Credit Card Transactions

Testing Result Code Responses

ABLE 6.2 Obtaining PayPal result code

Result Definition How to test

24 Invalid expiration date Use any of these as AMOUNT:

z 10502 z 10508

30 Duplicate Transaction Use the AMOUNT 10536 105 Credit error Attempt to credit an authorization 112 Failed AVS check Use the AMOUNT 10505 114 CVV2 Mismatch Use the AMOUNT 10504 1000 Generic Host (Processor) Error Use an AMOUNT other than those listed in this column

54 Website Payments Pro Payflow Edition Developer’s Guide

Verbosity: Viewing Processor-

Specific Transaction Results

Transaction results (especially values for decline s and error conditions) returned by the PayPal processor vary in detail level and in format. The VERBOSITY parameter enables you to control the kind and level of information you want returned.

By default, VERBOSITY is set to LOW .. A LOW setting causes the server to normalize the transaction result values. Normalizing the values limits them to a standardized set of values and simplifies the process of integration.

By setting VERBOSITY to MEDIUM, you can view PayPal’s raw response values. This setting is more “verbose” than the LOW setting in that it returns more detailed, processor-specific information.

Supported Verbosity Settings

PayPal supports the following VERBOSITY settings.

z LOW: This is the default setting for Payflow accounts. The following values are returned:

{RESULT , PNREF, RESPMSG, AUTHCODE, AVSADDR, AVSZIP, CVV2MATCH, IAVS, CARDSECURE}

z MEDIUM: All of the values returned for a LOW setting, plus the following values:

NOTE:For information on interpreting the responses returned by the processor for the MEDIUM

VERBOSITY setting, contact your processor directly.

TABLE A.1 Verbosity settings

Field Name Type Length Description

HOSTCODE char 7 Response code returned by the PayPal processor.

This value is not normalized.

RESPTEXT char 17 T ext corresponding to the response code returned by

the PayPal processor. This text is not normalized.

PROCAVS char 1 AVS response from the PayPal processor PROCCVV2 char 1 CVV2 response from the PayPal processor PROCCARDSECURE char 1 VPAS/SPA response from the PayPal processor. ADDLMSGS char Up to 1048

characters. Typically 50

characters.

Additional error message that indicates that the merchant used a feature that is disabled.

Website Payments Pro Payflow Edition Developer’s Guide 55

Verbosity: Viewing Processor-Specific Transaction Results

Supported Verbosity Settings

ABLE A.1 Verbosity settings (Continued)

Field Name Type Length Description

TRANSSTATE Integer 10 State of the transaction. The values are:

0 = General succeed state 1 = General error state 3 = Authorization approved 6 = Settlement pending (transaction is scheduled to

be settled) 7 =Settlement in progress (transaction involved in a

currently ongoing settlement) 8 = Settled successfully 9 = Authorization captured (once an authorization

type transaction is captured, its TRANSSTATE becomes 9)

10 = Capture failed (an error occurred while trying to capture an authorization because the transaction was already captured)

11 = Failed to settle (transactions fail settlement usually because of problems with the processor or because the card type is not set up with the processor)

1 2= Unsettled transaction because of incorrect account information

14 = For various reasons, the batch containing this transaction failed settlement

15 = Settlement incomplete due to a charge back. 106 = Unknown Status Transaction - Transactions

not settled. 206 = Transactions on hold pending customer

intervention.

DATE_TO_SETTLE

BATCHID

SETTLE_DATE

Date format

YYYY-MM-DD HH:MM:SS

Integer 10 Value available only after settlement has assigned a

Date format

YYYY-MM-DD HH:MM:SS

19 Value available only before settlement has started.

Batch ID.

19 Value available only after settl ement has co mpl ete d.

56 Website Payments Pro Payflow Edition Developer’s Guide

Verbosity: Viewing Processor-Specific Transaction Results

Changing the Verbosity Setting

Table A.2 shows the increments that are possible on basic TRANSSTATE values.

ABLE A.2 TRANSSTATE increments

Increment Meaning

+100 The TRANSSTATE is incremented by 100 if no client acknowledgment (ACK) is

received. For example, if the original TRANSSTATE is 6, the new TRANSSTATE is

106. Transactions in this range do not settle. For transactions in TRANSSTATE 106, use Auto Resettle in PayPal Manager’s

Transaction Terminal to subm it them for settlement or void them using a manual Void.

+200 The host process never receives ACK from the transaction broker (or backend

payment server). A transaction with a TRANSSTATE incremented by 200 is basically in limbo and will not be settled.

+1000 If a void is run against a successful Authorization or Sale transaction, the original

TRANSSTATE is incremented by 1000. For example, if the original TRANSSTATE is 6, the new TRANSSTATE is 1006.

Changing the Verbosity Setting

To specify a setting for VERBOSITY that differs from your account’s current setting, include the VERBOSITY=<value> name-value pair in the transaction request, where <value> is LOW or MEDIUM.

This is an example response with no VERBOSITY defined:

RESULT=0&PNREF=E19P0F5A5B95&RE SPMSG=Approved&AUT HCODE=111111&AVSADDR= Y&AVSZ IP=Y&CVV2MATCH=Y&PPREF=70C6798 7W0761540M&CORRELA TIONID=23795f89710e7& IAVS=N

This is an example response from the same request with VERBOSITY=MEDIUM:

RESULT=0&PNREF=E79P0E23873D&RE SPMSG=Approved&AUT HCODE=111111&AVSADDR= Y&AVSZ IP=Y&CVV2MATCH=Y&PPREF=71L6530 8H1608350J&CORRELA TIONID=6e4bbbefabd69& PROCAV S=X&PROCCVV2=M&IAVS=N

Website Payments Pro Payflow Edition Developer’s Guide 57

Verbosity: Viewing Processor-Specific Transaction Results

Changing the Verbosity Setting

58 Website Payments Pro Payflow Edition Developer’s Guide

Currency Codes

The following currencies are supported for use in transactions.

NOTE:American Express and Discovery support USD only.

TABLE B.1 Currencies and Currency Codes

Code Currency

AUD Australian Dollar CAD C an adian Dollar EUR Euro JPY Japanese Yen GBP Pound Sterling USD U.S. Dollar

Website Payments Pro Payflow Edition Developer’s Guide 59

Currency Codes

60 Website Payments Pro Payflow Edition Developer’s Guide

Country Codes

NOTE:This table lists country codes

defined by

Table 1: Country Codes

Country Code

AFGHANISTAN AF ÅLAND ISLANDS AX ALBANIA AL ALGERIA DZ AMERICAN SAMOA AS ANDORRA AD ANGOLA AO ANGUILLA AI ANTARCTICA AQ ANTIGUA AND BAR-

BUDA ARGENTINA AR ARMENIA AM ARUBA AW AUSTRALIA AU AUSTRIA AT AZERBAIJAN AZ BAHAMAS BS BAHRAIN BH BANGLADESH BD

ISO 3166-1.

Country Code

BELARUS BY BELGIUM BE BELIZE BZ BENIN BJ BERMUDA BM BHUTAN BT BOLIVIA BO BOSNIA AND HERZE-

GOVINA BOTSWANA BW BOUVET ISLAND BV BRAZIL BR BRITISH INDIAN

OCEAN TERRITORY BRUNEI DARUSSALAM BN BULGARIA BG BURKINA FASO BF BURUNDI BI CAMBODIA KH CAMEROON CM CANADA CA CAPE VERDE CV CAYMAN ISLANDS KY

BARBADOS BB

Country Codes

Country Code

CENTRAL AFRICAN

REPUBLIC CHAD TD CHILE CL CHINA CN CHRISTMAS ISLAND CX COCOS (KEELING)

ISLANDS COLOMBIA CO COMOROS KM CONGO CG CONGO, THE DEMO-

CD CRATIC REPUBLIC OF THE

COOK ISLANDS CK COSTA RICA CR COTE D'IVOIRE CI CROATIA HR CUBA CU CYPRUS CY CZECH REPUBLIC CZ DENMARK DK DJIBOUTI DJ DOMINICA DM DOMINICAN REPUBLIC DO ECUADOR EC EGYPT EG EL SALVADOR SV

Country Code

EQUATORIAL GUINEA GQ ERITREA ER ESTONIA EE ETHIOPIA ET FALKLAND ISLANDS

(MALVINAS) FAROE ISLANDS FO FIJI FJ FINLAND FI FRANCE FR FRENCH GUIANA GF FRENCH POLYNESIA PF FRENCH SOUTHERN

TERRITORIES GABON GA GAMBIA GM GEORGIA GE GERMANY DE GHANA GH GIBRALTAR GI GREECE GR GREENLAND GL GRENADA GD GUADELOUPE GP GUAM GU GUATEMALA GT GUERNSEY GG

Country Code

GUINEA GN GUINEA-BISSAU GW GUYANA GY HAITI HT HEARD ISLAND AND

MCDONALD ISLANDS HOLY SEE (VATICAN

CITY STATE) HONDURAS HN HONG KONG HK HUNGARY HU ICELAND IS INDIA IN INDONESIA ID

KOREA, REPUBLIC OF KR KUWAIT KW KYRGYZSTAN KG LAO PEOPLE'S DEMO-

CRATIC REPUBLIC LATVIA LV LEBANON LB LESOTHO LS LIBERIA LR LIBYAN ARAB JAMA-

HIRIYA LIECHTENSTEIN LI LITHUANIA LT LUXEMBOURG LU

IRAN, ISLAMIC REPUB-

LIC OF IRAQ IQ IRELAND IE ISLE OF MAN IM ISRAEL IL ITALY IT JAMAICA JM JAPAN JP JERSEY JE JORDAN JO KAZAKHSTAN KZ KENYA KE KIRIBATI KI KOREA, DEMOCRATIC

PEOPLE'S REPUBLIC OF

MACAO MO MACEDONIA, THE

MK FORMER YUGOSLAV REPUBLIC OF

MADAGASCAR MG MALAWI MW MALAYSIA MY MALDIVES MV MALI ML MALTA MT MARSHALL ISLANDS MH MARTINIQUE MQ MAURITANIA MR MAURITIUS MU MAYOTTE YT MEXICO MX

Country Codes

Country Code

MICRONESIA, FEDER-

ATED STATES OF MOLDOVA, REPUBLIC OFMD

MONACO MC MONGOLIA MN MONTSERRAT MS MOROCCO MA MOZAMBIQUE MZ MYANMAR MM NAMIBIA NA NAURU NR NEPAL NP NETHERLANDS NL NETHERLANDS ANTI-

LLES NEW CALEDONIA NC NEW ZEALAND NZ NICARAGUA NI NIGER NE NIGERIA NG NIUE NU NORFOLK ISLAND NF

Country Code

PALAU PW PALESTINIAN TERRI-

TORY, OCCUPIED PANAMA PA PAPUA NEW GUINEA PG PARAGUAY PY PERU PE PHILIPPINES PH PITCAIRN PN POLAND PL PORTUGAL PT PUERTO RICO PR QATAR QA REUNION RE ROMANIA RO RUSSIAN FEDERATION RU RWANDA RW SAINT HELENA SH SAINT KITTS AND

NEVIS SAINT LUCIA LC SAINT PIERRE AND

MIQUELON

NORTHERN MARIANA

ISLANDS NORWAY NO OMAN OM PAKISTAN PK

SAINT VINCENT AND

THE GRENADINES SAMOA WS SAN MARINO SM

Country Code

SAO TOME AND PRINC-

IPE SAUDI ARABIA SA SENEGAL SN SERBIA AND MON-

TENEGRO SEYCHELLES SC SIERRA LEONE SL SINGAPORE SG SLOVAKIA SK SLOVENIA SI SOLOMON ISLANDS SB SOMALIA SO SOUTH AFRICA ZA SOUTH GEORGIA AND

GS THE SOUTH SANDWICH ISLANDS

SPAIN ES SRI LANKA LK

TANZANIA, UNITED

REPUBLIC OF THAILAND TH TIMOR-LESTE TL TOGO TG TOKELAU TK TONGA TO TRINIDAD AND

TOBAGO TUNISIA TN TURKEY TR TURKMENISTAN TM TURKS AND CAICOS

ISLANDS TUVALU TV UGANDA UG UKRAINE UA UNITED ARAB EMIR-

ATES SUDAN SD SURINAME SR SVALBARD AND JAN

MAYEN SWAZILAND SZ SWEDEN SE SWITZERLAND CH SYRIAN ARAB REPUB-

LIC TAIWAN, PROVINCE OF

CHINA TAJIKISTAN TJ

UNITED KINGDOM GB

UNITED STATES US

UNITED ST ATES MINOR

OUTLYING ISLANDS

URUGUAY UY

UZBEKISTAN UZ

VANUATU VU

VENEZUELA VE

VIET NAM VN

VIRGIN ISLANDS, BRIT-

ISH

Country Codes

Country Code

VIRGIN ISLANDS, U.S. VI WALLIS AND FUTUNA WF WESTERN SAHARA EH YEMEN YE ZAMBIA ZM ZIMBABWE ZW

Index

ACCT parameter 19 ACCTTYPE parameter 19 ADDLMSGS parameter 55 address verification service 34 AMT parameter 19 APIs

documentation 11 downloading 11

application

testing 51 Australian Dollar 59 authorization/delayed capture transactions, when to

use 25

Baht 60 BATCHID parameter 56 Brazilian Real 59 BUTTONSOURCE parameter 19

Canadian Dollar 59 CAPTURECOMPLETE parameter 20, 27 CITY parameter 2 2 COMMENT1 parameter 1 9 COMMENT1parameter 24 COMMENT2 parameter 2 0 COUNTRY parameter 22 credit transaction type 28 currency code format 19, 20, 21 currency codes 19, 59 CURRENCY parameter 19 CUSTIP parameter 19 CUSTIPparameter 24 CUSTOM parameter 20 Customer Support 18 CUSTREF parameter 20 CVV2 parameter 24 CVV2 parameterPayflow parameters

CVV2 20 CVV2MATCH parameter 40 Czech Koruna 59

Danish Krone 59 DATE_TO_SETTLE parameter 56 documentation

API 11 Dollar 59, 60 downloading APIs 11 duplicate transactions 18

EMAIL parameter 20 Euro 59 EXPDATE parameter 19

firewalls. configuring 11 FIRSTNAME parameter 22 FIRSTNAMEparameter 24 Forint 59 Franc 59 fraud detection 22 FREIGHTAMT parameter 21

HANDLINGAMTparameter 21 Hong Kong Dollar 59 HOSTCODE parameter 55 Hungarian Forint 59

Instant Payment Notification 22 INVNUM parameter 20 Israeli New Sheqel 59

Index

ITEMAMT parameter 20

Japanese Yen 59

Koruna 59 Krona 59 Krone 59

L_COSTn parameter 21 L_DESCnparameter 21 L_QTYn parameter 21 L_SKUn parameter 22 L_TAXAMTn parameter 22 LASTNAME parameter 22 LASTNAMEparameter 24 length tags 15 libraries, .NET 9 libraries, Java 9 live transactions 12 live transactions host address 9

Malaysian Ringgit 59 MERCHANTSESSIONID parameter 22 Mexican Peso 59

New Dollar 59 New Sheqel 59 New Zealand Dollar 59 Norwegian Krone 59 NOTIFYURL parameter 22

online help 7 operation

testing 51

ORDERDESC 22 ORDERDESC parameter 22 ORIGID parameter 26, 29, 31

PARTNER parameter 15 Payflow documentation 7 Payflow parameters

ACCT 15, 19, 24, 25, 26, 29, 30, 31, 33

ACCTTYPE 19, 33

ADDLMSGS 55

AMT 15, 19, 24, 25, 26, 29, 30, 31

AVSADDR 34

AVSZIP 3 4

BATCHID 56

BUTTONSOURCE 19

CAPTURECOMPLETE 20, 27

CITY 22, 26, 30, 31, 33

COMMENT1 19, 24, 26, 30, 31

COMMENT2 20, 30, 31

COUNTRY 22, 33

CURRENCY 19

CUSTCODE 26, 30, 31

CUSTIP 19, 24, 26, 30, 31

CUSTOM 20

CUSTREF 20

CVV2 24, 35

CVV2MATCH 40

DATE_TO_SETTLE 56

EMAIL 20, 26, 30, 31

EXPDATE 16, 19, 24, 25, 26, 29, 30, 31, 33

FIRSTNAME 22, 24, 26, 30, 31, 33

FREIGHTAMT 21, 26, 30, 31

HANDLINGAMT 21

HOSTADDRESS 14

HOSTCODE 55

HOSTPORT 14

INVNUM 20, 26, 30, 31

ITEMAMT 20

L_COSTn 21

L_DESCn 21

L_QTYn 21

L_SKUn 22

L_TAXAMTn 22

LASTNAME 22, 24, 26, 30, 31, 33

MERCHANTSESSIONID 22

68 Website Payments Pro Payflow Edition Developer’s Guide

Index

NOTIFYURL 22 ORDERDESC 22 ORIGID 26, 28, 29, 31, 41 PARMLIST 14 PARTNER 15 PAYMENTTYPE 39 PNREF 26, 28, 29, 31, 41 PONUM 26, 30, 31 PROCAVS 55 PROCCARDSECURE 55 PROCCVV2 55 PROXYADDRESS 14 PROXYLOGON 14 PROXYPASSWORD 14 PROXYPORT 14 PWD 15 RECURRINGTYPE 22 RESPMSG 42 RESPTEXT 55 RESULT 42, 48 SETTLE_DATE 56 SHIPTOCITY 23, 26, 30, 31 SHIPTOCOUNTRY 23, 26, 30, 31 SHIPTOFIRSTNAME 26, 30, 31 SHIPTOLASTNAME 26, 30, 31 SHIPTOSTATE 23, 26, 30, 31 SHIPTOSTREET 23, 26, 30, 31 SHIPTOZIP 23, 26, 30, 31 STATE 22, 26, 30, 31, 33 STREET 22, 26, 30, 31, 33, 34 TAXAMT 20, 26, 30, 31 TENDER 18 TIMEOUT 14 TRANSSTATE 56 TRXTYPE 18, 23, 24, 25, 28, 30, 41 USER 15 VENDOR 15 VERBOSITY 13, 14, 20, 55

ZIP 22 , 24, 26, 30, 31, 33, 34 payflowpro.paypal.com 9 PAYMENTTYPE parameter 39 PayPal Developer Central 7 PayPal-supported currencies 59 Peso 59 Phillippine Peso 59 pilot-payflowpro.paypal.com 9 PNREF

format of value 41 PNREF value 41 Polish Zloty 59 Pound Sterling 59 PROCAVS parameter 55 PROCCARDSECURE parameter 55 PROCCVV2 parameter 55 PWD parameter 15

Real 59 RECURRINGTYPEparameter 22 reference transactions, when to use 32 RESPMSG value 42 RESPTEXT par ameter 55 RESULT value 42 Ringgit 59

sale transaction type 23 sale transactions, when to use 23 Sample Code and Documentation 7 SETTLE_DATE parameter 56 SHIP-TO Address parameters 23 SHIPTOCITY parameter 23 SHIPTOCOUNTRYparameter 23 SHIPTOSTATEparameter 23 SHIPTOSTREET parameter 23 SHIPTOZIP parameter 23 Singapore Dollar 59 SSL 11 STATE parameter 22 storefront

testing 51 storing credit card numbers 17 STREET parameter 22 Swedish Krona 59 Swiss Franc 59

Taiwan New Dollar 59 TAXAMTparameter 20 TENDER parameter 18 testing operation 51

Website Payments Pro Payflow Edition Developer’s Guide 69

Index

testing transactions host address 9 Thai Baht 60 transaction response

PNREF parameter 41 RESPMSG parameter 42 RESULT parameter 42

transactions

credit 28 sale 23

void 30 TRANSSTATE 106 57 TRANSSTATE parameter 56 TRXTYPE parameter 18 type N transactions 18

U.S. Dollar 60 USER parameter 15 using Authorization/Delayed Capture transactions 24 using Delayed Capture transactions 27

VENDOR parameter 15 VERBOSITY

changing setting 57

settings 55 VERBOSITY parameter 2 0, 55 void transaction type 30 void transactions, when to use 30

website integration considerations 17

Yen 59

ZIP parameter 22 ZIPparameter 24 Zloty 59

70 Website Payments Pro Payflow Edition Developer’s Guide

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

Submitting Sale Transactions

When To Use a Sale Transaction

Submitting Authorization/Delayed Capture Transactions

Additional Parameters For Sale Transactions

Typical Sale Transaction Parameter String

When To Use Authorization/Delayed Capture Transactions

Required Authorization Transaction Parameters

Typical Auth orization Transaction Parameter String

Required Delayed Capture Transaction Parameters

Delayed Capture Transaction: Capturing Transactions for Lower Amounts

Submitting Credit Transactions

Delayed Capture Transaction: Capturing Transactions for Higher Amounts

Delayed Capture Transaction: Error Handling and Retransmittal

Required Credit Transaction Parameters

Submitting Void Transactions

Credit Transaction Parameter Strings

When To Use a Void Transaction

Required Void Transaction Parameters

Example Void Transaction Parameter String

Recharging to the Same Credit Card (Reference Transactions)

When To Use a Reference Transaction

Transaction Types that Can Be Used as the Original Transaction

Fields Copied From Reference Transactions

Example Reference Transaction

Using Address Verification Service

Example Address Verification Service Request

Example Address Verification Service Response

Card Security Code Validation

Example CVV2 Request

Example CVV2 Response

Contents of a Response to a Credit Card Transaction Request

Address Verification Service Responses From PayPal

Card Security Code Results

Normalized Results

PayPal Card Security Code Results

PNREF Value

PNREF Format

RESULT Values and RESPMSG Text

RESULT Values for Transaction Declines or Errors

RESULT Values for Communications Errors

Testing Credit Card Transactions

Testing Guidelines

Credit Card Numbers Used for Testing

Testing Result Code Responses

Supported Verbosity Settings

Changing the Verbosity Setting

Currency Codes

TABLE B.1 Currencies and Currency Codes

Country Codes