PayPal Payflow Pro - 2009 Developer's Guide

Payflow Pro Developer’s Guide

Last updated: October 2009

Payflow Pro Developer’s Guide

Document Number: 200010.en_US-200910

© 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

How to Contact Customer Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . .13

About Payflow Pro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Payflow Pro Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Host Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

How Payflow Pro Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Supported Processing Platforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Supported Payment Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Payflow Pro Recurring Billing Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

About Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

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

Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Preparing the Payflow Client Application . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Activating Your Payflow Pro Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Chapter 3 Simple Payflow Transaction. . . . . . . . . . . . . . . . . 19

Transaction Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Request Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Data Modes for Sending. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

User Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Sale Transaction Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Typical Sale Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Formatting Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Payflow Pro Developer’s Guide 3

Contents

Chapter 4 Credit Card Transactions . . . . . . . . . . . . . . . . . . 23

Credit Card Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

About Credit Card Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Obtaining an Internet Merchant Account . . . . . . . . . . . . . . . . . . . . . . . . 24

Planning Your Payflow Pro Integration . . . . . . . . . . . . . . . . . . . . . . . . . 24

Complying With the E-commerce Indicator (ECI) . . . . . . . . . . . . . . . . . . . . 25

Handling Credit Card Type Information . . . . . . . . . . . . . . . . . . . . . . . . . 25

Parameters Used in Credit Card Transactions. . . . . . . . . . . . . . . . . . . . . . . . 26

Submitting Sale Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

When To Use a Sale Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Additional Parameters For Sale Transactions . . . . . . . . . . . . . . . . . . . . . . 28

Typical Sale Transaction Parameter String . . . . . . . . . . . . . . . . . . . . . . . 29

Submitting Authorization/Delayed Capture Transactions . . . . . . . . . . . . . . . . . . 29

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

Required Authorization Transaction Parameters . . . . . . . . . . . . . . . . . . . . 30

Typical Authorization Transaction Parameter String. . . . . . . . . . . . . . . . . . . 30

Required Delayed Capture Tr ansaction Parameters . . . . . . . . . . . . . . . . . . 30

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

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

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

Submitting Account Verifications With TRXTYPE=A. . . . . . . . . . . . . . . . . . . . . 32

When To Use Account Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Example Account Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Submitting Voice Authorization Transactions . . . . . . . . . . . . . . . . . . . . . . . . 33

When to Use a Voice Authorization Transaction. . . . . . . . . . . . . . . . . . . . . 33

Required Voice Authorization Transaction Parameters . . . . . . . . . . . . . . . . . 34

Submitting Credit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Required Credit Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . 34

Credit Transaction Parameter Strings . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Submitting Void Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

When To Use a Void Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Required Void Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 37

Example Void Transaction Parameter String . . . . . . . . . . . . . . . . . . . . . . 37

Submitting Inquiry Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

When To Use an Inquiry Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Required Parameters When Using the PNREF . . . . . . . . . . . . . . . . . . . . . 38

Inquiry Transaction Parameter String Using the PNREF . . . . . . . . . . . . . . . . 38

Required Parameters When Using the CUSTREF . . . . . . . . . . . . . . . . . . . 39

Inquiry Transaction Parameter String Using the CUSTREF . . . . . . . . . . . . . . . 39

4 Payflow Pro Developer’s Guide

Contents

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

When To Use a Reference Transaction . . . . . . . . . . . . . . . . . . . . . . . . . 40

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

Fields Copied From Reference Transactions . . . . . . . . . . . . . . . . . . . . . . 41

Example Reference Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Submitting Card-Present (SWIPE) Transactions. . . . . . . . . . . . . . . . . . . . . . . 42

Supported Processing Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Card-present Transaction Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Submitting Purchasing Card Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Using Address Verification Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Processing Platforms Supporting Address Verification Service . . . . . . . . . . . . . . . 44

Example Address Verification Service Request Parameter List . . . . . . . . . . . . . . . 45

Example Address Verification Service Response . . . . . . . . . . . . . . . . . . . . . . 45

Card Security Code Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Processing Platforms and Credit Cards Supporting Card Security Code . . . . . . . . 46

Chapter 5 Credit Card Testing . . . . . . . . . . . . . . . . . . . . . 49

Testing Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Credit Card Numbers Used for Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Result Values in Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Testing Result Values in Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . 50

RESULT Values Returned Based on Transaction Amount. . . . . . . . . . . . . . . . . . 50

Alternative Methods for Generating Specific RESULT Values. . . . . . . . . . . . . . 51

Testing Address Verification Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Testing Card Security Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Chapter 6 Responses to Transaction Requests . . . . . . . . . . . .55

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

BALAMT Response Parameter and Stored Value Cards . . . . . . . . . . . . . . . . . . 57

American Express CAPN Stored Value Card Example . . . . . . . . . . . . . . . . . 57

PNREF Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

PNREF Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

RESULT Values and RESPMSG Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

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

RESULT Values for Communications Errors . . . . . . . . . . . . . . . . . . . . . . 64

Appendix A Processors Requiring Additional Transaction Parameters . 67

Payflow Pro Developer’s Guide 5

Contents

American Express . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

American Express Additional Credit Card Parameters (CAPN) . . . . . . . . . . . . . 68

American Express Additional Credit Card Parameters (Legacy) . . . . . . . . . . . . 73

First Data Merchant Services (FDMS) Nashville. . . . . . . . . . . . . . . . . . . . . . . 76

FDMS Nashville, Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . 76

First Data Merchant Services (FDMS) South . . . . . . . . . . . . . . . . . . . . . . . . 77

FDMS South, Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . 77

First Data Merchant Services (FDMS) North. . . . . . . . . . . . . . . . . . . . . . . . . 77

FDMS North, Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . 77

Merchant e-Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Merchant e-Solutions, Additional Credit Card Parameters . . . . . . . . . . . . . . . 78

Elavon (Formerly Nova) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Elavon, Additional Credit Card Parameters . . . . . . . . . . . . . . . . . . . . . . . 79

Paymentech . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Paymentech Salem (New Hampshire), Additional Credit Card Parameters (CAPN) . . 79

Paymentech, Additional Credit Card Parameters (Legacy) . . . . . . . . . . . . . . . 82

TSYS Acquiring Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

TSYS Acquiring Solutions, Additional Credit Card Parameters (CAPN). . . . . . . . . 83

TSYS Acquiring Solutions, Additional Credit Card Parameters (Legacy) . . . . . . . . 89

Appendix B Performing TeleCheck Electronic Check Transactions . . . 91

TeleCheck Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Required Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Testing TeleCheck Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Example Test Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Preparing for TeleCheck Production Transactions . . . . . . . . . . . . . . . . . . . . . . 94

Responses to Telecheck Transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

HOSTCODE Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Appendix C Submitting Purchasing Card Level 2 and

Level 3 Transactions . . . . . . . . . . . . . . . . . . . . . . . .99

About Purchasing Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

About Program Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Accepted BIN Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100

About American Express Purchasing Card Transactions - Phoenix Processor . . . . . . .100

Supported Transaction Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

Avoiding Downgrade. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

Submitting Successful Level 3 Transactions . . . . . . . . . . . . . . . . . . . . . .101

6 Payflow Pro Developer’s Guide

Contents

Edit Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

Accepted BIN Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102

American Express Phoenix Purchasing Card Transaction Processing . . . . . . . . . . .102

American Express Phoenix Level 2 Parameters (CAPN) . . . . . . . . . . . . . . . .103

American Express Phoenix Level 2 Parameters (Legacy). . . . . . . . . . . . . . . .105

Example American Express Phoenix Level 2 Transaction Parameter String . . . . . .105

American Express Phoenix Level 3 Parameters. . . . . . . . . . . . . . . . . . . . .105

Example American Express Phoenix Level 3 Transaction Parameter String . . . . . .108

First Data Merchant Services (FDMS) Nashville Purchasing Card Transaction Processing.108 First Data Merchant Services (FDMS) North Purchasing Card Transaction Processing . .110

FDMS North Purchasing Card Line Item Parameters . . . . . . . . . . . . . . . . . .111

First Data Merchant Services South (FDMS) Purchasing Card Transaction Processing . .112

FDMS South Line Item Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .113

Example FDMS South Purchasing Card Level 2 and 3 Parameter String. . . . . . . .114

Example FDMS South Line Item Parameter String . . . . . . . . . . . . . . . . . . .114

Global Payments - Central Purchasing Card Transaction Processing. . . . . . . . . . . .115

Global Payments - Central Level 2 Parameters . . . . . . . . . . . . . . . . . . . . .115

Example Global Payments - Central Level 2 Visa or MasterCard Transaction Parameter

String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115

Global Payments - East Purchasing Card Transaction Processing . . . . . . . . . . . . .115

Global Payments - East Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . .116

Example Global Payments - East Level 2 Visa or MasterCard Transaction

Parameter String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116

Merchant e-Solutions Purchasing Card Transaction Processing . . . . . . . . . . . . . .116

Merchant e-Solutions Level 2 Parameters. . . . . . . . . . . . . . . . . . . . . . . .116

Merchant e-Solutions Level 3 MasterCard Parameters . . . . . . . . . . . . . . . . .117

Merchant e-Solutions Level 3 Visa Parameters . . . . . . . . . . . . . . . . . . . . .119

Elavon (Formerly Nova) Purchasing Card Transaction Processing . . . . . . . . . . . . .123

Elavon Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123

Elavon Additional Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123

Example Elavon Level 2 Transaction Parameter String . . . . . . . . . . . . . . . . .124

Paymentech Salem (New Hampshire) Purchasing Card Transaction Processing. . . . . .124

Paymentech Salem (New Hampshire) Level 2 Parameters (CAPN) . . . . . . . . . .124

Paymentech Salem (New Hampshire) Level 2 Parameters (Legacy) . . . . . . . . . .126

Paymentech Salem (New Hampshire) Level 3 Purchasing Card Parameters. . . . . .127

Paymentech Tampa Level 2 Purchasing Card Transaction Processing . . . . . . . . . . .130

Paymentech Tampa Level 2 Parameters . . . . . . . . . . . . . . . . . . . . . . . .131

Example Paymentech Tampa Level 2 Visa and MasterCard Transaction

Parameter String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131

TSYS Acquiring Solutions Purchasing Card Transaction Processing . . . . . . . . . . . .131

Payflow Pro Developer’s Guide 7

Contents

TSYS Acquiring Solutions Level 2 Parameters . . . . . . . . . . . . . . . . . . . . .131

TSYS Acquiring Solutions Level 3 MasterCard Parameters. . . . . . . . . . . . . . .132

TSYS Acquiring Solutions Level 3 Visa Parameters. . . . . . . . . . . . . . . . . . .134

Appendix D VERBOSITY: Viewing Processor-Specific

Transaction Results . . . . . . . . . . . . . . . . . . . . . . . . 139

Supported Verbosity Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139

Changing the Verbosity Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144

Setting the Verbosity Level on a Per-Transaction Basis. . . . . . . . . . . . . . . . .144

Setting the Default Verbosity Level for All Transactions. . . . . . . . . . . . . . . . .144

Appendix E Additional Reporting Para meters . . . . . . . . . . . . . 145

Appendix F ISO Country Codes . . . . . . . . . . . . . . . . . . . . 147

Appendix G Codes Used by FDMS South Only . . . . . . . . . . . . . 153

MasterCard Country Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153

Visa Country Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157

Units of Measure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161

FDMS South Currency Codes and Decimal Positions . . . . . . . . . . . . . . . . . . .166

Appendix H XMLPay . . . . . . . . . . . . . . . . . . . . . . . . . . 167

About XMLPay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167

Payflow Pro XMLPay Developer’s Guide . . . . . . . . . . . . . . . . . . . . . . . . . .167

Appendix I Additional Processor Information . . . . . . . . . . . . . 169

Moneris Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

8 Payflow Pro Developer’s Guide

Scope

Preface

This guide describes Payflow Pro, a high performance TCP/IP-based Internet payment solution and how to use it to process credit card. Payflow Pro is pre-integrated with leading ecommerce solutions and is also available as a downloadable software development kit (SDK).

This guide explains how to integrate Payflow Pro into your website or application to process credit card transactions over the Payflow payments gateway. It includes information and special requirements for all supported processors. To process Express Checkout transactions over the Payflow gateway, see the following Payflow guide: Express Checkout for Payflow Pro.

Intended Audience

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

https://www.paypal.com/us/cgi-

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

Payflow Pro Developer’s Guide 9

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

Revision History

Revision history for Payflow Pro Developer’s Guide.

TABLE 1.1 Revision history

Date Description

October 2009

z Added COMPANYNAME to reporting parameters. z Added new appendix on additional processor informaion. Currently includes Moneris

processor information.

z Added Account Verification as a type of transaction that uses TRXTYPE=A and

AMT=0 to verify credit card information.

z Updated length of PARTNER, USER, and VENDOR to 64 characters.

June 2009 FDMS supports unreferenced credits. April 2009 Minor corrections for technical accuracy and clarification. November 2008

z Moved coverage of Express Checkout to a separate new document, Express Checkout

for Payflow Pro.

z Removed coverage of the version 3 Payflow SDK, including test and live URLs. z Changed Paymentech New Hampshire to Paymentech Salem (New Hampshire) z Updated name of Nova processor to Elavon. z Corrected format of TSYS ORDERDATE field z Added more clarification to description of RESULT value 25 z Added more clarification of AMEX CAPN parameters in Appendix A z Updated Table 4.1 , “Credit card transaction request parameters,” to reflect credit card

parameter descriptions only and moved the non-credit card parameter descriptions to new tables in applicable sections of the chapter

z Minor corrections for technical accuracy and clarification

June 2008

Updated live and test URLs to reflect PayPal only: payflowpro.paypal.com live URL and

pilot-payflowpro.paypal.com test URL

Added Help Center URL to Preface. Added Paymentech New Hampshire processor specification updates, including:

z CAPN requirements z Support of card security code for American Express and Discover cards z Support of Switch/Solo Maestro card z Full authorization reversals

March 2008

Added PayPal processor responses. Updated RESULT value 0 to include information about PayPal processor success with warning

message

February 2008 Removed note that PayPal processor does not support non-referenced credits. It supports them now.

Updated test and live host URLs. Added BILLTOCOUNTRY to Paymentech additional parameters. Combined Telecheck transactions content into one appendix.

10 Payflow Pro Developer’s Guide

ABLE 1.1 Revision history

Date Description

Revision History

November 2007

Explains how merchant can determine what SDK version they are using. Provides guidelines to merchant to determine if merchant is following American Express CAPN

requirements. Explains more about VERBOSITY parameter. Combines appendixes on performing Telecheck transactions with Telecheck responses. Adds BIN ranges. Explains how to eliminate TRANSSTATE 106 results. Updates Index to include an alphabetical listing of all Payflow parameters cited in the guide. Adds new transaction type N.

Includes other minor edits for technical accuracy.

Payflow Pro Developer’s Guide 11

Revision History

12 Payflow Pro Developer’s Guide

Introduction

About Payflow Pro

Payflow Pro is a high performance TCP/IP-based internet payment solution that resides on your computer system. You can download it in the following forms from the SDKs and Downloads page on PayPal Developer Central:

z .NET library z Java library z HTTPS interface

Using the HTTPS interface, you can build your own API by posting directly to the Payflow servers via HTTPS.

NOTE:If you prefer to have Payflow Pro integration performed for you, you can obtain

Payflow Pro pre-integrated with leading e-commerce solutions. For a list of preintegrated solutions, see the Partner Solutions>Shopping Carts page on PayPal Developer Central.

Payflow Pro Documentation

Payflow Pro is described in the Payflow Pro documentation set on PayPal Developer Central. If you are implementing PayPal as a solution into your website, use this guide for general guidelines and guidelines on integrating credit card processing. If you are also implementing PayPal Express Checkout as a payment solution, see the Express Checkout for Payflow Pro guide for integration details.

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

How Payflow Pro Works

Payflow Pro uses a client/server architecture to transfer transaction data from you to the processing networks, and then returns the authorization results to you. Payflow Pro can process real-time credit card transactions and other transaction types to most of the financial processing centers in the United States.

Payflow Pro Developer’s Guide 13

Introduction

Supported Processing Platforms

1. The Payflow client encrypts each transaction request using the latest Secure Sockets Layer

(SSL) encryption and establishes a secure link with the Payflow server over the internet.

2. The Payflow server, a multi-threaded processing environment, receives the request and

transmits it (over a secure private network) to the appropriate financial processing network for real-time payment authorization.

3. The response (approved/declined, and so on) is received from the financial network and is

returned in the same session to the Payflow client.

4. The Payflow client completes each transaction session by transparently sending a

transaction receipt to the server before disconnecting the session.

The entire process is a real-time synchronous transaction. Once connected, the transaction is immediately processed and the answer returned in about three seconds. Processing transactions through the Payflow service does not affect or define the time periods of authorizations, nor does it influence the approval or denial of a transaction by the issuer.

When integrating with Payflow Pro, you need only be concerned with passing all the required data for transaction authorization. For transactions that you want to be settled (close batch), the operation is handled by PayPal.

Supported Processing Platforms

Payflow Pro supports the following processing platforms:

z PayPal z American Express Phoenix z American Express Brighton z First Data Merchant Services (FDMS) Nashville z First Data Merchant Services (FDMS) North z First Data Merchant Services (FDMS) South z First Data TeleCheck z Global Payments Central z Global Payments East z Merchant e-Solutions z Elavon (Formerly Nova) z Paymentech Salem (New Hampshire) z Paymentech Tampa z TSYS Acquiring Solutions (Formerly Vital Processing Services) z Moneris Solutions

14 Payflow Pro Developer’s Guide

Supported Payment Types

Payflow Pro supports multiple payment types in a single installation, including:

z Credit cards z PayPal (supported by PayPal’s Express Checkout product) z Pinless debit cards z Electronic checks z Check cards z Purchasing cards (also referred to as commercial cards, corporate cards, procurement

cards, or business cards) Level II and Level III

z Automated Clearing House (ACH). For information on performing ACH transactions,

contact your PayPal Sales Representative at paymentsales@PayPal.com

Introduction

Supported Payment Types

Payflow Pro Recurring Billing Service

The Recurring Billing Service is a scheduled payment solution that enables you to automatically bill your customers at regular intervals—for example, a monthly fee of $42 for 36 months with an initial fee of $129.

You enroll separately for the Payflow Pro Recurring Billing Service. Using Payflow Pro to define and manage recurring transactions programmatically is described in Payflow Pro – Recurring Billing Service User’s Guide. You can manage Recurring Billing tasks in PayPal Manager. See the online help for details.

About Security

It is your responsibility to protect your passwords and other confidential data and to implement security safeguards on your website and in your organization, or to ensure that your hosting company or internal web operations team is implementing them on your behalf.

IMPORTANT: To enable testing of Payflow Pro, PayPal pr ovides sample transaction scripts

that you customize with your Payflow Pro account information and password. Because the password is initially stored in the text of the program, it is vulnerable.

Do not use the test scripts in your production environment. To minimize fraud, machine passwords should always be encrypted. You must write a program that encrypts and decrypts your Payflow Pro account password.

Payflow Pro Developer’s Guide 15

Introduction

About Security

16 Payflow Pro Developer’s Guide

Downloading, Installing, and

Activating

The Payflow Software Development Kit (SDK) is a set of APIs to allow you to integrate 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 17

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

https://manager.paypal.com.

18 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 D, “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 20.

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 Payflow Pro documentation on Developer Central.

Website Payments Pro Payflow Edition Developer’s Guide 19

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 Connection para me ters

Parameter Description

HOSTADDRESS (Required) Payflow host name. See “Host Addresses” on page 13 fo r 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 val ues.

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 PARMLIST. 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 equal sign (=) characters have special meanings in the PARMLIST, name-value pairs like the following examples are not valid:

20 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 parame 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 21

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

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.

22 Website Payments Pro Payflow Edition Developer’s Guide

Credit Card Transactions

This chapter describes how to plan for implementing credit card processing, presents the core set of parameters used by all credit card processors, explains how to submit a transaction for each transaction type supported, and describes other credit card features such as card security.

Credit Card Features

Payflow Pro supports the following transaction types for credit card processing:

z Sale z Authorization (including Account Verification) z Voice Authorization z Delayed Capture z Credit z Void z Inquiry

Payflow Pro also supports the following credit card features:

z Recharging to the same credit card (also called reference transactions) z Securing credit card transactions by means of the Address Verification Service and card

security code validation

About Credit Card Processing

Credit card processing occurs in two steps — a real-time Authorization and a capture (settlement) of the funds that were authorized. As discussed below, you perform these two steps either as a single transaction or as two transactions, depending on your business model

For an Authorization, the server sends the transaction information to a credit card processor who routes the transaction through the financial networks 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 (discussed below), and returns a response: Approved, Declined, Referral, or other response values.

You receive the response a few seconds after you submit the transaction to the server. If an Authorization is approved, the bank temporarily reserves the credit for the amount of the transaction to prepare to capture (fulfill) the transaction. The hold on funds typically lasts for about a week.

Payflow Pro Developer’s Guide 23

Credit Card Transactions

About Credit Card Processing

NOTE:You cannot remove a hold on funds through the processing networks—you must

contact the card issuing bank to lift a hold early.

Capturing a transaction actually transfers the funds to your bank. At least once a day, PayPal gathers all transactions that are flagged to be settled and sends them in a batch file to the processor. The processor then char ges the issuing bank and transfers the funds to your bank. It typically takes a few days before the money is actually available in your account, depending on your bank.

Obtaining an Internet Merchant Account

T o accept credit cards over the internet, you need a special account called an Internet Merchant Account. Your account provider or merchant (acquiring) bank works with a PayPal-supported credit card processor, such as First Data, TSYS Acquiring Solutions (formerly Vital Processing Services), or Paymentech. T o use Payflow Pro to accept live cred it cards, you must provide certain details about your account to PayPal during the “Go Live” part of the enrollment process.

NOTE:An Internet Merchant Account is a different type of merchant account than a merchant

account used for face-to-face (in-person) retail transactions. It has additional risks associated with card-not-present (e-commerce) transactions. You need to obtain an Internet Merchant Account even if you already accept credit cards at your location.

To apply for an Internet Merchant Account, contact your merchant (acquiring) bank.

Planning Your Payflow Pro Integration

In designing your Payflow Pro integration, you should evaluate the following:

z Whether to use a one-step or two-step transaction process. One-step: Submit a Sale

transaction, which performs the Authorization and (if successful) then flags the transaction for settlement. T wo-step: P erform an Authorization-only transaction and then later perform a Delayed Capture transaction. The Delayed Capture transaction can be for the same amount as the original transaction or for a lower amount. (In the case of a split shipment, you can perform a Delayed Capture transaction for the initial shipment and a reference transaction for the final payment. These transaction types, plus the details of performing a Delayed Capture for an amount higher than the original, are described in “Delayed Capture

Transaction: Capturing Transactions for Higher Amounts” on page 32.

According to card association rules, most physical goods merchants should use a two-step process, since settlement should occur when the goods are fulfilled or shipped. A two-step process is also useful if you want to evaluate information in the response, such as whether the issuer verifies the billing address, and so on. Electronic goods merchants, who fulfill the order immediately, can use the one-step process. Check with your Internet Merchant Account provider for suggestions on the best method for you.

z Whether or how to use risk management tools such as address verification service and card

security code. For address verification service, if the data is submitted with the initial transaction, the issuer checks the street address and/or the zip (postal) code against the

24 Payflow Pro Developer’s Guide

Credit Card Transactions

About Credit Card Processing

billing address on file for the consumer. Address verification service is described on page

“Using Address Verification Service” on page 44.

Card security code refers to a 3- or 4-digit number that appears on the back of most credit cards. On American Express, the number appears above and to the right of the embossed card number. Card security code is known by other names, such as CVV2, depending on the type of card. If card security code data is submitted, the issuer can notify you whether the number matches the number assigned to the card. Card security code is described on page “Card Security Code Validation” on page 46.

It may also be possible to implement additional safeguards yourself or to use a fraud service. You might want to discuss risk management with your Internet Merchant Account provider.

z Store information in your local database or use PayPal Manager report s 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. You should also consider whether and how to use the merchant-defined fields COMMENT1 and COMMENT2 to help tie reports to your orders/customers or to report on other information about the transaction.

z If or how you want to integrate with other systems, such as order fulfillment, customer

service, and so on. You may wish to connect these systems directly to Payflow Pro for capturing funds, issuing refunds/credits, and so on. Alternatively, you may prefer to perform these steps manually using PayPal Manager. Either way, PayPal recommends that you monitor transaction activity using PayPal Manager.

z You may want to discuss, with your Internet Merchant Acquirer, practices that help you to

obtain the most advantageous rates.

Complying With the E-commerce Indicator (ECI)

Some processors support a software flag called E-commerce Indicator (ECI) that indicates that the associated transaction is an internet transaction. Payflow Pro complies with ECI basic requirements for all supported processors.

If you use the Buyer Authentication Service, then the ECI values reflects the Authentication status. See Payflow Pro Fraud Protection Servic e User’s Guide on Developer Central.

Handling Credit Card Type Information

The Payflow SDK does not check the credit card types that you are accepting. If a customer uses a card type that you are not signed up to accept, the Payflow SDK responds with RESULT value 23, “Invalid account number,” or the processor returns a message that the customer is not signed up for the card type. For details on RESULT values and response messages, see

“RESULT Values and RESPMSG Text” on page 56. Optionally, you can provide your

Payflow Pro Developer’s Guide 25

Credit Card Transactions

Parameters Used in Credit Card Transactions

customer with a list of the card types that you accept (in a drop-down list or menu, for example).

To accept additional credit card types, you must contact your acquiring bank (the merchant that holds your Internet Merchant Account) and ask them to add the card type to your acco unt. Upon notification from your Acquirer that you can start accepting the card type, you must add the card to your Payflow Pro account through PayPal Manager. See PayPal Manager online help for details.

Parameters Used in Credit Card Transactions

All credit card processors accept the basic parameters described in the table below with one exception: the PayPal processor does not support SWIPE.

Some processors require additional parameters described in the following sections:

z “Processors Requiring Additional Transaction Parameters” on page 65. z “Additional Reporting Parameters” on page 143

TABLE 4.1 Credit card transaction request p arameters

Parameter Description

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

z A = Automated clearinghouse z C = Credit card z D = Pinless debit z K = Telecheck z P = PayPal

See the Payflow ACH Payment Service Guide for details on the Automated clearinghouse tender type.

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 F = Voice Authorization z I = Inquiry 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.

26 Payflow Pro Developer’s Guide

Credit Card Transactions

Parameters Used in Credit Card Transactions

ABLE 4.1 Credit card transaction requ est parameters

Parameter Description

ACCT (Required for credit cards) Credit card or purchase card number. For the Pinless debit

TENDER type, ACCT can be the bank account number.

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

EXPDATE (Required) Expiration date of the credi t card.

Limitations: mmyy format. For example, 1008 represents N ovember 2008.

AMT (Required) Amount (Default: U.S. based currency).

Limitations: 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. Your processor and/or Internet Merchant Account provider may stipulate a maximum amount.

10 numeric characters plus decimal.

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

Limitations: 128 alphanumeric characters.

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

Limitations: 128 alphanumeric characters.

CVV2 (Optional) A code that is printed (not imprinted) on the back of a credit card. Used as

partial assurance that the card is in the buyer’s possession. Limitations: 3 or 4 digits.

FIRSTNAME (Optional) Account holder's first name.

Limitations: 30 alphanumeric characters.

LASTNAME (Optional but recommended) Account holder's last name.

Limitations: 30 alphanumeric characters.

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

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

ZIP (Optional) Account holder’s 5- to 9-digit zip (postal) code.

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

Payflow Pro Developer’s Guide 27

Credit Card Transactions

Submitting Sale Transactions

ABLE 4.1 Credit card transaction requ est parameters

Parameter Description

SWIPE (Required for card-pr esent transactions only) Used to pass the T rack 1 or Tr ack 2 data

(card’s magnetic stripe information) for card-present transactions. Include either Track 1 or Track 2 data—not both. If T rack 1 is physically damaged, the point-of-sale (POS) application can send Track 2 data inst ead .

The track data includes the disallowed = (equal sign) character. To enable you to use the data, the SWIPE parameter must include a length tag specifying the number of characters in the track data. For this reason, in addition to passing the track data, the POS application must count the characters in the track data and pass that number. Length tags are described in “Using Special Characters in Values” on page 20.

NOTE:SWIPE (card-present transactions) are not supported by the PayPal processor..

Limitations: Alphanumeric characters.

Submitting Sale Transactions

The Sale transaction (TRXTYPE=S) charges the specified amount against the account, and marks the transaction for immediate fund transfer during the next settlement period. PayPal submits each merchant’s transactions for settlement on a daily basis.

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

Additional Parameters For Sale Transactions

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

z ACCT z AMT z EXPDATE

NOTE:The pinless debit tender type requires essentially the same parameters as a credit card

transaction. In addition to the values required by all transactions, you must pass values for the ACCT and AMT parameters. The First Data Merchant Services (FDMS) South processing platform supports Sale and Credit transactions only.

28 Payflow Pro Developer’s Guide

Submitting Authorization/Delayed Capture Transactions

Typical Sale Transaction Parameter String

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

TRXTYPE=S&TENDER=C&USER=SuperU ser&PWD=SuperUserP assword&VENDOR=SuperU ser&PA RTNER=PayPal&ACCT=510510510510 5100&EXPDATE=1209& CVV2=123&AMT=99.00&FI RSTNAM E=John&LASTNAME=Smith&STREET=1 23 Main St.&CITY=San Jose&STATE=CA&ZIP=12345&COMMEN T1=Reservation&INV NUM=1234567890&PONUM= C12345 &CVV2=567&VERBOSITY=MEDIUM

Note that, besides the required parameters that you pass in a Sale transaction, this string includes other typical parameters. The COMMENT1 (and COMMENT2) fields help to track transaction information. The customer’s street address (STREET) and zip should be passed to use 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 “Submitting Card-Present (SWIPE) Transactions” on page 42 z “Card Security Code Validation” on page 46

Credit Card Transactions

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.

A Delayed Capture (TRXTYPE=D) transaction is performed after an Authorization to capture the original Authorization amount. The Delayed Capture is scheduled for settlement during the next settlement period.

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.

NOTE:If you signed up for the PayPal processor with Fraud Protection Services, you must use

delayed capture processing for all sale transactions.

If your business provides immediate fulfillment and you are not using the PayPal processor with Fraud Protection Services, you can use a simple Sale transaction instead. For details, see

“Submitting Sale Transactions” on page 28. 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 “Submitting Authorization/Delayed Capture

Transactions” on page 29.

Payflow Pro Developer’s Guide 29

Credit Card Transactions

Submitting Authorization/Delayed Capture Transactions

IMPORTANT: Only one Delayed Capture transaction is allowed per Authorization

transaction.

Required Authorization Transaction Parameters

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

z ACCT z AMT z EXPDATE

Typical Authorization 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=SuperU ser&PWD=SuperUserP assword&VENDOR=SuperU ser&PA RTNER=PayPal&ACCT=510510510510 5100&EXPDATE=1209& CVV2=123&AMT=99.00& FIRSTNAME=John&LASTNAME=Smith& STREET=123 Main St.&CITY=S an Jose &STATE=CA&ZIP=12345&COMMENT1=R eservation&INVNUM= 1234567890&PONUM=C123 45&CVV 2=567&VERBOSITY=MEDIUM

Required Delayed Capture Transaction Parameters

To perform a Delayed Capture transaction, you are required to pass the following parameter:

ORIGID

TABLE 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: 12 case-sensitive alphanumeric characters.

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

30 Payflow Pro Developer’s Guide

+ 146 hidden pages