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

Credit Card Transactions

Submitting Authorization/Delayed Capture Transactions

used. (Exceptions are ACCT, EXPDATE, and SWIPE. These parameters retain their original values.)

ABLE 4.3 Fields copied from Autho rizatio n to Delay ed Captu re transac tion

ACCT AMT CITY COMMENT1 COMMENT2 COMPANYNAME BILLTOCOUNTRY CUSTCODE CUSTIP DUTYAM T EMAIL EXPDATE FIRSTNAME MIDDLENAME LASTNAME FREIGHTAMT INVNUM PONUM SHIPTOCITY SHIPTOCOUNTRY SHIPTOFIRSTNAME SHIPTOMIDDLENAME SHIPTOLASTNAME SHIPTOSTATE SHIPTOSTREET SHIPTOZIP STATE STREE T SWIPE TAXAMT PHONENUM TAXEXEMPT 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&PWD=x1y2z3& PARTNER=PayPal&VEN DOR=SuperMerchant&USE R=S uperMerchant&ACCT=555555555555 4444&EXPDATE=0308& AMT=123.00&COMMENT1=S eco nd purchase&COMMENT2=Low risk customer &INVNUM=123456789&STR EET=5199 MAPLE&ZIP=94588

Example:Authorization Response

RESULT=0&PNREF=VXYZ01234567&RE SPMSG=APPROVED&AUTHCO DE=123456 &AVSADDR=Y&AVSZIP=N

Payflow Pro Developer’s Guide 31

Credit Card Transactions

Submitting Account Verifications With TRXTYPE=A

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&PWD=x1y2z3& PARTNER=PayPal&VEN DOR=.SuperMerchant &USER=SuperMerchant&ORIGID=VXY Z00887892

Example:Delayed Capture Response

RESULT=0&PNREF=VXYZ00895642&AU THCODE=25TEST&AVSA DDR=Y&AVSZIP=N

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

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 Account Verifications With TRXTYPE=A

Account Verification, also known as zero dollar Authorization (TRXTYPE=A), verifies credit card information. While Account Verification and normal Authorization transactions are submitted using TRXTYPE=A, Account Verification differs from Authorization in the following ways:

z The AMT value is always 0. If any other amount is submitted, the transaction as a normal

Authorization that places a hold on the cardholder’s open-to-buy limit.

z Although the RESULT value returned is 0 (Approved), the RESPMSG value is Verified

instead of Approved.

32 Payflow Pro Developer’s Guide

z The TRANSSTATE is set to 0 to prevent these types of transactions from being credited,

voided, or captured. See “VERBOSITY: Viewing Processor-Specific Transaction Results” on page 139 for

details on TRANSSTATE.

NOTE:RESULT value 4, Invalid Amount, is returned if the processor does not support

Account Verifications.

When To Use Account Verification

Use an Account Verification to validate account numbers and other authentication elements such as CVV2 and AVS. You can also use an Account Verification as a Reference T ransaction. See “Recharging to the Same Credit Card (Reference Transactions)” on page 40.

Example Account Verification

This is an example of account verification:

Credit Card Transactions

Submitting Voice Authorization Transactions

TRXTYPE=A&TENDER=C&USER=SuperUser&PWD=S uperUserPassword&VENDOR=Super User&PARTNER=PayPal&ACCT=41111111111111 11&EXPDATE=0712&CVV2=123&AMT=

0.00&CURRENCY=USD&STREET=123 Main St.&ZIP=112 32&VERBOSITY=MEDIUM

This is the response:

RESULT=0&PNREF=V79E1E4610CE&RESPMSG=Ver ified&AUTHCODE=010101&AVSADDR =Y&AVSZIP=Y&CVV2MATCH=Y&HOSTCODE=00&PRO CAVS=Y&PROCCVV2=M&IAVS=N

Submitting Voice Authorization Transactions

A Voice Authorization (TRXTYPE=F) transaction is a transaction that is authorized over the telephone from the processing network.

NOTE:The PayPal processor does not support Voice Authorization transactions.

When to Use a Voice Authorization Transaction

Some transactions cannot be authorized over the internet (for example, high dollar amounts) and require manual authorization. These transactions generate RESULT value 13 and are called Referral transactions.

In these situations, you contact the customer service department of your merchant bank and provide the payment information as requested. If the transaction is approved, the bank provides you with a voice Authorization code (AUTHCODE) for the transaction..

Once a Voice Authorization transaction has been approved, it is treated like a Sale transaction and is settled with no further action on your part.

Payflow Pro Developer’s Guide 33

Credit Card Transactions

Submitting Credit Transactions

Like Sale transactions, approved Voice Authorization transactions can be voided before settlement occurs.

Required Voice Authorization Transaction Parameters

When sending a Voice Authorization transaction request, you are required to include the AUTHCODE provided by your merchant bank.

TABLE 4.4 Voice Authorization transaction required parameter

Parameter Description

AUTHCODE (Required for Voice Authorization s only) Returned only for approved Voice

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

Limitations: Six alphanumeric characters.

The following is an example Voice Authorization transaction request parameter string:

TRXTYPE=F&TENDER=C&PARTNER=Pay Pal&VENDOR=SuperMe rchant&USER=SuperMerc hant&P WD=x1y2z3&AUTHCODE=AB34RT56&AC CT=5555555555554444&E XPDATE=0308&AMT=12 3.00

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

34 Payflow Pro Developer’s Guide

Credit Card Transactions

Submitting Credit Transactions

ORIGID

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

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

NOTE:These fields are not copied for referenced credits: TAXAMT, TAXEXEMPT, DUTYAMT,

FREIGHTAMT, and (for American Express only) DESC4.

NOTE:For processors that use the RECURRING parameter: If the RECURRING parameter was

set to Y for the original transaction, then the setting is ignored when forming the Credit transaction.

ABLE 4.6 Fields copied from original to Credit trans action

ACCT AMT CITY COMMENT1

Payflow Pro Developer’s Guide 35

Credit Card Transactions

Submitting Void Transactions

ABLE 4.6 Fields copied from original to Credit trans action

COMMENT2 COMPANYNAME BILLTOCOUNTRY CUSTCODE CUSTIP EMAIL EXPDATE FIRSTNAME MIDDLENAME LASTNAME INVNUM PONUM SHIPTOCITY SHIPTOCOUNTRY SHIPTOFIRSTNAME SHIPTOMIDDLENAME SHIPTOLASTNAME SHIPTOSTREET SHIPTOSTATE SHIPTOZIP STATE STREET SWIPE PHONENUM ZIP

Credit Transaction Parameter Strings

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

TRXTYPE=C&TENDER=C&PARTNER=Pay Pal&VENDOR=SuperMe rchant&USER=SuperMerc hant&P WD=x1y2z3&ORIGID=VPNE12564395

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

TRXTYPE=C&TENDER=C&PARTNER=Pay Pal&VENDOR=SuperMe rchant&USER=SuperMerc hant&P WD=x1y2z3&ACCT=555555555555444 4&EXPDATE=0308&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 if the processor supports it for a given card type. Because the honoring of authorization reversals is ultimately decided by the bank or issuer, there is no accurate way to determine if an individual bank or issuer has honored an authorization reversal request.

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 can void Delayed Capture, Sale, Credit, Authorization, and Voice Authorization

transactions. You cann ot 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.

36 Payflow Pro Developer’s Guide

Credit Card Transactions

Submitting Void Transactions

Required Void Transaction Parameters

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

ORIGID

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

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

NOTE:For processors that use the RECURRING parameter: If the RECURRING parameter was

set to Y for the original transaction, then the setting is ignored when forming the Void transaction.

ABLE 4.8 Fields copied from orig inal Void transaction

Example Void Transaction Parameter String

This is an example Void transaction parameter string:

Payflow Pro Developer’s Guide 37

Credit Card Transactions

Submitting Inquiry Transactions

“TRXTYPE=V&TENDER=C&PARTNER=Pa yPal&VENDOR=SuperM erchant&USER=SuperMer chant& PWD=x1y2z3&ORIGID=VPNE12564395 ”

Submitting Inquiry Transactions

An Inquiry transaction (TRXTYPE=I) returns the result and status of a transaction.

When To Use an Inquiry Transaction

You perform an inquiry using a reference to an original transaction—either the PNREF value returned for the original transaction or the CUSTREF value that you specified for the original transaction.

While the amount of information returned in an Inquiry transaction depends upon the VERBOSITY setting, Inquiry responses mimic the verbosity level of the original transaction as much as possible. For details on VERBOSITY, see “VERBOSITY: Viewing Processor -Specific

Transaction Results” on page 137.

Required Parameters When Using the PNREF

To submit an Inquiry transaction when using the PNREF, you must pass the following parameter:

ORIGID

ABLE 4.9 Inquiry request required parameter when using the PNREF

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

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

Inquiry Transaction Parameter Strin g Using the PNREF

This is an example Inquiry transaction parameter string using the ORIGID parameter set to the PNREF value:

TRXTYPE=I&TENDER=C&PARTNER=Pay Pal&VENDOR=SuperMe rchant &USER=SuperMerchant&PWD=x1y2z3 &ORIGID=VPNE125643 95

38 Payflow Pro Developer’s Guide

Credit Card Transactions

Submitting Inquiry Transactions

Required Parameters When Using the CUSTREF

To submit an Inquiry transaction when using the CUSTREF, you must pass the following parameter:

CUSTREF

Optionally , specify the STARTTIME and ENDTI ME parameters. The Inquiry transaction request parameters are described below.

TABLE 4.10 Inquiry transa ction re quest p arameters when using the CUSTREF

Parameter Description

CUSTREF (Required) Merchant-defined identifier for reporting and auditing purposes. Fo r

example, you can set CUSTREF to the invoice number. You can use CUSTREF when performing Inquiry transactions. To ensure that you

can always access the correct transaction when performing an Inquiry , you must provide a unique CUSTREF when submitting any transaction, including retries.

Limitations: 12 alphanumeric characters.

STARTTIME (Optional) For Inquiry transactions when using CUSTREF to specify the

transaction. ENDTIME specifies the end of the time period during which the transaction

specified by the CUSTREF occurred. See STARTTIME. ENDTIME must be less than 30 days after STARTTIM E. An inquiry cannot be

performed across a date range greater than 30 days. If you set ENDTIME, and not STARTTIME, then STARTTIME is defaulted to 30 days

before ENDTIME. If neither STARTTIME nor ENDTIME is specified, then the system searches the last

30 days. Limitations: 14 numeric characters in the format yyyymmddhhmmss.

ENDTIME (Optional) For Inquiry transactions when using CUSTREF to specify the

transaction. ENDTIME specifies the end of the time period during which the transaction

specified by the CUSTREF occurred. See STARTTIME. Limitations: 14 numeric characters.

IMPORTANT: If there are multiple transactions with a particular CUSTREF value, then the

Inquiry transaction returns only the last transaction with the specified CUSTREF. So, to ensure that you can always access the correct transaction, you must use a unique CUSTREF when submitting any transaction, including retries.

Inquiry Transaction Parameter String Using the CUSTREF

This is an example Inquiry transaction parameter string using the CUSTREF:

Payflow Pro Developer’s Guide 39

Credit Card Transactions

Recharging to the Same Credit Card (Reference Transactions)

TRXTYPE=I&TENDER=C&PARTNER=Pay Pal&VENDOR=SuperMe rchant&USER=SuperMerc hant&P WD=x1y2z3&CUSTREF=Inv00012345

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.

NOTE:The PNREF returned in the original transaction is valid for use in reference transactions

for a period of 12 months. A PNREF returned by Account Verification also can be used in a reference transaction.

When To Use a Referen ce 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 Authorization 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 Protection Services 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.

40 Payflow Pro Developer’s Guide

Credit Card Transactions

Recharging to the Same Credit Card (Referen ce Transactions)

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 Authorization (To capture the funds for an approved Authorization transaction, be sure to

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

z Credit z Delayed Capture z Sale z Voice Authorization (The Voice Authorization code is not copied to the new transaction) z Void

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.

TABLE 4.11 Fields copied from refere nce tra nsaction s

ACCTTYPE STREET ACCT CITY EXPDATE STATE FIRSTNAME ZIP MIDDLENAME BILLTOCOUNTRY LASTNAME SWIPE

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:

Payflow Pro Developer’s Guide 41

Credit Card Transactions

Submitting Card-Present (SWIPE) Transactions

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

You use an Authorization transaction for the full amount of the purchase of $100 as shown in this transaction request:

TRXTYPE=A&TENDER=C&PWD=x1y2z3& PARTNER=PayPal&VEN DOR=SuperMerchant&USE R=S uperMerchant&ACCT=555555555555 4444&EXPDATE=0308& AMT=100.00&INVNUM=123 456 789&STREET=5199 MAPLE&ZIP=9458 8

Note the value of the PNREF in the response:

RESULT=0&PNREF=VXYZ01234567&RE SPMSG=APPROVED&AUTHCO DE=123456&AVSADDR= Y&A VSZIP=N

NOTE:The PNREF returned in the original transaction is valid for use in reference

transactions for a period of 12 months.

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 as in this transaction request (See “Required Delayed Capture Transaction

Parameters” on page 30):

TRXTYPE=D&TENDER=C&PWD=x1y2z3& PARTNER=PayPal&VEN DOR=SuperMerchant&USE R=S uperMerchant&ORIGID=VXYZ012345 67&AMT=66.00

This is the response:

RESULT=0&PNREF=VXYZ01234568&AU THCODE=25TEST&AVSA DDR=Y&AVSZIP=N

3. Submit a new Sale transaction or Authorization/Delayed Capture tr ansaction 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. (This is a Sale transaction because only one Delayed Capture transaction is allowed per Authorization.) This is the Sale transaction request:

TRXTYPE=S&TENDER=C&PWD=x1y2z3& PARTNER=PayPal&VEN DOR=SuperMerchant&USE R=S uperMerchant&ORIGID=VXYZ012345 67&AMT=34.00

This is the response:

RESULT=0&PNREF=VXYZ01234569&AU THCODE=25TEST&AVSA DDR=Y&AVSZIP=N

Submitting Card-Present (SWIPE) Transactions

Payflow Pro supports card-present transactions (face-to-face purchases).

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

Follow these guidelines to take advantage of the lower card-present transaction rate:

z Contact your merchant account provider to ensure that they support card-present

transactions.

z Contact PayPal Customer Service to request having your account set up properly for

accepting and passing swipe data.

42 Payflow Pro Developer’s Guide

z If you plan to process card-present as well as card-not-present transactions, set up two

separate Payflow Pro accounts. Request that one account be set up for card-present transactions, and use it solely for that purpose. Use the other for card-not-present transactions. Using the wrong account may result in downgrades.

z A Sale is the preferred method to use for card-present transactions. Consult

with your acquiring bank for recommendations on other methods.

Supported Processing Platforms

PayPal is certified to submit card-present transactions for the following processing platforms:

z American Express Phoenix z First Data Merchant Services (FDMS) Nashville z First Data Merchant Services (FDMS) North z First Data Merchant Services (FDMS) South z Global Payments Central z Global Payments East

Credit Card Transactions

Submitting Card-Present (SWIPE) Transactions

z Merchant e-Solutions z Elavon (Formerly Nova) z Paymentech Salem (New Hampshire) z Paymentech Tampa z TSYS Acquiring Solutions

Card-present Transaction Syntax

Use the SWIPE parameter to pass the Track 1 or Track 2 data (the card’s magnetic stripe information). Include either Track 1 or Track 2 data—not both (up to 80 alphanumeric characters). If Track 1 is physically damaged, the POS application can send Track 2 data instead.

“Using Special Characters in Values” on page 20. The length tag in the following example is

[40]. Do not include the ACCT or EXPDATE parameters in card-present transactions, as this data is

included in the SWIPE value. This is an example card-present transaction parameter string:

“TRXTYPE=S&TENDER=C&PARTNER=Pa yPal&USER=SuperMer chant&PWD=SuperMercha nt&SWI PE[40]=;4912000033330026=15121 011000012345678?&A MT=21.00”

Payflow Pro Developer’s Guide 43

Credit Card Transactions

Submitting Purchasing Card Transactions

A purchasing card (also referred to as a commercial card, co rporat e card , procure men t card or business card) is a credit card that is issued at the request of an employer . It is usually reserved for business-related charges. The card issuer provides specialized reporting for this card type so the employer can monitor the use of the card. There is no method for determining whether a card is a purchase card or a commercial card based on the card number.

To obtain the best bank interchange rates for commercial cards, you must pass specific additional transaction information. Commercial card support and parameters vary from processor to processor. See“Submitting Purchasing Card Level 2 and Level 3 T ransactions” on

page 97.

NOTE:Purchasing card transactions are not supported by the PayPal processor.

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 =nomatch, 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 verification service is supported by most US 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 verification service (IAVS) response indicates whether address verification service response is international (Y), USA (N), or cannot be determined (X).

Processing Platforms Supporting Address Verification Service

TABLE 4.12 Processing plat forms supportin g Address Verification Service

American

Processing Platform

American Express Phoenix X — — —

44 Payflow Pro Developer’s Guide

Express Discover Master Card Visa

Credit Card Transactions

Example Address Verification Service Request Parameter List

ABLE 4.12 Processing plat forms suppo rting Address Verification Service

American

Processing Platform

American Express Brighton X — — — FDMS Nashville X X X X FDMS North X X X X FDMS South X X X X Global Payments Central X X X X Global Payments East X X X X Merchant e-Solutions X X X X Elavon (formerly Nova) X X X X

Express Discover Master Card Visa

Paymentech Salem (New Hampshire)

Paymentech Tampa X X X X TSYS Acquiring Solutions

(formerly Vital Processing Services)

XXXX

See your processor’s information in “Processors Requiring Additional Transaction

Parameters” on page 65 for information on their handling of address verification service.

Example Address Verification Service Request Parameter List

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

TRXTYPE=A&TENDER=C&PWD=x1y2z3& PARTNER=PayPal&VEN DOR=SuperMerchant&USE R=Supe rMerchant&&ACCT=55555555555544 44&EXPDATE=0308&AM T=123.00

Maple

&ZIP=98 765

&STREET= 5199

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 AVSZIP response is N.

RESULT=0&PNREF=VXW412345678&RE SPMSG=APPROVED&AUT HCODE=123456&AVSADDR= Y&AVSZ IP=N&IAVS=X

Payflow Pro Developer’s Guide 45

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.

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.

FIGURE 4.1 Card secu rity cod e

Processing Platforms and Credit Cards Supporting Card Security Code

NOTE:You need to contact American Express to be set up to accept their CID card security

code.

TABLE 4.13 Processing platforms supporting card security code

American

Processing Platform

American Express Phoenix X — — — American Express Brighton X — — —

Express Discover Master Card Visa

FDMS Nashville X X X X FDMS North X X X X

46 Payflow Pro Developer’s Guide

ABLE 4.13 Processing platforms supporting card security code

American

Processing Platform

Express Discover Master Card Visa

FDMS South X X X X Global Payments Central X X X X Global Payments East X X X X Merchant e-Solutions X X X X Elavon (formerly Nova) X X X X

Credit Card Transactions

Card Security Code Validation

Paymentech Salem (New

XXXX

Hampshire) Paymentech Tampa X X X X TSYS Acquiring Solutions

XXXX (formerly Vital Processing Services)

Payflow Pro Developer’s Guide 47

Credit Card Transactions

Card Security Code Validation

48 Payflow Pro Developer’s Guide

Credit Card Testing

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

“Host Addresses” on page 13. Transactions directed to this 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

The following are 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 5.1 Test credit card numbers

American Express 378282246310005 American Express 371449635398431 American Express Corporate 378734493671000 Diners Club 30569309025904 Diners Club 38520000023237 Discover 6011111111111117 Discover 6011000990139424 JCB 3530111333300000 JCB 3566002020360505 MasterCard 5555555555554444

Payflow Pro Developer’s Guide 49

Credit Card Testing

Result Values in Responses

ABLE 5.1 Test credit card numbers

MasterCard 5105105105105100 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.

Result Values in Responses

This section describes the result value responses that you receive.

Testing Result Values in Responses

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

ABLE 5.2 Results generated by the amount submitted

Amount Result

$0 – $1000 RESULT value 0 (Approved) $1001 – $2000 Certain amounts in this range will return specific PayPal results, and can be generated

by adding $1000 to that RESULT value. For example, for RESULT value 13 (Referral), submit the amount 1013.

If the amount is in this range but does not correspond to a PayPal result supported by this testing mechanism, RESULT value 12 (Declined) is returned

$2001+ RESULT value 12 (Declined)

RESULT Values Returned Based on Transaction Amount

This table lists the RESULT values that you can generate using the amount of the transaction. To generate a specific code, submit an amount of 1000 plus the code number (for example, submit an amount of 1013 for a result code of 13).

ABLE 5.3 Result values supporting the amount con trol

Processing Platform RESULT Values Available for Testing

American Express Phoenix American Express Brighton

50 Payflow Pro Developer’s Guide

0, 12, 13, 104, 1000

Credit Card Testing

RESULT Values Returned Based on Transaction Amount

ABLE 5.3 Result values supporting the amount con trol

Processing Platform RESULT Values Available for Testing

Elavon (Formerly Nova) 0, 12, 13, 104 First Data Merchant Services Nashville 0, 12, 13, 104 First Data Merchant Services North 0, 4, 5, 12, 13, 23, 24,114, 1000 First Data Merchant Services South 0, 12, 13, 104 Global Payments Central 0, 4, 5, 8, 12, 13, 23, 24, 104, 111, 114, 1000 Global Payments East 0, 4, 5, 12, 13, 23, 24, 30, 100, 104, 114, 1000 Paymentech Salem (New Hampshire) 0, 12, 13, 104 Paymentech Tampa 0, 3, 4, 5, 12, 13, 23, 24, 1000 TSYS Acquiring Solutions (Formerly Vital Processing

Services)

0, 4, 12, 13, 23, 104, 114, 1000

Alternative Methods for Generating Specific RESULT Values

The table below shows another method for obtaining RESULT values. Non-zero RESULT values from processors are not returned by the servers, and therefore cannot be simulated using the amount. In some cases, you may get certain results using the RESULT value plus 1000 even though this table suggests another means of obtaining the RESULT value.

ABLE 5.4 Obtaining RESULT value

RESULT Definition How to test using Payflow Pro

0 Approved Use an AMOUNT of $1000 or less

For all Processors except Global Payments Central (MAPP) and FDI Credit (C) and Force (F) transactions will always be approved

regardless of dollar amount or card number 1 User authentication failed Use an invalid PWD 2 Invalid tender Use an invalid TENDER, such as G 3 Invalid transaction type Use an invalid TRXTYPE, such as G 4 Invalid amount Use an invalid AMOUNT, such as –1 5 Invalid merchant

information 7 Field format error Submit a Delayed Capture transaction with no ORIGID 12 Declined Use the AMOUNT 1012 or an AMOUNT of 2001 or more 13 Referral Use the AMOUNT 1013

Payflow Pro Developer’s Guide 51

Use the AMOUNT 1005 - Applies only to the following processors: Global Payments East and Central, and American Express

Credit Card Testing

RESULT Values Returned Base d on Transaction Amount

ABLE 5.4 Obtaining RESULT value

RESULT Definition How to test using Payflow Pro

19 Original transaction ID not

Submit a Delayed Capture transaction with an invalid ORIGID

found 22 Invalid ABA number Applies only to ACH transactions – submit an invalid ABA number

(8 digits)

23 Invalid account number Submit an invalid account number, for example,

000000000000000

24 Invalid expiration date Subm it an invalid expiration date, for example, 0298 25 Transaction type not

mapped to this host

(Processor)

Submit a transaction for a card or tender you are not currently set up to accept, for example, a Diners card if you aren’t set up to accept

Diners 29 Invalid XML document Pass a bad XML document (XMLPay users only) 30 Duplicate Transaction Use the AMOUNT 1030 - Only applies to Global Payments East and

Central processors 50 Insufficient funds available Use the AMOUNT 1050 - Only applies to Paymentech 99 General error Use the 100 Invalid transaction returned

from host (Processor)

Use the AMOUNT 1100. Only applies to Global Payments East and

Central

AMOUNT 1099 - Only applies to Global Payments East

101 Time-out value too small Set timeout value to 1 103 Error reading response from

Use the AMOUNT 1103

host (Processor)

104 Timeout waiting for

Use the AMOUNT 1104

processor response 105 Credit error Attempt to credit an authorization 108 Void error Attempt to void a captured authorization 111 Capture error Capture an Authorization transaction twice or attempt to capture a

transaction that is not an Authorization transaction

112 Failed AVS check You cannot generate this RESULT value by subm itting an amount of

1112, but must submit a value for Address Verification Servicethat will fail In production, this error occurs only if your account is configured by PayPal customer service to use the “AVS Deny”

feature 113 Cannot exceed sales cap Applies to ACH transactions only 114 CVV2 Mismatch Use the AMOUNT 1114. Only applies to TSYS Acquiring Solutions,

Merchant e-Solutions, and Global Payments East and Central

processors

52 Payflow Pro Developer’s Guide

Testing Address Verification Service

ABLE 5.4 Obtaining RESULT value

RESULT Definition How to test using Payflow Pro

Credit Card Testing

1000 Generic Host (Processor)

Error

Use the AMOUNT 2000 - Does not apply to Elavon (formerly Nova),

American Express, or Global Payments East processors

Testing Address Verification Service

The Payflow testing server simulates Address Verification Service by returning a value for

AVSADDR based on the first three characters of the submitted value for STREET.

The testing server returns a value for AVSZIP based on the submitted ZIP value as shown in the table.

If STREET starts with 667 or higher or begin s with a non-numeric character, then the simulator returns AVSADDR=X, AVSZIP=X.

ABLE 5.5 Testing AVSADDR

Submitted Value for STREET Example STREET Value AVSADDR Result

000-333 24285 Elm Y 334-666 49354 Main N 667 or higher or begins with a non-numeric

character

79232 Maple X

ABLE 5.6 Testing AVSZIP

Submitted Value for ZIP Example ZIP Value AVSZIP Result

00000-50000 00382 Y 50001-99999 94303 N

Any value (if street address is 667 or higher or begins with a non-numeric character)

STREET=79232 Maple, ZIP=20304 X

Testing Card Security Code

If you submit a value for the card security code, the cardholder’s bank returns a Yes / No / Not Supported (Y / N / X) response on whether the value matches the number on file at the bank. Card security code is described in “Card Security Code Validation” on

page 46.

NOTE:Some processors will decline (RESULT value 12) a transaction if the card security code

does not match without returning a CVV2MATCH value. Test the results and check with your processor to determine whether they support card security code checking.

Payflow Pro Developer’s Guide 53

Credit Card Testing

Testing Address Verification Service

For the testing server, the first thre e ch aracters of the CVV2 value determine the CVV2MATCH result, as shown here.

TABLE 5.7 Testing CVV2MATCH

CVV2 Value CVV2MATCH Value

000 Y 001-300 Y 301-600 N 601 or higher X

54 Payflow Pro 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 6.8 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.

NOTE:For Account Verification transactions, RESULT=0 with

RESPMSG=Verified means a zero dollar authorization has been

successfully performed.

Any other value for RESULT indicates a decline or error. 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)

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:For Account Verification transactions, RESULT=0 with

RESPMSG=Verified means a zero dollar authorization has been

successfully performed.

Character length and limitations: variable, alphanumeric characters

Website Payments Pro Payflow Edition Developer’s Guide 55

Responses to Transaction Requests

Contents of a Response to a Credit Card Transaction Request

ABLE 6.8 Transaction response values

Field Description

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 Verification 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 international (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

CORRELATIONID Value used for tracking this Direct Payment transaction.

Character length and limitations: 13 alphanumeric characters

AMEXID

Unique transaction ID returned when VERBOSITY=MEDIUM or VERBOSITY=HIGH for tracking American Express CAPN transactions.

NOTE:American Express CAPN transactions only: used by merchants

who authorize transactions through the payflow gateway but settle through a third-party solution.

Character length and limitations: 15 numeric characters

56 Website Payments Pro Payflow Edition Developer’s Guide

Responses to Transaction Requests

BALAMT Response Parameter and Stored Value Cards

ABLE 6.8 Transaction response values

Field Description

AMEXPOSDATA Value returned when VERBOSITY=MEDIUM or VERBOSITY=HIGH..

Character length and limitations: 12 alphanumeic characters

BALAMT Response Parameter and Stored Value Cards

BALAMT is a parameter that may be returned by transactions meeting Card Acceptance Processing Network (CAPN) requirements when that transaction involves a stored value card. Stored value cards typically are offered as “gif t” cards, allowing the user to spend any amount up to the balance remaining on the card. BALAMT returns the ba lance on the card provided that the card is active and is not compromised. If the card is used to purchase merchandise exceeding the card balance, American Express declines the transaction and returns the card balance in BALAMT.

For details on American Express CAPN request transaction parameters, see Appendix C,

“Submitting Purchasing Card Level 2 and Level 3 Transactions.”

American Express CAPN Stored Value Card Example

The Authorization request is for a purchase of 123.00.

TRXTYPE=A&TENDER=C&PWD=x1y2z3& PARTNER=PayPal&VEN DOR=SuperMerchant&USE R=Supe rMerchant&ACCT=555555555555444 4&EXPDATE=0308&AMT =123.00&STREET=5199 MAPLE&ZIP=94588

Because the response returns a BALAMT of 99.00, the Authorization is declined.

RESULT=12&PNREF=VXYZ01234567&R ESPMSG=DECLINED&BA LANCE=99.00&AVSADDR=Y &AVSZI P=N

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

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.

Website Payments Pro Payflow Edition Developer’s Guide 57

Responses to Transaction Requests

RESULT Values and RESPMSG Text

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.

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.

NOTE:For Account Verification transactions, RESULT=0 with RESPMSG=Verified

means a zero dollar authorization has been successfully performed.

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.

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.

TABLE 6.9 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.

58 Website Payments Pro Payflow Edition Developer’s Guide

Responses to Transaction Requests

RESULT Values and RESPMSG Text

ABLE 6.9 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, VENDOR, 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 59

Responses to Transaction Requests

RESULT Values and RESPMSG Text

ABLE 6.9 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 Discove r

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 P ASSWORD 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

60 Website Payments Pro Payflow Edition Developer’s Guide

Responses to Transaction Requests

RESULT Values and RESPMSG Text

ABLE 6.9 Payflow Transaction RESULT Values and RESPMSG Text

RESULT RESPMSG and Explanation

104 Timeout waiting for processor response. Try your transaction again. 105 Credit error. Make sure you have not already credited this transacti on, or th at 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 la ter 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 61

Responses to Transaction Requests

RESULT Values and RESPMSG Text

ABLE 6.9 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

62 Website Payments Pro Payflow Edition Developer’s Guide

Responses to Transaction Requests

RESULT Values and RESPMSG Text

ABLE 6.9 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 received. 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 63

Responses to Transaction Requests

RESULT Values and RESPMSG Text

ABLE 6.9 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 Authentication transaction

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.

For information on firewall configuration, see Chapter 2, “Downloading, Installing, and

Activating.”

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

ABLE 6.10 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

64 Website Payments Pro Payflow Edition Developer’s Guide

Responses to Transaction Requests

RESULT Values and RESPMSG Text

ABLE 6.10 Communications RESULT values

RESULT Description

-21 Proxy write failed

-22 Failed to initia lize SSL certificate

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

Responses to Transaction Requests

RESULT Values and RESPMSG Text

66 Website Payments Pro Payflow Edition Developer’s Guide

Processors Requiring Additional Transaction Parameters

This appendix lists both required and optional parameters supplementary to the common parameter set.

In this Appendix

z “American Express” on page 67 z “First Data Merchant Services (FDMS) Nashville” on page 76 z “First Data Merchant Services (FDMS) South” on page 77 z “First Data Merchant Services (FDMS) North” on page 77 z “Elavon (Formerly Nova)” on page 79 z “Paymentech” on page 79 z “TSYS Acquiring Solutions” on page 83

American Express

In addition to the parameters in Table 4.1 , “Credit card transaction request parameters,” American Express accepts the parameters described in this section. Parameters to meet American Express Card Acceptance and Processing Network (CAPN) requirements are described in Table A.1. American Express (legacy) platform parameters are described in

Table A.2.

Payflow Pro Developer’s Guide 67

Processors Requiring Additional Transaction Parameters

American Express

American Express Additional Credit Card Parameters (CAPN)

NOTE:You should start coding to the CAPN parameters if you want to be able to impact what

appears on AMEX statements and reports. With a few exceptions, most merchants in the United States follow CAPN requirements; international merchants do not. If you are not sure whether you should make the coding changes, contact Customer Service. See “How to Contact Customer Support” on page 9 for contact information.

American Express Phoenix accepts the following parameters to meet CAPN requirements.

TABLE A.1 American Express CAPN parameters

Parameter Description Required Type Length

Retail Transaction Advice Addendum Parameters (for SWIPE transactions)

L_DESCn Description of this line-item (n is a line item

number from 1 to 6)

L_AMTn Amount of this line-item (n is a line item number

from 1 to 6) Must include a decimal and be exact to the cent

(42.00, not 42) and exclude comma separators (1234.56 not 1,234.56)

Examples: tip=3.00, convenience charge=2.00

L_QTYn Quantity of this line-item (n is a line item number

from 1 to 6)

Internet Transaction Data Parameters

EMAIL Account holder’s email address No Alpha-

PHONENUM Account holder’s telephone number No String 20 PHONETYPE Telephone company provided ANI information

identifier digits indicating the telephone call type Examples: cellular (61-63), payphone (27)

CUSTHOSTNAME Name of the server that the account holder is

connected to Example: PHX.QW.AOL.COM

No Alpha-

numeric

No Numeric 12

No Numeric 3

numeric

No Alpha-

numeric

No Alpha-

numeric and special characters

CUSTBROWSER Account holder’s HTTP browser type

Example:

MOZILLA/4.0~(COMPATIBLE;~MSIE ~5.0;~W INDOWS~95)

No Alpha-

numeric and special characters

68 Payflow Pro Developer’s Guide

Processors Requiring Additional Transaction Parameters

American Express

ABLE A.1 American Express CAPN parameters (Continued)

Parameter Description Required Type Length

CUSTIP Account holder’s IP address No Alpha-

numeric and special characters

SHIPTOCOUNTRY Numeric country code of ship-to country

Example: USA: 840

SHIPMETHOD Shipping method code. The values are:

01 = Same day 02 = Overnight/next day 03 = Priority, 2 - 3 days 04 = Ground, 4 or more days 05 = Electronic delivery 06 - ZZ = Reserved for future use

SKU Merchant product SKU No Alpha-

AVS Parameters

STREET Account holder’s street address (number and street

name)

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

excluding spaces, dashes, and non-numeric characters

Example: 951121737

No Alpha-

numeric

No Alpha-

numeric

No Alpha-

numeric

No String 9

PHONENUM Account holder’s telephone number. The formats

are

xxx-xxx-xxxx (US numbers) +xxxxxxxxxxx (international numbers)

SHIPTOFIRSTNAME First name in the shipping address No Alpha-

SHIPTOLASTNAME Last name in the shipping address No Alpha-

SHIPTOSTREET Shipping street address No Alpha-

SHIPTOCOUNTRY Numeric country code

Example: USA: 840

Payflow Pro Developer’s Guide 69

No String 20

numeric

No Alpha-

numeric

Processors Requiring Additional Transaction Parameters

American Express

ABLE A.1 American Express CAPN parameters (Continued)

Parameter Description Required Type Length

SHIPTOZIP Shipping 5- to 9-digit ZIP (postal) code excluding

spaces, dashes, and non-numeric characters Example: 951121737

SHIPTOPHONENUM Shipping telephone number No String 10 RECURRING Identifies the transaction as recurring. This value

does not activate PayPal’s Recurring Billing Service APIs.

If the RECURRING parameter was set to Y for the original transaction, then the setting is ignored when forming Credit, Void, and Force transactions.

If you subscribe to PayPal’s Fraud Protection Services:

To avoid charging you to filter recurring transactions that you know are reliable, the fraud filters do not screen recurring transactions.

To screen a prospective recurring customer, submit the transaction data using PayPal Manager’s Virtual Terminal. The filters screen the transaction in the normal manner. If the transaction triggers a filter, then you can follow the normal process to review the filter results.

No Alpha-

numeric

No Alpha-

numeric Y or N

Location Transaction Advice Addendum Parameters

MERCHANTNAME Name of merchant No MERCHANTSTREET Merchant’s street address (number and street

name)

MERCHANTCITY Merchant’s city No MERCHANTSTATE Merchant’s state No MERCHANTCOUNTRYCODEMerchant’s numeric country code

Example: USA: 840

MERCHANTZIP Merchant’s 5- to 9-digit ZIP (postal) code

excluding spaces, dashes, and non-numeric characters

Example: 951121737

Transaction Advice Detail Parameters

No Alpha-

numeric

70 Payflow Pro Developer’s Guide

Processors Requiring Additional Transaction Parameters

American Express

ABLE A.1 American Express CAPN parameters (Continued)

Parameter Description Required Type Length

ADDLAMTn Detail of a char ge where n is a value from 1 - 5

Use for additional breakdown of the amount Must include a decimal and be exact to the cent

(42.00, not 42) and exclude comma separators (1234.56 not 1,234.56)

Examples: tip=3.00, convenience charge=2.00

ADDLAMTTYPEn A 3-digit code indi cating the type of the

corresponding charge detail, where n is a value from 1 - 5

Airline Passenger Data Parameters

AIR-DEPARTUREDATE Departure date in the format YYYYMMDD. No Alpha-

AIR-PASSENGERNAME Name of the passenger in the following format

with fields separated by a space: surname firstname middleinitial title

AIR-ORIGIN Airport code of the originating airport.

For a list of airport codes, see http://www.world-

airport-codes.com/alphabetical/airportcode/a.html.

NOTE:Present day airport codes are three

characters in length. The five character length is designed to allow for future expansion.

No Numeric 12

No Alpha-

numeric

No Alpha-

numeric

No Alpha-

numeric

AIR-DESTINATION Destination airport code for the first segment of

the trip; this is not necessarily the final destination. For example, if a passenger flies from STL to MIA with a layover at JFK, the destination airport is JFK.

For a list of airport codes, see http://www.world-

airport-codes.com/alphabetical/airportcode/a.html.

NOTE:Present day airport codes are three

characters in length. The five character length is designed to allow for future expansion.

Payflow Pro Developer’s Guide 71

No Alpha-

numeric

Processors Requiring Additional Transaction Parameters

American Express

ABLE A.1 American Express CAPN parameters (Continued)

Parameter Description Required Type Length

AIRNUMBEROFCITIES

AIR-ROUTINGCITYn Airport codes of each city in this flight including

AIR-CARRIERn Two character airline code for each unique airline

Number of unique cities in this trip including the cities of origin and destination, where a maximum value of 10 is allowed. For example, AIR- NUMBEROFCITIES is 3 for the fo llowing trip:

DEN to LAX LAX to SFO SFO to DEN

If not provided, this value is equal to the number of AIR-ROUTINGCITYn parameters.

cities of origin and destination, where n is a value from 1 to 10.

For a list of airport codes, see http://www.world-

airport-codes.com/alphabetical/airportcode/a.html.

NOTE:Present day airport codes are three

characters in length. The five character length is designed to allow for future expansion.

in this flight, where n is a value from 1 to 10. If the same carrier is used for multiple segments of

the trip, it is passed only once. For example, the two AIR-CARRIERn values for the following trip are UA and AA:

UA flight from IAD to DEN UA flight from DEN to LAX UA flight from LAX to SFO AA flight from SFO to DFW

For information about airlines codes, see

ttp://en.wikipedia.org/wiki/Airline_codes-All.

No Numeric

No Alpha-

numeric

No Alpha-

numeric

AIR-FAREBASIS List discounts associated with the travel. No Alpha-

numeric

AIRNUMBEROFPASSENGER S

AIR-ISETICKET If this is an electronic ticket. The values are:

AIRRESERVATIONCODE

Number of passengers on this trip. No Numeri c

No Alpha-

Y = yes N = no

Code assigned to the travel reservation before the ticket was purchased.

No Alpha-

numeric

72 Payflow Pro Developer’s Guide

Processors Requiring Additional Transaction Parameters

American Express

ABLE A.1 American Express CAPN parameters (Continued)

Parameter Description Required Type Length

Other

FIRSTNAME Account holder's first and last name. Note: Even

though the parameter name indicates only the first name, this single parameter holds all of the person's name information (both first and last name, at a minimum).

LASTNAME Account holder's last name. No Alpha-

INVNUM Merchant invoice number. The merchant invoice

number is used for authorizations and settlements and, depending on your merchant bank, will appear on your customer's credit card statement and your bank reconciliation report. If you do not provide an invoice number, the transaction ID (PNREF) will be submitted.

ORDERDATE Order date

For example, July 28, 2003 is 072803. Format: mmddyy (with no slashes or dashes)

ORDERDATETIME Order time and date

Format is either YYYY-MM-DD or YYYY-MM-DD HH:MI:SS (where HH is in 24-hour time).If the value does

not conform to one of the formats or if the date is not valid (for example, 2004-17-35), then the transaction is rejected with:

RESULT=7(SIG_FIELD_ERR) RESPMSG=Invalid ORDERTIME

A truncated version of the ORDERTIME value (up to 7 characters) overwrites any value provided by ORDERDATE. If no value is provided, a NULL value is stored.

No Alpha-

numeric

No Alpha-

numeric

No Numeric 7

No 19

SWIPE Allows Track 1 and Track 2 data to be passed to

enable a card-present transaction

No Alpha-

numeric

American Express Additional Credit Card Parameters (Legacy)

In addition to the parameters in Table 4.1 , “Credit card transaction request parameters,” American Express Phoenix accepts the following legacy parameters.

NOTE:Merchants in the United States follow the CAPN requirements and use the parameters

described in Table A.1; international merchants do not and instead use the legacy

Payflow Pro Developer’s Guide 73

Processors Requiring Additional Transaction Parameters

American Express

parameters described in Table A.2. There are a few exceptions. If you are not sure, contact Customer Service. See “How to Contact Customer Support” on pa ge 9 for contact information.

TABLE A.2 American Express legacy parameters

Parameter Description Required Type Length

DESC Describes the transaction. No Alpha-

numeric

DESC1 Describes the transaction. No Alpha-

numeric

DESC2 Describes the transaction. No Alpha-

numeric

DESC3 Describes the transaction. No Alpha-

numeric

DESC4 Describes the transaction. No Alpha-

numeric

FIRSTNAME Account holder's first and last name. Note: Even

though the parameter name indicates only the first name, this single parameter holds all of the person's name information (both first and last name, at a minimum).

LASTNAME Account holder's last name. No Alpha-

No Alpha-

numeric

Brighton 40

Other American Express platforms 23

INVNUM Merchant invoice number. The merchant invoice

ORDERDATE Specifi es an order date.

For example, July 28, 2003 is 072803. Format: mmddyy (with no slashes or dashes)

No Alpha-

numeric

No Numeric 7

74 Payflow Pro Developer’s Guide

Processors Requiring Additional Transaction Parameters

American Express

ABLE A.2 American Express legacy parameters (Continued)

Parameter Description Required Type Length

ORDERDATETIME Specifies an order time and date.

Format is either YYYY-MM-DD or YYYY-MM-DD HH:MI:SS (where HH is in 24-hour time).If the value does

not conform to one of the formats or if the date is not valid (for example, 2004-17-35), then the transaction is rejected with:

RESULT=7(SIG_FIELD_ERR) RESPMSG=Invalid ORDERTIME

A truncated version of the ORDERTIME value (up to 7 characters) overwrites any value provided by ORDERDATE. If no value is provided, a NULL value is stored

RECURRING Identifies the transaction as recurring. This value

does not activate PayPal’s Recurring Billing Service APIs.

If the RECURRING parameter was set to Y for the original transaction, then the setting is ignored when forming Credit, Void, and Force transactions.

If you subscribe to PayPal’s Fraud Protection Services:

To avoid charging you to filter recurring transactions that you know are reliable, the fraud filters do not screen recurring transactions.

To screen a prospective recurring customer, submit the transaction data using PayPal Manager’s Manual Transactions page. The filters screen the transaction in the normal manner. If the transaction triggers a filter, then you can follow the normal process to review the filter results.

No 19

No Alpha-

numeric Y or N

SWIPE Allows Track 1 and Track 2 data to be passed to

enable a card-present transaction.

Payflow Pro Developer’s Guide 75

No Alpha-

numeric

Processors Requiring Additional Transaction Parameters

First Data Merchant Services (FDMS) Nashville

FDMS Nashville, Additional Credit Card Parameters

In addition to the parameters in Table 4.1 , “Credit card transaction request parameters,” FDMS Nashville accepts the following parameters:

TABLE A.3 FDMS Nashville additional parameters

Parameter Description Required Type Length

INVNUM Merchant invoice number. The merchant invoice number is

used for authorizations and settlements and, depending on your merchant bank, will appear on your customer's credit card statement and your bank reconciliation report. If you do not provide an invoice number, the transaction ID (PNREF) will be submitted.

RECURRING Identifies the transaction as recurring. This value does not

activate PayPal’s Recurring Billing Service API. If the RECURRING parameter was set to Y for the original

transaction, then the setting is ignored when forming Credit, Void, and Force transactions.

If you subscribe to PayPal’s Fraud Protection Services: T o avoid charging you to filter recurring transactions that

you know are reliable, the fraud filters do not screen recurring transactions.

SWIPE Allows Track 1 and Track 2 data to be passed to enable a

card-present transaction.

No Alpha-

numeric

No Alpha-

numeric Y or N

No Alpha-

numeric

76 Payflow Pro Developer’s Guide

Processors Requiring Additional Transaction Parameters

First Data Merchant Services (FDMS) South

FDMS South, Additional Credit Card Parameters

In addition to the parameters in Table 4.1 , “Credit card transaction request parameters,” FDMS South accepts the following parameters:

TABLE A.4 FDMS South add itional p arame ters

Parameter Description Required Type Length

SWIPE Allows Track 1 and Track 2 data to be passed to enable a

card-present transaction.

No Alpha-

numeric

First Data Merchant Services (FDMS) North

FDMS North, Additional Credit Card Parameters

In addition to the parameters in Table 4.1 , “Credit card transaction request parameters,” FDMS North (also known as FDMS CardNet) accepts the parameters in Table A.5.

ABLE A.5 FDMS North additional parameters

Parameter Description Required Type Length

DESC Use the DESC* parameters to pass in your DBA name

and other data describing the transaction. This information will be displayed in the end user’s statement.

Note: FDMS North passes the descriptive data to the card associations with the following character lengths:

z Visa: 25 z MasterCard: 22 z AMEX: 20 z DISC: 22

Some card associations truncate the value to 19 characters. If you have questions, consult the card association.

No Alpha-

numeric

MERCHSVC Defaults to CITY (where the merchant outlet is

located) for retail and to PHO NENUM for non-retail. For example, 800 111-1111. Use uppercase

characters. The first three positions must be numeric.

Payflow Pro Developer’s Guide 77

No Alpha-

numeric

Processors Requiring Additional Transaction Parameters

Merchant e-Solutions

Merchant e-Solutions, Additional Credit Card Parameters

In addition to the parameters in Table 4.1 , “Credit card transaction request parameters,” Merchant e-Solutions accepts the following parameters:

TABLE A.6 TSYS Acquiring Solutionsa additional parameters

Parameter Description Required Type Length

INVNUM Merchant invoice number. The merchant invoice number

is used for authorizations and settlements and, depending on your merchant bank, will appear on your customer's credit card statement and your bank reconciliation report. If you do not provide an invoice number, the transaction ID (PNREF) will be submitted.

SWIPE Allows Track 1 and Track 2 data to be passed to enable a

card-present transaction.

RECURRING Identifies the transaction as recurring. This value does

not activate PayPal’s Recurring Billing Service APIs. If the RECURRING parameter was set to Y for the

original transaction, then the setting is ignored when forming Credit, Void, and Force transactions.

If you subscribe to PayPal’s Fraud Protection Services: T o avoid char ging you to filter recurring transactions

that you know are reliable, the fraud filters do not screen recurring transactions.

To screen a prospective recurring customer, submit the transaction data using PayPal Manager’s Virtual Terminal page. The filters screen the transaction in the normal manner. If the transaction triggers a filter, then you can follow the normal process to review the filter results.

No Alpha-

numeric

No Alpha-

numeric

No Alpha-

numeric Y or N

Formerly Vital Processing Services

78 Payflow Pro Developer’s Guide

Processors Requiring Additional Transaction Parameters

Elavon (Formerly Nova)

Elavon, Additional Credit Card Parameters

In addition to the parameters in Table 4.1 , “Credit card transaction request

parameters,”Elavon accepts the following parameter:

TABLE A.7 Elavon additional parameters

Parameter Description Required Type Length

RECURRING Identifies the transaction as recurring. This value does

not activate PayPal’s Recurring Billing Service API. If the RECURRING parameter was set to Y for the original

transaction, then the setting is ignored when forming Credit, Void, and Force transactions.

If you subscribe to PayPal’s Fraud Protection Services: T o avoid charging you to filter recurring transactions that

you know are reliable, the fraud filters do not screen recurring transactions.

No Alpha-

numeric Y or N

Paymentech

Paymentech Salem (New Hampshire), Additional Credit Card Parameters

(CAPN)

In addition to the parameters in Table 4.1 , “Credit card transaction request parameters,” Paymentech Salem (New Hampshire) accepts the parameters in Table A.8 to meet CAPN requirements.

ABLE A.8 Additional Paymentech paramet ers to meet CAPN require ments

Parameter Description Required Type Length

Internet Transaction Data Parameters

EMAIL Account holder’s email address No Alpha-

numeric

Payflow Pro Developer’s Guide 79

Processors Requiring Additional Transaction Parameters

Paymentech

ABLE A.8 Additional Paymentech paramet ers to meet CAPN

Parameter Description Required Type Length

PHONENUM Account holder’s telephone number No String 20 PHONETYPE Telephone company provided ANI information

identifier digits indicating the telephone call type Examples: cellular (61-63), payphone (27)

CUSTHOSTNAME Name of the server that the account holder is

connected to Example: PHX.QW.AOL.COM

CUSTBROWSER Account holder’s HTTP browser type

Example:

MOZILLA/4.0~(COMPATIBLE;~MSIE ~5.0;~WI NDOWS~95)

CUSTIP Account holder’s IP address No Alpha-

SHIPTOCOUNTRY Numeric country code of ship-to country

Example: USA: 840

No Alpha-

numeric

No Alpha-

numeric and special character s

No Alpha-

numeric and special character s

No Alpha-

numeric

SHIPMETHOD Shipping method code. The values are:

01 = Same day 02 = Overnight/next day 03 = Priority, 2 - 3 days 04 = Ground, 4 or more days 05 = Electronic delivery 06 - ZZ = Reserved for future use

SKU Merchant product SKU No Alpha-

AVS Parameters

STREET Account holder’s street address (number and street

name)

No Alpha-

numeric

No Alpha-

numeric

80 Payflow Pro Developer’s Guide

Processors Requiring Additional Transaction Parameters

Paymentech

ABLE A.8 Additional Paymentech paramet ers to meet CAPN

Parameter Description Required Type Length

ZIP Account holder’s 5- to 9-digi t ZIP (postal) code

excluding spaces, dashes, and non-numeric characters

Example: 951121737

PHONENUM Account holder’s telephone number. The formats

are

xxx-xxx-xxxx (US numbers) +xxxxxxxxxxx (international numbers)

SHIPTOFIRSTNAME First name in the shipping address No Alpha-

SHIPTOLASTNAME Last name in the shipping address No Al pha-

SHIPTOSTREET Shipping street address No Alpha-

SHIPTOCOUNTRY Numeric country code

Example: USA: 840

SHIPTOZIP Shipping 5- to 9-digi t ZIP (postal) code exclu ding

spaces, dashes, and non-numeric characters Example: 951121737

No String 9

No String 20

numeric

No Alpha-

numeric

No Alpha-

numeric

SHIPTOPHONENUM Shipping telephone number No String 10 RECURRING Identifies the transaction as recurring. This value

does not activate the PayPal Recurring Billing Service API.

If the RECURRING parameter was set to Y for the original transaction, then the setting is ignored when forming Credit, Void, and Force transactions.

If you subscribe to PayPal’s Fraud Protection Services:

To avoid charging you to filter recurring transactions that you know are reliable, the fraud filters do not screen recurring transactions.

No Alpha-

numeric Y or N

Payflow Pro Developer’s Guide 81

Processors Requiring Additional Transaction Parameters

Paymentech

Paymentech, Additional Credit Card Parameters (Legacy)

In addition to the parameters in Table 4.1 , “Credit card transaction request parameters,” Paymentech accepts the following legacy parameters. For best AVS results, pass the city and state parameters in the parameter list.

TABLE A.9 Additional Paymentech paramet ers (lega cy)

Parameter Description Required Type Length

CITY Cardholder’s billing city. No Alpha 20 BILLTOCOUNTRY Cardholder’s billing country code Yes Numeric 3 INVNUM Merchant invoice num ber. The merchant invoice

MERCHDESCR Merchant descriptor.

For example, ABCCMPY*FALLCATALOG

MERCHSVC Merchant telephone number.

For example, 603-555-1212

STATE Cardholder’s billing state. No Alpha 2 SWIPE Allows Track 1 and Track 2 data to be passed to

enable a card-present transaction.

RECURRING Identifies the transaction as recurring. This value

does not activate PayPal’s Recurring Billing Service APIs.

If the RECURRING parameter was set to Y for the original transaction, then the setting is ignored when forming Credit, Void, and Force transactions.

If you subscribe to PayPal’s Fraud Protection Services:

To avoid charging you to filter recurring transactions that you know are reliable, the fraud filters do not screen recurring transactions.

No Alpha-

numeric

No Alpha-

numeric

No Alpha-

numeric

No Alpha-

numeric

No Alpha-

numeric Y or N

82 Payflow Pro Developer’s Guide

Processors Requiring Additional Transaction Parameters

TSYS Acquiring Solutions

ABLE A.9 Additional Paymentech paramet ers (lega cy)(Continued)

Parameter Description Required Type Length

RECURRINGTYPE (Paymentech Tampa only) Type of transaction

occurrence. The values are:

F = First occurrence S = Subsequent occurrence (default)

No Alpha 1

TSYS Acquiring Solutions

TSYS Acquiring Solutions, Additional Credit Card Parameters (CAPN)

In addition to the parameters in T able 4.1 , “Credit card transaction request parameters,” TSYS Acquiring Solutions accepts the following parameters to meet CAPN requirements.

ABLE A.10 Additional TSYS Acquiring Solutions parameters to meet CAPN

requirements

Parameter Description Required Type Length

Retail Transaction Advice Addendum Parameters (for SWIPE transactions)

L_DESCn Description of this line-item (n is a line item

number from 1 to 6)

No Alpha-

numeric

L_AMTn Amount of this line-item (n is a line item number

from 1 to 6) Must include a decimal and be exact to the cent

(42.00, not 42) and exclude comma separators (1234.56 not 1,234.56)

Examples: tip=3.00, convenience charge=2.00

L_QTYn Quantity of this line-item (n is a line item number

from 1 to 6)

Internet Transaction Data Parameters

EMAIL Account holder’s email address No Alpha-

PHONENUM Account holder’s telephone number No String 20 PHONETYPE Telephone company provided ANI information

identifier digits indicating the telephone call type Examples: cellular (61-63), payphone (27)

No Numeric 12

No Numeric 3

numeric

No Alpha-

numeric

Payflow Pro Developer’s Guide 83

Processors Requiring Additional Transaction Parameters

TSYS Acquiring Solutions

ABLE A.10 Additional TSYS Acquiring Solutions parameters to meet CAPN

requirements

Parameter Description Required Type Length

(Continued)

CUSTHOSTNAME Name of the server that the account holder is

connected to Example: PHX.QW.AOL.COM

CUSTBROWSER Account holder’s HTTP browser type

Example:

MOZILLA/4.0~(COMPATIBLE;~MSIE ~5.0;~W INDOWS~95)

CUSTIP Account holder’s IP address No Alpha-

SHIPTOCOUNTRY Numeric country code of ship-to country

Example: USA: 840

SHIPMETHOD Shipping method code. The values are:

01 = Same day 02 = Overnight/next day 03 = Priority, 2 - 3 days 04 = Ground, 4 or more days 05 = Electronic delivery 06 - ZZ = Reserved for future use

No Alpha-

numeric and special characters

No Alpha-

numeric and special characters

No Alpha-

numeric

No Alpha-

numeric

SKU Merchant product SKU No Alpha-

numeric

AVS Parameters

STREET Account holder’s street address (number and street

name)

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

excluding spaces, dashes, and non-numeric characters

Example:

PHONENUM Account holder’s telephone number. The formats

are

xxx-xxx-xxxx (US numbers) +xxxxxxxxxxx (international numbers)

951121737

No Alpha-

numeric

No String 9

No String 20

84 Payflow Pro Developer’s Guide

Processors Requiring Additional Transaction Parameters

TSYS Acquiring Solutions

ABLE A.10 Additional TSYS Acquiring Solutions parameters to meet CAPN

requirements

Parameter Description Required Type Length

(Continued)

SHIPTOFIRSTNAME First name in the shipping address No Alpha-

numeric

SHIPTOLASTNAME Last name in the shipping address No Alpha-

numeric

SHIPTOSTREET Shipping street address No Alpha-

numeric

SHIPTOCOUNTRY Numeric country code

Example: USA: 840

SHIPTOZIP Shipping 5- to 9-digit ZIP (postal) code excluding

spaces, dashes, and non-numeric characters Example: 951121737

SHIPTOPHONENUM Shipping telephone number No String 10 RECURRING Identifies the transaction as recurring. This value

does not activate PayPal’s Recurring Billing Service APIs.

If the RECURRING parameter was set to Y for the original transaction, then the setting is ignored when forming Credit, Void, and Force transactions.

If you subscribe to PayPal’s Fraud Protection Services:

To avoid charging you to filter recurring transactions that you know are reliable, the fraud filters do not screen recurring transactions.

No Alpha-

numeric

No Alpha-

numeric

No Alpha-

numeric Y or N

Location Transaction Advice Addendum Parameters

MERCHANTNAME Name of merchant No MERCHANTSTREET Merchant’s street address (number and street

name)

MERCHANTCITY Merchant’s city No MERCHANTSTATE Merchant’s state No

Payflow Pro Developer’s Guide 85

No Alpha-

numeric

Processors Requiring Additional Transaction Parameters

TSYS Acquiring Solutions

ABLE A.10 Additional TSYS Acquiring Solutions parameters to meet CAPN

requirements

Parameter Description Required Type Length

(Continued)

MERCHANTCOUNTRYCODEMerchant’s numeric country code

Example: USA: 840

MERCHANTZIP Merchant’s 5- to 9-digit ZIP (postal) code

excluding spaces, dashes, and non-numeric characters

Example: 951121737

Transaction Advice Detail Parameters

ADDLAMTn Detail of a char ge where n is a value from 1 - 5

Use for additional breakdown of the amount Must include a decimal and be exact to the cent

(42.00, not 42) and exclude comma separators (1234.56 not 1,234.56)

Examples: tip=3.00, convenience charge=2.00

ADDLAMTTYPEn A 3-digit code indi cating the type of the

corresponding charge detail, where n is a value from 1 - 5

Airline Passenger Data Parameters AIR-DEPARTUREDATE Departure date in the format YYYYMMDD. No Alpha-

No Alpha-

numeric

No Alpha-

numeric

No Numeric 12

No Alpha-

numeric

AIR-PASSENGERNAME Name of the passenger in the following format

with fields separated by a space: surname firstname middleinitial title

AIR-ORIGIN Airport code of the originating airport.

For a list of airport codes, see http://www.world-

airport-codes.com/alphabetical/airportcode/a.html.

NOTE:Present day airport codes are three

characters in length. The five character length is designed to allow for future expansion.

No Alpha-

numeric

No Alpha-

numeric

86 Payflow Pro Developer’s Guide

Processors Requiring Additional Transaction Parameters

TSYS Acquiring Solutions

ABLE A.10 Additional TSYS Acquiring Solutions parameters to meet CAPN

requirements

Parameter Description Required Type Length

(Continued)

AIR-DESTINATION Destination airport code for the first segment of

the trip; this is not necessarily the final destination. For example, if a passenger flies from STL to MIA with a layover at JFK, the destination airport is JFK.

For a list of airport codes, see http://www.world-

airport-codes.com/alphabetical/airportcode/a.html.

NOTE:Present day airport codes are three

characters in length. The five character length is designed to allow for future expansion.

AIRNUMBEROFCITIES

AIR-ROUTINGCITYn Airport codes of each city in this flight including

Number of unique cities in this trip including the cities of origin and destination, where a maximum value of 10 is allowed. For example, AIR- NUMBEROFCITIES is 3 for the following trip:

DEN to LAX LAX to SFO SFO to DEN

If not provided, this value is equal to the number of AIR-ROUTINGCITYn parameters.

cities of origin and destination, where n is a value from 1 to 10.

For a list of airport codes, see http://www.world-

airport-codes.com/alphabetical/airportcode/a.html.

No Alpha-

numeric

No Numeric

No Alpha-

numeric

NOTE:Present day airport codes are three

characters in length. The five character length is designed to allow for future expansion.

Payflow Pro Developer’s Guide 87

Processors Requiring Additional Transaction Parameters

TSYS Acquiring Solutions

ABLE A.10 Additional TSYS Acquiring Solutions parameters to meet CAPN

requirements

Parameter Description Required Type Length

(Continued)

AIR-CARRIERn Two character airline code for each unique airline

in this flight, where n is a value from 1 to 10. If the same carrier is used for multiple segments of

the trip, it is passed only once. For example, the two AIR-CARRIERn values for the following trip are UA and AA:

UA flight from IAD to DEN UA flight from DEN to LAX UA flight from LAX to SFO AA flight from SFO to DFW

For information about airlines codes, see

ttp://en.wikipedia.org/wiki/Airline_codes-All.

AIR-FAREBASIS List discounts associated with the travel. No Alpha-

AIRNUMBEROFPASSENGER S

AIR-ISETICKET If this is an electronic ticket. The values are:

AIRRESERVATIONCODE

Number of passengers on this trip. No Numeri c

Y = yes N = no

Code assigned to the travel reservation before the ticket was purchased.

No Alpha-

numeric

No Alpha-

numeric

No Alpha-

numeric

Other

FIRSTNAME Account holder's first and last name. Note: Even

though the parameter name indicates only the first name, this single parameter holds all of the person's name information (both first and last name, at a minimum).

LASTNAME Account holder's last name. No Alpha-

INVNUM Merchant invoice number. The merchant invoice

ORDERDATE Order date

For example, July 28, 2003 is 072803. Format: mmddyy (with no slashes or dashes)

No Alpha-

numeric

No Alpha-

numeric

No Numeric 7

88 Payflow Pro Developer’s Guide

Processors Requiring Additional Transaction Parameters

TSYS Acquiring Solutions

ABLE A.10 Additional TSYS Acquiring Solutions parameters to meet CAPN

requirements

Parameter Description Required Type Length

(Continued)

ORDERDATETIME Order time and date

Format is either YYYY-MM-DD or YYYY-MM-DD HH:MI:SS (where HH is in 24-hour time).If the value does

not conform to one of the formats or if the date is not valid (for example, 2004-17-35), then the transaction is rejected with:

RESULT=7(SIG_FIELD_ERR) RESPMSG=Invalid ORDERTIME

A truncated version of the ORDERTIME value (up to 7 characters) overwrites any value provided by ORDERDATE. If no value is provided, a NULL value is stored.

SWIPE Allows Track 1 and Track 2 data to be passed to

enable a card-present transaction

No 19

No Alpha-

numeric

TSYS Acquiring Solutions, Additional Credit Card Parameters (Legacy)

In addition to the parameters in T able 4.1 , “Credit card transaction request parameters,” TSYS Acquiring Solutions accepts the following legacy parameters:

ABLE A.11 TSYS Acquiring Solutions additional parameters (legacy)

Parameter Description Required Type Length

INVNUM Merchant invoice number. The merchant invoice number

SWIPE Allows Track 1 and Track 2 data to be passed to enable a

card-present transaction.

Payflow Pro Developer’s Guide 89

No Alpha-

numeric

No Alpha-

numeric

Processors Requiring Additional Transaction Parameters

TSYS Acquiring Solutions

ABLE A.11 TSYS Acquiring Solutions additional parameters (legacy)(Continued)

Parameter Description Required Type Length

RECURRING Identifies the transaction as recurring. This value does

not activate PayPal’s Recurring Billing Service API. If the RECURRING parameter was set to Y for the original

transaction, then the setting is ignored when forming Credit, Void, and Force transactions.

If you subscribe to PayPal’s Fraud Protection Services: T o avoid char ging you to filter recurring transactions

that you know are reliable, the fraud filters do not screen recurring transactions.

No Alpha-

numeric Y or N

90 Payflow Pro Developer’s Guide

Performing TeleCheck Electronic

Check Transactions

This chapter describes Telecheck (electronic check) transaction processing and testing.

NOTE:TeleCheck transactions are not supported on the PayPal processor.

Paypal offers electronic check acceptance through TeleCheck. Before processing electronic check transactions, merchants must obtain an account through TeleCheck (www.telecheck.com).

For information on:

z Performing credit card transactions, skip this chapter and see “Credit Card Transactions”

on page 23.”

z Performing ACH transactions, contact your PayPal Sales Representative at

paymentsales@PayPal.com

TeleCheck Parameters

Parameters used for processing electronic checks through TeleCheck are described in

Table B.1. Required and optional parameters are noted.

NOTE:Appendix E, “Additional Reporting Parameters,” provides a list of parameters that you

can pass for reporting purposes.

Required Parameters

As a summary of Table B.1, the following parameters are required for every electronic check transaction:

TRXTYPE TENDER CHKTYPE PARTNER VENDOR USER PWD AMT CITY DL or SS CHKNUM EMAIL MICR NAME STATE

Payflow Pro Developer’s Guide 91

Performing TeleCheck Electronic Check Transactions

TeleCheck Parameters

STREET

Parameter Description Required Type Length

ZIP

TABLE B.1 TeleCheck Parameters

AMT This is the transaction amount. Default: U.S. dollars. The

transaction amount should always specify a decimal, and the exact amount to the cent (for example, 34.00, instead of

34). Do not include comma separators in the amount. Use

1199.95 not 1,199.95.

CITY Account holder’s city Y es Alpha 20 COMMENT1 User-defined value for reporting and auditing purposes. No Alpha-

COMMENT2 User-defined value for reporting and auditing purposes. No Alpha-

CHKNUM Account holder’s next unused (available) check number Yes Numeric 7 CHKTYPE Check type: P: personal (default) or

C: company

If CHKTYPE=P, then a value for either DL or SS must be passed as an identifier.

If CHKTYPE=C, then the Federal Tax ID must be passed as the SS value.

DL Driver’s license number. If CHKTYPE=P, a value for either

DL or SS must be passed as an identifier. Format: XXnnnnnnnn XX = State Code nnnnnnnn = DL Number

Yes Numeric

US Dollars only.

numeric

Yes Alpha

Yes Alpha-

numeric

128

DOB Account holder’s date of birth.

Format: mmddyyyy. For example, July 28, 1965 is represented as 07281965.

EMAIL Account holder’s e-mail address Yes Alpha-

INVNUM Check invoice number No Alpha-

MICR Magnetic Ink Check Reader. This is the entire line of

numbers at the bottom of all checks. It includes the transit number, account number, and check number.

NAME Account holder’s name as it appears on the check Yes Alpha-

No Alpha-

numeric

Yes Alpha-

numeric

92 Payflow Pro Developer’s Guide

Performing TeleCheck Electronic Check Transactions

Testing TeleCheck Transactions

ABLE B.1 TeleCheck Parameters (Continued)

Parameter Description Required Type Length

PARTNER The authorized PayPal Reseller that registered you for the

Payflow service provided you with a Partner ID. If you registered yourself, use PayPal.

This parameter is case-sensitive.

PHONENUM Account holder’s telephone number No Numeric 20 PWD Case-sensitive 6- to 32-character password that you

created while registering for the account.

SS Account holder’s social security number.

If CHKTYPE=P, a value for either DL or SS must be passed as an identifier.

If CHKTYPE=C, the Federal Tax ID must be passed as the SS value.

STATE Account holder’s state Yes Alpha 2 STREET Account holder’s street address Yes Alpha-

TENDER Tender type (method of payment). Use only the value K

(electronic check).

TRXTYPE Type of transaction that should be processed. Allowed

transaction types: Sale (S), Void (V), Inquiry (I).

USER Case-sensitive login ID for the Payflow Pro account that

you created while registering for the account. In the future, each account will allow multiple users. This

parameter will specify the user.

Yes Alpha-

numeric

Yes Alpha-

numeric

No Alpha-

numeric

Yes Alpha 1

Yes Alpha-

numeric

VENDOR Case-sensitive Vendor ID that you created while

registering for the account.

ZIP Account holder’s 5- to 9-digit postal code (called ZIP code

in the USA). Do not use spaces, dashes, or non-numeric characters.

Yes Alpha-

numeric

Yes Alpha 9

Testing TeleCheck Transactions

PayPal provides a test server to support testing and configuration. For information on the test server URL, see “Host Addresses” on page 13.

Example Test Transaction

“TRXTYPE=S&TENDER=K&CHKTYPE=P& PARTNER=<your Part ner Name (typically PayPal>&VENDOR=<your Merchant Login Name>&USER=< your Merchant Login

Payflow Pro Developer’s Guide 93

Performing TeleCheck Electronic Check Transactions

Preparing for TeleCheck Production Transactions

Name>&PWD=<your Payflow passwo rd>& AMT=42.00&STREET=1234 Main&CITY=Buffalo&DL=CA123456&CHKNUM=1001&EMAIL =<y our e-mail address>&MICR=<Use a MICR value from Table B.2>&NAME=Sally&STATE=CA&ZIP=95050”

ABLE B.2 MICR values for testing

MICR HOSTCODE TeleCheck Result

1234567804390850001001 000800 Check Approved ECA 1234567804390850011001 000801 Check Approved No ECA 1234567804390850021001 000802 Check Approved ECA, No Guarantee 1234567804390850031001 000803 Check Approved No ECA, No Guarantee 1234567804390850041001 000804 Check Decline Negative Data 1234567804390850051001 000805 Check Decline Scoring 1234567804390850071001 000807 Check Failed

Preparing for TeleCheck Production Transactions

Before going into production with your check integration, you must certify your storefront with TeleCheck. To begin the certification process, send an e-mail to

ica_certification@telecheck.com. Be sure to include the following information:

z Your test website address where test transactions can be processed z The name, e-mail address, and phone number of the person to contact about any needed

corrections. The certification process usually takes 2-3 days. Use the host address of the live server described in “Host Addresses” on page 13.

Responses to Telecheck Transactions

When a transaction finishes, PayPal returns a response string made up of name-value pairs. For example:

RESULT=0&PNREF=VXYZ01234567&HO STCODE=000500&RESP MSG=Approved

94 Payflow Pro Developer’s Guide

Performing TeleCheck Electronic Check Transactions

HOSTCODE Values

Telecheck transaction response values are described in Table B.3.

TABLE B.3 Transaction responses common to all tender types

Field Description Ty pe Length

RESULT The outcome of the attempted transaction. A result of 0 (zero) indicates

the transaction was approved. Any other number indicates a decline or error. RESULT values are described in “RESULT Values and

RESPMSG Text” on page 58.

PNREF PayPal Reference ID, a unique number that identifies the transaction.

PNREF is described in “HOSTCODE Values” on page 95.

HOSTCODE TeleCheck’s response code representing the results of the transaction

authorization attempt. These values are described in “HOSTCODE

Values” on page 95.

RESPMSG A descriptive message associated with decline or error RESULTs.

Response messages are described in Chapter , “Responses to

Transaction Requests.”

HOSTCODE Values

The HOSTCODE reflects the TeleCheck server result. The following tables describe the HOSTCODE values. TeleCheck requires that you display certain verbiage to the purchaser based on the returned HOSTCODE value—check with TeleCheck for details.

NOTE:Many of these codes will not be encountered under normal operating conditions—they

are included as a troubleshooting aid. In the tables, the Frequency column indicates the likelihood that you will encounter the code.

Numeric Variable

Alphanumeric

Numeric 6

Alphanumeric

Variable

ABLE B.4 Sale Approved HOSTCODE values

Code Response Description Frequency

000500 Sale Approved Sale Approved by credit card network Common 000501 Sale Time-out Sale transaction time-out in credit card network Common 000502 Test Card Test card sale approved (never billed) Common 000504 ANI Sale Approved 900/Telc o sale approved ANI bill only 000505 PB Sale Approved Private billing sale approved PB only 000800 Sale Approved Direct Check Sale/ECA approved Direct Check 000801 Sale Approved Direct Check Sale approved (no ECA) Direct Check 000802 Sale Approved Direct Check Sale/ECA approved no guarantee Direct Check 000803 Sale Approved Direct Check Sale approved no ECA no guarantee Direct Check

Payflow Pro Developer’s Guide 95

Performing TeleCheck Electronic Check Transactions

HOSTCODE Values

TABLE B.5 Sale Declined HOSTCODE values

Code Response Description Frequency

000300 Sale Declined Sale declined by credit card network Common 000301 Sale Rejected Sale does not meet risk standards Common 000804 Check Declined Direct Check Sale declined negative data Direct Check 000805 Check Declined Direct Check Sale Decline Scoring Direct Check 000807 Check Failure Direct Check Sale Direct Check

ABLE B.6 Inquiry Approved HOSTCODE values

Code Response Description Frequency

000400 OTB Approved Preauthorization approved. AVS matches if provided. Common 000401 No Response No response from cred it card network for preauth. Common 000402 AVS Time-out Preauth ori zation approved, AVS timed out AVS only 000403 PB Approved Private billing app rov ed. PB only 000410 Positive Record Previo us positi ve history. Common 000420 Test card Approved Test Card Common 000421 OTB/AVS Approval Preauthorization approved, AVS match AVS only 000503 ANI Bill approved 900/TELCO billing approved ANI bill only

ABLE B.7 General Failure HOSTCODE values

Code Response Description Frequency

000100 General Failure General host based failure Rare 000101 Invalid Value Invalid for one or more fields in transaction Common 999999 Unknown Response TeleCheck received an unknown response Rare

ABLE B.8 Inquiry Declined HOSTCODE values

Code Response Description Frequency

000200 Preauth Declined Declined by credit card or Telco network (LIDB) Common 000201 PIN Mismatch Mismatch on PIN stored in TeleCheck database Not Used

96 Payflow Pro Developer’s Guide

Performing TeleCheck Electronic Check Transactions

HOSTCODE Values

TABLE B.8 Inquiry Declined HOSTCODE values

Code Response Description Frequency

000210 Negative Card Record Temporary and permanent blocks. Prior OTB decline, sale

Common decline or CS block Transaction falls below minimum scoring standards. Most frequently used for risk scoring declines, where a transaction falls below minimum standards.

000215 Negative ANI Record ANI previously blocked by CS Common 000220 Chargeback Card Card with chargeback history Common 000225 Chargeback ANI ANI with chargeback history Common 000230 Exceed card profile 000240 Too many Cards 000250 Exceed ANI profile 000260 Too Many Phones

Card has exceeded usage limits Uncommon

ANI has excessive number of cards Uncommon

ANI has exceeded usage limits Uncommon Card has been used from excessive ANI Uncommon

000270 OTB/AVS Decline OTB decline and AVS mismatch AVS OTB

only

000271 OTB/AVS Decline OTB approved and AVS mismatch AVS OTB

only

000272 OTB/AVS Decline OTB decline and AVS match AVS OTB

only

000280 Risk Referral Temporary Risk referral, AVS necessary Common 000281 Card Not Qualified Card does not meet minimum bank restrictions Not Used 000282 PB Risk Referral Private billing risk referral, AV S necessary PB Only

a. This data is included in risk scoring decisions and a response of 210 has higher precedence.

Payflow Pro Developer’s Guide 97

Performing TeleCheck Electronic Check Transactions

HOSTCODE Values

98 Payflow Pro Developer’s Guide

Submitting Purchasing Card

Level 2 and Level 3 Transactions

PayPal Payment Services supports passing Purchasing Card Level 2 information (such as purchase order number, tax amount, and charge description) in the settlement file.

If additional required invoice information and line item details are included in the transaction, PayPal formats Purchasing Card Level 3 information in an appropriate format, for example, EDI (Electronic Data Interchange) 810 format as required by American Express during settlement processing.

About Purchasing Cards

Purchasing Cards are used in the procurement process to eliminate paper-based order systems and associated costs, to improve control and accountability through itemized statements, to foster better risk controls through spending limits and buying from approved vendors, to reduce administrative overhead because employees are empowered to make small purchases, and to enable enterprises to negotiate better contract pricing and discounts with suppliers through the use of vendor detail reports.

To promote acceptance and usage of Purchasing Card programs, card issuers have established incentive rates for merchants. These rates are available for merchants who comply at either Level 2 or Level 3 (described in the next section). T ransactions that comply at Level 1 qualify as normal credit card transactions.

NOTE:Card issuing institutions perform strict data verification on the enhanced data that is

submitted with Level 2 or Level 3 transactions. Issuers may charge stiff penalties if fields contain either inaccurate or filler data. Only transactions that contain accurate data are eligible for the incentive rates.

About Program Levels

The term Level does not apply to the card, but to the transaction data submitted for that card. Generally, a higher level means more detailed data for reporting.

Table C.1 describes the transaction levels that are recognized.

TABLE C.1 Transaction levels

Level Description

Level 1 Function as normal credit cards and are authorized and associated with normal

transaction data in authorization and settlement. Any merchant who accepts credit cards supports this level.

Payflow Pro Developer’s Guide 99

Submitting Purchasing Card Level 2 and Level 3 Transactions

About American Express Purchasing Card Transactions - Phoenix Processor

TABLE C.1 Transaction levels

Level Description

Level 2 Additional data regarding sales tax, customer code, purchase order number,

invoice number are captured at the point of sale. In most cases, this information is combined with the merchant’s tax ID number, state, and postal code data and is then passed through during settlement. For some processors and banks, however, a Level 2 authorization may include some of this data.

Level 3 S ignificant additional information such as line items, product codes, item

descriptions, unit price, unit quantities, and ship-to postal data are added to the Level 2 data to provide optimal reporting to buyers and sellers. Settlement transactions typically carry Level 3 data.

Level 2 and Level 3 data is generally considered non-financial data. Lack of adeq uate data may cause a transaction to be downgraded.

PayPal generally requires up to Level 2 information in an Authorization transaction followed by additional Level 3 data in the associated Delayed Capture transaction. A Sale transaction should include all Level 3 data since it is authorized and later settled.

Accepted BIN Ranges

Visa, MasterCard, and American Express publish specific Bank Identification Number (BIN) ranges for purchasing cards. Sometimes the determination of whether a card is a purchasing

card is left to the processor (for example, TSYS Acquiring Solutions

). In other cases, the Payflow payments gateway makes the determination based on the BIN range (for example, FDMS South and American Express).

BIN ranges accepted for American Express Level 2 and Level 3 transactions are listed on page 102.

About American Express Purchasing Card Transactions -

Phoenix Processor

The information in this section applies to transactions processed by the American Express Phoenix Processor, not necessarily to all American Express cards. Level 2 and Level 3 purchasing card rules may differ for American Express card transactions processed by other processors such as Paymentech or First Data Nashville.

1. Formerly Vital Processing Services

100 Payflow Pro Developer’s Guide

PayPal Payflow Pro - 2009 Developer's Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

Scope

Preface

Intended Audience

Related Documentation

How to Contact Customer Support

Revision History

Introduction

About Payflow Pro

Payflow Pro Documentation

Host Addresses

How Payflow Pro Works

Supported Processing Platforms

Supported Payment Types

Payflow Pro Recurring Billing Service

About Security

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

Credit Card Transactions

Credit Card Features

About Credit Card Processing

Obtaining an Internet Merchant Account

Planning Your Payflow Pro Integration

Complying With the E-commerce Indicator (ECI)

Handling Credit Card Type Information

Parameters Used in Credit Card Transactions

Submitting Sale Transactions

When To Use a Sale Transaction

Additional Parameters For Sale Transactions

Submitting Authorization/Delayed Capture Transactions

Typical Sale Transaction Parameter String

When To Use Authorization/Delayed Capture Transactions

Required Authorization Transaction Parameters

Typical Authorization Transaction Parameter String

Required Delayed Capture Transaction Parameters

Submitting Account Verifications With TRXTYPE=A

Delayed Capture Transaction: Capturing Transactions for Lower Amounts

Delayed Capture Transaction: Capturing Transactions for Higher Amounts

Delayed Capture Transaction: Error Handling and Retransmittal

When To Use Account Verification

Example Account Verification

Submitting Voice Authorization Transactions

When to Use a Voice Authorization Transaction

Submitting Credit Transactions

Required Voice Authorization Transaction Parameters

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

Submitting Inquiry Transactions

When To Use an Inquiry Transaction

Required Parameters When Using the PNREF

Inquiry Transaction Parameter Strin g Using the PNREF

Required Parameters When Using the CUSTREF

Inquiry Transaction Parameter String Using the CUSTREF

Recharging to the Same Credit Card (Reference Transactions)

When To Use a Referen ce Transaction

Transaction Types that Can Be Used as the Original Transaction

Fields Copied From Reference Transactions

Example Reference Transaction

Submitting Card-Present (SWIPE) Transactions

Supported Processing Platforms

Card-present Transaction Syntax

Submitting Purchasing Card Transactions